# Welcome
Source: https://docs.lerian.studio/en/index

Guides, platform capabilities, API references, and integration tutorials for the Lerian core banking platform: Midaz, the products around it, Brazil Rails, and Interfaces.

# Build core banking on primitives you control.

Guides, platform capabilities, and API references for the entire Lerian ecosystem, from the double-entry ledger up.

[Explore the products →](/en/products/about-products)

[See the integration diagrams](/en/diagrams/introduction)

[Get started →](/en/start-here/getting-started) · [Start with the fundamentals →](/en/start-here/fundamentals/core-banking/what-is-core-banking) · [API reference →](/en/reference/introduction)

## Go from zero to your first transaction.

01

### [Model your ledger](/en/start-here/getting-started)

Set up your Organization, Ledger, and Accounts.

02

### [Post a transaction](/en/products/midaz/transactions-overview)

Move value with strict double-entry guarantees.

03

### [Deploy anywhere](https://github.com/LerianStudio/helm)

BYOC on AWS, GCP, on-prem, or Lerian Cloud.

## Products

Lerian is a complete, modular core banking platform. Start with the components that fit your operation and compose them into the platform you need.

### [![](https://mintcdn.com/lerian-49cb71fc/5dD4BTy_lmC0R8p5/images/icons/midaz.svg?fit=max\&auto=format\&n=5dD4BTy_lmC0R8p5\&q=85\&s=016d1c1908b9ae42d80bb50a49d90bad) Midaz CORE](/en/products/midaz/what-is-midaz)

The double-entry ledger at the platform's core: organizations, ledgers, accounts, and transactions you fully control.

Get started with Midaz →

### [![](https://mintcdn.com/lerian-49cb71fc/5dD4BTy_lmC0R8p5/images/icons/tracer.svg?fit=max\&auto=format\&n=5dD4BTy_lmC0R8p5\&q=85\&s=84a6c37f8f2cf59ada19656e3559f3f6) Tracer](/en/products/tracer/what-is-tracer)

Apply real-time spending controls and analyze transaction risk as money moves.

Trace a transaction →

### [![](https://mintcdn.com/lerian-49cb71fc/5dD4BTy_lmC0R8p5/images/icons/matcher.svg?fit=max\&auto=format\&n=5dD4BTy_lmC0R8p5\&q=85\&s=55ca7734fc78f84f2aacfc823802af86) Matcher](/en/products/matcher/what-is-matcher)

Reconcile transactions across banks, processors, and ERPs, and work through the exceptions that don't match.

Reconcile a batch →

### [![](https://mintcdn.com/lerian-49cb71fc/5dD4BTy_lmC0R8p5/images/icons/flowker.svg?fit=max\&auto=format\&n=5dD4BTy_lmC0R8p5\&q=85\&s=82555c849a03e5f2d4d4d5c6b8372a7a) Flowker](/en/products/flowker/what-is-flowker)

Orchestrate financial workflows and connect third-party services through its API.

Design a workflow →

### [ Lender](/en/products/lender/what-is-lender)

Run the full credit journey, from product definition and origination through servicing, accounting, and audit.

Explore Lender →

### [![](https://mintcdn.com/lerian-49cb71fc/5dD4BTy_lmC0R8p5/images/icons/reporter.svg?fit=max\&auto=format\&n=5dD4BTy_lmC0R8p5\&q=85\&s=3a2ac26a15de0a860fc4566278f28c2a) Reporter](/en/products/reporter/what-is-reporter)

Turn ledger and platform data into audit-ready reports from configurable templates.

Build a report →

## Brazil Rails and Interfaces

Where the platform meets Brazil's payment system. A Brazil rail is Lerian's own messaging with BACEN, Núclea, or Dataprev. An interface is the product surface over a rail, from Lerian or from a connectivity partner. Either way, you keep your ledger, your data, and your business logic.

### Brazil Rails

What are Brazil Rails?
The Brazil Rails tab documents Brazil's national payment and regulatory systems.

→

[Open](/en/rails/what-are-brazil-rails)

Native messaging
The two ways the Lerian platform reaches Brazil's payment system.

→

[Open](/en/rails/native-messaging)

SPI (Pix)
A native Pix connector to BACEN's SPI.

→

[Open](/en/rails/spi/what-is-lerian-spi)

SPB (TED)
Lerian SPB is your direct, non-intermediated BACEN STR connector.

→

[Open](/en/rails/spb/what-is-lerian-spb)

### Interfaces

What are Interfaces?
Lerian's integrations to payment products.

→

[Open](/en/interfaces/introduction)

Pix Lerian
A Pix application plugin for integration and testing with a mock provider adapter.

→

[Open](/en/interfaces/pix-lerian)

Pix JD
Direct Pix via JD: participate as a direct participant on SPI and DICT.

→

[Open](/en/interfaces/pix-jd/direct-pix-via-jd)

TED JD
Understand how the Bank Transfer plugin handles SPB communication.

→

[Open](/en/interfaces/ted-jd/ted-in-lerian)

##  Lerian Console

One web interface to operate Lerian products: dashboards, settings, and per-product modules in a single place.

[About the Console →](/en/platform/console/about-lerian-console)

[Console settings →](/en/platform/console/about-settings)

## Platform

### [Access Manager](/en/platform/access-manager)

Control who can do what, across your Lerian products.

### [Streaming Hub](/en/platform/streaming-hub/what-is-streaming-hub)

Consume platform events and fan them out to your systems through signed webhooks, queues, or a pull API (the platform's event delivery edge).

### [Multi-tenancy](/en/platform/multi-tenancy)

How Lerian Cloud and supported BYOC products isolate tenants.

### [Observability](/en/platform/observability)

Centralized logs, metrics, and traces across services.

Also in Platform: [Narya](/en/platform/narya/what-is-narya) · [Deploy](https://github.com/LerianStudio/helm) · [Lifecycle Management](/en/platform/lifecycle-management) · [Licensing](/en/platform/licensing/license-manager)

## News

Features, improvements, and changes across the platform and its documentation.

[View latest announcements →](/en/news/latest-news)

[Discord](https://discord.gg/DnhqKwkGv3)

[GitHub](https://github.com/LerianStudio)

[LinkedIn](https://www.linkedin.com/company/lerianstudio)

[Instagram](https://www.instagram.com/lerian.studio)

[Dev.to](https://dev.to/lerian)

© 2026 Lerian. All rights reserved.


# Our plugins
Source: https://docs.lerian.studio/en/products/about-plugins

Explore the plugins available across Lerian products: what each plugin does, when to enable it, and how it fits with Midaz and other core services.

Instead of building custom features from scratch, you can plug in what you need and keep everything else stable, scalable, and secure.

Plugins run alongside the product platform and add new logic, endpoints, or workflows to support specific business needs. Plugin availability is product-specific. The currently documented plugins below extend Midaz.

In this documentation the plugins live under the [Interfaces](/en/interfaces/introduction) tab, as Pix JD, Pix BTG, TED JD, and Payments BTG.

> [!WARNING]
>
> Plugins are premium features for Enterprise institutions only. Lerian licenses each plugin separately.

> [!NOTE]
>
> **CRM** is no longer a plugin. Midaz embeds CRM as a core component, and CRM needs no additional license. See [CRM Overview](/en/products/midaz/crm/crm-overview) for details.

> [!NOTE]
>
> **Fees Engine** is part of Midaz rather than a standalone plugin, a licensed capability embedded in the unified Midaz Ledger process. See [Fees Engine overview](/en/products/midaz/fees/fees-engine-overview) for details.

## Available plugins for Midaz

***

> **[Pix](/en/interfaces/pix/pix-overview)**
>
> Integrate Pix with Midaz, including SPI and DICT services, to manage keys, transactions, claims, and regulatory workflows.

> **[Bank Transfer (TED)](/en/interfaces/ted/ted-overview)**
>
> Process electronic transfers between banks through TED, managing transaction validation, settlement, and regulatory compliance.

> **[Payments (Boletos & Bill Payment)](/en/interfaces/payments-btg/boleto-and-bill-payment)**
>
> Issue boletos and pay bills (DARF taxes and utility invoices) through the Payments module in Lerian Console, recorded in your Midaz ledger.

## Why plugins are separate services

***

Lerian designed Midaz to be composable. This gives you:

* **Flexibility**: Add, update, or remove plugins without downtime
* **Separation of concerns**: Business-specific logic lives in the plugin, not the core
* **Better control**: Each plugin has its own versioning, deployment, and monitoring
* **Safe evolution**: The platform can grow without breaking your integrations

> [!TIP]
>
> Think of a plugin as a microservice with a clear purpose. It feels native to the platform, but it evolves on its own schedule.

## What a plugin can do

***

A plugin can:

* Expose new APIs
* Persist and transform data
* Run background jobs and scheduled tasks
* React to events, such as new transactions or ledger updates
* Define its own configuration, rules, and access policies

A plugin that follows the Midaz interface contract and authentication model integrates like a native feature.

## Building your own plugin

***

We provide deployment guides to help teams build plugins that are reliable, secure, and easy to maintain.

> [!NOTE]
>
> If you're interested in building or enabling a plugin, talk to a Lerian representative. We'll help you evaluate, license, and deploy the right setup for your use case.


# Our products
Source: https://docs.lerian.studio/en/products/about-products

Discover Lerian products, platform services, Brazil Rails, and Interfaces, and how modular building blocks compose into a complete core banking platform.

Lerian is a complete, modular core banking platform. Each product covers one financial domain end to end. You adopt one product on its own, or you combine several into one platform.

Lerian has six products: Midaz, Tracer, Matcher, Flowker, Lender, and Reporter. Lerian licenses every product to institutions.

## Products

***

> **[Midaz](/en/products/midaz/what-is-midaz)**
>
> Create ledgers, manage transactions, and use core entities like accounts and assets, with CRM and the Fees Engine built in as part of Midaz. Connect rails like Pix and TED.

> **[Tracer](/en/products/tracer/what-is-tracer)**
>
> Validate transactions in real time, apply rules and spending limits, and return ALLOW, DENY, or REVIEW decisions.

> **[Matcher](/en/products/matcher/what-is-matcher)**
>
> Validate external transactions against the ledger and surface mismatches. Built for accuracy, traceability, and automation.

> **[Flowker](/en/products/flowker/what-is-flowker)**
>
> Orchestrate transaction flows using validations, approvals, and external triggers with logic and plugin coordination.

> **[Lender](/en/products/lender/what-is-lender)**
>
> Run the credit journey end to end: loan products, origination, servicing, accounting, and Brazil-first regulatory support.

> **[Reporter](/en/products/reporter/what-is-reporter)**
>
> Generate and download reports from reusable templates, filter their data, and manage recurring reporting deadlines. Supports HTML, XML, CSV, PDF, and TXT output.

## Platform services

***

Console, Access Manager, Streaming Hub, Multi-tenancy, and Observability are platform services. They serve every product and are not products themselves.

> **[Console](/en/platform/console/about-lerian-console)**
>
> Operate every Lerian product from one web interface, with one login and one navigation.

> **[Access Manager](/en/platform/access-manager)**
>
> Control human and machine access across the products, and issue the tokens each service trusts.

> **[Streaming Hub](/en/platform/streaming-hub/what-is-streaming-hub)**
>
> Consume platform events and fan them out to your systems through signed webhooks, queues, or a pull API.

> **[Multi-tenancy](/en/platform/multi-tenancy)**
>
> Serve independent institution contexts from one deployment, and keep each request inside its own tenant.

> **[Observability](/en/platform/observability)**
>
> Collect metrics, traces, and logs from Lerian workloads through OpenTelemetry.

## Brazil Rails and Interfaces

***

A Brazil rail is Lerian-owned messaging software that connects your institution to BACEN or to a market infrastructure, with no intermediary. An interface is the product surface over a rail.

Pix Lerian is an application plugin that uses a connectivity adapter and Midaz. It is not the native Lerian SPI rail. Pix JD, Pix BTG, TED JD, and Payments BTG are partner interfaces that ship as separately deployed Midaz plugins. Pix Lerian v1.0.0 is available for integration and testing with the mock provider adapter.

> **[Brazil Rails](/en/rails/what-are-brazil-rails)**
>
> Read what each rail carries, and how Lerian native messaging reaches BACEN and the market infrastructures.

> **[Interfaces](/en/interfaces/introduction)**
>
> Read the API, the ledger integration, and the operational controls for each payment product.


# Building a complete core banking
Source: https://docs.lerian.studio/en/products/building-a-complete-core-banking

How the Lerian pieces come together into one working core banking: what connects to what, and how much you wire yourself versus what comes pre-configured.

In [Fundamentals](/en/start-here/fundamentals/core-banking/what-is-core-banking) you learned the concepts. This page is how the Lerian pieces come together into one working core banking.

A complete Lerian core banking combines Midaz with the products and interfaces you choose. You can adopt a product on its own. That is by design. Midaz embeds CRM and the Fees Engine. Other pieces deploy separately, and Lerian does not pre-wire them to each other. You connect them in a setup step.

How much of this you do depends on who runs your infrastructure:

* **Managed**: Lerian runs your infrastructure and wires the pieces at deploy time. You open the Console, enable the products, and use them. You set no environment variables and make no integration calls. (You won't need the rest of this page.)
* **Self-hosted / BYOC**: you run the infrastructure, so you do the wiring. Configure each product's URLs and environment, and deploy it. The rest of this page walks that. After you connect it, you can operate from the Console or call the APIs directly. That is a UX choice and needs no extra wiring.

**Enterprise** is a commercial tier, not a deployment model. Enterprise clients can be **managed or self-hosted**. See [Products, platform, and plans](/en/products/products-and-plugins) for what's included.

## Start with the ledger

***

Midaz is the ledger foundation of a Lerian core banking. Stand it up first when the capabilities you adopt record to Midaz.

**CRM is already part of Midaz.** Midaz includes the holders and aliases you learned about. You wire nothing extra. You just enable it.

→ [Set up Midaz](/en/products/midaz/midaz-setup) · [CRM in Midaz](/en/products/midaz/crm/crm-overview)

## Connect the pieces to the ledger

***

Most other pieces are standalone services. The Fees Engine is the exception, because it runs inside the ledger process. The pieces do not all connect the same way. Here is who calls whom at runtime:

![Runtime flow across your application, the payment plugins, the Fees Engine, Tracer, Reporter, and the Midaz ledger](https://mintcdn.com/lerian-49cb71fc/Gw2zNPznAbAjotN1/images/en/d2/flow-core-banking.svg?fit=max\&auto=format\&n=Gw2zNPznAbAjotN1\&q=85\&s=c72ab5a19b8cf1cc340e0f11599bd62b)

Who calls whom at runtime

* **Payment interfaces write to the ledger for you.** Your application calls a [payment interface](/en/interfaces/introduction) such as TED or Pix. The interface moves the money and records the operations in Midaz, even from its own background workers. Your application does not touch the ledger for those movements. Partner interfaces ship as Midaz plugins: separately deployed services that extend Midaz and that Lerian licenses separately. Lerian sets the connection to Midaz at deploy time, and your application never sees it. → [TED setup](/en/interfaces/ted-jd/ted-configuration)
* **The Fees Engine runs inside the ledger.** Lerian licenses the **Fees Engine** as part of the Midaz ledger process. When a configured fee package applies, Midaz adds the fee calculations to the transaction you submit. No separate fee service sits between your application and the ledger. Your application can still call the fees endpoints on the same process to estimate fees before it submits. For any movement you record without a payment interface, your application writes to the Midaz API directly. → [Connect the Fees Engine to Midaz](/en/products/midaz/fees/connecting-fees-to-midaz)
* **Reporter reads configured data sources.** It reads those sources in one direction only, to build statements and reports, and it never writes back. In a managed setup, Lerian configures the agreed data sources during onboarding. In self-hosted or BYOC deployments, configure a data source before you build reports that use it. → [Reporter](/en/products/reporter/reporter-quick-start)
* **Tracer connects to Midaz through configuration.** Without `TRACER_BASE_URL`, the integration stays off. Set that variable to the Tracer gRPC address, and Midaz initializes a reservation client. Midaz calls reserve, confirm, and release only when `tracer.mode` is `advisory` or `enforce`. Midaz honors a Tracer skip only when the request asks for it and the ledger enables `allowTracerSkip`. → [Tracer integration guide](/en/products/tracer/integration-guide)

Your application can also integrate with Tracer on its own.

> [!NOTE]
>
> Tracer checks your configured policies and limits, not account balances. The ledger stays the source of truth for what an account holds.

The exact URLs, credentials, and environment settings live in each product's own setup docs (linked above).

## One login across the pieces

***

The pieces share authentication through **Access Manager**, so they work as one product with one login. Access Manager issues the tokens each service trusts, and it holds the credentials each piece uses. Keep those details in one place, and point every piece at it.

→ [Access Manager](/en/platform/access-manager)

## Deploy the stack

***

There's no single "install everything" bundle. Deploy each selected component with its supported distribution artifact and bring them up in order:

**Midaz → Access Manager → products and interfaces → Console**

The Console comes last because it needs the others already running.

→ [Helm charts](https://github.com/LerianStudio/helm)

## Operate it from the Console

***

After everything runs, the **Console** is your single pane of glass. Enable the pieces and manage them with one login. When you enable a module in the Console, it turns on in the interface and shares the login. The piece-to-ledger wiring is the deployment step above, and the Console does not do it for you.

→ [Lerian Console](/en/platform/console/about-lerian-console)

## On a managed setup

***

If Lerian runs your infrastructure, Lerian already did all the wiring above. From your side, you enable the modules in the Console and start using them. You set no environment variables, and you run no deployment. The integration journey on this page is what Lerian handles underneath.

## Going further (optional)

***

You assemble a complete Lerian core banking from modular building blocks. Add **[Matcher](/en/products/matcher/what-is-matcher)** for reconciliation and **[Flowker](/en/products/flowker/what-is-flowker)** for workflow automation when their capabilities fit your operation. Matcher runs in the SaaS or the BYOC model, and you sign in through Access Manager. Flowker runs in the SaaS model only.


# About Midaz
Source: https://docs.lerian.studio/en/products/midaz/about-midaz

Explore Midaz's Ledger service, its Onboarding and Transaction domains, and its embedded CRM and Fees capabilities.

Midaz is a core ledger (The core financial book that records all transactions, balances, and operations for an organization. It is the single source of truth for a business unit's finances.). Financial institutions use it to build, operate, and scale their transactions on a modular foundation. You keep full control of your stack.

Midaz's Ledger service has two core domains: **Onboarding** and **Transaction**. It also embeds CRM for holders and instruments, and Fees. Together, they provide the components to configure, execute, and govern financial flows.

> [!NOTE]
>
> This domain-driven architecture keeps configuration (Onboarding) and execution (Transaction) separate but integrated.

## Domains and APIs

***

### Onboarding domain

In the **Onboarding Domain**, institutions structure their financial operations. They configure the essential entities of their ledger. This domain sets the rules, accounts, and relationships that govern how the ledger records and interprets transactions.

#### Components of the Onboarding Domain

* **Organizations**: A business entity that runs on Midaz, such as a bank, fintech, or subsidiary. Each organization holds its own ledgers and configurations. One platform then supports multi-entity operations.

* **Ledgers**: The core financial book of an organization. Ledgers (The core financial book that records all transactions, balances, and operations for an organization. It is the single source of truth for a business unit's finances.) track every balance, transaction, and operation. They protect the integrity of all financial data. Think of a ledger as the single source of truth for a business unit's finances.

* **Assets (A unit of value tracked in the ledger: traditional currencies (BRL, USD), digital currencies (BTC), or custom units like loyalty points. Every account is linked to exactly one asset.)**: The units of value that the ledger tracks, such as BRL, USD, BTC, or loyalty points. With this flexibility, institutions manage traditional currencies, digital assets, and custom reward programs in the same system.

* **Account Types (A classification defining the nature and purpose of an account, such as checking, savings, escrow, or settlement. Account types enable proper transaction routing.)**: Classifications that define the nature and purpose of accounts, for example checking, savings, escrow, or settlement. With `validateAccountType` enabled, a new non-external Account's `type` must match a registered value. Operation Routes separately validate accounts during route processing.

* **Accounts**: The fundamental units of value storage, where money or any asset lives. Each account always links to an Asset. You can group accounts into segments or portfolios to reflect your business structure.

* **Portfolios (A grouping of accounts belonging to the same account holder, business unit, or purpose. It ties together checking, savings, and investment accounts for a unified view.)**: A group of accounts that belong to the same customer, business unit, or purpose. For example, one client may hold checking, savings, and investment accounts in different currencies. A portfolio ties them together for a unified view.

* **Segments (A classification applied to accounts that share characteristics, like account holder tiers (VIP, Student) or regional divisions. Rules and pricing can differ by segment.)**: Groups of accounts that share traits, such as customer tiers or regional divisions, for example VIP or Student. Segments help you enforce different rules, prices, or benefits across your customer base.

> [!TIP]
>
> The Onboarding Domain configures how your financial world is structured. It gives consistency before any transaction takes place.

### Transaction Domain

After you configure the Onboarding Domain, the **Transaction Domain** takes over. It handles the real-time execution and movement of funds.

#### Components of the Transaction Domain

* **Balances**: The current balance of any account, including its available and on-hold amounts. This real-time snapshot supports validations, pre-transaction checks, and customer-facing displays.

* **Operation Routes (A reusable template that defines the rules for one leg of a financial transaction: which accounts participate, in what direction, and under what accounting annotation.)**: Reusable templates that define the rules for each leg of a financial transaction. A route specifies which accounts participate, in what direction (source, destination, or bidirectional), and under what accounting annotation. Every transaction type then follows consistent business rules.

* **Operations (The atomic unit of movement in the ledger: a single debit or credit. Every transaction is composed of one or more operations. Operations make transactions precisely traceable for compliance and reporting.)**: The atomic unit of movement in the ledger, a single debit or credit. The ledger breaks every financial movement into operations. This gives a complete audit trail (A chronological, immutable record of every action and transaction in the system, essential for regulatory compliance and dispute resolution.) and precise traceability for compliance and reporting.

* **Accounting Routes (A complete transaction blueprint composed of multiple Operation Routes. It defines all the debits and credits involved in a transaction type, so each transaction of that type complies with double-entry rules. Exposed as transactionRoute in the API.)**: Complete transaction blueprints that combine multiple Operation Routes. For example, a Pix Transfer route defines its source and destination rules. When you enable Accounting Route validation, Midaz validates the transaction route and its Operation Routes for that transaction type. The API exposes this as the `transactionRoute` resource.

* **Transactions**: The actual movement of value between accounts. A transaction can involve multiple **Operations**, such as fees, taxes, or splits. This supports complex financial flows, like marketplace payouts or multi-party settlements, in a single atomic event.

> [!TIP]
>
> The Transaction Domain processes every movement in compliance with the business and accounting rules you configure upstream.

## Domain reference

***

Midaz is a domain-driven ledger platform.

| Domain | Purpose | Key APIs |
| :- | :- | :- |
| **Onboarding** | Structure and configuration of the financial ecosystem. | Organizations, Ledgers, Assets, Account Types, Accounts, Portfolios, Segments |
| **Transaction** | Execution, movement, and accounting of financial operations. | Balances, Accounting Routes (`transactionRoute`), Transactions, Operation Routes, Operations |


# Account types
Source: https://docs.lerian.studio/en/products/midaz/account-types

Register Account Types to enforce classification per Ledger, validate the type field on account creation, and align account behavior with your accounting rules.

Account Types classify the accounts in your ledger. Each [**Account Type**](/en/reference/products/midaz/v2/create-account-type) has a name, a description, a unique key value, and a default [balance direction](/en/products/midaz/balance-overdraft).

You register the Account Types that match your accounting structure. When you enable Account Type validation, the ledger checks the `type` field of every new non-external Account against these registered types.

## How Account Type validation works

### Enabling Account Type validation

You enable Account Type validation per ledger through the [Ledger Settings API](/en/products/midaz/ledgers#ledger-settings). Send a `PATCH` request to the Ledger Settings endpoint:

```json PATCH /v2/organizations/{organization_id}/ledgers/{ledger_id}/settings theme={null}
{
  "accounting": {
    "validateAccountType": true
  }
}
```

### Behavior of the `type` field in Accounts API

When you create an Account, the `type` field behavior depends on the validation setting:

* **Validation disabled (default):** You must provide a `type`. It accepts any string value up to 256 characters. The ledger does not compare it to registered Account Types.
* **Validation enabled:** The `type` field must match the `keyValue` of a registered Account Type. Midaz stores new `keyValue` values in lowercase and compares the value case-insensitively. Use lowercase values in requests and configuration. If it does not match, the ledger rejects the account with a validation error. External accounts skip this check.

> [!TIP]
>
> Midaz checks the `type` only when you create an Account. You cannot change the `type` of an existing Account.

### The `keyValue` field

> [!NOTE]
>
> The `keyValue` field identifies an Account Type. It has these constraints:
>
> * **Immutable:** You set `keyValue` when you create the Account Type. You cannot change it afterward. The Update Account Type endpoint does not accept this field.
> * **Unique per ledger:** Each `keyValue` must be unique within a ledger.
> * **Used for validation:** When you enable `validateAccountType` in Ledger Settings, the ledger compares the `type` field of each non-external Account case-insensitively with a registered `keyValue`. The ledger rejects any non-external Account with an unregistered `type`.

## Managing Account Types

***

You manage Account Types through the API or the Lerian Console.

* [Create an Account Type](/en/reference/products/midaz/v2/create-account-type): Register a new Account Type for your Ledger.
* [List Account Types](/en/reference/products/midaz/v2/list-account-types): Retrieve all Account Types configured in your Ledger.
* [Retrieve an Account Type](/en/reference/products/midaz/v2/get-account-type-by-id): Get detailed information about a specific Account Type.
* [Update an Account Type](/en/reference/products/midaz/v2/update-account-type): Modify the definition of an existing Account Type.
* [Delete an Account Type](/en/reference/products/midaz/v2/delete-account-type): Remove an Account Type that is no longer in use.

> [!NOTE]
>
> **See also**
>
> * [Transaction Routing](/en/products/midaz/transaction-routing-entities): Operation Routes use `ruleType: account_type` to validate an account's `type` against the route's configured `account.validIf` values.
> * [Accounting Entries](/en/products/midaz/accounting-entries): How Midaz resolves debit and credit rubrics for the accounts these types classify.


# Accounting Entries
Source: https://docs.lerian.studio/en/products/midaz/accounting-entries

Map transaction actions and route directions to accounting classifications, and annotate every operation with its accounting code and description.

Accounting Entries (also known as **Rubricas**) map a transaction action and route direction to an accounting `code` and `description`. They annotate an operation after route resolution. Operation Route rules and transaction legs determine the participating accounts.

## What are Accounting Entries

***

A **rubric** maps a transaction action and route direction to an accounting classification. Instead of computing each classification by hand, you register rubrics once. Midaz then resolves them automatically as it processes transactions.

Each rubric carries:

* **`code`**: an accounting code (for example, `1.1.1.001`).
* **`description`**: a human-readable label for the entry (e.g., `Customer checking — outbound`).

When the engine processes a transaction with route validation (`accounting.validateRoutes`) enabled and a matching rubric registered, it resolves the rubric for each operation. It records the resulting **`routeCode`** and **`routeDescription`** on the operation. This gives you a complete audit trail from transaction to operation to rubric. Your teams can trace exactly which accounting rule applied to each movement.

> [!NOTE]
>
> Configure rubrics per action on each Operation Route. For `direct` and `commit` actions, **Source** routes require the **debit** rubric and **Destination** routes require the **credit** rubric. Dedicated `block` and `unblock` rubrics are optional. If they are absent, Midaz resolves the `direct` rubric for those actions. Source-side `hold` and `cancel` actions require **both** rubrics, and `overdraft` requires **both** on every supported route type. **Bidirectional** routes always require **both**.

## The 9 action types

***

Each action is a distinct transactional event. The first five actions cover the transaction lifecycle. The next three cover overdraft, block, and unblock movements. The last one covers transactions that span Ledgers. An Operation Route can map different debit and credit rubrics for each action. Every stage of an operation then receives the right accounting annotation.

The Hold and Cancel rows show a balance with `direction: credit`. On a `direction: debit` balance, a hold increases `available` and a cancel decreases it. `onHold` moves the same way on both.

| Action | Identifier | Description |
| :- | :- | :- |
| **Direct** | `direct` | Immediate, single-step debit/credit with no intermediate stages (e.g., a fee or adjustment). |
| **Hold** | `hold` | Reserves funds by creating a pending movement (moves value from `available` to `onHold` on the source account). |
| **Commit** | `commit` | Confirms a previously held amount, releasing the `onHold` value to the destination account. |
| **Cancel** | `cancel` | Cancels/reverses a hold, returning the `onHold` value to the `available` balance on the source account. |
| **Revert** | `revert` | Reverses an `APPROVED` transaction by creating a counter-transaction that undoes the original. |
| **Overdraft** | `overdraft` | Classifies overdraft movements. The **debit** rubric marks overdraft usage (the deficit grows) and the **credit** rubric marks repayment (the deficit shrinks). Both rubrics are required when this entry is configured. |
| **Block** | `block` | Optionally classifies a fund-block movement that freezes value on an account (for example, an `asset-freeze`). |
| **Unblock** | `unblock` | Optionally classifies the release of previously blocked funds back to the `available` balance. |
| **Cross-ledger** | `crossLedger` | Classifies the External Account legs that Midaz adds when a transaction spans Ledgers. The **debit** rubric marks value that arrives from another Ledger. The **credit** rubric marks value that leaves to another Ledger. Both rubrics are required. |

**Overdraft** classifies companion operations that the engine generates automatically during overdraft usage and repayment. For every supported route type and direction, configure both the debit and credit rubrics. **Block** and **unblock** can use dedicated rubrics for operations that the block and unblock transaction endpoints produce. Without those rubrics, those actions use the `direct` rubric. When needed, register dedicated rubrics for these actions in the same way as for the other actions.

> [!TIP]
>
> Each action can point to different debit and credit rubrics on the same Operation Route. Map only the actions a route uses. If you enable strict validation (below), cover every action your transactions emit.

## Configuring Accounting Entries

***

You register rubrics through the API as part of your Operation Routes. The `accountingEntries` block on a route defines one entry per action. Each entry carries its `debit` and/or `credit` rubric:

```json accountingEntries theme={null}
{
    "accountingEntries": {
        "direct": {
            "debit": {
                "code": "1.1.1.001",
                "description": "Customer checking — outbound"
            },
            "credit": {
                "code": "1.1.1.002",
                "description": "Customer checking — inbound"
            }
        }
    }
}
```

You manage these entries through the Operation Route endpoints. See [Create an Operation Route](/en/reference/products/midaz/v2/create-operation-route) and [Update an Operation Route](/en/reference/products/midaz/v2/update-operation-route). For the full configuration flow, refer to [Transaction Routing](/en/products/midaz/transaction-routing-entities#4-configure-accounting-entries-actions).

## Validation modes

***

Midaz reacts to a missing rubric based on the Ledger's accounting settings. Two distinct gates control this behavior:

### Default (graceful)

By default (`accounting.validateRoutes` disabled), Midaz does not resolve rubrics at all: the transaction proceeds normally and the `routeCode` and `routeDescription` fields stay empty (nil) for every operation. It raises no error.

### Strict (opt-in)

Set `accounting.validateRoutes` to `true` in the [Ledger Settings](/en/products/midaz/ledgers#ledger-settings) to enforce route validation. In strict mode, Midaz returns `0157` when no Operation Route of the Transaction Route has an entry for the requested action. It returns `0117` when a leg names no Operation Route, or one that the Transaction Route does not provide for that action. An overdraft movement on a route without an `overdraft` entry returns `0492`.

```json PATCH /v2/organizations/{organization_id}/ledgers/{ledger_id}/settings theme={null}
{
  "accounting": {
    "validateRoutes": true
  }
}
```

> [!TIP]
>
> Use **strict mode** in production ledgers where every transaction type needs an accounting classification. The graceful default helps while you onboard routes. In production, it can silently leave movements without a classification.

When Midaz finds a matching rubric, it annotates the operation with two fields:

* **routeCode**: the `code` of the resolved `AccountingRubric` for that action and direction.
* **routeDescription**: the description of the resolved rubric, populated alongside `routeCode`.


# Accounting
Source: https://docs.lerian.studio/en/products/midaz/accounting-in-midaz

Get an overview of accounting in Midaz: Chart of Accounts, Account Types, Accounting Entries, and Operations that keep every posting balanced and traceable.

Midaz records accounting for real-time financial systems. It supports route-driven double-entry flows for direct transactions, as well as lifecycle actions such as cancellation. Cancellation operates on the source side only. Route validation is disabled by default. Enable it to validate the configured account and accounting-entry rules. Midaz supports digital products, embedded finance, and high-volume operations.

This page is the entry point for the Accounting section. It introduces the core primitives and shows how they fit together. It also points you to the reference pages and to a hands-on walkthrough of accounting end to end.

## How the primitives relate

***

Midaz turns business events into balanced ledger postings. A small set of primitives builds on each other:

#### Chart of Accounts

This is the structure of balances your product needs. Midaz has no dedicated Chart of Accounts API. Instead, you model it on a ledger from assets, accounts, segments, portfolios, and account types. The `code` field on an Accounting Entry (for example `1.1.1.001`) carries the traditional account number for each posting.

#### Account Types

These are reusable classifications that you assign to accounts. Each account type has a name, a key value, a description, and a default [balance direction](/en/products/midaz/balance-overdraft). You use account types to group accounts in your financial structure.

#### Accounting Entries (Rubricas)

A route does not need an entry for every transaction action. When it emits an action, the entry must satisfy the route-specific debit and credit requirements. Each configured entry contains the debit and/or credit rubric required by its operation route. Every present rubric has a `code` and description. With route validation (`accounting.validateRoutes`) enabled, Midaz stamps the matching rubric onto each operation, based on the operation's action and direction.

#### Operations

A transaction produces ledger movements. An **Operation** is a single leg of a transaction, one debit or one credit on a specific account. Midaz validates that the original transaction’s source, destination, and send totals agree. Its returned operation set is not always a debit/credit pair: pending creation and cancellation process only source-side legs. Each operation carries a `transactionId`, an `amount`, and an `assetCode`. When route validation (`accounting.validateRoutes`) is enabled on the ledger and the operation route defines accounting entries, the operation also carries a `routeCode` and a `routeDescription` from the resolved rubric.

> [!NOTE]
>
> With `accounting.validateRoutes` enabled, when an operation route defines an accounting entry, Midaz resolves a rubric for the operation's action and direction. It writes the rubric `code` to the operation's `routeCode` and links the operation with a `transactionId`. Together, these fields give a complete audit trail: transaction → operation → rubric. Your teams trace which accounting rule applied to each movement, without extra lookups.

At a glance, the flow is:

![Diagram showing the Accounting primitives workflow](https://mintcdn.com/lerian-49cb71fc/SFzzdxyH5SN7w_fC/images/en/d2/accounting-primitives.svg?fit=max\&auto=format\&n=SFzzdxyH5SN7w_fC\&q=85\&s=ae5fe0b8b7b390d8c8be5c76f53fe479)

Accounting primitives workflow

> [!TIP]
>
> If you are new to Midaz accounting, start with the **[Accounting Walkthrough](/en/products/midaz/accounting-walkthrough)**. It gives a step-by-step path from the chart of accounts to a working Pix payment example.


# Accounting walkthrough
Source: https://docs.lerian.studio/en/products/midaz/accounting-walkthrough

An end-to-end, hands-on guide to designing and implementing accounting in Midaz, from chart of accounts to a working Pix payment example.

This guide shows you how to implement accounting in Midaz from start to finish. It assumes you are a developer. You want only enough accounting context to model a real product. By the end, you understand how the primitives fit together. You can also wire up a complete Pix payment with correct double-entry postings.

For the conceptual overview and links to each reference page, see **[Accounting](/en/products/midaz/accounting-in-midaz)**.

## 1. Double-entry accounting fundamentals

***

Midaz supports double-entry bookkeeping through its transaction routes. Configure a route with source and destination Operation Routes, or a Bidirectional Operation Route that covers both sides. With **Validate Routes** enabled, Midaz validates each transaction against the configured route rules.

Route validation is disabled by default. Enable it only after you configure the routes your Ledger needs. Lifecycle actions do not all use both sides: cancellation is source-only and releases held funds on the source Account.

> [!NOTE]
>
> Think about *where value comes from* (the debit side / source) and *where it goes* (the credit side / destination). Every Midaz operation lands on one side of that equation.

## 2. Chart of Accounts in Midaz

***

In traditional accounting, the Chart of Accounts (CoA) defines account categories (Assets, Liabilities, Equity, Income, Expenses), their hierarchy, and how to classify movements.

> [!NOTE]
>
> Midaz does not have a dedicated Chart of Accounts API. The CoA is the result of how you combine assets, accounts, segments, portfolios, and account types. The `code` field on Accounting Entries (e.g. `1.1.1.001`) is where traditional account numbering appears in practice. Each `code` annotates a posting with its classification.

Midaz lets you mirror or adapt a CoA digitally using a small set of primitives:

* **Assets** define *what* moves: currencies (BRL, USD), points/miles, crypto tokens, or internal units of value.
* **Accounts** are balance containers. Each has an asset code and type. It can also belong to a portfolio and segment. An **alias** (e.g. `@external/BRL`) identifies each account and keeps routing intuitive.
* **Segments** categorize and isolate accounts (customer vs. internal funds, business units, multi-tenant separation).
* **Portfolios** group accounts that share a purpose or belong to the same entity.

To map a CoA in Midaz, you decide which balances you need and classify them with Account Types. You then organize them with segments and portfolios on a ledger, and assign `code` values on your Accounting Entries to match your numbering scheme.

### A recommended process

**1. Map your financial model**

List the balances you need: customer balances, internal accounts, reserve/settlement accounts, fee and revenue accounts. This is your CoA blueprint.

**2. Define account types**

Create an Account Type per conceptual category, e.g. `CASH`, `SETTLEMENT`, `FEE_REVENUE`, `FEE_EXPENSE`, `TREASURY`.

**3. Create segments and portfolios**

Segments separate business domains (`CUSTOMER_FUNDS`). Portfolios manage ownership and grouping (`customer_12345_wallet`).

**4. Create accounts**

For each logical balance, create a ledger account (customer BRL account, treasury account, provider fee expense account, merchant settlement account).

## 3. Setting up Account Types

***

Account Types classify accounts by nature and purpose. With `validateAccountType` enabled, a new non-external Account's `type` must match a registered `keyValue`. An Operation Route can separately use `ruleType: account_type` to validate an account during route processing. Account Types do not themselves define permitted operations, internal or external status, or reconciliation rules.

A typical setup for a payments product:

* **CASH** → liquid customer funds
* **SETTLEMENT** → funds awaiting clearing
* **FEE\_REVENUE** → fees collected
* **FEE\_EXPENSE** → provider fees
* **TREASURY** → internal operations

To enable Account Type validation, understand the `type` field, and manage Account Types via the API, see **[Account Types](/en/products/midaz/account-types)**.

### Understanding balance buckets

Before you wire up two-phase flows, understand that each balance tracks funds in distinct fields:

* **`available`**: funds you can spend or send right now. Debits and credits to a balance move this number.
* **`onHold`**: funds that a pending `hold` reserves and does not yet commit. They still belong to the account until you commit or cancel the hold.
* **`overdraftUsed`**: overdraft consumed by the balance, when overdraft is enabled.

The three fields carry decimal strings with exact precision (for example, `"12.50"`). There is no separate `scale` field to interpret. See [Transaction amount](/en/products/midaz/amount) for the decimal value model.

The two-phase actions change `available` and `onHold` on the source balance. These rows show a balance with `direction: credit`. On a `direction: debit` balance, a hold increases `available` and a cancel decreases it. `onHold` moves the same way on both.

| Action | `available` | `onHold` |
| - | - | - |
| **Direct** | Debited (source) / credited (destination) | unchanged |
| **Hold** | ↓ decreased on source | ↑ increased on source |
| **Commit** | credited on destination | ↓ released from source |
| **Cancel** | ↑ returned to source | ↓ released back to `available` |
| **Revert** | restored on both sides via a counter-transaction | unchanged |

For the full balance model (multiple balances per account, permission flags, overdraft, and history), see **[Balances](/en/products/midaz/balances)**.

## 4. Defining Accounting Entries (Rubricas)

***

**Accounting Entries** (Rubricas) map a transaction action and route direction to an accounting `code` and `description`. You register rubrics once instead of computing accounting classifications by hand for each movement. When `accounting.validateRoutes` is enabled on the ledger and a matching rubric is configured, Midaz annotates each operation with the resulting `routeCode` and `routeDescription`. Operation Route rules and transaction legs determine the participating accounts.

You configure rubrics **per action** on each Operation Route, inside the `accountingEntries` block. For `direct` and `commit` actions, source routes require the **debit** rubric and destination routes require the **credit** rubric. Dedicated `block` and `unblock` rubrics are optional. When you do not configure them, Midaz resolves the `direct` rubric for those actions. Source-side `hold` and `cancel` actions require **both** rubrics, `overdraft` requires **both** on every supported route type, and bidirectional routes always require **both**.

### The five transaction-lifecycle actions

| Action | Code | What it does |
| - | - | - |
| **Direct** | `direct` | Immediate, single-step posting with no intermediate stages (e.g. a fee or adjustment). |
| **Hold** | `hold` | Reserves funds by creating a pending movement (`available` → `onHold` on the source). |
| **Commit** | `commit` | Confirms a previously held amount, releasing `onHold` to the destination. |
| **Cancel** | `cancel` | Cancels a hold, returning `onHold` value to `available` on the source. |
| **Revert** | `revert` | Reverses an `APPROVED` transaction via a counter-transaction when its Operation Routes are bidirectional. |

Each action can point to different debit/credit rubrics on the same Operation Route. Every stage of an operation then receives the right accounting annotation. You register these mappings through the Operation Route endpoints. See [Create an Operation Route](/en/reference/products/midaz/v2/create-operation-route).

```json theme={null}
{
  "accountingEntries": {
    "direct": {
      "debit":  { "code": "1.1.1.001", "description": "Customer cash-out" },
      "credit": { "code": "2.1.1.001", "description": "External settlement" }
    }
  }
}
```

For the full model, see **[Accounting Entries (Rubricas)](/en/products/midaz/accounting-entries)**.

## 5. Transaction routing

***

Routing is a two-layer system that resolves at runtime:

* **Operation Routes** define the rules for each leg of a transaction: its side (source, destination, or both) and an optional account rule. They carry the **Accounting Entries (rubricas)** above.
* **Transaction Routes** define the business event that triggers accounting (`PIX_CASH_OUT`, `WALLET_TRANSFER`, `BANK_SLIP_SETTLEMENT`, …) and combine Operation Routes into a balanced financial event.

When you submit a transaction, you name its Transaction Route. With route validation enabled, Midaz checks each leg against its Operation Route and resolves the rubric for the current action.

For route structure, fields, the operation-type validation matrix, and API behavior, see **[Transaction Routing](/en/products/midaz/transaction-routing-entities)**.

## 6. End-to-end example: a Pix payment

***

This example is a simple Pix cash-out. A customer sends BRL out of their wallet to an external account.

**1. Account setup**

Create the customer account on your ledger. Midaz creates `@external/BRL` automatically together with the `BRL` Asset. Do not create it yourself.

* `customer_12345_brl`: Account Type `CASH`, asset `BRL`
* `@external/BRL`: the automatically created external settlement account for funds leaving the ledger

**2. Enable route validation and register rubrics**

Enable `accounting.validateRoutes` on the ledger. Then, on the Operation Route for the customer leg (source), register the `direct` debit rubric. On the external leg (destination), register the `direct` credit rubric:

```json theme={null}
{
  "accountingEntries": {
    "direct": {
      "debit":  { "code": "1.1.1.001", "description": "Pix cash-out — customer" },
      "credit": { "code": "2.1.1.001", "description": "Pix cash-out — external settlement" }
    }
  }
}
```

This block is a combined illustration of both rubrics. Register only the `debit` field on the Source route and only the `credit` field on the Destination route.

**3. Transaction**

Submit a transaction against the `PIX_CASH_OUT` Transaction Route. Move, say, `100.00 BRL` from `customer_12345_brl` to `@external/BRL`.

**4. Resulting operations**

Midaz records two balanced operations:

* **Debit** `customer_12345_brl` `100.00 BRL`, `routeCode: 1.1.1.001`
* **Credit** `@external/BRL` `100.00 BRL`, `routeCode: 2.1.1.001`

Both share the same `transactionId`. This gives you a full trail from transaction → operation → rubric.

For a two-phase flow (hold → commit/cancel), register the `hold`, `commit`, and `cancel` rubrics on the source route and the `commit` rubric on the destination route. Submit the corresponding actions. Each stage resolves its own rubric.

## 7. Validation modes

***

Midaz controls route validation with the `accounting.validateRoutes` setting on each ledger. The default is `false`. In this graceful mode, Midaz skips route validation. It leaves the `routeCode` and `routeDescription` fields empty on every operation and raises no error. Graceful mode is convenient while you onboard routes.

In production, set `accounting.validateRoutes` to `true` in the [Ledger Settings](/en/products/midaz/ledgers#ledger-settings). Strict mode then validates the routes on every transaction:

```json theme={null}
{
  "accounting": {
    "validateRoutes": true
  }
}
```

In strict mode, Midaz returns `0157` when no Operation Route of the Transaction Route has an entry for the requested action. It returns `0117` when a leg names no Operation Route, or one that the Transaction Route does not provide for that action. When a route resolves, Midaz stamps `routeCode` and `routeDescription` from its rubric.

> [!TIP]
>
> Use **strict mode** (`validateRoutes: true`) in production ledgers where every transaction type needs an accounting classification. Keep the graceful default only while you onboard routes.

## Next steps

***

* Review the **[Accounting](/en/products/midaz/accounting-in-midaz)** overview and reference pages for full field-level detail.
* Once your ledger produces structured postings, see **[Lerian Reporter](/en/products/reporter/what-is-reporter)** to transform ledger events into reconciliation files, financial statements, and COSIF-aligned regulatory outputs.


# Accounts
Source: https://docs.lerian.studio/en/products/midaz/accounts

Use Accounts as the core financial unit of a Midaz Ledger, tied to a single Asset and recording every debit, credit, and balance for a customer or product.

An Account is the core financial unit of a Midaz Ledger. Each Account links to one Asset and records every debit, credit, and balance for that Asset. In banking terms, an Account is a financial product, such as a checking account, a savings account, or a loan account.

> [!TIP]
>
> Midaz does not limit how many accounts you create. Create as many as your structure needs.

## Account structure

***

* **Account > Ledger**: You create an Account within a Ledger. The Ledger tracks and consolidates all balances and operations.
* **Account > Portfolio**: You can group Accounts into [**Portfolios**](/en/products/midaz/portfolios) to represent customer clusters, product lines, or business units.
* **Account > Asset**: Each Account links to a **single Asset**. The Asset defines the type of value the Account holds, such as BRL, USD, BTC, or loyalty points.
* **Account > Account Type**: When you enable Account Type validation, each non-external Account must use a registered Account Type. You register Account Types for your business classification.

## Key characteristics

***

* Each Account links to exactly one Asset.
* Each Account has a unique identifier within a Ledger.

## Multiple accounts per customer

***

A single customer often holds more than one balance.

The same customer might hold balances that behave differently:

* **Different nature**: a main balance, a benefit balance, or a promotional balance.
* **Different operational rules**: a court-ordered account that accepts inflows but restricts outflows.
* **Separate statement and reconciliation**: a product sub-account or pocket that you track on its own.

When the balance, ledger, statement, or rule differs, each one becomes its own Account. You classify it by an [Account Type](/en/products/midaz/account-types), group it under the customer with a [Portfolio](/en/products/midaz/portfolios), and tie it to identity through [CRM](/en/products/midaz/crm/crm-overview). One account with labels works until the balances diverge. Separate accounts keep each balance accurate from the start.

> [!TIP]
>
> For the full reference architecture (one customer, many accounts, with step-by-step examples), see [Midaz for multi-account customers](/en/products/midaz/midaz-for-multi-account-customers).

## External Account

***

External Accounts in Midaz represent accounts outside your organization's structure. They track money that enters or leaves your ledger, usually to and from users, partners, or financial providers.

External accounts have these characteristics:

* **Hold the counterparty balance** for money that enters or leaves your ledger.
* **The Ledger creates a canonical external Account automatically** when you create an Asset.
* **The canonical external Account follows a clear naming pattern**: `@external/<asset-code>`, such as `@external/BRL`.

These accounts record inflows and outflows at the ledger boundary.

> [!CAUTION]
>
> **Do not try to delete or change an external account.** Midaz blocks these operations to keep the Ledger accurate and traceable.

### External account codes

The canonical external Account created with an Asset follows the naming pattern `@external/<asset-code>`. The asset code in that alias is the lookup key. You can retrieve this canonical Account and its balances with convenience endpoints that accept only the asset code:

* `GET .../accounts/external/{code}`: Retrieve the external account for an asset code (for example, `BRL` resolves to `@external/BRL`).
* `GET .../accounts/external/{code}/balances`: Retrieve the balances for that external account.

These endpoints are shortcuts for the canonical external Account. They prepend `@external/` to the code you provide, then perform an alias-based lookup. The result is identical to a query by that full alias.

### Entity ID (external system reference)

The `entityId` field exists on any account, not only external accounts. It links the account to a record in an external system, such as a core banking platform, a CRM, or a partner system.

* **Not the same as alias**: You use the alias in transactions, and it must be unique within a ledger. The `entityId` is only a reference for your integration, and Midaz does not use it to move value.
* **Optional**: Set it when you create the account or when you update it. The maximum length is 256 characters.
* **Use case**: When your system already has an account identifier, such as `EXT-ACC-12345`, store it in `entityId`. You can then map between Midaz and your source of truth.

```json JSON theme={null}
{
  "name": "User Checking Account",
  "assetCode": "BRL",
  "alias": "@user_checking_123",
  "entityId": "EXT-ACC-12345",
  "type": "checking"
}
```

## Parent Account ID

***

The **Parent Account ID** links two accounts within Midaz. You define the relationship based on your business logic. The parent Account must be in the same Ledger and use the same Asset.

You can use it for a traditional parent-child structure or for another relationship that your business needs.

## Blocked accounts

***

Set `blocked` to `true` when you create or update an Account. Midaz then refuses every transaction that moves the Account, as source or destination. The block does not stop the cancellation of a pending transaction.

To allow one debit of an exact amount out of a blocked Account, [create a single-use block exception](/en/reference/products/midaz/v2/create-account-block-exceptions). Then send its ID in the `accountBlockExceptionId` field of the transaction.

## Account aliases

***

An alias replaces a complex account ID with a readable label. This makes accounts easier to identify.

* **For example**: Instead of the ID `3172933b-50d2-4b17-96aa-9b378d6a6eac`, you can use `@username_1`.

### Use the Account Alias in Transactions

When you create a transaction, identify each Account by its **account alias**. Do not use the account ID.

An alias is **optional** when you create a non-external Account. If you skip it, Midaz uses the account ID as the alias. A user-created external Account requires an alias. The alias you set can have up to 100 characters from `a-z`, `A-Z`, `0-9`, `@`, `:`, `_`, and `-`.

## Managing Accounts

***

You can manage your Accounts through the API or the Lerian Console.

### Via API

* [Create an Account](/en/reference/products/midaz/v2/create-account): Open a new Account linked to an Asset.
* [Open a holder-owned Account](/en/reference/products/midaz/v2/create-holder-account): Open an Account that a Holder owns, and optionally its Instrument, in one call.
* [List Accounts](/en/reference/products/midaz/v2/list-accounts): View all Accounts in a Ledger.
* [Retrieve an Account](/en/reference/products/midaz/v2/get-account-by-id): Get details of a specific Account.
* [Retrieve an Account by Alias](/en/reference/products/midaz/v2/get-account-by-alias): Get details of a specific Account by its alias.
* [Retrieve an External Account](/en/reference/products/midaz/v2/get-account-external-by-code): Get details of a specific External Account by its asset code.
* [Update an Account](/en/reference/products/midaz/v2/update-account): Edit the metadata or settings of an existing Account.
* [Delete an Account](/en/reference/products/midaz/v2/delete-account): Delete a specific Account.
* [Close an Account](/en/reference/products/midaz/v2/close-account): Close an Account whose balances are all exactly zero. Midaz keeps its history and refuses any later movement.

> [!WARNING]
>
> **Transfer any remaining balance to another account before you delete an account.** Midaz does not delete an account or sub-account that still holds a balance. Midaz also refuses to delete or close an account with a balance that owes [fee debt](/en/products/midaz/fees/fee-debt) (`0527`) or that other balances owe fee debt to (`0528`).

### Via Lerian Console

You can view, create, edit, and delete Accounts on the Accounts page. This page is in the Midaz module of the Lerian Console.

[**Learn more in the Managing Accounts guide.**](/en/products/midaz/console/managing-accounts)


# Accounts
Source: https://docs.lerian.studio/en/products/midaz/accounts-overview

Learn how to create, group, and classify Midaz Accounts using Portfolios and Segments to match your customers, product lines, and business unit structure.

Accounts are the core financial units in Midaz. This section covers how to create, organize, and classify Accounts. You group them to match your business structure, from individual balances to customer-level groupings.

## Content

***

Here, you'll find:

* [**Accounts**](/en/products/midaz/accounts): The core financial unit in a Ledger. Each Account uses one Asset and records its debits, credits, and balances. Midaz also supports External Accounts to track value that moves in or out of your organization.

* [**Portfolios**](/en/products/midaz/portfolios): Groups of Accounts that belong to one entity, such as a customer or business unit. A Portfolio works like a wallet that holds that entity's Accounts across different Assets.

* [**Segments**](/en/products/midaz/segments): A classification for Accounts that share characteristics. You group Accounts into Segments to organize them by tier or type, such as premium card tiers or student accounts.


# Transaction amount
Source: https://docs.lerian.studio/en/products/midaz/amount

Use the transaction field that belongs to the endpoint version. Midaz does not use one global amount field across every transaction API.

Amount fields apply to transaction-creation bodies, not every transaction endpoint. The v1 creation payloads use decimal `value`. The API accepts a JSON number or string. A string avoids client-side IEEE-754 rounding. The v2 `direct`, `hold`, `block`, `unblock`, and `batch` creation endpoints require string `amount`. Commit, cancel, and revert identify an existing transaction by its ID and take no amount.

> [!WARNING]
>
> Do not combine field conventions from different transaction versions. Use the API reference for the specific operation you call.


# Architecture
Source: https://docs.lerian.studio/en/products/midaz/architecture

Explore Midaz's modular architecture, centered on the Ledger service and its supporting infrastructure.

> [!NOTE]
>
> Midaz runs the modular Ledger service and a separate Tracer service. Deploy and scale each service and its supporting infrastructure for your environment. For a business-oriented overview, see [About Midaz](/en/products/midaz/about-midaz).

Midaz can run in public or private cloud environments. Select and operate the infrastructure that fits your deployment requirements.

Midaz uses a modular architecture. Ledger is organized around domain boundaries, with supporting infrastructure for storage, caching, messaging, and streaming. Tracer runs as a separate service.

## Repository and deployment boundary

Midaz ships two runtimes in one repository and release: the Ledger modular monolith (with CRM and Fees) and Tracer. Tracer is not embedded in the Ledger process: deploy and scale it separately.

Ledger HTTP v2 can opt into the one-way reservation seam to Tracer. Ledger HTTP v1 never calls it. Tracer's public HTTP surface remains `/v1`, so the seam does not create a public Tracer v2 API. Tracer never calls Ledger.

## Modular architecture

***

The diagram below (*Figure 1*) shows how the pieces fit together.

![Layered diagram of Midaz: the cluster layer that you manage, the front-end layer with Lerian Console, the back-end layer with the Ledger (with CRM and Fees) and Tracer as a separate runtime, the data layer with PostgreSQL, MongoDB, Valkey, and RabbitMQ, and the Helm chart layer.](https://mintcdn.com/lerian-49cb71fc/Wqp8NG2BwBLM-rZd/images/en/d2/midaz-macro-architecture.svg?fit=max\&auto=format\&n=Wqp8NG2BwBLM-rZd\&q=85\&s=f9045b806d418acce709ff232958ea58)

Figure 1. Midaz macro-architecture

### 1. Cluster layer (managed by you)

You manage this layer. It provides the Kubernetes foundation that runs Midaz. Enable these services:

* **Service**: Networking abstraction to expose and route services.
* **AutoScaler**: Automatically adjusts the number of pods.
* **HPA (Horizontal Pod Autoscaler)**: Scales applications based on metrics.
* **Secrets**: Secure management of sensitive data.
* **ConfigMap**: Externalized configuration management.

This layer governs and coordinates all components within the cluster.

### 2. Front-end layer

The front-end layer provides the user interface for system interaction (admin panel, dashboards, and more).

> [!NOTE]
>
> Newer releases of Midaz no longer include a bundled console in the repository. [Lerian Console](/en/platform/console/about-lerian-console) now provides the visual interface. The Lerian Console includes Midaz as one product module.
>
> If you use an older version of Midaz, you may still have the standalone Midaz Console. Midaz v3.5.0 and later releases do not include it. Migrate to Lerian Console for the latest features and improvements.

### 3. Back-end layer

The Ledger back-end is a modular monolith that holds the core responsibilities of the Midaz ledger. Midaz also runs Tracer as a separate service.

Ledger brings together four core components:

* **Onboarding domain**: manages organizations, ledgers, assets, portfolios, segments, and accounts.
* **Transactions domain**: handles financial transactions, operations, and asset movements.
* **CRM**: is embedded in the Ledger process.
* **Fees**: is embedded in the Ledger process.

This approach keeps clear domain boundaries. It also simplifies deployment and lowers operational complexity.

### 4. Data layer

This layer holds the databases and infrastructure components that support application data and event flows:

* **PostgreSQL**: separate `onboarding` and `transaction` databases, each with a primary connection and an optional replica connection.
* **Valkey**: A Redis-compatible key-value store. The ledger validates and updates live balances in it, then syncs them to PostgreSQL. It also caches data.
* **MongoDB**: Stores semi-structured data: entity metadata, CRM holders and instruments, and fee and billing packages.
* **RabbitMQ**: Message broker for asynchronous transaction processing and event exchanges of the ledger.
* **Redpanda**: Kafka-compatible broker for Ledger event streams. Ledger publishes configured events to it only when you set `STREAMING_ENABLED=true` and configure streaming brokers.

Persistence is deployment-specific. The bundled Compose configuration does not mount a data volume for Redpanda. Configure production storage and retention for each service.

### 5. Helm Chart layer

Midaz uses Helm Charts to deploy and configure the infrastructure.

The chart connects the code to Kubernetes. It deploys each component the same way across environments.

> [!TIP]
>
> For more details, see the [Deploying using Helm](https://github.com/LerianStudio/helm/tree/main/charts/midaz) page.

## How the layers work together

***

Each layer has a focused role.

* Kubernetes coordinates how the layers communicate.
* Helm keeps deployments and configurations in sync.

You can add new components as needed without disruption to what already runs.


# Assets
Source: https://docs.lerian.studio/en/products/midaz/assets

Define the currencies, cryptocurrencies, and tokenized instruments your Accounts hold, with multi-asset support across a single Ledger.

Assets represent the financial instruments or currencies that Accounts hold. Each Account holds exactly one Asset.

Assets can include:

* Currencies (e.g., BRL, USD, EUR)
* Cryptocurrencies (e.g., BTC, ETH)
* Non-currency assets (e.g., gold, loyalty points, tokenized securities)

Midaz keeps each Asset independent within the Ledger. Balances stay clearly defined.

### Multi-Asset

Midaz supports traditional currencies, cryptocurrencies, commodities, and tokenized assets in one system. Use it for multi-currency wallets, cross-border payments, or digital asset portfolios.

## Asset structure

***

* **Asset > Account**: Each Account holds a single Asset.
* **Asset > Ledger > Account**: You define Assets at the Ledger level. You create Accounts from the available Assets.

## Key characteristics

***

* You must define each Asset before you use it.
* Each Asset has a unique identifier, such as a currency code.
* Midaz stores asset rates, but the Ledger transaction flow does not use them to convert values. The source and destination assets of a transaction must match.

> [!NOTE]
>
> When you create an Asset, Midaz automatically creates an [External Account](/en/products/midaz/accounts) if one does not exist. The External Account backs every transaction that enters or leaves the Ledger.
>
> The External Account uses the naming convention `@external/<asset-code>`, for example, `@external/BRL`.

## Managing Assets

***

You can manage Assets through the API or the Lerian Console.

### Via API

* [List Assets](/en/reference/products/midaz/v2/list-assets): View all Assets in a Ledger.
* [Retrieve an Asset](/en/reference/products/midaz/v2/get-asset-by-id): Get details of a specific Asset.
* [Create an Asset](/en/reference/products/midaz/v2/create-asset): Register a new Asset in the Ledger.
* [Update an Asset](/en/reference/products/midaz/v2/update-asset): Edit the properties of an existing Asset.
* [Delete an Asset](/en/reference/products/midaz/v2/delete-asset): Mark an Asset as deleted.

> [!CAUTION]
>
> Deleting an Asset marks its External Account as deleted. It does not move or clear any balance. Settle the balances in that Asset before you delete it.

### Via Lerian Console

You can view, create, edit, and delete Assets on the Assets page in the Midaz module of the Lerian Console.

[**Learn more in the Managing Assets guide.**](/en/products/midaz/console/managing-assets)


# Async transaction processing
Source: https://docs.lerian.studio/en/products/midaz/async-transaction-processing

Async transaction processing validates the call fast, then persists the write through RabbitMQ, for lower API latency and higher throughput.

## When synchronous writes become the bottleneck

***

A client sends a transaction. Midaz must do two things: validate it and persist the result. In synchronous mode, both steps run in the same request.

This model is simple and predictable, but it has a ceiling. At high volume, database writes become the bottleneck. Each transaction holds a connection, waits for locks, and competes for I/O.

Async mode breaks that dependency. Midaz validates the transaction, returns the response at once, and persists the data in the background through RabbitMQ. The client gets faster responses.

For broader scaling guidance, see [Scalability strategies](/en/products/midaz/scalability-strategies).

## How it works

***

### Synchronous mode (default)

![Sequence diagram showing the client sending a POST /transaction to the Midaz API, which validates it, writes the transaction and operations to PostgreSQL, and returns 201 Created to the client.](https://mintcdn.com/lerian-49cb71fc/eJbUTctk-eLsW0J5/images/en/d2/sync-transaction-flow.svg?fit=max\&auto=format\&n=eJbUTctk-eLsW0J5\&q=85\&s=80107b258808f015d108c00ffdd6a92f)

Figure 1. Synchronous transaction flow.

The full flow has these steps:

1. **The client sends** a `POST /transaction` to the Midaz API.

2. **The API validates the request.** It runs request-shape validation, balance checks, and limit enforcement here.

3. **The API writes to PostgreSQL.** It persists the transaction and its operations in the same request cycle.

4. **The API returns `201 Created`** to the client with the created transaction. The response carries the `CREATED` status, and Midaz stores the transaction as `APPROVED`. A `201` means Midaz applied the transaction to balances.

**Characteristics:**

* Response time includes database write latency.
* Each transaction is an independent database operation.
* Simpler to reason about.

> [!NOTE]
>
> Even in synchronous mode, Midaz updates balances atomically in Redis during the request. Redis is authoritative for balances. The write above persists the transaction and its operations, not the Postgres balance rows. The always-on balance-sync worker reconciles those rows (see [Balance synchronization](#balance-synchronization)).

### Asynchronous mode

Midaz validates the transaction the same way. Instead of a direct database write, Midaz publishes a message to RabbitMQ. A background consumer picks up the message and handles persistence separately.

![Sequence diagram showing the client sending a POST /transaction to the Midaz API, which validates it, publishes the payload to RabbitMQ, and immediately returns 201 Created to the client. In parallel, RabbitMQ delivers the message to a background consumer, which writes the transaction and operations to PostgreSQL; balances are handled by the dedicated balance-sync worker.](https://mintcdn.com/lerian-49cb71fc/gKGrvDlaceQM1W4Y/images/en/d2/async-transaction-flow.svg?fit=max\&auto=format\&n=gKGrvDlaceQM1W4Y\&q=85\&s=be9a180c76a5d019e32f25af357905a9)

Figure 2. Asynchronous transaction flow. The client receives a response as soon as the message is published, and persistence happens in the background.

The full flow has these steps:

1. **The client sends** a `POST /transaction` to the Midaz API.

2. **The API validates the request.** It runs request-shape validation, balance checks, and limit enforcement exactly as in synchronous mode.

3. **The API publishes the transaction payload to RabbitMQ** instead of a direct database write.

4. **The API returns `201 Created`** to the client as soon as the queue accepts the message. The client does not wait for database persistence. The response carries the `CREATED` status, and Midaz stores the transaction as `APPROVED`. A `201` means Midaz applied the transaction to balances.

5. **RabbitMQ delivers the message** to a background consumer, decoupled from the API request.

6. **The consumer writes to PostgreSQL.** It persists the transaction and its operations from the queued message. The balance-sync worker copies balances to PostgreSQL in both modes (see the **Balance synchronization** section).

**Characteristics:**

* Response time excludes database write latency.
* List queries show a new transaction after the consumer writes it.
* Background consumers write to the database at their own pace, with retries. Batch inserts require an enabled Bulk Recorder.

> [!TIP]
>
> The validation step is identical in both modes. Balance checks, request-shape validation, and limit enforcement all happen before the API responds, regardless of processing mode. The difference is only in *when* the data hits the database.

## Built-in resilience

***

If the publish to RabbitMQ fails in async mode, Midaz writes the transaction to the database in the request. If that write also fails, the transaction stays applied to balances. Midaz keeps the transaction record and retries the write in the background. Synchronous mode uses the same recovery when its database write fails.

This means:

* During a queue outage, Midaz writes directly to the database.
* A failed database write does not reject a transaction that Midaz already applied to balances.
* Midaz logs the queue failure and the deferred write so your operations team can investigate them.

> [!WARNING]
>
> During a queue outage, latency can increase because writes go straight to the database. Monitor your RabbitMQ health to keep async mode active.

## Enabling async mode

***

Set one environment variable in the ledger application:

```bash Environment variable theme={null}
RABBITMQ_TRANSACTION_ASYNC=true
```

With `false` (the default), all transactions use synchronous processing and persist directly to PostgreSQL. The ledger still connects to RabbitMQ and runs its consumer in this mode.

With `true`, the ledger publishes transaction payloads to the configured RabbitMQ exchange. A background consumer then handles persistence.

## RabbitMQ configuration

***

Async mode uses the following RabbitMQ settings (all in the ledger `.env`):

| Variable | Description | Example value |
| :- | :- | :- |
| `RABBITMQ_TRANSACTION_ASYNC` | Enable async processing. | `false` |
| `RABBITMQ_HOST` | RabbitMQ server hostname. | `midaz-rabbitmq` |
| `RABBITMQ_PORT_HOST` | AMQP protocol port. | `3003` |
| `RABBITMQ_PORT_AMQP` | Management API port. | `3004` |
| `RABBITMQ_DEFAULT_USER` | Producer credentials (user). | `transaction` |
| `RABBITMQ_DEFAULT_PASS` | Producer credentials (password). | — |
| `RABBITMQ_CONSUMER_USER` | Consumer credentials (user). | `consumer` |
| `RABBITMQ_CONSUMER_PASS` | Consumer credentials (password). | — |
| `RABBITMQ_NUMBERS_OF_WORKERS` | Number of consumer worker goroutines. | `5` |
| `RABBITMQ_NUMBERS_OF_PREFETCH` | Messages prefetched per worker. | `10` |
| `RABBITMQ_TRANSACTION_BALANCE_OPERATION_EXCHANGE` | Exchange name for transaction messages. | `transaction.transaction_balance_operation.exchange` |
| `RABBITMQ_TRANSACTION_BALANCE_OPERATION_KEY` | Routing key. | `transaction.transaction_balance_operation.key` |
| `RABBITMQ_TRANSACTION_BALANCE_OPERATION_QUEUE` | Queue name. | `transaction.transaction_balance_operation.queue` |

> [!TIP]
>
> The consumer uses separate credentials (`RABBITMQ_CONSUMER_USER` / `RABBITMQ_CONSUMER_PASS`) from the producer. The consumer republishes the messages that it retries, so it also needs write access to the transaction exchange.

## Balance synchronization

***

A dedicated balance-sync worker copies balances from Redis to PostgreSQL. This worker runs in both synchronous and asynchronous modes.

| Variable | Description | Default |
| :- | :- | :- |
| `BALANCE_SYNC_BATCH_SIZE` | Number of balance updates to batch before flushing. | `50` |
| `BALANCE_SYNC_FLUSH_TIMEOUT_MS` | Maximum wait time (ms) before flushing an incomplete batch. | `500` |
| `BALANCE_SYNC_POLL_INTERVAL_MS` | How often (ms) the worker checks for pending updates. | `50` |

The balance-sync worker runs automatically in both modes. You need no extra setup beyond an available Redis instance.

## RabbitMQ circuit breaker

***

A built-in circuit breaker protects the RabbitMQ publishes of audit messages, overdraft events, and annotation transactions. It monitors the health of the RabbitMQ connection and fails fast when the broker goes down. This prevents request pileups and cascading failures.

The circuit breaker is active on the RabbitMQ path. The circuit breaker follows the standard three-state model:

* **Closed** (normal): requests flow through to RabbitMQ. The breaker counts failures.
* **Open** (tripped): the breaker does not contact RabbitMQ. An annotation transaction goes straight to the database, and Midaz returns an error if that write fails. A background health checker monitors the broker and attempts recovery.
* **Half-open** (probing): the breaker lets a limited number of requests through to test RabbitMQ recovery. If they succeed, the circuit closes. If they fail, it reopens.

The circuit opens when either condition is true:

* The number of consecutive failures reaches the threshold, OR
* The failure ratio reaches the configured percentage within the counting window

### Circuit breaker configuration

| Variable | Description | Default |
| :- | :- | :- |
| `RABBITMQ_CIRCUIT_BREAKER_CONSECUTIVE_FAILURES` | Consecutive failures before the circuit opens. | `15` |
| `RABBITMQ_CIRCUIT_BREAKER_FAILURE_RATIO` | Failure percentage (0–100) that triggers open state. | `50` |
| `RABBITMQ_CIRCUIT_BREAKER_MIN_REQUESTS` | Minimum requests before evaluating the failure ratio. | `10` |
| `RABBITMQ_CIRCUIT_BREAKER_INTERVAL` | Time window (seconds) for counting failures. Counters reset after each interval. | `120` |
| `RABBITMQ_CIRCUIT_BREAKER_TIMEOUT` | How long (seconds) the circuit stays open before transitioning to half-open. | `30` |
| `RABBITMQ_CIRCUIT_BREAKER_MAX_REQUESTS` | Requests allowed through in half-open state to probe recovery. | `3` |
| `RABBITMQ_CIRCUIT_BREAKER_HEALTH_CHECK_INTERVAL` | How often (seconds) the background health checker pings RabbitMQ. | `30` |
| `RABBITMQ_CIRCUIT_BREAKER_HEALTH_CHECK_TIMEOUT` | Timeout (seconds) for each health check ping. | `10` |

> [!TIP]
>
> For most production deployments, the defaults work well. Tune `CONSECUTIVE_FAILURES` and `TIMEOUT` if your RabbitMQ cluster has known recovery patterns. For example, lower the timeout if your broker recovers within seconds. Increase consecutive failures if you see transient network blips.

## How async mode connects to Bulk Recorder

***

Async mode and the [Bulk Recorder](/en/products/midaz/bulk-recorder) work together:

1. **Async mode** decouples the API response from persistence. Transactions go to RabbitMQ instead of directly to PostgreSQL.

2. **Bulk Recorder** optimizes how the consumer writes those messages to the database. It batches multiple messages into single bulk inserts.

| Configuration | Processing behavior |
| :- | :- |
| Async `false` | Direct database write per transaction (synchronous) |
| Async `true`, Bulk Recorder `false` | Queue-based, one message processed at a time |

## When to use async mode

***

**Use async mode when:**

* You need lower API response times for transaction creation.
* Your workload involves high transaction volumes (hundreds+ per second).
* You run batch operations like mass payouts or settlements.
* You want to decouple your API tier from database performance.

**Keep synchronous mode when:**

* You need direct, request-bound transaction persistence.
* Transaction volume is low to moderate.
* You work in a development or testing environment where simplicity matters more than throughput.

> [!TIP]
>
> You can switch between modes at any time. Change `RABBITMQ_TRANSACTION_ASYNC` and restart the ledger application. You need no data migration, because the transaction format is the same in both paths.


# Balance Overdraft
Source: https://docs.lerian.studio/en/products/midaz/balance-overdraft

Enable controlled Balance Overdraft in Midaz with automatic split operations, credit repayment priority, and limits for BNPL or settlement accounts.

Balance Overdraft lets you debit a balance beyond its available funds. The primary balance never goes negative. Midaz tracks the deficit as **OverdraftUsed** and splits the operation between the primary balance and an internal companion balance. When credits arrive, Midaz repays the overdraft first. Any remainder flows to Available.

This mechanism supports credit lines, BNPL, settlement accounts, earned wage access, and any product that needs controlled negative positions.

## Balance direction

***

Balances carry a `direction` field that defines how debits and credits affect the balance:

| Direction | Behavior | Typical use |
| - | - | - |
| `credit` | Debit decreases, credit increases | Checking accounts, wallets, reserves |
| `debit` | Debit increases, credit decreases | Loans, overdraft tracking, payables |

At creation, Midaz uses an explicit `direction` when provided, then the Account Type's `defaultDirection`. If neither is set, the balance uses `credit`. External Accounts always use `debit`.

> [!NOTE]
>
> You set direction at creation time. It is immutable. The overdraft companion balance (described below) always uses `direction=debit`.

## Balance settings

***

The `settings` object on a balance controls overdraft behavior:

| Field | Type | Description |
| - | - | - |
| `allowOverdraft` | boolean | Enables overdraft on this balance |
| `overdraftLimitEnabled` | boolean | Gates whether a limit is enforced |
| `overdraftLimit` | string (decimal) | Maximum overdraft amount. Required when `overdraftLimitEnabled` is `true`. Must be greater than `0`. |

> [!NOTE]
>
> The `settings` object also carries `balanceScope`. It identifies a transactional balance (the default) or a system-managed internal balance, such as the overdraft companion. You can set `balanceScope: "transactional"` when you create or update a public balance. You cannot set `balanceScope: "internal"` through the public API.

## Configuration modes

***

### No overdraft (default)

`allowOverdraft` is `false` by default. A debit cannot take a balance with `direction: credit` below zero.

```json JSON theme={null}
{
  "key": "checking",
  "settings": {
    "allowOverdraft": false
  }
}
```

### Unlimited overdraft

The derived position can go negative without a cap. The persisted `Available` balance remains at `0`, while Midaz tracks the deficit as `OverdraftUsed`. Use this for settlement or pool accounts, where negative positions are normal and you reconcile them externally.

```json JSON theme={null}
{
  "key": "settlement",
  "settings": {
    "allowOverdraft": true,
    "overdraftLimitEnabled": false
  }
}
```

### Limited overdraft

The derived position can go negative up to a defined limit. The persisted `Available` balance remains at `0`, while Midaz tracks the deficit as `OverdraftUsed`. This is the most common mode for consumer credit products.

```json JSON theme={null}
{
  "key": "checking",
  "settings": {
    "allowOverdraft": true,
    "overdraftLimitEnabled": true,
    "overdraftLimit": "5000.00"
  }
}
```

> [!WARNING]
>
> When `overdraftLimitEnabled` is `true`, you must set `overdraftLimit` to a positive decimal string. If you omit it or set it to `"0"`, Midaz returns error `0172`.

## How overdraft works

***

### Operation split

When a debit transaction exceeds the available funds, Midaz automatically splits the operation:

1. The debit consumes all remaining Available and floors it at **0**.
2. Midaz accrues the excess as **OverdraftUsed** on the primary balance.

**Example:** Balance has Available = 300. A debit of 500 arrives.

| Step | Available | OverdraftUsed | Description |
| - | - | - | - |
| Before | 300 | 0 | Normal state |
| After | 0 | 200 | 300 consumed from Available, 200 accrued as overdraft |

The transaction succeeds as a single atomic operation. The caller does not need to handle the split. Midaz does it automatically.

> [!NOTE]
>
> If you configure a limit, Midaz checks the resulting OverdraftUsed against `overdraftLimit` before it processes the transaction. If the result exceeds the limit, Midaz rejects the transaction with error `0167`.

### Automatic repayment (refund split)

When a credit arrives and `OverdraftUsed > 0`, Midaz prioritizes repayment:

1. Midaz applies the credit to **OverdraftUsed** first and reduces the debt.
2. Any remaining amount after OverdraftUsed reaches 0 flows to **Available**.

**Example:** OverdraftUsed = 200, Available = 0. A credit of 350 arrives.

| Step | Available | OverdraftUsed | Description |
| - | - | - | - |
| Before | 0 | 200 | Overdraft active |
| After | 150 | 0 | 200 repaid, 150 goes to Available |

> [!TIP]
>
> Repayment is automatic. You cannot bypass it. Midaz reduces overdraft positions as early as possible, which keeps the balance healthy.

### Pending transactions and overdraft

A `PENDING` transaction creates a hold. It does not draw overdraft. If a hold would exceed Available, Midaz rejects the transaction with error `0018 - Insufficient Funds Error`. The rejected hold does not change Available, OnHold, or `OverdraftUsed`.

When you cancel a pending transaction, Midaz releases its hold. A pending transaction created by an earlier Midaz version can already carry overdraft. Midaz still unwinds that legacy state correctly during cancellation.

## Position

***

Every balance response includes a computed `position` block. It gives a real-time view of the balance state:

| Field | Description |
| - | - |
| `available` | Derived `position.available`. It can be negative when the persisted balance has `Available = 0` and `OverdraftUsed > 0`. |
| `onHold` | Mirrors `Balance.OnHold` (funds reserved by pending operations). |
| `overdraftLimitAvailable` | Remaining non-negative overdraft headroom. It is `"0"` when a configured limit is fully used and is omitted when overdraft is unlimited. |

> [!WARNING]
>
> Do not cache the `position` block for accounting purposes. Midaz never persists it. It computes the block at query time from the current balance state.

## Companion balance

***

When you create or update a balance with `allowOverdraft` set to `true` for the first time, Midaz auto-provisions a **companion balance** under the same account. The companion balance records the liability side of the double-entry. Midaz creates it once per account and reuses it across every overdraft draw and repayment.

| Property | Value | Why |
| - | - | - |
| `key` | `"overdraft"` | Reserved system key |
| `direction` | `debit` | The companion tracks a liability: debits grow it, credits shrink it |
| `scope` | `internal` | Blocks direct user operations |
| `allowSending` | `true` | Required for DEBIT operations on the companion (overdraft draws) |
| `allowReceiving` | `true` | Required for CREDIT operations on the companion (overdraft repayments) |

This balance is fully system-managed:

* You cannot create, modify, or delete it through the public API.
* Midaz reserves the key `"overdraft"`. A request that creates a balance with this key returns error `0170`.
* It mirrors the liability as a proper double-entry record, so the ledger stays balanced.

> [!NOTE]
>
> The `scope: "internal"` value blocks direct user operations, regardless of the permission flags above. Midaz rejects any direct operation on this balance with error `0168`. The companion moves only through system-driven overdraft enrichment.

## Overdraft state on operations

***

Every operation exposes the overdraft state on the `balance` and `balanceAfter` blocks. The `overdraftUsed` field records the overdraft consumed before and after the operation. This gives a complete audit trail without a separate balance query.

System-managed companion operations on the `"overdraft"` balance use `type: "OVERDRAFT"` (uppercase). The `direction` field carries the lifecycle: `"debit"` for a draw, `"credit"` for a repayment.

```json Primary debit drawing overdraft theme={null}
{
  "type": "DEBIT",
  "direction": "debit",
  "amount": { "value": "300" },
  "accountAlias": "@user123",
  "balanceKey": "checking",
  "balance": {
    "available": "300",
    "onHold": "0",
    "version": 1,
    "overdraftUsed": "0"
  },
  "balanceAfter": {
    "available": "0",
    "onHold": "0",
    "version": 2,
    "overdraftUsed": "200"
  }
}
```

```json Companion overdraft draw theme={null}
{
  "type": "OVERDRAFT",
  "direction": "debit",
  "amount": { "value": "200" },
  "balanceKey": "overdraft",
  "balance": {
    "available": "0",
    "onHold": "0",
    "version": 1,
    "overdraftUsed": "0"
  },
  "balanceAfter": {
    "available": "200",
    "onHold": "0",
    "version": 2,
    "overdraftUsed": "200"
  }
}
```

Both the primary and the companion operation share the same `overdraftUsed` before/after pair. They mirror the primary balance's overdraft transition, so the lifecycle is visible from either row. The internal `snapshot` JSONB column on the `operations` table stores the same values for indexing and historical reconstruction. This column is not part of the public JSON wire. The values surface on `balance.overdraftUsed` and `balanceAfter.overdraftUsed` instead. Midaz can add future system-generated context to the snapshot without breaking the public contract.

> [!TIP]
>
> Companion operations inherit the primary operation's `routeId`. For each overdraft-capable route, configure both the `debit` and `credit` rubrics of the `overdraft` entry. Midaz requires both. Midaz resolves `routeCode` and `routeDescription` from the rubric that matches the companion's direction.

## Overdraft events

***

At runtime, Midaz enables overdraft-event publication unless `RABBITMQ_OVERDRAFT_EVENTS_ENABLED` is explicitly `false`. The bundled example environment sets the flag to `false`. A deployment that starts from that example publishes no overdraft events until you set it to `true`.

```bash Environment theme={null}
# The bundled example disables overdraft-event publication. Runtime enables it unless the flag is explicitly false.
RABBITMQ_OVERDRAFT_EVENTS_ENABLED=false

# Optional: route overdraft events to a dedicated exchange.
# When unset, the broker's default exchange is used.
RABBITMQ_OVERDRAFT_EVENTS_EXCHANGE=transaction.overdraft_events.exchange
```

### Event types

| Event | Description |
| - | - |
| `overdraft.drawn` | Overdraft was consumed (OverdraftUsed increased) |
| `overdraft.repaid` | Overdraft was partially repaid (OverdraftUsed decreased but remains > 0) |
| `overdraft.cleared` | Overdraft was fully repaid (OverdraftUsed reached 0) |

### Example event payload

```json JSON expandable theme={null}
{
  "source": "midaz",
  "eventType": "balance",
  "action": "overdraft.drawn",
  "timestamp": "2026-04-28T14:30:00.000000Z",
  "version": "v3.0.0",
  "organizationId": "0198575d-f9fd-702b-bb15-fa4c980b32c7",
  "ledgerId": "0198575d-fa0b-7ac7-8b7d-9d3ab7dccafc",
  "payload": {
    "accountId": "0198575f-a8f9-7924-a6d7-8122f2c77ddd",
    "transactionId": "019b2c3d-4e5f-6789-0123-456789abcdef",
    "amount": "200",
    "overdraftBalance": "200",
    "timestamp": "2026-04-28T14:30:00.000000Z"
  }
}
```

> [!TIP]
>
> Use overdraft events to trigger downstream workflows: interest accrual, customer notifications, risk alerts, or automatic collection processes.

## Use cases

***

### Checking account overdraft (cheque especial)

Classic consumer credit. The checking account's derived position can go negative up to a pre-approved limit. The persisted `Available` balance remains at `0` and the outstanding amount is tracked as `OverdraftUsed`.

```json JSON theme={null}
{
  "key": "checking",
  "settings": {
    "allowOverdraft": true,
    "overdraftLimitEnabled": true,
    "overdraftLimit": "2000.00"
  }
}
```

### Buy Now, Pay Later (BNPL)

A BNPL provider issues a purchase credit against the customer's balance. This creates an immediate overdraft position that the customer repays in installments.

```json JSON theme={null}
{
  "key": "bnpl",
  "settings": {
    "allowOverdraft": true,
    "overdraftLimitEnabled": true,
    "overdraftLimit": "10000.00"
  }
}
```

### Earned Wage Access / Salary advance

Employees draw against future earnings. Payroll credits clear the overdraft position when they arrive.

```json JSON theme={null}
{
  "key": "salary-advance",
  "settings": {
    "allowOverdraft": true,
    "overdraftLimitEnabled": true,
    "overdraftLimit": "3000.00"
  }
}
```

### Marketplace receivables advance

Sellers receive an advance on future receivables. Midaz repays the overdraft automatically as sales settlements arrive.

```json JSON theme={null}
{
  "key": "receivables",
  "settings": {
    "allowOverdraft": true,
    "overdraftLimitEnabled": true,
    "overdraftLimit": "50000.00"
  }
}
```

### Settlement / Pool accounts (unlimited mode)

Settlement and pool accounts routinely go negative during intraday processing. Unlimited overdraft avoids artificial rejections while you reconcile the position by end-of-day.

```json JSON theme={null}
{
  "key": "settlement-pool",
  "settings": {
    "allowOverdraft": true,
    "overdraftLimitEnabled": false
  }
}
```

### Revolving credit lines (B2B)

Businesses draw and repay from a revolving credit facility. The overdraft limit represents the total credit line.

```json JSON theme={null}
{
  "key": "credit-line",
  "settings": {
    "allowOverdraft": true,
    "overdraftLimitEnabled": true,
    "overdraftLimit": "500000.00"
  }
}
```

### Insurance pre-financing

Insurers pre-finance claims before premium collection cycles close. The overdraft covers the gap between payout and collection.

```json JSON theme={null}
{
  "key": "claims-prefin",
  "settings": {
    "allowOverdraft": true,
    "overdraftLimitEnabled": true,
    "overdraftLimit": "100000.00"
  }
}
```

### Loyalty programs (advanced points)

Customers redeem points before they earn them. The overdraft tracks the point deficit and clears as customers accrue new points.

```json JSON theme={null}
{
  "key": "loyalty-points",
  "settings": {
    "allowOverdraft": true,
    "overdraftLimitEnabled": true,
    "overdraftLimit": "10000"
  }
}
```

## Protection rules

***

Overdraft introduces several immutability and access constraints to maintain ledger integrity:

* **Direction is immutable.** Once you set a balance's `direction` at creation, you cannot change it.
* **Internal balances block writes.** You cannot create, delete, or update the `"overdraft"` companion balance through the public API. A PATCH returns error `0175`.
* **Reserved keys.** Midaz reserves the key `"overdraft"` for the system-managed companion balance.
* **Disabling overdraft preserves outstanding debt.** You can set `allowOverdraft: false` while `OverdraftUsed > 0` to block future draws, while incoming credits still repay the existing debt.
* **Limit cannot drop below usage.** If `OverdraftUsed = 200`, Midaz rejects `overdraftLimit: "100"` with error `0173`, so repay below the new ceiling first or set a higher limit.

For error codes 0167–0175, see the [Midaz error list](/en/reference/products/midaz/error-list).

## Next steps

***

* Learn about [Balances](/en/products/midaz/balances), the foundation that overdraft builds on.
* Understand [Operations](/en/products/midaz/operations) to trace how overdraft splits appear in the ledger.
* Set up the [Event Publisher](/en/products/midaz/event-publisher) to consume overdraft lifecycle events.
* Explore [Transactions](/en/products/midaz/transactions) for the full picture of double-entry accounting in Midaz.


# Balances
Source: https://docs.lerian.studio/en/products/midaz/balances

Track multiple Balances per Account to segment funds into investment reserves, credit limits, and operational funds without extra Accounts.

A **Balance** represents the value that a specific account holds in Midaz. It reflects the result of all operations (debits and credits) over time. Each balance belongs to one asset, such as BRL, USD, or BTC.

## Multiple balances

***

A single account can hold several balances. A unique key identifies each one. This lets institutions segment funds without creating multiple accounts for the same customer.

> [!CAUTION]
>
> External accounts cannot have multiple balances. **Each external account holds exactly one balance.**

Typical use cases include:

* Investment reserves
* Credit limits
* Collateral (blocked) funds
* Day-to-day operational funds

This approach increases flexibility. It keeps the double-entry model (debit and credit) intact for accounting consistency, traceability, and transparency.

> [!WARNING]
>
> If a transaction does not provide a `balanceKey`, Midaz uses the account's default balance.

### Balance key

A `key` field identifies each balance uniquely within the account.

* **Maximum length**: 100 characters, with no whitespace.
* **Default key**: `"default"`. Midaz creates the default balance automatically when the account is created.
* **Uniqueness**: Each key must be unique per account. A request to create a balance with a key that already exists on the account returns an error.
* **In transactions**: If a transaction does not specify a `balanceKey`, Midaz uses the balance with key `"default"`.

> [!NOTE]
>
> You set the `key` at creation time and cannot change it later. Choose descriptive keys like `"credit"`, `"collateral"`, or `"savings"` to make your balance model self-documenting.

### Permission flags

Each balance has two independent permission flags that control whether it can participate in transactions:

| Flag | Type | Description |
| - | - | - |
| `allowSending` | boolean | Whether funds can be sent **from** this balance |
| `allowReceiving` | boolean | Whether funds can be received **into** this balance |

These flags are per-balance. They apply to one balance, not to the whole account. Both default to `true` when you do not set them.

**Common use cases:**

* **Receive-only balance**: Set `allowSending` to `false` to block outbound transfers and still accept inflows.
* **Send-only balance**: Set `allowReceiving` to `false` to prevent new funds from entering this balance.

You can set both flags when you create a balance. You can also update them independently through the [Update a Balance](/en/reference/products/midaz/v2/update-balance) endpoint. If an update request omits a flag, its current value stays unchanged.

> [!WARNING]
>
> Midaz reads permission flags during transaction validation. A flag change applies to transactions validated after the update succeeds. Changes never alter operations already processed.

## Usage examples

***

* **User Wallet (BRL)**: A digital wallet that shows an available balance of R\$500.
  * *Use case*: Show the balance in a mobile banking app and validate funds before a payment.
* **Settlement Account (USD)**: A liquidity provider account with a USD balance of \$120,000.
  * *Use case*: Make sure daily treasury operations keep enough buffer for FX settlements.
* **Blocked Balance (BRL)**: An account balance reserved as collateral.
  * *Use case*: Prevent the use of funds until a loan closes or the borrower meets the conditions.

> [!NOTE]
>
> A blocked (collateral) balance restricts funds at the balance level. Midaz holds the value in a separate balance and combines it with permission flags to keep the funds unavailable. This differs from a [Block transaction](/en/products/midaz/transactions#blocking-and-unblocking-funds), which records a ledger movement with `BLOCK`-typed operations. A Block transaction flags funds for reasons like a compliance hold. Use a collateral balance for a standing operational restriction. Use a Block transaction when you need an auditable ledger entry.

## Balance structure

***

* **Balance > Account**: Each Balance belongs to an Account, which holds and moves value.
* **Balance > Asset**: Each Balance uses a specific Asset, such as BRL or BTC.
* **Balance > Ledger**: Balances exist within a Ledger, which enables multi-book environments.
* **Balance > Key**: Each Balance has a unique key within the account (e.g., `default`, `credit`, `collateral`).

*Figure 2* shows an example of the structure.

![Balance structure relationships](https://mintcdn.com/lerian-49cb71fc/SFzzdxyH5SN7w_fC/images/en/d2/balance-structure-relationships.svg?fit=max\&auto=format\&n=SFzzdxyH5SN7w_fC\&q=85\&s=7b2fdced4a1a0db1ed925b210b01b16d)

Figure 2. Balance structure relationships diagram.

A balance includes metadata about the state of funds, such as pending operations and effective availability.

## Key characteristics

***

* **Real-time tracking**: Midaz updates balances with every confirmed operation.
* **Multiple balances per account**: Accounts can hold several balances, each with its own rules.
* **Single source of truth**: Balances reflect the net sum of all operations on the account.
* **Query by context**: You can list balances within an organization and ledger, retrieve them by account ID or alias, and retrieve an External Account’s balance by asset code. The balance-list endpoints do not filter by a generic asset code or `balanceKey`.
* **Supports external accounts**: You can retrieve balances for internal or external accounts, such as liquidity pools or partners.

## Using balances in transactions

***

The following transaction endpoints accept a `balanceKey` field to specify which balance to use:

* [Create a Transaction using JSON](/en/reference/products/midaz/v1/create-transaction-json)
* [Create an Inflow Transaction](/en/reference/products/midaz/v1/create-transaction-inflow)
* [Create an Outflow Transaction](/en/reference/products/midaz/v1/create-transaction-outflow)
* [Create a Transaction Annotation](/en/reference/products/midaz/v1/create-transaction-annotation)

If a request does not provide a `balanceKey`, Midaz uses the account's default balance.

### New fields in responses

* `balanceKey` - Appears in transactions and operations to show which balance the transaction used.
* `key` - Appears in balances to identify each balance uniquely.

> [!CAUTION]
>
> Always use the `balanceKey` consistently across requests and responses. This avoids mismatches when accounts hold multiple balances.

## Balance cache key (Valkey)

***

Balances in the cache (Valkey) include the `balanceKey`.

```json theme={null}
balance:{transactions}:<org_id>:<ledger_id>:<account_alias>#<balance_key>
```

The key carries the `balance:{transactions}:` prefix, and the `balance_key` is appended to the account alias with a `#` separator.

> [!WARNING]
>
> Update direct Valkey readers to construct `balance:{transactions}:<org_id>:<ledger_id>:<account_alias>#<balance_key>`, including `#default` for the default balance.

## Overdraft

***

Balances support **overdraft**, the ability to debit a balance beyond its available funds. When you enable overdraft, Midaz tracks the deficit as `overdraftUsed`. Midaz also handles the operation split and repayment automatically.

Two fields support this feature:

* **`direction`**: A new balance of a non-external account takes the `defaultDirection` of its account type when that type sets one. Otherwise, direction is `credit` for non-external accounts and `debit` for External Accounts. Additional balances may set direction at creation. It cannot change afterward.
* **`settings`**: Controls overdraft behavior with `allowOverdraft`, `overdraftLimitEnabled`, and `overdraftLimit`.

> [!NOTE]
>
> Midaz reserves the key `"overdraft"` for the system-managed companion balance that records the liability side. A request to create a balance with this key returns an error.

`settings.balanceScope` also distinguishes balances by scope. **Transactional** balances (the default) are user-managed and take part in regular transactions. The system operates **internal** balances exclusively, such as the overdraft companion. User transactions cannot target, modify, or delete them through the public API.

For full details on configuration modes, operation splits, automatic repayment, events, and use cases, see [Balance Overdraft](/en/products/midaz/balance-overdraft).

## Balance history

***

Midaz provides **point-in-time queries** for balances. You can retrieve a balance state at a past timestamp on or after the balance’s creation. If no operation exists before that timestamp, Midaz returns the initial zero state. It returns `404` when the requested timestamp precedes balance creation. This supports auditing, reconciliation, and historical reporting.

### How it works

When you query balance history, Midaz returns historical identity and amount fields. It omits `allowSending`, `allowReceiving`, `deletedAt`, and `metadata`. The current implementation also does not reconstruct historical `direction` or `settings`, and returns `overdraftUsed` as zero. Do not treat it as a full regular-balance response minus permission flags.

> [!TIP]
>
> **Why does history exclude permission flags?**
>
> `allowSending` and `allowReceiving` are mutable operational settings. You can toggle them at any time without a ledger entry. Balance amounts (`available`, `onHold`) change only from recorded transactions. Permission flags represent the *current* operational state of a balance, not a fact about its past.
>
> Historical audits and reconciliation care about amounts at a point in time. Whether sending or receiving worked at a given moment does not matter for audit or reconciliation. Mutable permission state in immutable snapshots would add ambiguity without value.

### Use cases

* **Regulatory auditing**: Prove the exact balance of an account at a specific compliance checkpoint.
* **Reconciliation**: Compare balance snapshots across systems at matching timestamps.
* **Dispute resolution**: Retrieve the precise account state at the time of a contested transaction.
* **End-of-day reporting**: Capture balance positions at market close for treasury operations.

> [!WARNING]
>
> The `date` parameter is required. It must follow the format `yyyy-mm-dd hh:mm:ss` (e.g., `2026-01-15 10:30:00`). Midaz returns `404` when the requested timestamp precedes balance creation.

### Querying balance history

You can query history for a single balance or for all balances of an account:

* [Retrieve Balance History](/en/reference/products/midaz/v2/get-balance-at-timestamp) - Get the state of a specific balance at a given point in time.
* [Retrieve Balance History by Account](/en/reference/products/midaz/v2/get-account-balances-at-timestamp) - Get the state of all balances for an account at a given point in time.

## Managing Balances

***

You can retrieve your balances through the API. The Midaz ledger engine computes balance amounts from transactions. You cannot set `available` or `onHold` directly. You manage the balance records (key, permission flags, and settings) through the endpoints below.

* [Create a Balance](/en/reference/products/midaz/v2/create-additional-balance) - Create a new balance for an account by defining a unique key.
* [List Balances](/en/reference/products/midaz/v2/get-all-balances) - Retrieve all balances by organization and ledger.
* [Retrieve a Balance](/en/reference/products/midaz/v2/get-balance-by-id) - Get the balance of a specific account by its unique ID.
* [Retrieve Balances by Account](/en/reference/products/midaz/v2/get-all-balances-by-account-id) - Get the balance for a specific account.
* [Retrieve a Balance by Account Alias](/en/reference/products/midaz/v2/get-balances-by-alias) - Get the balance with a human-readable account alias (e.g., @user123).
* [Retrieve a Balance of an External Account](/en/reference/products/midaz/v2/get-balances-external-by-code) - Retrieve the balance of an external account (e.g., `@external/BRL`).
* [Update a Balance](/en/reference/products/midaz/v2/update-balance) - Update the permission flags and settings of a balance.
* [Delete a Balance](/en/reference/products/midaz/v2/delete-balance) - Delete a balance entry from the system. Midaz refuses to delete a balance that owes [fee debt](/en/products/midaz/fees/fee-debt) (`0527`) or that other balances owe fee debt to (`0528`).

> [!TIP]
>
> To trace how a balance formed, use the Operations API to inspect the ledger history that affected that account.

## Next steps

***

* Use the [Operations API](/en/products/midaz/operations) to trace transactions that involve multiple balances.
* Combine multiple balances with [Accounting Routes](/en/products/midaz/transaction-routing-entities) to create flexible and scalable financial flows.


# Production ready
Source: https://docs.lerian.studio/en/products/midaz/best-practices

Hub for Midaz production best practices covering common mistakes, scalability strategies, banking entity hierarchy, and hardening for high-volume workloads.

For direct transactions, use Accounting Routes and enable route validation after you configure the route rules your Ledger needs. Lifecycle actions can follow a different shape. Cancellation releases held funds on the source side only.

These best practices help you keep financial operations transparent, auditable, and compliant.

## Content

***

This section contains the following pages:

* [**Common mistakes to avoid**](/en/products/midaz/common-mistakes-to-avoid): The most common mistakes with Midaz and how to avoid them.
* [**Scalability strategies**](/en/products/midaz/scalability-strategies): How to scale your Midaz deployment for high transaction volumes and multi-currency, multi-entity operations.
* [**Structuring bank operations with Midaz**](/en/products/midaz/structuring-bank-operation): A strategic approach to entity hierarchy and account structure in a banking environment.
* [**Midaz production best practices**](/en/products/midaz/midaz-production-best-practices): Recommendations to set up your Midaz production environment from the start. You minimize downtime, protect your data, and handle high-volume workloads.


# Build on Midaz
Source: https://docs.lerian.studio/en/products/midaz/build-midaz-sdk

Build integrations on Midaz with the official Go and TypeScript SDKs: typed clients, sensible defaults, and shared patterns for API calls and errors.

Midaz SDKs are the public integration layer for applications that call Midaz APIs.

Use an SDK to build an application, automation, backend service, or integration on Midaz. Each SDK works with Midaz resources: organizations, ledgers, accounts, portfolios, balances, transactions, assets, and metadata.

The SDKs give you typed, idiomatic interfaces for the Midaz API. You focus on product behavior, not raw HTTP requests, payloads, pagination, or response parsing.

## Available SDKs

***

We offer two official SDKs:

> **[Go SDK](/en/products/midaz/midaz-sdk-go)**
>
> Use the official Go SDK to build Midaz integrations in Go.

> **[TypeScript SDK](/en/products/midaz/midaz-sdk-typescript)**
>
> Use the official TypeScript SDK to build Midaz integrations in Node.js or TypeScript applications.

## Why use Midaz SDKs?

***

* Developer-friendly: clean interfaces, strong typing, and sensible defaults.
* API-focused: SDKs connect to the public Midaz APIs. Your application keeps control of its data and business logic.

## SDKs and internal libraries

***

SDKs are the public path for external applications to integrate with Midaz.

Lerian also maintains internal shared libraries for its own services, plugins, and platform components. Lerian engineering teams use these libraries to standardize how services behave. These libraries are not public integration contracts. Do not treat them as supported APIs for external applications.

To integrate with Midaz, start with the official SDK for your language. If an SDK does not cover a capability, use the Midaz API directly or contact Lerian first.


# Build an account statement
Source: https://docs.lerian.studio/en/products/midaz/building-account-statements

Turn Midaz account operations into a clear customer statement by filtering by date, direction, and route with the List Operations by Account endpoint.

You build an account statement from Midaz account operations. Each operation is a ledger movement that links to an account, such as a credit, debit, hold, release, or overdraft event.

To build a statement, retrieve the account operations for the period. Keep the operations that affect the statement view. Then transform each operation into a row that users understand.

![Account balance flow](https://mintcdn.com/lerian-49cb71fc/SFzzdxyH5SN7w_fC/images/en/d2/account-balance-flow.svg?fit=max\&auto=format\&n=SFzzdxyH5SN7w_fC\&q=85\&s=1d9f29821d6e2e687c6d9bd8e4c5a89f)

Account balance flow

## 1. Retrieve account operations

Use the [List Operations by Account](/en/reference/products/midaz/v2/get-all-operations-by-account) endpoint to list operations for a specific account:

```json theme={null}
GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/operations
```

## 2. Apply query filters

Use query parameters to define the statement period, control pagination, and filter the operations that the endpoint returns.

### Required for statement queries

| Parameter | Description |
| - | - |
| `start_date` | Start date of the statement period |
| `end_date` | End date of the statement period |
| `limit` | Number of items per page |
| `sort_order=desc` | Returns the most recent operations first |

You need these fields for this statement use case. They define the statement window and make the result predictable for users.

### Required for pagination

| Parameter | Description |
| - | - |
| `cursor` | Cursor returned from the previous response |

### Optional filters

| Parameter | Description |
| - | - |
| `direction=credit` | Returns only incoming operations |
| `direction=debit` | Returns only outgoing operations |
| `type` | Filters by operation type |
| `route_id` | Filters by the operation route ID (UUID) |
| `route_code` | Filters by the operation route code |

The endpoint can return the following operation types:

| Type | What it means |
| - | - |
| `CREDIT` | Value entering the account |
| `DEBIT` | Value leaving the account |
| `ON_HOLD` | Amount temporarily locked |
| `RELEASE` | Previously locked amount released |
| `OVERDRAFT` | Movement related to overdraft usage |
| `BLOCK` | System-generated account-block companion row |
| `UNBLOCK` | System-generated account-unblock companion row |
| `FEE_SETTLEMENT` | Settlement of a fee debt |
| `FEE_REFUND` | Refund of a settled fee debt on a revert |

Use `type` to classify the accounting movement. Use `direction` to decide whether the statement shows the amount as positive or negative.

Example request:

```json theme={null}
GET /v1/organizations/org_123/ledgers/ledger_001/accounts/account_456/operations?start_date=2026-05-01&end_date=2026-05-31&limit=50&sort_order=desc
```

## 3. Transform operations into statement entries

Each object in the `items` array can become one statement row.

### Required for statement rendering

| Statement field | Operation field |
| - | - |
| Date | `createdAt` |
| Description | `description` |
| Movement type | `type` |
| Direction | `direction` |
| Amount | `amount.value` |
| Currency or asset | `assetCode` |
| Balance after operation | `balanceAfter.available` |
| Receipt or transaction reference | `transactionId` |

You need these fields to render a useful statement row. The API does not require all of them. A statement without them loses meaning, traceability, or balance context.

### Recommended for user-friendly statements

| Statement context | Operation field |
| - | - |
| Counterparty | `metadata.counterparty` |
| Document | `metadata.document` |
| Pix key | `metadata.pixKey` |
| End-to-end ID | `metadata.endToEndId` |
| Channel | `metadata.channel` |
| Category | `metadata.category` |

Midaz returns the ledger movement. The integrating system should add business context in the `metadata` of each relevant `source.from[]` and `distribute.to[]` entry when it creates the transaction. Metadata does not propagate from source entries to destination entries.

Example transformation:

```json theme={null}
{
  "date": "2026-05-18T14:23:11Z",
  "description": "Pix transfer received",
  "type": "CREDIT",
  "direction": "credit",
  "amount": "150.00",
  "asset": "BRL",
  "balanceAfter": "1240.55",
  "transactionId": "txn_987654",
  "metadata": {
    "counterparty": "John Doe",
    "pixKey": "john@example.com",
    "category": "Transfer"
  }
}
```

## 4. Apply statement display rules

### Use `direction` to determine the sign

| Direction | Display behavior |
| - | - |
| `credit` | Display as a positive amount |
| `debit` | Display as a negative amount |

> [!WARNING]
>
> Do not use `type` to determine whether the value is positive or negative. The `type` field classifies the accounting movement, while `direction` defines whether the value enters or leaves the account.

### Handle hold and release operations separately

Do not display operations with the following types as regular settled movements:

* `ON_HOLD`
* `RELEASE`

Instead:

* `ON_HOLD` should appear as a balance hold or temporary lock
* `RELEASE` should appear as a balance release or unlock

### Define a settled-operation policy

Do not use `balanceAffected` as a settled-operation predicate. A normal `ON_HOLD` operation can set `balanceAffected` to `true` without changing the available balance. Define your statement policy explicitly from operation type and status, and show `ON_HOLD` and `RELEASE` according to the hold/release rules above.

## 5. Handle pagination

The endpoint splits responses into pages according to the `limit` value.

To retrieve all operations:

1. Read the `next_cursor` field from the response
2. Send it as the `cursor` parameter in the next request
3. Repeat until the response no longer returns `next_cursor`

Example flow:

```text theme={null}
Request 1
  -> returns items + next_cursor

Request 2
  -> cursor=next_cursor
  -> returns more items + next_cursor

Repeat until next_cursor is no longer returned
```

## Example statement output

After you apply filters, transform operations, and apply display rules, the final statement can look like this:

| Date | Description | Amount | Balance after |
| - | - | - | - |
| 2026-05-18 | Pix received from John Doe | +150.00 BRL | 1,240.55 BRL |
| 2026-05-18 | Card purchase | -45.90 BRL | 1,194.65 BRL |

The API does not return a ready-made statement page. It returns ledger events that the integrating system turns into a statement experience.

## Add business context

The operations endpoint returns accounting events. A user-facing statement needs more context than the ledger movement alone.

Send business metadata in each operation's metadata when you create the transaction. Midaz stores those fields with that operation. The statement can use them later to show who, what, and why behind the movement.

* `counterparty`
* `document`
* `pixKey`
* `endToEndId`
* `channel`
* `category`

Example metadata:

```json theme={null}
"send": {
  "source": {
    "from": [{
      "accountAlias": "customer_123",
      "metadata": {
        "counterparty": "John Doe",
        "document": "12345678900",
        "pixKey": "john@example.com",
        "endToEndId": "E1234567890123456789012345678901",
        "channel": "PIX",
        "category": "Transfer"
      }
    }]
  }
}
```

This lets you display entries such as:

* "Pix received from John Doe"
* "Card purchase at Coffee Shop"
* "Transfer to Savings Account"

instead of generic accounting descriptions.

If the integrating system does not send these fields, the statement still works. It can then only display the accounting data that the operation returns.

> [!TIP]
>
> Midaz keeps the ledger consistent and auditable. The integrating system adds business context to each operation's metadata.


# Bulk Recorder
Source: https://docs.lerian.studio/en/products/midaz/bulk-recorder

Use the Bulk Recorder to batch RabbitMQ messages into bulk PostgreSQL inserts, cutting database round trips and raising throughput on high-volume workloads.

## Batch writes for high-volume workloads

***

Every transaction in Midaz creates balance operations that Midaz must persist. In the default synchronous mode, Midaz writes them directly to the database in the request cycle. This is fine for moderate volumes. At scale (thousands of transactions per second), it becomes the bottleneck.

The Bulk Recorder accumulates messages and writes them in batches. It makes fewer round trips to PostgreSQL, lowers lock contention, and raises throughput. High-volume workloads gain the most: mass payouts, batch settlements, and real-time payment processing.

For broader strategies to scale Midaz, see [Scalability strategies](/en/products/midaz/scalability-strategies).

## How it works

***

The Bulk Recorder sits between the RabbitMQ consumer and the database layer. Instead of inserting each message at once, it collects messages in a buffer and flushes them under two conditions:

1. **Batch size reached**: the buffer fills to the configured size.
2. **Timeout elapsed**: the configured flush timeout expires, even if the buffer is not full.

Whichever condition happens first triggers the flush. This gives large batches under load and low latency during quiet periods.

![Sequence diagram showing RabbitMQ delivering messages to the BulkCollector, which buffers them until the batch size or timeout is reached, then sends a chunked bulk INSERT to PostgreSQL and acknowledges each message back to RabbitMQ.](https://mintcdn.com/lerian-49cb71fc/Cb_meREQqa6luqbJ/images/en/d2/bulk-recorder-flow.svg?fit=max\&auto=format\&n=Cb_meREQqa6luqbJ\&q=85\&s=cf6291e64238dddc753da5b89a5caeba)

Figure 1. End-to-end flow of the Bulk Recorder between RabbitMQ and PostgreSQL.

Here is the full flow, step by step:

1. **RabbitMQ delivers messages** to the BulkCollector one at a time: Message 1, Message 2, up to Message N.

2. **The BulkCollector holds them in memory** instead of one write per message. It collects until the batch fills or the flush timeout expires.

3. **The BulkCollector sends a chunked bulk INSERT to PostgreSQL.** Midaz splits large batches into chunks that respect PostgreSQL's parameter limits. Each chunk uses `ON CONFLICT (id) DO NOTHING`, so retries and duplicate deliveries stay safe.

4. **PostgreSQL confirms the write** and stores the data.

5. **The BulkCollector acknowledges each message** back to RabbitMQ after the write. It acknowledges them one at a time, not in a single bulk ack. This stops a shared channel from acking messages that other workers still process.

## Enabling Bulk Recorder

***

Bulk mode works only in a single-tenant deployment and requires async mode. The explicit Bulk Recorder setting is optional because it defaults to enabled:

```bash Environment variables theme={null}
RABBITMQ_TRANSACTION_ASYNC=true
BULK_RECORDER_ENABLED=true
```

## Configuration

***

| Variable | Description | Default |
| :- | :- | :- |
| `BULK_RECORDER_ENABLED` | Enable or disable bulk mode. | `true` |
| `BULK_RECORDER_SIZE` | Number of messages to accumulate before flushing. `0` = auto-calculated. | `0` (auto) |
| `BULK_RECORDER_FLUSH_TIMEOUT_MS` | Maximum time (ms) to wait before flushing an incomplete batch. | `100` |
| `BULK_RECORDER_MAX_ROWS_PER_INSERT` | Maximum operation rows per `INSERT`. Values above 1,000 have no effect. | `1000` |

### Auto-calculated batch size

When `BULK_RECORDER_SIZE` is set to `0` (the default), Midaz derives the batch size:

```
batch size = RABBITMQ_NUMBERS_OF_WORKERS × RABBITMQ_NUMBERS_OF_PREFETCH
```

> [!WARNING]
>
> If you set `BULK_RECORDER_SIZE` by hand, keep it aligned with your prefetch settings. A size much larger than `workers × prefetch` rarely fills the collector. The collector then flushes mostly on the timeout.

## Tuning for your workload

***

The two main levers are **batch size** and **flush timeout**. The right balance depends on your priority: latency or throughput.

### Low latency (real-time processing)

Keep batches small and timeouts short. Midaz persists messages quickly, even when batches are not full.

```bash Low-latency configuration theme={null}
RABBITMQ_NUMBERS_OF_WORKERS=5
RABBITMQ_NUMBERS_OF_PREFETCH=10
BULK_RECORDER_SIZE=0          # auto: 5 × 10 = 50
BULK_RECORDER_FLUSH_TIMEOUT_MS=50
```

### High throughput (batch operations)

Larger batches and longer timeouts maximize database efficiency. Use this for mass payouts, end-of-day settlements, or migration workloads.

```bash High-throughput configuration theme={null}
RABBITMQ_NUMBERS_OF_WORKERS=10
RABBITMQ_NUMBERS_OF_PREFETCH=20
BULK_RECORDER_SIZE=0          # auto: 10 × 20 = 200
BULK_RECORDER_FLUSH_TIMEOUT_MS=300
```

> [!TIP]
>
> Start with the defaults and adjust from what you observe. To confirm your settings, watch for the `Bulk mode configured for consumer` log at startup.

## Safety guarantees

***

These mechanisms keep the Bulk Recorder safe:

### Idempotency

Every bulk insert uses `ON CONFLICT (id) DO NOTHING`. If a message arrives twice (from a retry, a redelivery, or a network fault), PostgreSQL drops the duplicate.

### Deadlock prevention

Before each bulk insert, Midaz sorts the record IDs. All concurrent writers then acquire locks in the same order. This removes the most common source of PostgreSQL deadlocks under high concurrency.

### Internal chunking

Midaz splits large batches into chunks that fit within PostgreSQL's 65,535-parameter limit per query. Each `INSERT` carries at most 1,000 rows.

## When to use

***

**Use Bulk Recorder when:**

* You process high volumes of transactions (hundreds or thousands per second).
* Your workload includes batch operations like mass payouts, settlements, or data migrations.
* You already use async transaction processing (`RABBITMQ_TRANSACTION_ASYNC=true`).
* You want to reduce database load and connection pressure.

**Keep it disabled when:**

* Your volume is low enough that individual inserts are not a bottleneck.
* You debug transaction processing and want a simpler, message-by-message flow.


# Closing a customer account
Source: https://docs.lerian.studio/en/products/midaz/closing-a-customer-account

Follow the eight-step flow to freeze, settle, close, and archive a customer account across Ledger and CRM in line with BACEN account closure and audit requirements.

To close a customer account in Midaz, you work across two areas: the **Ledger** (accounts and balances) and **CRM** (holders and alias accounts). BACEN rules make account closure a regulated event, so the order matters. Stop new credits first, then settle pending activity and return any remaining funds. Then close each account. The close operation refuses an account that still holds funds. Archive the CRM records last.

This guide covers the full closure flow, from the [Holder](/en/products/midaz/crm/holders) to its [Alias Accounts](/en/products/midaz/crm/alias-accounts). You can run the flow two ways. **[Via API](#via-api)** gives you the endpoint, an example payload, and the compliance rationale for each step. **[Via Console](#via-console)** gives you the same steps as point-and-click actions in the Midaz Console.

> [!WARNING]
>
> Follow the steps in order. Do not archive CRM records before you close the accounts.

## Overview

***

The closure flow has eight steps, grouped into three phases:

| Phase | Steps | Goal |
| :- | :- | :- |
| **1. Freeze** | 1–2 | Mark the Holder inactive and stop new credits at the balance level. |
| **2. Settle and zero** | 3–4 | Clear pending activity and return remaining funds to the customer. |
| **3. Close and archive** | 5–8 | Close the Ledger Accounts and archive CRM records under retention policy. |

> [!NOTE]
>
> Throughout this guide, `{organization_id}` and `{ledger_id}` identify the Midaz Organization and Ledger that own the accounts. This guide abbreviates the paths to `/v1/.../accounts/{accountId}` and `/v2/.../accounts/{accountId}` for readability.

## Prerequisites

***

Before you start, make sure you have:

* The `holderId` of the customer to offboard.
* The `accountId` values linked to that Holder across every Ledger in the Organization. Retrieve them with `GET /v2/organizations/{organization_id}/holders/{holder_id}/accounts`. The response is paginated, so retrieve every page. Add the optional `ledger_id` query parameter only when you need to narrow the list to one Ledger.
* The `instrument_id` of each Alias Account, mapped to its corresponding `accountId`. List the Holder's instruments with `GET /v2/organizations/{organization_id}/instruments?holder_id={holder_id}` (also paginated) and use each instrument's `accountId` field to map it to the Ledger Account. Steps 6 and 7 target these `instrument_id` values.
* Confirmation from your compliance team that you can end the customer relationship (no legal holds, open disputes, or pending regulatory requirements).
* Appropriate API credentials with permission to modify holders, instruments, balances, and accounts. Steps 6 and 7 update and delete instruments, so the credentials must carry `patch` and `delete` access on the `instruments` resource. Step 5 needs `post` and `delete` access on the `accounts` resource.

> [!WARNING]
>
> Closing an account cannot be undone. Before you proceed, confirm there are no active products or open obligations.

## Via API

***

Run the full closure flow programmatically. Each step lists the endpoint, an example payload, and the compliance rationale.

### Step 1: Freeze the Holder

Mark the Holder as inactive to record the closure across your systems. Update the Holder and set the `status` field on its person profile to an inactive value.

```http theme={null}
PATCH /v2/organizations/{organization_id}/holders/{holder_id}
```

```json theme={null}
{
  "naturalPerson": {
    "status": "INACTIVE"
  }
}
```

> [!NOTE]
>
> Marking the Holder inactive is a record change, not a deletion. The Holder record stays fully readable for audit. This status does not block new credits on its own. Step 2 blocks inflows at the balance level. For a legal person, set `legalPerson.status` instead.

### Step 2: Block credits on the accounts

For each account linked to the Holder, prevent new funds from entering. First, list the [Balances](/en/products/midaz/balances) of the account. Then update each balance to disable receiving. If a balance has a non-zero `overdraftUsed`, repay it first: a balance that refuses inflows also refuses the repayment.

**Retrieve the account balances:**

```http theme={null}
GET /v1/.../accounts/{accountId}/balances
```

**For each `balanceId` returned, block incoming funds:**

```http theme={null}
PATCH /v1/.../balances/{balanceId}
```

```json theme={null}
{
  "allowReceiving": false
}
```

> [!WARNING]
>
> Repeat this step for **every** `balanceId` on **every** account belonging to the Holder. A single balance left open can still receive credits and block closure later.

> [!TIP]
>
> When you set `allowReceiving` to `false`, the balance blocks new inflows but still allows outflows. This is exactly what you need in Step 4 to return the remaining balance to the customer. For details on the permission flags, see [Balances](/en/products/midaz/balances).

### Step 3: Settle pending activity

Before you can zero a balance, the account must have no in-flight movements.

* **Check for transactions in processing.** Confirm the account has no pending or uncommitted transactions. Commit or cancel them as appropriate using [Commit a pending transaction](/en/reference/products/midaz/v2/commit-transaction) or [Cancel a pending transaction](/en/reference/products/midaz/v2/cancel-transaction).

> [!WARNING]
>
> The close operation in Step 5 refuses an account whose funds a pending transaction still holds.

### Step 4: Zero the balance

Return any remaining funds to the customer (the account holder) and confirm `available = 0`, `onHold = 0`, and `overdraftUsed = 0` on every balance.

* If a balance owes [fee debt](/en/products/midaz/fees/fee-debt), settle it first with [Collect open fee debts](/en/reference/products/midaz/v2/collect-a-balance-s-open-fee-debts). The close operation refuses a balance that owes fee debt (`0527`).
* Record a **return transaction** that moves the remaining `available` amount from each customer account to the holder's designated destination (for example, an external settlement account). Use [Create a transaction](/en/reference/products/midaz/v1/create-transaction-json).
* **Confirm `available = 0`, `onHold = 0`, and `overdraftUsed = 0`** on every balance of every account in the Ledger before you proceed. You can check this with [Retrieve balances by account](/en/reference/products/midaz/v2/get-all-balances-by-account-id).

> [!WARNING]
>
> The close operation refuses an account with any balance whose `available`, `onHold`, or `overdraftUsed` amount is not exactly zero.

### Step 5: Close the Ledger Accounts in Midaz

After you zero the balances and clear pending activity, close each Ledger Account.

```http theme={null}
POST /v2/.../accounts/{accountId}/close
```

The request takes no body. A successful request returns `204 No Content`, and every later read of the account shows the closing instant in `closedAt`. Repeat for every account linked to the Holder. See [Close an account](/en/reference/products/midaz/v2/close-account) for the full contract and the [Midaz error list](/en/reference/products/midaz/error-list) for each refusal.

Then delete each closed account with `DELETE /v2/.../accounts/{accountId}`. Step 8 refuses to archive a Holder that still owns an account that is not deleted. See [Delete an account](/en/reference/products/midaz/v2/delete-account).

> [!NOTE]
>
> Deleting an account is a logical removal. Its transactions remain available for audit and reporting. Midaz refuses every later movement on a closed account, and unblocking the account does not reopen it. An external account cannot be closed.

### Step 6: Register the closing date on the alias

Record the official closure date on the Holder's Alias Account so the CRM and any regulatory exports reflect when the relationship ended.

```http theme={null}
PATCH /v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}
```

```json theme={null}
{
  "bankingDetails": {
    "closingDate": "2026-06-09"
  }
}
```

> [!NOTE]
>
> The `closingDate` field lives in the `bankingDetails` object of the Alias Account and uses `YYYY-MM-DD` format. See [Alias Accounts](/en/products/midaz/crm/alias-accounts) for the full field reference. BACEN account-lifecycle reporting needs an accurate closing date.

### Step 7: Archive the alias accounts in CRM

Archive each Alias Account in CRM. Use a **soft delete**. It removes the record from active use but keeps it for the regulatory retention period.

```http theme={null}
DELETE /v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}
```

> [!WARNING]
>
> Do **not** pass `hard_delete=true`. A regulated closure must archive (soft-delete) the record and keep it. It must not erase the record permanently. See [Delete an instrument](/en/reference/products/midaz/v2/delete-instrument).

### Step 8: Archive the Holder in CRM

After you archive all of its alias accounts, archive the Holder itself with a soft delete.

```http theme={null}
DELETE /v2/organizations/{organization_id}/holders/{holder_id}
```

> [!WARNING]
>
> As in Step 7, omit `hard_delete=true`. Keep the Holder record under the applicable retention policy for audit and regulatory inspection. See [Delete a holder](/en/reference/products/midaz/v2/delete-holder).

## Via Console

***

Run the same eight-step closure flow from the [Midaz Console](/en/products/midaz/console/midaz-module). The Console covers most of the flow point-and-click, but blocking credits (Step 2) and closing the accounts (Step 5) require the API. Each step below notes the equivalent API step on this page.

> [!WARNING]
>
> The order is the same as the API flow. Do not archive CRM records before you close the accounts.

### Step 1: Freeze the Holder

Mark the Holder as inactive to record the closure. This is a record change and does not block new credits on its own.

**Step 1**

From the **Holders** page, find the Holder to close.

**Step 2**

Click the three dots () in the **Actions** column, and select **Edit**.

**Step 3**

In the Holder form, set the **Status** to **Inactive**.

**Step 4**

Confirm the update.

> [!NOTE]
>
> Marking the Holder inactive is a record change, not a deletion. The record stays fully readable for audit. It does not block new credits on its own. Step 2 blocks inflows at the balance level. See [Editing a Holder](/en/products/midaz/console/crm-editing-a-holder).

### Step 2: Block credits on the accounts

> [!WARNING]
>
> **This step requires the API. The Console does not support editing balance flags after account creation.** The Console lets you set `allowReceiving` only when you first create an Account, not when you edit an existing balance. Use the API to disable receiving on every balance.
>
> Follow [Step 2: Block credits on the accounts](#step-2-block-credits-on-the-accounts) in the Via API section.

For each account linked to the Holder, use the API to set `allowReceiving` to `false` on every `balanceId`. This blocks new inflows while outflows remain available for the return transaction in Step 4. Repay any non-zero `overdraftUsed` before this step.

### Step 3: Settle pending activity

Confirm there are no in-flight movements before you zero any balance.

**Step 1**

From the **Transactions** page, filter by the accounts linked to the Holder. Confirm the account has no pending or uncommitted transactions, and commit or cancel any that are in flight.

**Step 2**

Review any pending transactions and commit or cancel them as appropriate.

### Step 4: Zero the balance

Return any remaining funds to the customer and confirm `available = 0`, `onHold = 0`, and `overdraftUsed = 0` on every balance.

**Step 1**

From the **Transactions** page, click **New Transaction**. Create a **return transaction** that moves the remaining `available` amount from each customer account to the holder's designated destination, for example an external settlement account. See [Creating a Transaction](/en/products/midaz/console/creating-a-transaction).

**Step 2**

Open each account and confirm **available = 0**, **onHold = 0**, and **overdraftUsed = 0** before you continue.

> [!WARNING]
>
> The close operation refuses an account with any balance whose `available`, `onHold`, or `overdraftUsed` amount is not exactly zero.

### Step 5: Close the Ledger Accounts in Midaz

> [!WARNING]
>
> **Closing requires the API.** Follow [Step 5: Close the Ledger Accounts in Midaz](#step-5-close-the-ledger-accounts-in-midaz) in the Via API section.

Then delete each closed account:

**Step 1**

From the **Accounts** page, find the Account linked to the Holder, click the three dots () in the **Actions** column, and select **Delete**.

**Step 2**

A confirmation dialog will appear. Click **Confirm** to finalize the deletion.

**Step 3**

Repeat for every account linked to the Holder.

See [Deleting an Account](/en/products/midaz/console/deleting-an-account).

### Step 6: Register the closing date on the alias

Record the official closure date on the Holder's Alias Account so the CRM and regulatory exports reflect when the relationship ended.

**Step 1**

From the **Alias Accounts** page, find the alias account to update, click the three dots () in the **Actions** column, and select **Edit**.

**Step 2**

In the Alias Account form, set the **Closing Date** (in `bankingDetails`) to the official closure date using `YYYY-MM-DD` format.

**Step 3**

Confirm the update.

> [!NOTE]
>
> BACEN account-lifecycle reporting needs an accurate closing date. See [Editing an Alias Account](/en/products/midaz/console/crm-editing-alias-account).

### Step 7: Archive the alias accounts in CRM

Archive each Alias Account with a **soft delete**. It removes the record from active use but keeps it for the regulatory retention period.

**Step 1**

From the **Alias Accounts** page, find the alias account to archive, click the three dots () in the **Actions** column, and select **Delete**.

**Step 2**

A confirmation dialog will appear. Click **Confirm** to finalize.

> [!WARNING]
>
> Use the standard (soft) delete. It archives and keeps the record instead of erasing it permanently. In regulated deployments, Midaz keeps the underlying record for the retention period. See [Deleting an Alias Account](/en/products/midaz/console/crm-deleting-alias-account).

### Step 8: Archive the Holder in CRM

After you archive all of its alias accounts, archive the Holder itself with a **soft delete**.

**Step 1**

From the **Holders** page, find the Holder to archive, click the three dots () in the **Actions** column, and select **Delete**.

**Step 2**

A confirmation dialog will appear. Click **Confirm** to finalize.

> [!WARNING]
>
> Use **Soft Delete** (the default), not Hard Delete. Keep the Holder record under the applicable retention policy for audit and regulatory inspection. See [Deleting a Holder](/en/products/midaz/console/crm-deleting-a-holder).

## BACEN compliance notes

***

* **Order is mandatory.** Freeze first (Steps 1–2), then settle and zero (Steps 3–4). This order stops funds from entering an account that is mid-closure.
* **Return funds before closing.** Return any residual balance to the customer before you close an account. The close operation refuses an account that holds funds.
* **Archive, don't erase.** A soft delete (no `hard_delete`) keeps Holders and alias accounts available for the regulatory retention period. Permanent deletion would remove evidence that BACEN audits need.
* **Record the closing date.** The `closingDate` on the alias gives regulators an authoritative timestamp for when the relationship ended.
* **Preserve the audit trail.** The operations of a deleted account remain queryable for reconciliation and reporting.

> [!TIP]
>
> Treat the eight steps as a single transaction from a compliance standpoint. If any step fails, pause and resolve it before you continue. Do not leave the customer in a partially closed state.


# Common mistakes to avoid
Source: https://docs.lerian.studio/en/products/midaz/common-mistakes-to-avoid

Avoid the typical pitfalls of Midaz implementations in Ledger structuring, Asset segregation, Accounting Routes, and external Accounts.

A reliable Midaz implementation depends on a few structural choices you make early. Avoid the common mistakes below to keep balances accurate and access under control.

## Poor Ledger structuring

***

* **Mistake:** You design ledgers that are too complex or too simplistic. For example, one ledger per customer creates fragmentation. Grouping unrelated processes creates confusion.
* **Best practice:** Structure ledgers around key business areas or legal entities. Use organized groupings instead of a one-to-one approach. This improves manageability and internal transfers.

## Not using Portfolios for clients

***

* **Mistake:** You treat each account in isolation instead of grouping it under a portfolio. This makes it hard to track all accounts linked to a single customer.
* **Best practice:** Create a portfolio for each customer. Group their accounts for simple queries, relationship management, and reporting.

## Mixing Assets in one Account

***

* **Mistake:** You manage multiple currencies or asset types in a single account, often through metadata overrides. This leads to unclear balances and reporting inconsistencies.
* **Best practice:** Assign one asset per account. If a customer needs multi-currency support, create separate accounts. Use naming conventions or portfolios to structure them.

## Inadequate Accounting Routes

***

* **Mistake:** You submit transactions without properly configured Operation Routes or Accounting Routes (Transaction Routes in the API). This causes inconsistent validations, misrouted funds, and unreliable ledger data.
* **Best practice:** Define Accounting Routes that reflect your business logic and compliance requirements, then set the Ledger setting `accounting.validateRoutes` to `true` to enforce them. Its default is `false`. Use Operation Routes to validate the source and destination of each operation when route validation is enabled.

## Overlooking External Account handling

***

* **Mistake:** You mishandle external transactions. For example, you delete an account when funds leave the bank, which causes imbalances.
* **Best practice:** Use the canonical `@external/<asset-code>` Account (for example, `@external/BRL`) for money that flows into and out of Midaz. This keeps the ledger balanced and matches real bank statements.

## Security lapses in access control

***

* **Mistake:** You grant excessive privileges to administrators or use shared accounts. This compromises security and accountability.
* **Best practice:** Implement role-based access control (RBAC) from the start. Do not use root or admin accounts for daily operations. Enforce strict credential management. Audit permissions regularly to prevent unauthorized privilege escalation.

## Improper error handling in transactions

***

* **Mistake:** You fail to handle failed transactions in the integration layer. This leads to false assumptions about successful operations.
* **Best practice:** Always validate transaction API responses. Implement retries with backoff for transient errors, and send the same `X-Idempotency` key on each retry. Log permanent failures. Make sure upstream systems, such as core banking applications, handle rejected transactions and notify the user.


# Community support
Source: https://docs.lerian.studio/en/products/midaz/community-support

Connect with the Midaz community on GitHub Discussions and Discord to ask questions and share feedback, or use GitHub Issues to report bugs.

Midaz is a mission-critical service. If you're using the Community version, this page outlines the channels where you can ask questions, report bugs, and share ideas.

> [!CAUTION]
>
> If you're an **Enterprise** institution, use the [**Lerian Support Portal**](/en/products/midaz/lerian-support-portal) to get guaranteed response times and access to our dedicated support team.

## GitHub Discussions

***

Use the [Discussions tab](https://github.com/LerianStudio/midaz/discussions) in our repository to:

* Ask questions or request help.
* Propose enhancements.
* Share use cases or feedback.
* Participate in existing threads.

We monitor this space regularly and encourage open conversation. Don’t be shy. Your question might help others too.

## Report a bug

***

Use [GitHub Issues](https://github.com/LerianStudio/midaz/issues) to report a bug. Include the behavior you observed, the expected result, and enough context for maintainers to reproduce it.

## Join our Discord

***

For real-time conversations, join the [Lerian Discord community](https://discord.gg/DnhqKwkGv3). This is the place for:

* Quick questions and peer support.
* Staying in the loop with the latest updates.
* Talking directly with maintainers and other users.

Look for the **#midaz** channel.

## Contribute

***

If you’re ready to go a step further:

* Fork the repo, make your changes, and submit a PR.
* Share your own plugin ideas or integrations.

All contributions are welcome, from fixing a typo to designing a new feature.

## Not sure where to start?

***

You don’t need permission to get involved.


# Midaz entities
Source: https://docs.lerian.studio/en/products/midaz/core-entities

See how Midaz core entities (Organizations, Ledgers, Assets, Portfolios, Accounts, Segments, and Balances) connect to support financial operations at scale.

This diagram shows how the main building blocks of Midaz connect to support financial operations at scale. Figure 1 gives an overview of how the system works.

![Midaz core building blocks and how its interconnected domains fit together to support financial operations at scale](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/midaz-entities-v3.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=bda0ca5101ade6a55c127a3375af6e62)

Figure 1. Midaz and its interconnected domains and modular structure.

## Core components

***

### Midaz

Midaz is at the center. It coordinates everything, from data persistence to business logic.

### Data Layer

All data flows into the persistent **data layer**. This layer gives the system durability, consistency, and performance.

## Domains and relationships

***

### Organizations

Each organization is a distinct environment in Midaz. It can hold one or many ledgers, based on how you structure your data.

### Ledgers

A ledger holds all financial activity. It tracks balances, stores assets, and processes transactions. Every ledger belongs to an organization.

From here, the system branches into:

* **Assets**: define the kind of value you track.
* **Portfolios**: group related accounts under a shared purpose.

### Assets

Assets define the units of value, like BRL, USD, points, or tokens. Each account uses one specific asset.

### Portfolios

Portfolios group accounts by business logic. You can create as many portfolios as you need to organize your financial structure.

### Accounts & Segments

An account can belong to a portfolio. **Segments** group accounts, so you can isolate data by customer, product, region, or any other dimension.

**Account Types** classify accounts by nature and purpose. They enable transaction routing and operational validation across account categories.

### Balance

A **Balance** represents the net amount an **Account** holds of a given **Asset** in a specific **Ledger**.

* An account can carry **multiple balances**. Each has a `balanceKey` (e.g. `default`, `collateral`, `operational`) to partition funds without splitting the account.
* An **external account** has only one balance (`default`).
* If you omit `balanceKey` in a transaction, Midaz uses the default balance.
* Midaz derives balance amounts from ledger operations. You can add and delete balances and change their settings.

### Transactions

A transaction moves value between accounts. Each transaction contains **operations** (debits and credits). This keeps your logic consistent, traceable, and aligned with your business model and accounting policies.

### Accounting Routes entities

The [Accounting Routes entities](/en/products/midaz/transaction-routing-entities) extend Midaz. They create a structured system that guarantees correct annotations and correct financial-flow directions.

It has two parts:

* **Operation Routes:** define atomic transaction behaviors. Each route sets how Midaz annotates and directs one financial movement, based on your business rules and accounting standards.
* **Accounting Routes:** orchestrate multiple Operation Routes into balanced financial events. When route validation is enabled in the ledger settings, they enforce the configured transaction structure. (The API calls this `transactionRoute`.)

This pair defines the transaction structure. When you enable route validation in the ledger settings, Midaz validates transactions against the configured route.

## Get help

***

> [!TIP]
>
> **Need help designing your Midaz setup?**
>
> Our consulting service can help you tailor the structure to your organization's needs. This applies whether you start from scratch or optimize an existing setup.
>
> [Contact us](https://lerian.studio/contact) to learn more.


# Key features
Source: https://docs.lerian.studio/en/products/midaz/core-features

Explore the core capabilities that make Midaz adaptable and scalable: native events, multi-asset support, segments, and double-entry accounting.

Midaz is a core ledger. Financial institutions use it to build, operate, and scale their transactions on a modular foundation. You keep full control of your stack.

Use Midaz to launch new financial products or to modernize existing processes. The features below show how the ledger records value, scales across organizations, and keeps balances consistent.

## Native event publisher

***

Midaz emits supported domain events through its configured streaming publisher. Configure and operate the delivery path required by your environment before relying on an event stream for downstream processing.

## Client segments

***

Group Accounts into ledger-scoped Segments. These persisted associations support scoped rules and operational grouping.

## Double-entry accounting

***

Midaz records Transactions as Operations, including debit, credit, hold, and release movements. When Accounting Route validation is enabled, configured routes validate applicable participation and posting rules.

## Multi-currency/asset support

***

Midaz supports transactions in multiple currencies and assets. You operate across different financial ecosystems from one ledger.

## Multi-organization/ledger support

***

One Midaz instance can run multiple Organizations and Ledgers. The domain model scopes financial resources by Organization and Ledger.

## N:N transactions

***

A single transaction can move value between many source and destination accounts. This N:N model supports complex business flows.

## Native race condition handling

***

Race conditions happen when multiple operations change the same balance at the same time. Midaz validates and updates all balances of a transaction in one atomic step. Transactions stay reliable and accurate under high concurrency.

## Wallets portfolio management

***

Group accounts into portfolios to manage them together. You get full visibility and control over assets and balances.

## Visual interface

***

A web console gives you a single place to manage transactions, configuration, and system insights.

> [!NOTE]
>
> In newer releases, **[Lerian Console](/en/platform/console/about-lerian-console)** provides the visual interface for Midaz. Midaz runs there as the **[Midaz Module](/en/products/midaz/console/midaz-module)**. If you run an older version, you may still have the standalone Midaz Console.


# Data model
Source: https://docs.lerian.studio/en/products/midaz/data-model

Reference the core tables and schemas that power Midaz, designed for developers and database administrators working close to the data.

> [!TIP]
>
> **This page is for developers and database administrators.** It contains detailed database schemas and table structures. For a business-level overview of Midaz entities and their relationships, see [About Midaz](/en/products/midaz/about-midaz).

Explore the core tables that power Midaz. As Midaz evolves, it may add new fields and tables.

Midaz keeps the tables on this page in two PostgreSQL databases:

* **Onboarding database**: `organization`, `ledger`, `asset`, `account_type`, `account`, `portfolio`, and `segment`.
* **Transaction database**: `balance`, `operation_route`, `operation`, `transaction_route`, and `transaction`.

Midaz stores the `metadata` of each entity in MongoDB, not in these tables. Column names are database names and can differ from the API field names.

## Tables

***

### Table: `organization`

| Column | Type | Description |
| :- | :- | :- |
| **id** | `uuid` | The unique identifier of the Organization. |
| **parent\_organization\_id** | `uuid` | The unique identifier of the parent Organization. |
| **legal\_name** | `text` | The legal name of the Organization. |
| **doing\_business\_as** | `text` | The trade name of the Organization. |
| **legal\_document** | `text` | The document of the Organization. |
| **address** | `jsonb` | The address of the Organization. |
| **status** | `text` | The status code. |
| **status\_description** | `text` | The description of the status. |
| **created\_at** | `timestamptz` | Timestamp of creation (UTC). |
| **updated\_at** | `timestamptz` | Timestamp of last update (UTC). |
| **deleted\_at** | `timestamptz` | Timestamp of soft deletion, if applicable (UTC). |

### Table: `ledger`

| Column | Type | Description |
| :- | :- | :- |
| **id** | `uuid` | The unique identifier of the Ledger. |
| **organization\_id** | `uuid` | The unique identifier of the Organization. |
| **name** | `text` | The name of the Ledger. |
| **status** | `text` | The status code. |
| **status\_description** | `text` | The description of the status. |
| **settings** | `jsonb` | The [Ledger settings](/en/products/midaz/ledgers#ledger-settings). |
| **created\_at** | `timestamptz` | Timestamp of creation (UTC). |
| **updated\_at** | `timestamptz` | Timestamp of last update (UTC). |
| **deleted\_at** | `timestamptz` | Timestamp of soft deletion, if applicable (UTC). |

### Table: `asset`

| Column | Type | Description |
| :- | :- | :- |
| **id** | `uuid` | The unique identifier of the Asset. |
| **organization\_id** | `uuid` | The unique identifier of the Organization. |
| **ledger\_id** | `uuid` | The unique identifier of the Ledger. |
| **name** | `text` | The name of the Asset. |
| **type** | `text` | The type of Asset (`currency`, `fiat`, `crypto`, `commodity`, `others`). |
| **code** | `text` | The code used to refer to the Asset. |
| **status** | `text` | The status code. |
| **status\_description** | `text` | The description of the status. |
| **created\_at** | `timestamptz` | Timestamp of creation (UTC). |
| **updated\_at** | `timestamptz` | Timestamp of last update (UTC). |
| **deleted\_at** | `timestamptz` | Timestamp of soft deletion, if applicable (UTC). |

### Table: `account_type`

| Column | Type | Description |
| :- | :- | :- |
| **id** | `uuid` | The unique identifier of the Account Type. |
| **organization\_id** | `uuid` | The unique identifier of the Organization. |
| **ledger\_id** | `uuid` | The unique identifier of the Ledger. |
| **name** | `varchar(100)` | Name of the Account Type. |
| **description** | `text` | Description of the Account Type. |
| **key\_value** | `varchar(50)` | The key that identifies the Account Type in the Ledger. |
| **default\_direction** | `varchar(16)` | The default [balance direction](/en/products/midaz/balance-overdraft) for Accounts of this type: `credit` or `debit`. |
| **created\_at** | `timestamptz` | Timestamp of creation (UTC). |
| **updated\_at** | `timestamptz` | Timestamp of last update (UTC). |
| **deleted\_at** | `timestamptz` | Timestamp of soft deletion, if applicable (UTC). |

### Table: `account`

| Column | Type | Description |
| :- | :- | :- |
| **id** | `uuid` | The unique identifier of the Account. |
| **organization\_id** | `uuid` | The unique identifier of the Organization. |
| **ledger\_id** | `uuid` | The unique identifier of the Ledger. |
| **asset\_code** | `text` | The code used to refer to the Asset. |
| **name** | `text` | The name of the Account. |
| **alias** | `text` | The alias that transactions use to address the Account. |
| **type** | `text` | The type of account. |
| **parent\_account\_id** | `uuid` | The unique identifier of the Parent Account. |
| **entity\_id** | `text` | A reference to a record in an external system. |
| **holder\_id** | `uuid` | The unique identifier of the Holder that owns the Account. |
| **holder\_check\_skipped** | `boolean` | `true` when a `skip` flag bypassed the Holder check at creation. |
| **portfolio\_id** | `uuid` | The unique identifier of the Portfolio. |
| **segment\_id** | `uuid` | The unique identifier of the Segment. |
| **status** | `text` | The status code. |
| **status\_description** | `text` | The description of the status. |
| **blocked** | `boolean` | `true` when the Account is blocked. |
| **closed\_at** | `timestamptz` | Timestamp of closing, if applicable (UTC). |
| **created\_at** | `timestamptz` | Timestamp of creation (UTC). |
| **updated\_at** | `timestamptz` | Timestamp of last update (UTC). |
| **deleted\_at** | `timestamptz` | Timestamp of soft deletion, if applicable (UTC). |

### Table: `portfolio`

| Column | Type | Description |
| :- | :- | :- |
| **id** | `uuid` | The unique identifier of the Portfolio. |
| **organization\_id** | `uuid` | The unique identifier of the Organization. |
| **ledger\_id** | `uuid` | The unique identifier of the Ledger. |
| **entity\_id** | `text` | The unique identifier of the user responsible for the Portfolio. |
| **name** | `text` | The name of the Portfolio. |
| **status** | `text` | The status code. |
| **status\_description** | `text` | The description of the status. |
| **created\_at** | `timestamptz` | Timestamp of creation (UTC). |
| **updated\_at** | `timestamptz` | Timestamp of last update (UTC). |
| **deleted\_at** | `timestamptz` | Timestamp of soft deletion, if applicable (UTC). |

### Table: `segment`

| Column | Type | Description |
| :- | :- | :- |
| **id** | `uuid` | The unique identifier of the Segment. |
| **organization\_id** | `uuid` | The unique identifier of the Organization. |
| **ledger\_id** | `uuid` | The unique identifier of the Ledger. |
| **name** | `text` | The name of the Segment. |
| **status** | `text` | The status code. |
| **status\_description** | `text` | The description of the status. |
| **created\_at** | `timestamptz` | Timestamp of creation (UTC). |
| **updated\_at** | `timestamptz` | Timestamp of last update (UTC). |
| **deleted\_at** | `timestamptz` | Timestamp of soft deletion, if applicable (UTC). |

### Table: `balance`

| Column | Type | Description |
| :- | :- | :- |
| **id** | `uuid` | The unique identifier of the Balance. |
| **organization\_id** | `uuid` | The unique identifier of the Organization. |
| **ledger\_id** | `uuid` | The unique identifier of the Ledger. |
| **account\_id** | `uuid` | The unique identifier of the Account. |
| **alias** | `text` | The alias of the Account. |
| **key** | `text` | The balance key. The default balance uses `default`. |
| **asset\_code** | `text` | The code used to refer to the Asset. |
| **available** | `decimal` | The available amount. |
| **on\_hold** | `decimal` | Amount on hold/reserved. |
| **version** | `bigint` | Balance version. |
| **account\_type** | `text` | The type of account. |
| **allow\_sending** | `boolean` | If true, indicates that sending transactions is permitted. |
| **allow\_receiving** | `boolean` | If true, indicates that receiving transactions is permitted. |
| **direction** | `varchar(16)` | The [balance direction](/en/products/midaz/balance-overdraft): `credit` or `debit`. |
| **overdraft\_used** | `decimal` | The overdraft amount in use. |
| **settings** | `jsonb` | The balance settings, such as the overdraft limit. |
| **created\_at** | `timestamptz` | Timestamp of creation (UTC). |
| **updated\_at** | `timestamptz` | Timestamp of last update (UTC). |
| **deleted\_at** | `timestamptz` | Timestamp of soft deletion, if applicable (UTC). |

### Table: `operation_route`

| Column | Type | Description |
| :- | :- | :- |
| **id** | `uuid` | The unique identifier of the Operation Route. |
| **organization\_id** | `uuid` | The unique identifier of the Organization. |
| **ledger\_id** | `uuid` | The unique identifier of the Ledger. Empty for a route that belongs to the Organization. |
| **title** | `varchar(255)` | Short text summarizing the purpose of the operation. Used as an entry note for identification. |
| **description** | `varchar(250)` | Detailed description of the Operation Route purpose and usage. |
| **code** | `text` | The code of the Operation Route. |
| **operation\_type** | `varchar(20)` | The entry's applicability: `source`, `destination`, or `bidirectional`. |
| **account\_rule\_type** | `varchar(20)` | The rule that selects the account: `alias` or `account_type`. |
| **account\_rule\_valid\_if** | `text` | The values that the account rule accepts. |
| **accounting\_entries** | `jsonb` | The [accounting entries](/en/products/midaz/accounting-entries) of the route. |
| **created\_at** | `timestamptz` | Timestamp of creation (UTC). |
| **updated\_at** | `timestamptz` | Timestamp of last update (UTC). |
| **deleted\_at** | `timestamptz` | Timestamp of soft deletion, if applicable (UTC). |

### Table: `operation`

| Column | Type | Description |
| :- | :- | :- |
| **id** | `uuid` | The unique identifier of the Operation. |
| **transaction\_id** | `uuid` | The unique identifier of the Transaction. |
| **organization\_id** | `uuid` | The unique identifier of the Organization. |
| **ledger\_id** | `uuid` | The unique identifier of the Ledger. |
| **account\_id** | `uuid` | The unique identifier of the Account. |
| **account\_alias** | `text` | The alias for the account used in the operation. |
| **balance\_id** | `uuid` | The unique identifier of the Balance. |
| **balance\_key** | `text` | The key of the Balance. |
| **description** | `text` | Description of the operation. |
| **type** | `text` | The type of the operation, such as `DEBIT`, `CREDIT`, `ON_HOLD`, or `RELEASE`. |
| **direction** | `varchar(10)` | The direction of the operation: `debit` or `credit`. |
| **asset\_code** | `text` | The code used to refer to the Asset. |
| **amount** | `decimal` | The amount of the operation. |
| **available\_balance** | `decimal` | The available amount before the operation. |
| **on\_hold\_balance** | `decimal` | The amount on hold before the operation. |
| **available\_balance\_after** | `decimal` | The available amount after the operation. |
| **on\_hold\_balance\_after** | `decimal` | The amount on hold after the operation. |
| **balance\_version\_before** | `bigint` | The balance version before the operation. |
| **balance\_version\_after** | `bigint` | The balance version after the operation. |
| **balance\_affected** | `boolean` | `false` when the operation does not change the balance, as in an annotation transaction. |
| **chart\_of\_accounts** | `text` | The name of the chart of accounts that the operation belongs to. |
| **route** | `text` | **\[Deprecated]** Legacy route identifier, kept for backward compatibility. Use `route_id` instead. |
| **route\_id** | `uuid` | Identifier of the route used by the operation (the current route field). |
| **route\_code** | `text` | The code of the accounting rubric that Midaz resolved for the operation. |
| **route\_description** | `text` | The description of the accounting rubric that Midaz resolved for the operation. |
| **snapshot** | `jsonb` | System context of the operation, such as the overdraft use before and after it. |
| **status** | `text` | The status code. |
| **status\_description** | `text` | The description of the status. |
| **recorded\_at** | `timestamptz` | Timestamp of when the ledger recorded the operation (UTC). |
| **created\_at** | `timestamptz` | Timestamp of creation (UTC). |
| **updated\_at** | `timestamptz` | Timestamp of last update (UTC). |
| **deleted\_at** | `timestamptz` | Timestamp of soft deletion, if applicable (UTC). |

### Table: `transaction_route`

| Column | Type | Description |
| :- | :- | :- |
| **id** | `uuid` | The unique identifier of the Transaction Route. |
| **organization\_id** | `uuid` | The unique identifier of the Organization. |
| **ledger\_id** | `uuid` | The unique identifier of the Ledger. Empty for a route that belongs to the Organization. |
| **title** | `varchar(255)` | Short text summarizing the purpose of the transaction. Used as an entry note for identification. |
| **description** | `varchar(250)` | A description for the Transaction Route. |
| **created\_at** | `timestamptz` | Timestamp of creation (UTC). |
| **updated\_at** | `timestamptz` | Timestamp of last update (UTC). |
| **deleted\_at** | `timestamptz` | Timestamp of soft deletion, if applicable (UTC). |

The `operation_transaction_route` table links each Transaction Route to its Operation Routes.

### Table: `transaction`

| Column | Type | Description |
| :- | :- | :- |
| **id** | `uuid` | The unique identifier of the transaction. |
| **parent\_transaction\_id** | `uuid` | The unique identifier of the parent transaction, such as the transaction that a revert reverses. |
| **group\_id** | `uuid` | Links the transactions that one cross-ledger request creates. |
| **organization\_id** | `uuid` | The unique identifier of the Organization. |
| **ledger\_id** | `uuid` | The unique identifier of the Ledger. |
| **description** | `text` | Description of the transaction. |
| **route** | `text` | **\[Deprecated]** Legacy route identifier, kept for backward compatibility. Use `route_id` instead. |
| **route\_id** | `uuid` | Identifier of the route used by the transaction (the current route field). |
| **status** | `text` | The status code. |
| **status\_description** | `text` | The description of the status. |
| **amount** | `decimal` | The sent amount. |
| **asset\_code** | `text` | The code used to refer to the Asset. |
| **chart\_of\_accounts\_group\_name** | `text` | The name of the chart of accounts group used to categorize the operations of a transaction. |
| **body** | `jsonb` | Internal copy of the transaction request. |
| **fees\_skipped** | `boolean` | `true` when a `skip` flag bypassed the fee calculation. |
| **tracer\_skipped** | `boolean` | `true` when a `skip` flag bypassed Tracer. |
| **created\_at** | `timestamptz` | Timestamp of creation (UTC). |
| **updated\_at** | `timestamptz` | Timestamp of last update (UTC). |
| **deleted\_at** | `timestamptz` | Timestamp of soft deletion, if applicable (UTC). |

## Data model

***

*Figure 1* shows the core Midaz tables and their relationships. Use it to guide data handling and integration.

![Core Midaz database tables and the relationships between them, as a reference for data handling and integration](https://mintcdn.com/lerian-49cb71fc/0kJvev-xNu0CYwa1/images/en/d2/midaz-data-model-v3.svg?fit=max\&auto=format\&n=0kJvev-xNu0CYwa1\&q=85\&s=a5eb57d19d7615145bcf1d20b23c419c)

Figure 1. Midaz tables and their relations.


# Event publisher
Source: https://docs.lerian.studio/en/products/midaz/event-publisher

Publish Midaz transaction lifecycle CloudEvents to Kafka-compatible brokers for downstream integrations.

## Uses for transaction lifecycle events

***

Transaction lifecycle events let downstream systems react without coupling to the transaction API. Use them for notifications, reconciliation, analytics, and compliance workflows.

For the complete catalog and consumer contract, see [Receiving Midaz events](/en/products/midaz/receiving-midaz-events).

## Enable transaction lifecycle events

***

Midaz publishes lifecycle CloudEvents to a Kafka-compatible broker. Publication is off by default. Configure the ledger application with a broker list and its CloudEvents source:

```env theme={null}
STREAMING_ENABLED=true
STREAMING_BROKERS=<broker-list>
STREAMING_CLOUDEVENTS_SOURCE=ledger
```

You must set `STREAMING_CLOUDEVENTS_SOURCE` when you enable streaming. The ledger, CRM, and Fees binary uses `ledger`. The transaction facts publish to `lerian.streaming.ledger`.

If you enable streaming without `STREAMING_BROKERS`, Midaz refuses to start. When streaming is off, Midaz uses a no-op emitter.

## Lifecycle events

***

Midaz emits these public facts for eligible persisted transaction state changes:

| Fact | When Midaz emits it |
| - | - |
| `transaction.posted` | A newly created transaction is `APPROVED` and has no parent transaction. |
| `transaction.reverted` | A newly created `APPROVED` transaction has a parent transaction. |
| `transaction.committed` | A transaction status update reaches `APPROVED`. |
| `transaction.canceled` | A transaction status update reaches `CANCELED`. |

Midaz does not emit a lifecycle fact for a newly created `PENDING` transaction, a `NOTED` transaction, or a no-op state change. A pending transaction emits only when a later status update commits or cancels it.

When one request moves value across ledgers, Midaz also emits one fact for the whole movement: `transaction_group.posted`, `transaction_group.committed`, `transaction_group.canceled`, or `transaction_group.reverted`.

## Consume events

***

Subscribe to `lerian.streaming.ledger` and select the facts you need using the CloudEvents headers. Do not infer event type from the Kafka topic: Midaz uses one application topic for ledger, CRM, and Fees facts.

Use the producer manifest as the deployment-time contract:

```http theme={null}
GET /v1/streaming/manifest
```

The manifest remains available even when publication is off. The [Midaz event reference](/en/reference/events/midaz) lists the event payloads.

> [!NOTE]
>
> Event publication is best effort and does not make the broker write transactional with the ledger mutation. Consumers must be idempotent and deduplicate on `(ce-source, ce-id)`.


# FAQ
Source: https://docs.lerian.studio/en/products/midaz/faq

Answers to common Lerian and Midaz questions on API pagination limits, SaaS data isolation, tenant JWT scoping, and multi-organization platform configuration.

## Lerian APIs

***

This section answers common questions about Lerian's APIs.

> **Is there a maximum number of records per page in API listings? Can I increase this limit?**
>
> Yes. In Midaz, the default maximum is **100** records per page. This limit keeps performance consistent and controls the data volume in each request. To raise it, set the `MAX_PAGINATION_LIMIT` environment variable in your deployment configuration. Most listings accept larger page sizes after you restart the application.
>
> **Important**: A larger page size can slow response times, especially with large datasets. Test in staging before you change production.

## Tenants on Lerian Cloud

***

These questions cover data isolation and tenant scoping on Lerian Cloud.

> **Is my data isolated from other institutions in SaaS?**
>
> Yes. Your data is isolated from every other tenant, with its own credentials. The platform resolves your tenant from the JWT on every request. There is no way to access another tenant's data through the API.

> **Do I need to pass a tenant ID in my API requests?**
>
> No. The JWT access token you receive during authentication carries your tenant context. The platform resolves it automatically. You do not need to include a tenant identifier in headers or request bodies.

> **Can I have multiple Organizations under a single tenant?**
>
> Yes. A tenant can contain multiple Organizations. Each Organization has its own Ledgers, accounts, and transactions. The platform scopes all of them to your tenant automatically.

> **Is the API different between SaaS and self-hosted deployments?**
>
> No. The API surface is identical: same endpoints, same payloads, same responses. SaaS requires authentication on every request, and your token scopes all operations to your tenant.

## Midaz

***

These questions cover Organizations, Ledgers, Accounts, Transactions, and more in Midaz.

### Organizations

> **Do different Organizations communicate with each other?**
>
> Each Organization operates independently. A cross-ledger transaction can move value between Ledgers of different Organizations in the same tenant.

> **Can I use a single license across multiple Organizations?**
>
> See [Lerian's License](/en/start-here/evaluate-and-deploy/lerians-license) for how each license applies to Organizations.

> **Can an Organization have multiple Plugins?**
>
> Yes. An Organization can have more than one Plugin.

> **Can an Organization have multiple Ledgers?**
>
> Yes. An Organization can manage multiple Ledgers.

> **Can I create transactions between a Parent Organization and a Child Organization?**
>
> You can create a **Parent Organization** and a **Child Organization**. Each Organization keeps its own Ledger and operates independently. To move value between their Ledgers, send one cross-ledger transaction. Every participating Ledger must set `settings.crossLedger.enabled` to `true`, and none can have `accounting.validateRoutes` set to `true`. You can also orchestrate the transfer with these steps:
>
> **Step 1**
>
> In the source ledger, create a transaction from the original account (**source**) to the asset's **external account** (distribute). This removes the value from the source ledger.
>
> **Step 2**
>
> In the destination ledger, create a second transaction. The **source** is now the asset's **external account**, and the destination is the receiving account (**distribute**).
>
> This pattern moves value between ledgers in different Organizations.

### Ledgers

> **Do different Ledgers communicate with each other?**
>
> Ledgers keep separate books. A cross-ledger transaction moves value between Ledgers that set `settings.crossLedger.enabled` to `true`.

> **How can I make transactions between Ledgers?**
>
> Send one `POST /v2/transactions/direct` or `POST /v2/transactions/hold` request with legs in each Ledger. Every participating Ledger must set `settings.crossLedger.enabled` to `true`. Midaz creates one balanced transaction per Ledger. You can also move the amount through an External Account in two steps:
>
> **Step 1**
>
> Ledger A -> External Account.
>
> **Step 2**
>
> External Account -> Ledger B.

> **Do I need a separate Ledger for each Plugin?**
>
> No. A single Ledger can support multiple Plugins. For example, one Ledger can handle both Exchange and Pix Plugins.

### Assets

> **Can an Asset be linked to multiple Accounts?**
>
> Yes. Many Accounts can use the same Asset. Each Asset also links to an External Account. Midaz creates that External Account automatically when you create the Asset.

> **What types of Assets can I use?**
>
> Midaz supports several Asset types:
>
> * *currency*: Traditional fiat currencies like BRL, USD, and EUR.
> * *fiat*: An alternative type for fiat currencies; like `currency`, the Asset code must follow ISO 4217.
> * *crypto*: Digital assets such as BTC, ETH, and other cryptocurrencies.
> * *commodity*: Tangible goods like gold, soybean, and oil.
> * *others*: Custom Assets, including loyalty points and tokenized securities.

### Portfolios

> **How does a Portfolio work?**
>
> A **Portfolio** groups accounts that belong to the same entity (**CPF/CNPJ**). For example, one CPF with two different `segmentId` values has two matching accounts. You create a Portfolio for that CPF to link both accounts under one structure.

### Accounts

> **Can an Account be associated with multiple Assets?**
>
> No. Each Account links to a single Asset. You cannot change this link.

> **What is an External Account?**
>
> An External Account receives funds from outside the Ledger. It brings money into the system.

> **How can I create an External Account?**
>
> Midaz creates an **External Account** automatically when you create an Asset. You can also create one yourself: send `type` as `external` with an `alias`.

> **Can an Account be linked to several Segments?**
>
> No. Each account links to only one Segment (`segmentId`).

> **Is there a limit to how many Accounts I can create in Midaz?**
>
> No. You can create as many Accounts as you need. Midaz sets no limit on the number of Accounts.

> **What is the process for adding funds to an account or performing a cash-in using money coming from outside the Ledger (Midaz) environment?**
>
> The balance top-up process works as follows:
>
> 1. When you create an Asset (for example, BRL) in the Midaz Ledger, Midaz also creates an External Account for that Asset.
> 2. This External Account mirrors the balances the institution holds outside Midaz. Those balances can sit in a PI account, a settlement account, a reserve account, or a traditional bank or payment account.
> 3. To deposit funds from outside the Midaz Ledger into a user account, follow these steps:
>    * Create a transaction with the External Account as the source and the target accounts as the destination.
>    * Midaz debits the External Account by the amount (so it becomes negative) and credits the destination accounts by the values in the transaction payload.

### Transactions

> **What is the minimum structure of a Transaction?**
>
> A Transaction must have at least two Operations. For example, a transfer of R\$ 100 from Account A to Account B has two operations:
>
> * **Operation 1:** Debit R\$ 100 from Account A.
> * **Operation 2:** Credit R\$ 100 to Account B.

> **Is it possible to generate a PDF transfer receipt containing the details of a completed transaction?**
>
> Lerian gives clients several ways to access transaction receipts:
>
> 1. **Via APIs**: retrieve transaction data through the APIs, then generate a visual receipt in any format you choose.
> 2. **With the Reporter**: extract transaction data and create custom visual receipts.
> 3. **Through the Console**: access transaction data directly in the Lerian Console.

### Entities

> **How can I create an Entity?**
>
> The `entityId` field accepts external IDs of up to 256 characters. Midaz does not validate their format. You can use the IDs that already exist in your database and integrate them into your system.

### Idempotency

> **Can I reuse an idempotency key across endpoints?**
>
> No. Scope each key to a single operation and endpoint.

> **What happens if I change the TTL on a retry?**
>
> Midaz uses only the TTL from the first request. A later change has no effect.

> **Will the replayed response always be identical?**
>
> Yes. For a completed request, Midaz returns the same result it stored from the first request. It also sets the `X-Idempotency-Replayed` header to `true`.

> **What's the default TTL if I don't send X-TTL?**
>
> The default TTL is **300 seconds** (5 minutes). Send the `X-TTL` header to set a custom value in seconds.

### Accounting in Midaz

> **How can I reflect my own Chart of Accounts in Midaz?**
>
> Midaz lets you mirror your organization's official **Chart of Accounts** in the platform. You configure two core features:
>
> * [Account Types](/en/products/midaz/accounts): create the logical categories from your chart, such as Assets, Liabilities, Revenue, and Expenses. Assign them to accounts in your ledger. When you enable account type validation (`validateAccountType`), the `type` field in the Accounts API must match a registered value.
> * [Accounting Routes](/en/products/midaz/transaction-routing-entities): use Operation Routes to validate each leg of a transaction. For example, a debit must come from an account of type `user_wallet`. Use Accounting Routes (the `transactionRoute` resource in the API) to define complete transaction patterns that match your accounting logic.
>
> Account Types and Accounting Routes together enforce your accounting rules at the ledger level. Midaz validates every transaction against your Chart of Accounts when you enable route validation (`validateRoutes`). You do not hardcode rules in your business logic.

## Plugins

***

Plugins extend Midaz with integration and process orchestration. They provide abstractions so you can focus on your business model instead of system logic outside your domain.

The questions below cover how plugins work, how you deploy them, and the options available.

> **What are Plugins?**
>
> Plugins are technologies that integrate into the Midaz ledger. They simplify process integration and orchestration. They provide abstractions so clients can focus on their business model. Clients do not build or manage system logic outside their domain.

> **How are plugins distributed?**
>
> After you contract a plugin, Lerian provides it. In the [BYOC model](/en/start-here/evaluate-and-deploy/deployment-models), the plugin runs in your infrastructure, next to your Midaz instance. Applications connect to each plugin according to its function.

> **What plugin options does Lerian offer?**
>
> Lerian provides two types of plugins, grouped by origin:
>
> * **Native Plugins:** Lerian develops and integrates these plugins into the Midaz ledger. Lerian provides full support for them.
> * **Marketplace Plugins:** Lerian's partners create these plugins for specific market niches. Lerian helps integrate them into Midaz. The partners provide and support them directly.

## Fees Engine

***

These questions cover Fees Engine. Fees Engine is a licensed Midaz capability that runs inside the unified ledger process.

### General Concepts

> **What is Fees Engine?**
>
> Fees Engine is part of Midaz. It runs in the Midaz ledger process to calculate fees for financial transactions. Configure and deploy it with Midaz. Learn more in the [Fees Engine overview](/en/products/midaz/fees/fees-engine-overview). It works across three main domains:
>
> * **Fee Packages (`/v2/organizations/{organization_id}/ledgers/{ledger_id}/packages`):** defines charging rules per transaction (flat fee, percentage, or whichever is greater).
> * **Billing Packages (`/v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages`):** defines periodic charges based on transaction volume or account maintenance.
> * **Calculation and estimation:** the Ledger evaluates fees during the transaction flow. Use `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/estimates` for a package-specific preview and `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate` for periodic billing.

> **How does Fees Engine fit into the Lerian ecosystem?**
>
> Fees Engine runs inside the Midaz ledger process. When a configured fee package applies, Midaz incorporates its fee calculations into the transaction. It uses ledger query use cases rather than an external HTTP connection to Midaz.

> **What do I need to send in every request to Fees Engine?**
>
> Fees endpoints are organization-scoped through the organization ID in the `/v2` URL path. The platform resolves tenant context from the authenticated request; send the authorization material required by your Access Manager configuration.
>
> ```
> Authorization: Bearer ***
> ```

> **What database does Fees Engine use for storage?**
>
> Fees Engine uses MongoDB for storage. Deletions follow the **soft-delete** pattern. Fees Engine does not remove records physically. It marks them with `deletedAt` instead. A deleted record does not appear in listings, but you can still audit it.

> **What Midaz version provides the integrated Fees module?**
>
> Midaz v4 exposes Fees inside the unified Ledger on `/v2`.

### Fee Packages

> **What is a Fee Package?**
>
> A Fee Package (`Package`) is a set of charging rules under one `feeGroupLabel`. Each package links to an **Organization + Ledger**, and optionally to a **Segment**. A package can contain several fees (`Fee` objects), each with its own calculation logic. Learn more about [Fee Packages](/en/products/midaz/fees/using-fee-engine).

> **How do I create a Fee Package?**
>
> Send a `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/packages` with the following body. See the [Create Package API reference](/en/reference/products/midaz/v2/create-package) for full details.
>
> ```json theme={null}
> {
>   "feeGroupLabel": "Digital Account Fees",
>   "segmentId": "{segment_id}",
>   "minimumAmount": "100.00",
>   "maximumAmount": "50000.00",
>   "transactionRoute": "{transaction_route_id}",
>   "enable": true,
>   "waivedAccounts": ["exempt-account-1", "exempt-account-2"],
>   "fees": {
>     "admin_fee": {
>       "feeLabel": "Administrative Fee",
>       "calculationModel": {
>         "applicationRule": "percentual",
>         "calculations": [
>           { "type": "percentage", "value": "1.50" }
>         ]
>       },
>       "referenceAmount": "originalAmount",
>       "priority": 1,
>       "isDeductibleFrom": true,
>       "creditAccount": "fee-revenue-account"
>     }
>   }
> }
> ```

> **Can a package be temporarily disabled?**
>
> Yes. Set the `enable` field to `false` when you create or update the package. Fees Engine skips a disabled package during fee calculation, even when the transaction context matches its scope.

> **How does the package scope work (minimumAmount / maximumAmount)?**
>
> Fees Engine applies the package only to transactions whose value falls within the `[minimumAmount, maximumAmount]` range. If the transaction value falls outside this range, Fees Engine ignores the package.
>
> **Example:** A package with `minimumAmount: 100` and `maximumAmount: 5000` charges fees only on transactions between 100 and 5,000.

> **Can I filter a package by transaction route?**
>
> Yes. Set the `transactionRoute` field to a transaction route ID. Fees Engine then considers the package only for transactions that carry that `routeId`.

> **What are waivedAccounts?**
>
> These are account aliases that the package **exempts** from fees. When every source account of a transaction is in `waivedAccounts`, Fees Engine does not apply the package fees. A waived account does not pay a package fee.
>
> ```json theme={null}
> "waivedAccounts": ["vip-account", "employee-account"]
> ```
>
> This package does not charge these accounts.

> **Do listing endpoints have pagination?**
>
> Yes. The listing endpoints (`GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/packages`, `GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages`) support the `limit` and `page` query parameters for pagination.
>
> ```
> GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/packages?limit=20&page=2
> ```

### Calculation Models

> **What calculation models are available?**
>
> The `applicationRule` field inside `calculationModel` defines how Fees Engine calculates the fee. See [Calculation Models](/en/products/midaz/fees/fee-engine-calculation) for full details. There are three options:
>
> | Rule | Description |
> | - | - |
> | `flatFee` | Fixed-amount fee |
> | `percentual` | Percentage fee based on the reference amount |
> | `maxBetweenTypes` | Evaluates 2 or more calculations; applies the **greater** result |

> **How do I configure a flat fee (flatFee)?**
>
> Use exactly **1 calculation** of type `flat`:
>
> ```json theme={null}
> "calculationModel": {
>   "applicationRule": "flatFee",
>   "calculations": [
>     { "type": "flat", "value": "5.00" }
>   ]
> }
> ```
>
> This charges a fixed 5.00 regardless of the transaction amount.

> **How do I configure a percentage fee (percentual)?**
>
> Use exactly **1 calculation** of type `percentage`:
>
> ```json theme={null}
> "calculationModel": {
>   "applicationRule": "percentual",
>   "calculations": [
>     { "type": "percentage", "value": "2.50" }
>   ]
> }
> ```
>
> This charges 2.5% of the transaction's reference amount.

> **How does maxBetweenTypes work?**
>
> `maxBetweenTypes` requires **2 or more calculations**. Fees Engine calculates each and applies the **greater result**.
>
> **Example:** Minimum fee of 3.00 or 1% of the value, whichever is greater:
>
> ```json theme={null}
> "calculationModel": {
>   "applicationRule": "maxBetweenTypes",
>   "calculations": [
>     { "type": "flat", "value": "3.00" },
>     { "type": "percentage", "value": "1.00" }
>   ]
> }
> ```
>
> For a 200 transaction: 1% = 2.00 vs. 3.00 flat → charges **3.00**.
> For a 500 transaction: 1% = 5.00 vs. 3.00 flat → charges **5.00**.

> **Can I mix multiple percentages in maxBetweenTypes?**
>
> Yes. You can include any combination of `flat` and `percentage`. Fees Engine evaluates all of them and applies the greatest. `flatFee` and `percentual` require exactly 1 calculation. Only `maxBetweenTypes` accepts 2 or more.

### Important Fields

> **What is referenceAmount and how does it affect calculation?**
>
> The `referenceAmount` defines **which value** Fees Engine calculates the fee on:
>
> * `originalAmount`: the original transaction value, **before** any fees.
>
> * `afterFeesAmount`: the transaction value **after** higher-priority fees apply.
>
> > [!NOTE]
> >
> > The fee with `priority: 1` runs first, so it **must** use `originalAmount`. No prior fees exist to consider.

> **What is isDeductibleFrom and when should I use it?**
>
> When `isDeductibleFrom: true`, Fees Engine deducts the fee from the amount the sender sends. The recipient receives the discounted amount.
>
> When `false`, Fees Engine charges the fee **separately**. The sender sends the full amount, and Fees Engine debits the fee apart.
>
> **Constraints:**
>
> * `isDeductibleFrom: true` requires `referenceAmount: originalAmount`
> * If the type is `percentage`: the value cannot exceed 100
> * If the type is `flat`: the value cannot exceed the package's `minimumAmount`

> **How does the priority field work?**
>
> The `priority` defines the **execution order** of fees within a package. Fees Engine runs lower values first.
>
> * `priority: 1` → executed first (must use `originalAmount`)
> * `priority: 2` → executed after, can use `afterFeesAmount`
>
> Use priorities to chain fees. For example, run an administrative fee on the original amount. Then run an IOF fee on the amount after the administrative fee.

> **What is creditAccount?**
>
> It is the alias of the ledger account that receives the fee revenue. Each fee can have a different `creditAccount`. This helps when different fees belong to different cost centers.
>
> ```json theme={null}
> "creditAccount": "admin-fee-revenue-account"
> ```

> **What are routeFrom and routeTo inside a fee?**
>
> These fields define the routes of the **accounting legs** that the fee charge generates. They are optional. They let you track the origin and destination of fee movements in the ledger.

### Billing Packages

> **What are Billing Packages?**
>
> Billing Packages are **periodic** charge packages, independent of per-transaction fee calculation. See [Billing Package examples](/en/products/midaz/fees/billing-package-examples) for use cases. There are two types:
>
> * **`volume`:** charges based on the **number of transactions** in a period, with tiered pricing.
> * **`maintenance`:** charges a **fixed fee per account** in a given scope.

> **When should I use volume billing?**
>
> Use volume billing to charge clients by the **number of processed transactions**. This is a common model for payment platforms with volume-based pricing. You define price tiers that apply as volume grows.
>
> ```json theme={null}
> {
>   "type": "volume",
>   "eventFilter": {
>     "transactionRoute": "PIX",
>     "status": "approved"
>   },
>   "pricingModel": "tiered",
>   "tiers": [
>     { "minQuantity": 0, "maxQuantity": 1000, "unitPrice": "0.50" },
>     { "minQuantity": 1001, "unitPrice": "0.30" }
>   ],
>   "assetCode": "BRL",
>   "debitAccountAlias": "client-account",
>   "creditAccountAlias": "volume-revenue-account"
> }
> ```

> **When should I use maintenance billing?**
>
> Use maintenance billing to charge a **fixed periodic fee per account**. For example, charge a monthly fee per active account. You specify the scope (`segmentId`, `portfolioId`, or `aliases`) and the fee amount.
>
> ```json theme={null}
> {
>   "type": "maintenance",
>   "feeAmount": "15.00",
>   "assetCode": "BRL",
>   "maintenanceCreditAccount": "maintenance-revenue-account",
>   "accountTarget": {
>     "segmentId": "{segment_id}"
>   }
> }
> ```
>
> > [!NOTE]
> >
> > `accountTarget` must have exactly **one** of the three fields: `segmentId`, `portfolioId`, or `aliases` (maximum 100 aliases).

> **How do tiers work in volume billing?**
>
> Tiers define the **unit price per tier** as volume increases. The rules are:
>
> 1. Must be **contiguous**: no gaps between tiers (`minQuantity` of the next = `maxQuantity` of the previous + 1).
> 2. Must not **overlap**.
> 3. For multiple tiers, the last tier must omit `maxQuantity`. A single bounded tier is accepted. A positive billable count outside that tier fails the entire calculation call.
>
> **Example of correct tiers:**
>
> ```json theme={null}
> "tiers": [
>   { "minQuantity": 0, "maxQuantity": 500, "unitPrice": "0.80" },
>   { "minQuantity": 501, "maxQuantity": 2000, "unitPrice": "0.60" },
>   { "minQuantity": 2001, "unitPrice": "0.40" }
> ]
> ```

> **What is freeQuota?**
>
> It is a **free allowance**. Fees Engine does not charge a set number of transactions before tiers apply. This helps pricing models with a minimum included volume.
>
> **Example:** `freeQuota: 100` means Fees Engine does not charge the first 100 transactions in the period.

> **What are discountTiers?**
>
> These are discount tiers for volume billing. They reduce the charged amount based on extra criteria. They complement the logic of the main `tiers`.

> **What is countMode in volume billing?**
>
> It defines **how Fees Engine counts transactions**:
>
> * `perRoute`: counts transactions by route (e.g., total approved Pix).
> * `perAccount`: counts transactions per individual account.

### Fee calculation and billing

> **How are transaction fees calculated in Midaz v4?**
>
> The Ledger evaluates fees in the transaction flow when a matching package applies. Use `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/estimates` for a package-specific preview.

> **Which v4 endpoints configure fees?**
>
> Configure transaction fee packages at `/v2/organizations/{organization_id}/ledgers/{ledger_id}/packages` and periodic billing packages at `/v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages`.

> **How do I calculate periodic billing?**
>
> Call `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate` after you configure billing packages. It processes the configured rules for that Ledger.

### Common Errors

> **What does error 0188 "originalAmount is required when priority is one" mean?**
>
> The fee with `priority: 1` must have `referenceAmount: "originalAmount"`. It is the first fee to run, so no prior fees exist to base the calculation on.
>
> **Fix:**
>
> ```json theme={null}
> {
>   "priority": 1,
>   "referenceAmount": "originalAmount"
> }
> ```

> **How do I fix error 0205 "originalAmount is required when isDeductibleFrom is true"?**
>
> Fees with `isDeductibleFrom: true` can only use `referenceAmount: "originalAmount"`. Update the field:
>
> ```json theme={null}
> {
>   "isDeductibleFrom": true,
>   "referenceAmount": "originalAmount"
> }
> ```

> **Why do I get error 0208 "calculation value flat invalid"?**
>
> When `isDeductibleFrom: true` and the type is `flat`, the fee value cannot exceed the package's `minimumAmount`. This prevents a fee that is larger than the minimum transaction value.
>
> **Example:** If `minimumAmount: 100`, the flat fee cannot exceed 100.

> **When does error 0207 "calculation value percentage invalid" occur?**
>
> This error occurs when `isDeductibleFrom: true`, the type is `percentage`, and the value is above 100. A deductible percentage fee of 100% would zero out the transaction. Values above 100 are invalid.

> **How do I fix error 0218 "tiers have a gap"?**
>
> Volume billing tiers must cover all ranges without gaps. Check that the `minQuantity` of each tier is exactly `maxQuantity + 1` of the previous tier.
>
> ```json theme={null}
> // ❌ Wrong — gap between 500 and 600
> { "minQuantity": 0, "maxQuantity": 500, "unitPrice": "0.80" },
> { "minQuantity": 600, "unitPrice": "0.40" }
>
> // ✅ Correct
> { "minQuantity": 0, "maxQuantity": 500, "unitPrice": "0.80" },
> { "minQuantity": 501, "unitPrice": "0.40" }
> ```

> **Error 0229: "Exactly one of segmentId, portfolioId, or aliases must be provided"**
>
> In maintenance billing, the `accountTarget` field accepts only **one** of the three options. Do not combine fields:
>
> ```json theme={null}
> // ❌ Wrong
> "accountTarget": {
>   "segmentId": "{segment_id}",
>   "portfolioId": "{portfolio_id}"
> }
>
> // ✅ Correct
> "accountTarget": {
>   "segmentId": "{segment_id}"
> }
> ```

> **Is there a limit on aliases in accountTarget?**
>
> Yes. The `aliases` field accepts a maximum of **100 aliases** per maintenance Billing Package.

> **Errors 0189 and 0191: flatFee needs exactly 1 calculation of type flat**
>
> The `applicationRule: "flatFee"` accepts exactly 1 calculation, and it must be of type `flat`. Do not use `percentage` with `flatFee`.
>
> ```json theme={null}
> // ✅ Correct
> "calculationModel": {
>   "applicationRule": "flatFee",
>   "calculations": [{ "type": "flat", "value": "10.00" }]
> }
> ```

> **Errors 0189 and 0190: percentual needs exactly 1 calculation of type percentage**
>
> Like `flatFee`, the `applicationRule: "percentual"` accepts exactly 1 calculation of type `percentage`.

> **Error 0201: "applicationRule maxBetweenTypes must have more than 1 calculation"**
>
> `maxBetweenTypes` requires at least 2 calculations, because it needs values to compare.

> **What should I check when the package is not applied to the transaction?**
>
> Diagnostic checklist (see also [Best Practices](/en/products/midaz/fees/fees-engine-best-practices)):
>
> * **`enable`:** is the package active (`enable: true`)?
> * **Ledger:** did you create the package in the ledger of the transaction?
> * **`minimumAmount` / `maximumAmount`:** is the transaction value within the range?
> * **`transactionRoute`:** if the package has `transactionRoute`, does the transaction use the same route?
> * **`segmentId`:** if the package is scoped to a segment, does the account belong to it?
> * **`waivedAccounts`:** is the account listed as exempt?

> **Can a deleted record be recovered?**
>
> Fees Engine soft-deletes records. It marks them with `deletedAt` and does not remove them from the database. The API has no restoration endpoint. Contact the Lerian team if you need to recover a deleted record.


# Foundation
Source: https://docs.lerian.studio/en/products/midaz/foundation-overview

Meet the foundation layer of Midaz: Organizations, Ledgers, and Assets, the structural building blocks that all Accounts, Balances, and Transactions rely on.

The foundation layer defines the structural building blocks of your financial data in Midaz. Organizations, Ledgers, and Assets form the base on which all accounts, balances, and transactions operate.

## Content

***

* [**Organizations**](/en/products/midaz/organizations): The top-level entity that represents a financial institution. Organizations govern all financial data. They can also establish parent-child hierarchies for structures like subsidiaries, regional branches, or business units.
* [**Ledgers**](/en/products/midaz/ledgers): Ledgers track all transactions and operations. Organizations can use multiple Ledgers to segregate financial operations by business line, geography, or regulatory requirement.
* [**Assets**](/en/products/midaz/assets): Define the units of value your system works with: currencies like BRL and USD, cryptocurrencies, loyalty points, or tokenized securities. Each Account uses a single Asset. Midaz supports multi-asset operations within one system.


# Getting help
Source: https://docs.lerian.studio/en/products/midaz/getting-help

Find the right support channel for Midaz: community support for Community users and the Lerian Support Portal for Enterprise clients.

When you get stuck, this section points you to the right support channel.

## Content

***

* [**Community support**](/en/products/midaz/community-support): If you use the **Community** version of Midaz, start here. Join GitHub Discussions or Discord to ask questions, report bugs, and collaborate with others.
* [**Lerian Support Portal**](/en/products/midaz/lerian-support-portal): For **Enterprise** clients with a support agreement, this is the official channel. Raise tickets, request services, and get help with production issues. Your SLA sets the guaranteed response times.


# Ledgers
Source: https://docs.lerian.studio/en/products/midaz/ledgers

Use Ledgers to track the Transactions and Operations of each Organization and to orchestrate cross-ledger transfers through the External Account of each Ledger.

A **Ledger** keeps a precise record of all the Transactions and Operations of an Organization. A Ledger tracks every financial event: deposits, withdrawals, transfers, and fees.

Organizations can use multiple Ledgers to segregate financial operations. For example, a bank keeps separate Ledgers for different business lines, regions, or regulatory requirements. A single Ledger can also handle all operations for a simpler setup.

## Ledger structure

***

* **Ledger > Organization:** Each Organization can own multiple Ledgers, but each Ledger belongs to only one Organization.
  * Use multiple Ledgers only when you need to segregate data or operations, for example internal treasury operations versus customer accounts.

> [!WARNING]
>
> By default, a transaction **cannot** move funds between Ledgers. A transaction can span Ledgers only when every Ledger it touches enables the `crossLedger.enabled` setting.

### How to orchestrate cross-Ledger transactions

When every Ledger involved enables `crossLedger.enabled`, send one `direct` or `hold` transaction through the v2 API. Each leg names the `organizationId` and `ledgerId` of its account. Midaz splits the transfer into one balanced transaction per Ledger:

1. **Debit from the source Ledger:** The account in Ledger 1 sends the amount to the External Account of Ledger 1 (`@external/<asset>`).
2. **Credit to the destination Ledger:** The External Account of Ledger 2 sends the amount to the target account.

The transactions share one `groupId`. In a `direct` transaction, they succeed or fail together.

## Key characteristics

***

* All Accounts and Transactions exist within a Ledger.
* Each Ledger keeps a balanced set of Accounts.
* You can use multiple Ledgers for segmentation, but cross-ledger transactions need explicit handling.

## Multiple Ledgers

***

Midaz lets you create multiple Ledgers for each organization. For example, a company can separate financial records by country, department, or business function.

### Example use case

Consider a global enterprise with business in multiple regions:

* Ledger 1: US Business
* Ledger 2: EU Business
* Ledger 3: APAC Business

With separate Ledgers, the company keeps region-specific transaction records, tax rules, and currency settings. It still has unified oversight of all operations.

### When to create a new Ledger

A Ledger is a hard boundary. Every movement between Ledgers passes through the External Account of each Ledger (see [How to orchestrate cross-Ledger transactions](#how-to-orchestrate-cross-ledger-transactions)). This cost drives the decision. Create a new Ledger only when the segments rarely move money between each other.

Use this heuristic to pick the right level of separation:

| Mechanism | What it separates | Reach for it when |
| - | - | - |
| **Ledger** | A complete, self-contained set of books, with its own accounts, balances, and asset configuration | You need true isolation: a separate legal entity, country, or regulatory regime, where balances should never mix and cross-segment movements are rare. |
| **[Portfolio](/en/products/midaz/portfolios)** | A grouping of accounts *within* one Ledger | You want a consolidated view of a customer or business unit, but the accounts still transact freely with the rest of the Ledger. |
| **[Account](/en/products/midaz/accounts) / [Account Type](/en/products/midaz/account-types)** | An individual balance and its rules | A single balance needs its own statement, nature, or restrictions. |

If two sets of balances often transact with each other, keep them in the **same** Ledger. Separate them with Portfolios or Accounts. Split into multiple Ledgers only when the isolation is worth the orchestration overhead.

## Customizing Ledgers

***

In Midaz, you can tailor each Ledger's configuration to your requirements. Assets are scoped to a Ledger, so the same code is an independent record in each Ledger with its own name, type, status, and metadata.

**Example** To represent Bitcoin (BTC) across Ledgers, create the BTC asset independently in each Ledger and set the name, status, and metadata each Ledger needs.

> [!NOTE]
>
> Amounts in Midaz are arbitrary-precision decimals. There is no per-asset or per-Ledger decimal-place setting. You do not configure a scale when you create an asset.

## Benefits of using Ledgers in Midaz

***

* **Clear organization**: Keep clear, distinct financial records for each part of your business.
* **Custom configurations**: Adjust asset settings, currencies, or other parameters per Ledger for local or departmental needs.
* **Scalability**: Add or change Ledgers as your organization grows or diversifies.
* **Transparency**: Get a complete view across all financial activities. Each Ledger adds to one operational picture.

## Ledger settings

***

Each Ledger has configurable settings that control how it validates transactions. For example, you can require every transaction to follow a predefined route. You can also require account types to match your business rules. The Ledger then rejects invalid movements before it records them.

You can change these settings at any time through the API. You do not need to restart the service or change code.

### Available settings

| Setting | Default | Description |
| - | - | - |
| `accounting.validateAccountType` | `false` | When enabled, each new account must use an account type registered for the Ledger. The Ledger rejects the account creation if the type is not registered. |
| `accounting.validateRoutes` | `false` | When enabled, every transaction must include an associated transaction route. Each operation is also validated against its operation route rules. |
| `accounting.requireHolder` | `false` | When enabled, each account that you create through the v2 API must name an existing holder. |
| `overrides.allowFeeSkip` | `false` | When enabled, a transaction request can set `skip.fees` to `true` to post without the fee calculation. If the setting is disabled, Midaz refuses that request with error `0490`. |
| `overrides.allowTracerSkip` | `false` | When enabled, a transaction request can set `skip.tracer` to `true` to skip the Tracer call. If the setting is disabled, Midaz refuses that request with error `0490`. |
| `overrides.allowHolderSkip` | `false` | When enabled, an account creation request can skip the holder check. |
| `tracer.mode`, `tracer.failPosture`, `tracer.timeoutMs` | `off`, `open`, `250` | Control how the Ledger calls Tracer. See the [Tracer integration guide](/en/products/tracer/integration-guide#midaz-ledger-reservation-seam). |
| `crossLedger.enabled` | `false` | When enabled, the Ledger can take part in a transaction that spans Ledgers. |

> [!TIP]
>
> Start with `validateAccountType` and `validateRoutes` disabled while you configure your operation routes and transaction routes. Once your routing setup is complete, enable validation to enforce your business rules.

### How settings affect transactions

When you enable `validateRoutes` for a Ledger:

1. Every transaction to that Ledger **must** reference a valid transaction route.
2. The Ledger validates each operation against the corresponding operation route rules.
3. The Ledger rejects any non-compliant transaction before it records the movement.

When you enable `validateAccountType`:

1. The Ledger checks each new account against its registered account types.
2. If the account type is not registered, the Ledger rejects the account creation.

> [!WARNING]
>
> If you enable validation on a Ledger that already processes transactions, existing records do not change. Validation applies to the requests that you submit after you enable the setting. This includes a commit, cancel, or revert of an earlier transaction.

### Managing settings via API

Use the Ledger Settings endpoints to retrieve and update these configurations:

* [Retrieve Ledger Settings](/en/reference/products/midaz/v2/get-ledger-settings): view the current settings for a Ledger.
* [Update Ledger Settings](/en/reference/products/midaz/v2/update-ledger-settings): change one or more settings with a partial update (deep merge).

> [!NOTE]
>
> Midaz applies changes with a deep merge and modifies only the fields you include in the request.

## Managing Ledgers

***

You can manage your Ledgers through the API or Lerian Console.

### View API

* [List Ledgers](/en/reference/products/midaz/v2/list-ledgers) - View the details of all Ledgers.
* [Retrieve a Ledger](/en/reference/products/midaz/v2/get-ledger-by-id) - Get details of a specific Ledger.
* [Create a Ledger](/en/reference/products/midaz/v2/create-ledger) - Register a new Ledger.
* [Update a Ledger](/en/reference/products/midaz/v2/update-ledger) - Edit the details of an existing Ledger.
* [Delete a Ledger](/en/reference/products/midaz/v2/delete-ledger) - Mark a Ledger as deleted.

> [!NOTE]
>
> When you delete a Ledger, Midaz does not remove it permanently.
>
> Instead, Midaz sets a `deletedAt` timestamp. Midaz then excludes the Ledger from every read, and you can no longer use it. Its `status.code` does not change. This preserves historical data for audit trails. Midaz rejects Ledger deletion in a production environment.

### Via Lerian Console

You can view, create, edit, and delete Ledgers on the Ledgers page in the Midaz Module of Lerian Console.

[**Learn more in the Managing Ledgers guide.**](/en/products/midaz/console/managing-ledgers-via-console)

> [!TIP]
>
> If you create your first Ledger in Lerian Console, you do it as part of the onboarding flow. To learn more, see the [Midaz Module onboarding](/en/products/midaz/console/midaz-console-onboarding) guide.


# Metadata indexes
Source: https://docs.lerian.studio/en/products/midaz/metadata-indexes

Create MongoDB metadata indexes on transactions, operations, and routes to speed up queries and filters on custom metadata keys in high-volume Midaz setups.

## Metadata filters on large collections

***

Every entity in Midaz supports [metadata](/en/reference/metadata): custom key-value pairs that extend the standard data model. Queries that filter a large collection by a metadata field can become slow without an index.

A metadata index is a MongoDB index on a specific metadata key. It turns an expensive collection scan into a fast indexed lookup. Indexes help most in production, where transaction volumes are high and you filter or sort by metadata values.

## How it works

***

When you create a metadata index, Midaz builds a MongoDB index on the `metadata.<key>` field of the entity collection. After that, a query that filters by the metadata key can use the index. MongoDB finds the documents directly, without a full collection scan.

Indexes are:

* **Per-entity**: Each index targets a specific entity type (e.g., `transaction`, `operation`).
* **Per-key**: Each index covers a single metadata key.
* **Optional uniqueness**: You can require that no two documents share the same value for the indexed metadata key.
* **Sparse by default**: The index includes only documents that have the metadata key. This saves storage and speeds up writes.

## Supported entity types

***

Midaz supports metadata indexes for these entities:

| Entity | Collection | Module |
| :- | :- | :- |
| `transaction` | Transactions | Transaction |
| `operation` | Operations | Transaction |
| `operation_route` | Operation Routes | Transaction |
| `transaction_route` | Transaction Routes | Transaction |
| `organization` | Organizations | Onboarding |
| `ledger` | Ledgers | Onboarding |
| `account` | Accounts | Onboarding |
| `asset` | Assets | Onboarding |
| `segment` | Segments | Onboarding |
| `portfolio` | Portfolios | Onboarding |
| `account_type` | Account Types | Onboarding |

## Creating a metadata index

***

Use the [Create a Metadata Index](/en/reference/products/midaz/v2/create-metadata-index) endpoint:

```json POST /v1/settings/metadata-indexes/entities/{entity_name} theme={null}
{
  "metadataKey": "tier",
  "unique": false,
  "sparse": true
}
```

**Parameters:**

| Field | Type | Required | Description |
| :- | :- | :- | :- |
| `metadataKey` | string | Yes | The metadata key to index. Must start with a letter and contain only alphanumeric characters and underscores. Max 100 characters. |
| `unique` | boolean | No | Whether the index enforces uniqueness across documents. Default: `false`. |
| `sparse` | boolean | No | Whether the index only includes documents that have the metadata key. Default: `true`. |

**Response:**

```json JSON theme={null}
{
  "indexName": "metadata.tier_1",
  "entityName": "transaction",
  "metadataKey": "tier",
  "unique": false,
  "sparse": true
}
```

## Listing metadata indexes

***

Use the [List Metadata Indexes](/en/reference/products/midaz/v2/get-all-metadata-indexes) endpoint. It returns all indexes across all entity types with their usage statistics:

```json GET /v1/settings/metadata-indexes theme={null}
[
  {
    "indexName": "metadata.tier_1",
    "entityName": "transaction",
    "metadataKey": "tier",
    "unique": false,
    "sparse": true,
    "stats": {
      "accesses": 1523,
      "statsSince": "2024-12-01T10:30:00Z"
    }
  }
]
```

The `stats.accesses` field shows how many queries used the index since statistics collection started. Use it to find unused indexes that you can safely delete.

## Deleting a metadata index

***

Use the [Delete a Metadata Index](/en/reference/products/midaz/v2/delete-metadata-index) endpoint:

```
DELETE /v1/settings/metadata-indexes/entities/{entity_name}/key/{index_key}
```

Set `{index_key}` to the metadata key, such as `tier`, not to the index name.

> [!CAUTION]
>
> Deletion takes effect immediately. It affects query performance for any operation that used the index. Before you delete an index, make sure no critical query depends on it.

## Performance considerations

***

**When to create indexes:**

* You frequently filter transactions or operations by a specific metadata key (e.g., `tier`, `channel`, `partner_id`).
* List queries on a large collection are slow when they filter by metadata.
* You need to enforce uniqueness on a metadata field (e.g., external reference IDs).

**When NOT to create indexes:**

* You rarely query by the metadata key. The index only costs storage and slows writes.
* The collection is small enough that full scans are fast.
* You want to add an index speculatively, "just in case."

**Limits:**

Midaz does not enforce its own cap on the number of metadata indexes per entity. MongoDB's per-collection index limit applies instead. Keep the index count deliberate: list the indexes and delete any with low or zero `accesses`.

> [!TIP]
>
> Start with indexes on the metadata keys you query in production. Use the `stats.accesses` field from the list endpoint to make sure queries use each index. Delete the indexes that no query uses.

## Related pages

***

* [Metadata](/en/reference/metadata): how metadata works across all Midaz entities.
* [Create a Metadata Index](/en/reference/products/midaz/v2/create-metadata-index): API reference.
* [List Metadata Indexes](/en/reference/products/midaz/v2/get-all-metadata-indexes): API reference.
* [Delete a Metadata Index](/en/reference/products/midaz/v2/delete-metadata-index): API reference.


# Midaz for academic records
Source: https://docs.lerian.studio/en/products/midaz/midaz-for-academic-record-management

Use Midaz to record enrollments, grades, and achievements as immutable Ledger transactions, with automated transcripts and audit-ready histories.

Universities manage thousands of student records across many departments. The data sits in separate enrollment systems, grading platforms, and administrative databases. When an audit starts or a student requests a transcript, staff rebuild a complete history by hand. This process is slow and error-prone.

Midaz treats each academic activity as a Ledger transaction. It records every enrollment, grade, and achievement immutably, with a full audit trail, the same way it records financial movements.

### Benefits

* **Security and integrity**: Every academic record is an immutable transaction. You cannot change its accounts or amounts after you record it.
* **Transparency**: Students, advisors, and administrators see a single, consistent view of the complete academic record.
* **Efficiency**: Transcript generation, GPA calculations, and audit preparation become automated queries instead of manual processes.

## What changes with Midaz

***

| Without Midaz | With Midaz |
| :- | :- |
| Student records spread across enrollment, grading, and admin systems | Single ledger tracks all academic activities as immutable transactions |
| Transcript generation requires manual cross-referencing | Query the operations of a student's accounts for a complete academic history |
| Grade disputes involve digging through logs and email chains | Every grade assignment is a timestamped, immutable transaction with full audit trail |
| GPA calculations done manually or in disconnected spreadsheets | Balance queries on grade accounts return grade totals for GPA calculations |
| Audit preparation takes weeks of data gathering | Query transactions for any date range through the API |

## Using Midaz

***

* **Organization & Ledger:** The university registers as an Organization in Midaz. It creates a Ledger to track all academic activities as transactions.
* **Assets:** Create an Asset for each academic metric, such as `ENROLLMENT`, `GRADE`, `ATTENDANCE`, and `ACHIEVEMENT`. Asset codes use uppercase letters only.
* **Student Portfolios:** For each student, create a Portfolio. The Portfolio is the academic record and holds all relevant academic metrics.
* **Accounts for academic metrics:** Create accounts for the academic metrics inside each student's Portfolio. Each account holds one Asset. Examples include:
  * **Course enrollments Account**: Records the courses the student enrolls in.
  * **Grades Account**: Tracks the grades the student receives.
  * **Attendance Account**: Monitors class attendance.
  * **Achievements Account**: Records extracurricular achievements and recognitions.
* **Transactions**: Use transactions to update accounts based on academic activities. Record the course or activity in each transaction's metadata:
  * **Course enrollment**: When a student enrolls in a course, create a transaction. The transaction moves one `ENROLLMENT` unit from `@external/ENROLLMENT` to the student's "Course Enrollments" account.
  * **Grade assignment**: When an instructor assigns a grade, create a transaction. The transaction moves the grade, in `GRADE`, from `@external/GRADE` to the student's grade account.
  * **Attendance marking**: To mark attendance, move `ATTENDANCE` from `@external/ATTENDANCE` to the student's "Attendance" account.
  * **Achievements**: Similarly, add achievements to the "Achievements" account via transactions.
* **Reports**: Query the ledger to build a full academic record for each student, across enrollments, grades, attendance, and achievements. These queries support academic counseling and transcript generation.
  * For example, retrieve all operations of the Grades Account. Use the available balance to calculate the student's GPA.


# Midaz for multi-account customers
Source: https://docs.lerian.studio/en/products/midaz/midaz-for-multi-account-customers

Model multiple Midaz accounts under a single customer, with segregated balances, ledgers, statements, and external identifiers per account.

A single customer rarely has a single balance. The same person can hold a main account, a benefit account, a blocked account, a product sub-account, or a promotional balance. Each balance has its own rules, its own statement, and its own reconciliation needs.

The common shortcut treats these as labels on one account and sorts them out in application code. That works until balances, ledgers, statements, or operational rules must diverge. At that point, a single account can no longer show where the money is.

This page shows the reference architecture for **one customer with many Midaz accounts**. It maps each part of the model to a native platform entity. Then it walks through an example: three accounts for the same customer document.

## Each balance as its own account

***

For **product and operations teams**, each balance becomes its own account. The Ledger then enforces segregation rules, such as a blocked outflow or a benefit-only spend. The rule lives in the Ledger, not in application logic. Each account carries its own statement and reconciliation trail.

For **engineering teams**, each external address resolves to a specific account before Midaz posts a transaction. Core banking numbers and payment-rail identifiers each point to one balance. You never guess which balance an incoming event belongs to. There is no separate balance store to keep in sync with the Ledger.

| One account with labels | Many accounts per customer |
| - | - |
| Balance "types" live in metadata or app code | Each balance is its own Account with its own ledger and statement |
| Blocking or restricting funds requires custom logic | Account Type and route rules enforce restrictions at the Ledger |
| Statements must be filtered and reassembled per balance | Each account produces a clean, independent statement |
| External identifiers all point to the same balance | Each external identifier resolves to a specific account |
| Reconciliation mixes unrelated movements | Reconciliation is separated by account by design |

## The reference architecture

***

The model is **one owner, N accounts, N external identifiers**:

* **One owner**: the customer, identified by a document (CPF, CNPJ, tax ID). The owner represents *who* holds the relationship. It does not carry a balance and does not decide transaction routing.
* **N accounts**: each account is a self-contained accounting position, with its own balance, ledger, statement, and rules.
* **N external identifiers**: the addresses other systems (a core banking platform, a payment rail) use to reach a specific account. Each identifier resolves to exactly one account.

A middleware layer keeps the map between external identifiers and accounts. It resolves each identifier to the correct account *before* the call to Midaz. Midaz remains the source of truth for accounts, balances, and entries.

![One customer, many accounts: reference architecture](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/flowchart-multiaccounts.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=4bc292432ee995aeabaa2061bfee73ff)

Reference architecture: one customer, many accounts.

> [!NOTE]
>
> When balance, ledger, statement, or operational rule differs by destination, point each identifier at a distinct account. Do not treat an external identifier as a nickname for one shared balance.

## How Midaz maps the model

***

Every part of this architecture maps to a native Midaz entity. You do not build a separate balance store or invent an accounting layer.

| Concept | Midaz entity | What it does |
| - | - | - |
| The owner (customer) | [**Holder**](/en/products/midaz/crm/holders) | Identity behind the accounts (`NATURAL_PERSON` or `LEGAL_PERSON`), keyed by `document`. Owns each account through its `holderId`. Holds no balance. |
| Each balance position | [**Account**](/en/products/midaz/accounts) | Source of truth for balance, entries, and statement. |
| The nature of each balance | [**Account Type**](/en/products/midaz/account-types) | Classifies an account (main, benefit, blocked) and enables route validation. |
| All accounts of one customer | [**Portfolio**](/en/products/midaz/portfolios) | Groups a customer's accounts to view the total relationship. |
| External address → account | [**Account alias**](/en/products/midaz/accounts#account-aliases) + [**`entityId`**](/en/products/midaz/accounts#entity-id-external-system-reference) | The alias is how transactions address an account; `entityId` links it to an external system's identifier. |
| Banking and regulatory context | [**Instrument (CRM)**](/en/products/midaz/crm/crm-getting-started) | Attaches branch, account number, and regulatory fields. Links a Holder to a specific account. |

> [!TIP]
>
> Much of what an external "alias registry" would do is already native. The account **alias** is the in-Ledger address. **`entityId`** stores your external system's identifier. The middleware's job is narrow: translate an external rail identifier into the right account alias, then post.

## Prerequisites

***

This example assumes a running Midaz environment with the following in place:

| Requirement | Details |
| - | - |
| **Midaz** (v4.x.x+) | Core Ledger with an Organization and Ledger already created |
| **A registered asset** | `BRL` registered as the operating asset in the Ledger |
| **Account Type validation** | Enabled per-Ledger so new accounts must use a registered type (see Step 1) |
| **CRM** | Part of the ledger binary. Use it to attach identity, banking, and regulatory context |

## Building three accounts for one customer

***

The customer with document `12345678900` needs three accounts. The **main** account is free for ordinary movement. The **benefit** account follows product rules. The **blocked** account accepts inflows but restricts outflows.

**1. Enable Account Type validation**

Turn on validation so new accounts must declare a registered type.

```json theme={null}
PATCH /v2/organizations/{org_id}/ledgers/{ledger_id}/settings

{
  "accounting": {
    "validateAccountType": true
  }
}
```

Settings take effect immediately. You do not need to redeploy.

**2. Register the Account Types**

Create one Account Type per balance nature. The `keyValue` is what each account's `type` field must match.

```json theme={null}
POST /v2/organizations/{org_id}/ledgers/{ledger_id}/account-types

{
  "name": "Main Account",
  "description": "Ordinary account, free for regular movement",
  "keyValue": "main_account"
}
```

Repeat for `benefit_account` (movement under product rules) and `restricted_account`. The `restricted_account` is the **blocked** account. The type alone restricts nothing. With route validation on, transaction routes can condition its outflows. To block them, set `allowSending` to `false` on its balance.

**3. Register the customer as a Holder**

Create one Holder for the customer. The same Holder owns all three accounts and keeps identity in one place.

> [!NOTE]
>
> In Midaz v4, CRM is part of the ledger binary, so it needs no separate service or port. The organization ID travels in the URL path. See [Getting started with CRM](/en/products/midaz/crm/crm-getting-started) for the full schema.

```bash theme={null}
curl -X POST http://localhost:3002/v2/organizations/{org_id}/holders \
  -H "Content-Type: application/json" \
  -d '{
    "type": "NATURAL_PERSON",
    "name": "Jane Smith",
    "document": "12345678900",
    "contact": {
      "primaryEmail": "jane.smith@example.com"
    }
  }'
```

Save the returned `id`. It is the `holderId` for the next steps.

**4. Create the three accounts**

Each account links to the `BRL` asset and declares its `type`. It carries an `alias` (its in-Ledger address) and an `entityId` (its identifier in your external system). The `holderId` makes the Holder the owner of the account. You cannot change the owner later.

```json theme={null}
POST /v2/organizations/{org_id}/ledgers/{ledger_id}/accounts

{
  "name": "Main account - 12345678900",
  "assetCode": "BRL",
  "alias": "@cust_12345678900_main",
  "entityId": "0001/12345-1",
  "holderId": "<holder-id>",
  "type": "main_account"
}
```

Create the benefit account with `alias` `@cust_12345678900_benefit`, `entityId` `0001/88888-2`, and `type` `benefit_account`. Create the blocked account with `alias` `@cust_12345678900_blocked`, `entityId` `0002/77777-0`, and `type` `restricted_account`. Use the same `holderId` for both.

> [!TIP]
>
> The `entityId` is where you store the external address that other systems use to reach this account. It is your map between Midaz and your source system.

**5. Link each account to the Holder**

Create one Instrument per ledger account to attach banking and regulatory context. The Instrument remains inside the unified Ledger binary while keeping customer-facing details outside the transactional account and balance model.

```bash theme={null}
curl -X POST http://localhost:3002/v2/organizations/{org_id}/holders/{holder_id}/instruments \
  -H "Content-Type: application/json" \
  -d '{
    "ledgerId": "<your-ledger-id>",
    "accountId": "<main-account-id>",
    "bankingDetails": {
      "branch": "0001",
      "account": "12345",
      "type": "CACC",
      "countryCode": "BR"
    },
    "metadata": {
      "purpose": "main"
    }
  }'
```

The main account's `entityId` (`0001/12345-1`) decomposes into the `branch` (`0001`) and `account` (`12345`) you record here. That external address now resolves to one specific account. Repeat for the benefit and blocked accounts, and point `accountId` at each one.

You now have one customer, three accounts, and three distinct external addresses. Each account keeps its own balance, statement, and rules under a single Holder.

| Owner | External identifier | Midaz account | Use | Treatment |
| - | - | - | - | - |
| `12345678900` | `0001/12345-1` | `@cust_..._main` | Main account | Free for ordinary movement |
| `12345678900` | `0001/88888-2` | `@cust_..._benefit` | Benefit account | Movement governed by product rules |
| `12345678900` | `0002/77777-0` | `@cust_..._blocked` | Court-ordered / blocked | Inflow allowed, outflow conditioned or blocked |

## The transaction boundary

***

When an external event arrives, the resolution happens *before* the call to Midaz. Each layer stays in its lane, and that preserves accounting clarity.

**1. External event**

A transaction, query, or settlement arrives with an external identifier.

**2. Middleware resolves the identifier**

The middleware looks up the external identifier and resolves it to the correct Midaz account alias. It also applies status validation (active, blocked, closed).

**3. Midaz posts to the right account**

Midaz records the entry against the resolved account and preserves balance and ledger. Statement and reconciliation stay separate by account.

| Layer | Responsibility | Should not do |
| - | - | - |
| **CRM / registration** | Hold the commercial and identity view of the customer, including the link between document and relationship. | Transaction routing, destination decisions, or settlement rules. |
| **Middleware** | Resolve external identifiers to a Midaz account before the transaction, and apply status validation. | Invent balances, duplicate accounting, or depend on the CRM in real time for routing. |
| **Midaz** | Record accounts, balances, entries, ledgers, and statements as the financial source of truth. | Know external-rail details beyond the identifiers needed for integration. |

> [!TIP]
>
> An identifier for a blocked or closed account must fail validation before the call to Midaz. Routing decisions belong in the middleware. The Ledger stays the source of truth for balances and entries.

## Outcomes of many accounts per customer

***

* **Real segregation**: each balance has its own ledger and statement. You cannot spend a blocked balance through the main account by accident.
* **Unambiguous routing**: every external event has a single, well-defined destination account.
* **Centralized identity**: one Holder owns many accounts. Identity and contact data live in one place while balances stay separate.
* **Native**: accounts, types, aliases, and `entityId` are platform primitives, so there's no parallel balance store to reconcile against the Ledger.

## What you need to get started

***

| Requirement | Details |
| - | - |
| **Midaz** (v4.x.x+) | Organization, Ledger, and a registered asset |
| **Account Type validation** | Enabled per-Ledger via the [Ledger Settings API](/en/products/midaz/ledgers#ledger-settings) |
| **Account Types** | One per balance nature (main, benefit, blocked, …) |
| **Accounts** | One per balance, each with an `alias` and an `entityId` |
| **CRM** | A Holder per customer, plus an optional Instrument per ledger account |

## Next steps

***

> **[Accounts](/en/products/midaz/accounts)**
>
> The core financial unit: aliases, `entityId`, and external accounts.

> **[Account Types](/en/products/midaz/account-types)**
>
> Classify accounts and enforce their nature with route validation.

> **[Portfolios](/en/products/midaz/portfolios)**
>
> Group a customer's accounts to view the total relationship.

> **[CRM: Holders & Instruments](/en/products/midaz/crm/holders)**
>
> Centralize identity and attach banking and regulatory context.


# Midaz for supply chains
Source: https://docs.lerian.studio/en/products/midaz/midaz-for-supply-chain-management

Use Midaz as a ledger for supply chain management, recording every raw material, production, and shipping movement as an immutable, auditable transaction.

Manufacturing companies manage complex material flows. Raw materials arrive from many suppliers, move through production stages, become finished goods, and ship to customers. A quality issue or a regulatory audit asks where a material came from and where it went. Today that answer takes days of cross-referencing spreadsheets and ERP exports.

Midaz records every material movement as an immutable ledger transaction. From receiving to production to shipping, you get a complete and auditable history of your supply chain.

### Benefits

* **Transparency and traceability**: An immutable audit trail documents every step. Recall investigations and compliance audits become straightforward.
* **Efficiency**: Real-time balance queries show inventory levels and production stages. You avoid manual stock checks and planning delays.

## What changes with Midaz

***

| Without Midaz | With Midaz |
| :- | :- |
| Material tracking spread across ERP modules, spreadsheets, and emails | Every material movement is a ledger transaction with full audit trail |
| Recall investigations take days of cross-referencing multiple systems | Query the ledger for the complete journey of any material |
| Inventory counts done manually or through periodic reconciliation | Real-time balance queries show current stock at any stage (raw, in-production, finished) |
| Supplier disputes lack authoritative records | Immutable transactions record every delivery and movement |
| Regulatory audits require weeks of data preparation | Query transactions for any date range through the API |

## Using Midaz

***

* **Assets**: Set up each supply chain item as an Asset. Asset codes use uppercase letters only, such as `STEEL` or `WIDGET`. Assets cover everything from raw materials to final products.

* **Portfolios**: Create a portfolio for each warehouse. A portfolio groups the accounts that track material and goods flow.

* **Accounts**: Within each portfolio, create an account for each item at each supply chain stage. Each account holds one Asset. For example:

  * **Raw materials account**: Tracks raw materials held in the warehouse.

  * **In-production account**: Monitors materials in the production process.

  * **Finished goods account**: Records completed products ready for distribution.

  * **Shipment account**: Tracks items in transit to customers or other warehouses.

* **Transactions**: Use a transaction to update accounts as materials move through each stage. For example:

  * **Receiving materials**: When materials arrive, a transaction moves the amount from the item's external account, such as `@external/STEEL`, to the warehouse's Raw Materials account. Record the supplier in the transaction metadata.

  * **Production**: During production, a transaction moves the amount from the Raw Materials account to the In-Production account.

  * **Production completion**: When production finishes, one transaction per consumed material moves it from its In-Production account to the material's external account. Another transaction moves the finished products from the product's external account to the Finished Goods account.

  * **Shipping**: When goods ship, a transaction moves the amount from the Finished Goods account to the Shipment account.

* **Reports**: Query Midaz for current inventory levels, production output, and shipment status. Use the data to plan stock, production schedules, and logistics.

* **Compliance and audits**: The immutable Midaz ledger keeps supply chain records secure and audit-ready.


# Getting started with Midaz
Source: https://docs.lerian.studio/en/products/midaz/midaz-getting-started

Run Midaz locally in about ten minutes: clone the repo, start infrastructure, create your first Organization, Ledger, Accounts, and process a first transaction.

In this guide, you set up a working Midaz environment. You then run the core workflow behind any financial application on the platform. You create an organization, a ledger, and accounts, and then process your first transaction.

By the end, you have a running ledger ready for your use case. This can be payments, lending, marketplace settlement, or internal treasury.

## Prerequisites

***

Before you begin, install these tools:

| Tool | Minimum version | Check command |
| - | - | - |
| [Go](https://go.dev/dl/) | 1.27.0+ | `go version` |
| [Docker](https://docs.docker.com/get-docker/) | 24+ | `docker --version` |
| [Docker Compose](https://docs.docker.com/compose/install/) | 2.20+ | `docker compose version` |
| [Make](https://www.gnu.org/software/make/) | 3.81+ | `make --version` |
| [Git](https://git-scm.com/) | 2.30+ | `git --version` |

> [!NOTE]
>
> Midaz runs on **macOS** (Apple Silicon and Intel) and **Linux** (amd64). On Windows, run it through **WSL2**.

## Step 1: Clone the repository

***

Clone the Midaz repository and move into the project directory.

```bash Terminal theme={null}
git clone https://github.com/LerianStudio/midaz.git
cd midaz
```

## Step 2: Set up environment files

***

Midaz uses `.env` files to configure each component. Generate them from the provided examples:

```bash Terminal theme={null}
make set-env
```

This command copies `.env.example` to `.env` in each component directory. The default values work for local development. You do not need to change them.

> [!WARNING]
>
> Docker must run before this step. `make set-env` also generates the `LCRYPTO_*` CRM keys through a Docker one-shot container. The command fails if Docker is unavailable.

## Step 3: Start the infrastructure

***

Start the supporting services that Midaz needs: PostgreSQL, MongoDB, Valkey, RabbitMQ, Redpanda, and OpenTelemetry.

```bash Terminal theme={null}
make infra COMMAND=up
```

Wait until the containers are up. Check their status with:

```bash Terminal theme={null}
docker compose -f components/infra/docker-compose.yml ps
```

> [!TIP]
>
> Infrastructure services use the following default ports:
>
> | Service | Port |
> | - | - |
> | PostgreSQL Primary | 5701 |
> | PostgreSQL Replica | 5702 |
> | MongoDB | 5703 |
> | Valkey (Redis) | 5704 |
> | Grafana (OTEL) | 3100 |
> | RabbitMQ AMQP | 3003 |
> | RabbitMQ Management | 3004 |
> | Redpanda (Kafka API) | 19092 |

## Step 4: Start Midaz

***

Midaz runs as a single **Ledger** service that includes the onboarding and transaction domains. Start it with:

```bash Terminal theme={null}
make up
```

This command starts the infrastructure, runs the ledger and Tracer migration containers, and then starts the ledger and Tracer services. All ledger APIs are available on **port 3002**.

Check that Midaz responds:

```bash Terminal theme={null}
curl http://localhost:3002/health
```

You should receive a `200 OK` response.

## Step 5: Create an organization

***

An organization represents the business entity behind the financial operation: your company, a client, or a regulated institution. In production, it maps to the legal entity that holds your ledgers, accounts, and transactions.

> [!TIP]
>
> For the complete endpoint specification, see [Create an Organization](/en/reference/products/midaz/v2/create-organization).

```bash Terminal theme={null}
curl -X POST http://localhost:3002/v2/organizations \
  -H "Content-Type: application/json" \
  -d '{
    "legalName": "Acme Corp",
    "legalDocument": "12345678000100",
    "status": {
      "code": "ACTIVE"
    },
    "address": {
      "country": "BR"
    }
  }'
```

> [!NOTE]
>
> Save the `id` returned in the response. You use it in the next steps as `{organization_id}`.

## Step 6: Create a ledger

***

A ledger is an isolated book of records within an organization. You can create separate ledgers for different financial domains, such as payments, fee collection, or settlement. Each ledger has its own accounts and transaction history.

> [!TIP]
>
> For the complete endpoint specification, see [Create a Ledger](/en/reference/products/midaz/v2/create-ledger).

```bash Terminal theme={null}
curl -X POST http://localhost:3002/v2/organizations/{organization_id}/ledgers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Primary Ledger",
    "status": {
      "code": "ACTIVE"
    }
  }'
```

Save the returned `id` as `{ledger_id}`.

## Step 7: Create an asset

***

An asset defines the unit of value tracked in the ledger. This can be a fiat currency like BRL or USD. It can also be loyalty points, crypto tokens, securities, or any custom unit your business tracks.

You must create at least one asset before you create accounts.

> [!TIP]
>
> For the complete endpoint specification, see [Create an Asset](/en/reference/products/midaz/v2/create-asset).

```bash Terminal theme={null}
curl -X POST http://localhost:3002/v2/organizations/{organization_id}/ledgers/{ledger_id}/assets \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Brazilian Real",
    "type": "currency",
    "code": "BRL",
    "status": {
      "code": "ACTIVE"
    }
  }'
```

## Step 8: Create accounts

***

Accounts represent the participants or buckets in your financial flow: a customer wallet, a revenue pool, a merchant account, or an internal reserve. Each account links to a single asset and follows double-entry accounting rules.

You need at least two accounts to process a transaction: one to debit (source) and one to credit (destination).

> [!TIP]
>
> For the complete endpoint specification, see [Create an Account](/en/reference/products/midaz/v2/create-account).

Midaz created the source account `@external/BRL` when you created the BRL asset. Create a destination account:

```bash Terminal theme={null}
curl -X POST http://localhost:3002/v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Account",
    "assetCode": "BRL",
    "type": "deposit",
    "status": {
      "code": "ACTIVE"
    },
    "alias": "@customer-001"
  }'
```

## Step 9: Process your first transaction

***

A transaction moves value between accounts with full traceability. Midaz records every transaction as a balanced operation. It debits the source and credits the destination, so your books stay consistent by design.

> [!TIP]
>
> For the complete endpoint specification, see [Create a Transaction using the v2 direct model](/en/reference/products/midaz/v2/create-transaction-direct).

```bash Terminal theme={null}
curl -X POST http://localhost:3002/v2/transactions/direct \
  -H "Content-Type: application/json" \
  -d '{
    "description": "First transaction",
    "asset": "BRL",
    "amount": "1000",
    "debits": [
      {
        "alias": "@external/BRL",
        "organizationId": "{organization_id}",
        "ledgerId": "{ledger_id}",
        "amount": "1000"
      }
    ],
    "credits": [
      {
        "alias": "@customer-001",
        "organizationId": "{organization_id}",
        "ledgerId": "{ledger_id}",
        "amount": "1000"
      }
    ]
  }'
```

> [!NOTE]
>
> This transaction sends `"1000"` from `@external/BRL` to `@customer-001`. Midaz stores monetary values as decimal strings and does not apply an asset-specific scale.
>
> Your integration defines the display and rounding rules for BRL amounts. Do not parse monetary values as binary floating point.

## Step 10: Verify the balance

***

Check the destination account balance to confirm the transaction.

> [!TIP]
>
> For the complete endpoint specification, see [Retrieve a Balance by Account Alias](/en/reference/products/midaz/v2/get-balances-by-alias).

```bash Terminal theme={null}
curl http://localhost:3002/v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/alias/@customer-001/balances
```

The returned balance should reflect the credited amount. At this point, you have a working ledger that processes real transactions.

## Explore the API

***

Midaz can serve its OpenAPI 3.1 spec and interactive API documentation. The docs surface is off by default. To enable it, set `OPENAPI_DOCS_ENABLED=true` in `components/ledger/.env` and run `make restart`. Then access:

* **API docs**: `http://localhost:3002/docs`
* **OpenAPI spec**: `http://localhost:3002/openapi.json` (or `/openapi.yaml`)

## Observability

***

Midaz ships with a preconfigured Grafana instance integrated with OpenTelemetry.

* **Grafana dashboard**: `http://localhost:3100`
* **Default credentials**: `midaz` / `lerian`

The local ledger configuration ships with telemetry off. To send telemetry to Grafana, set `ENABLE_TELEMETRY=true` in `components/ledger/.env` and run `make restart`.

## Stopping Midaz

***

To stop all services:

```bash Terminal theme={null}
make down
```

To remove the Midaz containers and volumes, run the command below. It also runs `docker system prune -f` and `docker volume prune -f`, which affect every project on your machine:

```bash Terminal theme={null}
make clean-docker
```

## Next steps

***

> [!TIP]
>
> New to Midaz? Start with [Midaz entities](/en/products/midaz/core-entities) to understand organizations, ledgers, accounts, and transactions.

> **[Creating transactions](/en/products/midaz/transactions-overview)**
>
> Learn the different ways to create transactions, including JSON, inflow, and outflow, and when to use each.

> **[Deploy to production](https://github.com/LerianStudio/helm/blob/main/charts/midaz/README.md#install-midaz-helm-chart)**
>
> Deploy Midaz to Kubernetes using the official Helm chart.

> **[Setting up CRM](/en/products/midaz/crm/crm-getting-started)**
>
> Manage holders and alias accounts to connect real-world identities to your Midaz accounts.

> **[Extend with plugins](/en/products/about-plugins)**
>
> Add Pix and other capabilities to your Midaz deployment.


# Midaz in a global portfolio
Source: https://docs.lerian.studio/en/products/midaz/midaz-in-a-global-portfolio

Model multi-currency customer relationships in Midaz: group BRL, USD, and EUR Accounts under a single Portfolio for a unified global banking view.

With Midaz, you can build a global account structure like the ones major banks offer. Clients hold accounts in multiple currencies, such as BRL, USD, and EUR. You manage every currency account under a single client profile.

## What changes with Midaz

***

| Without Midaz | With Midaz |
| :- | :- |
| Multi-currency accounts require separate systems or complex workarounds | Each currency is an Asset (A unit of value tracked in the ledger: traditional currencies (BRL, USD), digital currencies (BTC), or custom units like loyalty points. Every account is linked to exactly one asset.); accounts in different currencies grouped under one Portfolio (A grouping of accounts belonging to the same account holder, business unit, or purpose. It ties together checking, savings, and investment accounts for a unified view.) |
| No unified customer view across currencies | A single portfolio shows all of a client's accounts (BRL, USD, EUR) in one place |
| Currency-specific reporting built manually per system | Filter the account list by portfolio through the API |
| Adding a new currency means provisioning new infrastructure | Create a new Asset and an account. The ledger handles the rest |

## Using Midaz

***

* **Organization and Ledger:** ABC Bank registers as an Organization in Midaz. It then creates a Ledger to track all customer transactions.
* **Assets:** The bank defines an Asset for each currency it supports.
* **Customer Portfolios:** Each customer has a Portfolio. It groups their checking, savings, and credit accounts in one place.
* **Customer Accounts:** Create an Account for each currency the customer uses. Group these accounts under the customer's Portfolio.


# Midaz in banking
Source: https://docs.lerian.studio/en/products/midaz/midaz-in-banking

Model retail, corporate, and personalized banking in Midaz with Portfolios, Segments, and dedicated settlement Accounts.

Midaz supports three banking models: **retail banking**, **corporate banking**, and **personalized banking services**. It uses portfolios (A grouping of accounts belonging to the same account holder, business unit, or purpose. It ties together checking, savings, and investment accounts for a unified view.) and segments (A classification applied to accounts that share characteristics, like account holder tiers (VIP, Student) or regional divisions. Rules and pricing can differ by segment.) to model each one.

## What changes with Midaz

***

| Without Midaz | With Midaz |
| :- | :- |
| Customer accounts scattered across legacy systems with no unified view | Single ledger (The core financial book that records all transactions, balances, and operations for an organization. It is the single source of truth for a business unit's finances.) with portfolios grouping all accounts per customer |
| Adding new products (savings, credit) requires core system changes | New account types and segments configured via API, with no code changes to the ledger |
| Fee and interest tracking mixed with operational accounts | Dedicated internal accounts for fee income, interest expense, and settlement (The process of finalizing a financial transaction by transferring actual funds between institutions. Settlement accounts act as clearing points where money is held temporarily before reaching its final destination.) |
| Segmentation (VIP, Student) enforced manually per product | Segments classify accounts, and the Fees Engine waives fees for a whole segment |
| Corporate hierarchies require custom workarounds | Native child accounts (A sub-account under a parent account, used for budgeting or organizational purposes. Each tracks its own balance.) and multi-portfolio support for subsidiaries |

## Adding products without changing the core ledger

***

Banks add products without changing core ledger structures. You configure new account types and segments through the API.

## Retail banking for individual customers

***

A retail bank runs on a single organization and a primary ledger. Each customer maps to a portfolio.

### Using Midaz

* **Organization & Ledger:** ABC Bank registers as an organization. It creates a "Retail Banking Ledger" for all customer transactions.
* **Assets (A unit of value tracked in the ledger: traditional currencies (BRL, USD), digital currencies (BTC), or custom units like loyalty points. Every account is linked to exactly one asset.):** The bank defines an asset for every currency it operates. This gives multi-currency support for domestic and international accounts.
* **Customer portfolios:** Each customer has a portfolio. It holds their checking, savings, and credit accounts.
* **Transactions:** Midaz records deposits, transfers, and payments with full traceability.
* **Internal accounts:** Fee and interest accounts track the bank's revenue and expenses.
* **Segments for personalization:** You classify accounts into service tiers, such as Standard or Gold. The Fees Engine can waive fees for a tier.
* **Child accounts (A sub-account under a parent account, used for budgeting or organizational purposes. Each tracks its own balance.) for budgeting:** Customers create sub-accounts under their savings account for better money management.

#### Example: ATM withdrawal

John Doe withdraws \$100 from an ATM:

**1. Debit**

\$100 from John’s checking account.

**2. Credit**

\$100 to an "ATM Cash Dispensed" internal account.

**3. Fee**

Midaz debits \$3 from John’s account and credits the Fee Income account.

## Corporate banking for business and enterprise customers

***

Corporate banking needs a more detailed structure. It often uses separate ledgers or segments to keep it apart from retail banking.

### Using Midaz

* **Dedicated Ledger:** ABC Bank creates a "Corporate Banking Ledger" for business accounts.
* **Portfolios for enterprises:** Each corporate client, such as ACME Corp, gets a portfolio with accounts for operations, payroll, and taxes.
* **Hierarchical accounts:** Child accounts let a business split funds across departments under one parent account.
* **Bulk transactions:** Midaz supports large operations, such as payroll with many simultaneous debits and credits.
* **Segments & Products:** You classify companies as SME or Large Enterprise to offer tailored services.
* **Multi-entity clients:** You give each subsidiary its own portfolio under the same organization.

#### Example: loan disbursement & supplier payments

ACME Corp receives a \$1,000,000 loan:

**1. Credit**

\$1,000,000 to ACME’s loan account.

**2. Debit**

\$1,000,000 from the bank’s Loans Receivable account.

**3. ACME uses funds**

* \$100,000 payment to a supplier at ABC Bank (internal transfer).
* \$50,000 payment to an external supplier (external transfer recorded in the clearing account).

## Portfolios and Segments for personalized services

***

Banks offer custom financial products. Midaz supports this through portfolios and segments.

### Customization strategies

* **Youth & student accounts:** You assign these accounts to a "Student" segment. The Fees Engine waives their fees.
* **Premium banking:** You group "Diamond" accounts in a premium segment. You apply fee rules to the whole segment.
* **Co-branded & special products:** You define loyalty points as an asset and track them in a customer's account.
* **Unified account views:** An application filters the account list by portfolio.
* **Cross-portfolio operations:** A customer with a personal and a business portfolio transfers funds between them. The accounts stay separate in each portfolio.

#### Example: student account perks

**Step 1**

A new customer signs up as a student.

**Step 2**

You assign their account to the "Student" segment.

**Step 3**

The Fees Engine waives their monthly fees.

**Step 4**

When the customer reaches a set age, you move the account to a different segment.


# Midaz models
Source: https://docs.lerian.studio/en/products/midaz/midaz-models

Compare Midaz Community and Enterprise models: choose the licensing tier that fits your needs and pair it with SaaS or BYOC deployment.

Midaz offers two licensing models: **Community** and **Enterprise**. Community fits developers and teams that want the core ledger at no cost. Enterprise fits organizations that need scale, compliance, and support.

## Deployment flexibility

***

Both models are available under Lerian's [BYOC (Bring Your Own Cloud)](/en/start-here/evaluate-and-deploy/deployment-models) model. You deploy and operate the platform in your own infrastructure. Enterprise institutions can also choose the **SaaS** model, where Lerian manages the full infrastructure.

Your licensing model (Community or Enterprise) defines what features you get. Your deployment model (SaaS or BYOC) defines how the platform runs. These are independent choices.

For a full comparison, see [Deployment models](/en/start-here/evaluate-and-deploy/deployment-models).

## Community model

***

The **Community** model gives you full access to Midaz's core features at no cost, with community support.

### What the Community model includes

* Free access to [Midaz's core features](/en/products/midaz/core-features).
* Community support through Discord and GitHub.
* Helm Charts for simpler deployments.

This model fits developers, startups, and teams that try Midaz without enterprise support or SLAs.

## Enterprise model

***

The **Enterprise** model fits organizations that require scalability, compliance, and dedicated support. It includes everything in the Community model, plus:

### What the Enterprise model adds

* **Lifecycle management** that keeps your infrastructure optimized.
* **Software support** for mission-critical operations.
* **Advanced access management** and **role-based control**.
* **Onboarding assistance** to speed up adoption.
* **Software availability SLA** for uptime commitments.
* **Incident reports and security compliance**.
* **Plugin integration** in a preconfigured environment.

> [!NOTE]
>
> Plugins are available only to Enterprise clients.
>
> If you want access on another plan, [get in touch](https://lerian.studio/contact).

## Choosing the right model

***

### Services

| | Community | Enterprise |
| :- | :- | :- |
| **Community Forum (Github/Discord)** | | |
| **Helm Charts available** | | |
| **Lifecycle management** | | |
| **Observability (through Telemetry)** | | |
| **Software support** | | |
| **Software availability SLA** | | |
| **Incident reports** | | |
| **Onboarding assistance** | | |

### Enterprise features

| | Community | Enterprise |
| :- | :- | :- |
| **Single sign-on (SSO)** | | |
| **Workflows** | | |
| **Event streaming (webhooks)** | | |
| **Observability - Telemetry** | | |
| **Cross-organization transactions** | | |
| **Access Manager RBAC** | | |
| **Multi-tenant support** | | |

### Core features

| | Community | Enterprise |
| :- | :- | :- |
| **Native event publisher** | | |
| **User credentials** | | |
| **Parent account ID** | | |
| **Client segments** | | |
| **Double-entry** | | |
| **Multi-currency/asset Support** | | |
| **Multi-organization/ledger Support** | | |
| **N:N transactions** | | |
| **Native race condition (per-account)** | | |
| **Self-reconciliation** | | |
| **Wallets portfolio** | | |
| **Terraform deploy** | | |
| **Visual interface** | | |


# Midaz production best practices
Source: https://docs.lerian.studio/en/products/midaz/midaz-production-best-practices

Set up Midaz for production with multi-AZ deployment, autoscaling, managed services, and the Kubernetes resilience patterns Lerian recommends.

Midaz runs in production at high volume. This guide gives you the deployment, high-availability, and observability patterns Lerian recommends. Follow them to keep downtime low and protect your data.

## Best-fit setup

***

Start a production deployment with these choices:

* Deploy across multiple availability zones.
* Run at least 3 worker nodes with autoscaling.
* Separate application and database workloads.
* Use managed services such as RDS, ElastiCache, and MongoDB Atlas.
* Apply Kubernetes patterns for resilience, security, and observability.
* Automate backups and alerting from day one.

## Infrastructure planning

***

### Cluster architecture

Plan the cluster for resilience and performance:

* Deploy across multiple availability zones.
* Run at least 3 worker nodes for high availability.
* Enable node autoscaling to absorb workload spikes.
* Separate application and database workloads when possible.

### Resource sizing

* Match node sizes to the expected workload.
* Give critical services enough resources first.
* Apply resource quotas to prevent contention.
* Monitor usage and tune the sizing over time.

### Storage

* Use SSD-backed storage for all database components.
* Define a storage class for each cloud provider.
* Provision volumes with headroom for growth.
* Use replicated or durable storage for critical data.

## Database architecture and high availability

***

Midaz uses CQRS (Command Query Responsibility Segregation) to separate reads from writes. This design lets you scale each path on its own.

### PostgreSQL

* Use a dedicated primary for writes and replicas for reads.
* Enable synchronous replication for critical data.
* Configure automatic failover with Patroni or AWS RDS.
* Monitor replication lag and consistency.
* Prefer managed services such as AWS RDS or GCP Cloud SQL.

### Redis / Valkey

* Deploy one primary with replicas across multiple zones. Midaz does not support Redis Cluster mode for transactions.
* Enable automatic failover with a Sentinel topology via `REDIS_MASTER_NAME`, or with a managed service with cluster mode disabled. Set `REDIS_HOST` to one address, or set `REDIS_MASTER_NAME` for Sentinel. Without `REDIS_MASTER_NAME`, a comma-separated `REDIS_HOST` selects Cluster mode. A managed service (ElastiCache, Memorystore) is the safer default.

### MongoDB

* Use replica sets with members across zones.
* Monitor role transitions and lag.
* Schedule regular backups.
* Use managed services such as MongoDB Atlas or AWS DocumentDB.

## Messaging infrastructure

***

Midaz runs two messaging surfaces. Kafka-compatible streaming and asynchronous transaction processing are off by default. The legacy RabbitMQ overdraft and audit publishers are enabled at runtime unless you explicitly set their flags to `false`. The bundled example configuration sets those flags to `false`:

* **RabbitMQ** carries the optional write-behind pipeline that stores confirmed transactions in PostgreSQL and MongoDB (`RABBITMQ_TRANSACTION_BALANCE_OPERATION_*`, enabled with `RABBITMQ_TRANSACTION_ASYNC=true`) plus legacy outbound overdraft and audit exchanges. Use a managed RabbitMQ service such as AWS MQ or CloudAMQP in production.
* **RedPanda** is the event backbone. Set `STREAMING_ENABLED=true`, `STREAMING_BROKERS`, and `STREAMING_CLOUDEVENTS_SOURCE` set to exactly `ledger` for ledger, CRM, and Fees, or `tracer` for Tracer. Facts publish to `lerian.streaming.ledger` or `lerian.streaming.tracer`. Route by CloudEvents headers. Transaction-lifecycle facts publish through this surface.

Optional PostgreSQL read replicas (`DB_ONBOARDING_REPLICA_*` and `DB_TRANSACTION_REPLICA_*`) serve reads. Transactional reads go to the primary by default.

## High availability strategies

***

### Service redundancy

* Deploy multiple replicas for every service.
* Use anti-affinity rules to spread services across zones.
* Apply Pod Disruption Budgets to limit downtime during updates.

### Load balancing

* Use ingress controllers with health checks.
* Avoid session affinity unless a service requires it.
* Enable connection draining for smooth rollouts.

## Security considerations

***

### Network security

* Apply Kubernetes network policies to control traffic.
* Give each service account minimal permissions.
* Secure external access with TLS.
* Restrict admin interfaces with IP allowlists.

### Secret management

* Use Kubernetes Secrets for credentials and tokens.
* Rotate secrets on a regular schedule.
* Never hardcode secrets in containers or config files.
* Use an external secret manager for a stronger posture.

## Monitoring and observability

***

### Metrics

* Monitor the key application and infrastructure KPIs.
* Set alert thresholds that lead to action.
* Use dashboards for real-time visibility.

### Logging

* Centralize logs across all services.
* Use a structured format for easier filtering.
* Apply log retention and rotation policies.
* Define log-based alerts for critical events.

### Tracing

* Enable distributed tracing across services.
* Sample traces to balance performance and cost.
* Correlate traces with logs and metrics for full visibility.

### Alerting

* Create clear, reliable alerts.
* Tune thresholds to reduce noise.
* Route each alert through the right channel.
* Keep runbooks for recurring issues.

## Backup strategy

***

* Automate regular backups for critical systems.
* Store backups in more than one location or region.
* Test the restore procedure on a regular schedule.
* Keep the backup documentation current and accessible.

## Idempotency

***

Protect critical operations against duplicate processing in production:

* Send an idempotency key on every transaction create request with the `X-Idempotency` header.
* Use explicit, deterministic keys tied to your business IDs (order IDs, payment references), not auto-generated keys.
* Read the `X-Idempotency-Replayed` response header to tell a new transaction from a cached replay.
* Set the `X-TTL` header in seconds to match your retry window. The default is 300. Use a shorter value for synchronous flows and a longer one for asynchronous flows.

> [!NOTE]
>
> Several Lerian products support idempotency through their own header conventions. For implementation details and a comparison across products, see [Retries and idempotency](/en/reference/retries-idempotency).

## Aligning infrastructure to the Midaz architecture

***

Align your infrastructure to the Midaz architecture and you gain:

* Clean read/write separation with CQRS.
* Compatibility with managed cloud services.
* A clear path to observability, failover, and secure operations.

Review your setup on a regular schedule.

## What’s next?

***

* Read the [Midaz deployment guide](/en/products/midaz/deployment).
* [Contact our team](https://lerian.studio/contact) for tailored support.


# Midaz SDK for Go
Source: https://docs.lerian.studio/en/products/midaz/midaz-sdk-go

Build Go applications on top of Midaz with the official Go SDK: typed pagination, structured errors, retries, and OpenTelemetry observability.

The **Midaz SDK for Go** is the Go client for the Midaz ledger and Tracer APIs. It gives you typed access to each service (Organizations, Ledgers, Accounts, Transactions, and more) with one surface for authentication, pagination, errors, retries, logging, and observability.

## Getting started

***

### Step 1 – Install Go

Install Go before you use the SDK. The SDK declares **Go 1.26** in `go.mod`. Its public API uses `iter.Seq2` and `log/slog`.

**Step 1**

Go to the [official Go website](https://golang.org/dl/).

**Step 2**

Download the installer for your OS (Windows, macOS, or Linux).

**Step 3**

[**Follow the installation instructions.**](https://go.dev/doc/install)

### Step 2 – Create or use an existing Go project

**Create a Go project:**

To create a Go project, use the following command:

```bash Bash theme={null}
mkdir my-midaz-app
cd my-midaz-app
go mod init my-midaz-app
```

**Use an existing Go project:**

If you're working in an existing project, make sure there's a `go.mod` file in the root. If not, run the following command to create one:

```bash Bash theme={null}
go mod init your-module-name
```

### Step 3 – Add the Midaz SDK

Inside your project directory, run the following command to add the SDK to your `go.mod` and `go.sum` files:

> [!WARNING]
>
> **The module path requires the `/v6` suffix.** If you omit it, Go resolves an old v1 release. Import `github.com/LerianStudio/midaz-sdk-golang/v6`.

```bash Bash theme={null}
go get github.com/LerianStudio/midaz-sdk-golang/v6
```

> [!TIP]
>
> In VS Code or GoLand, your IDE may automatically run `go get` when you import a new package.

### Step 4 – Import the SDK

Create or open a `main.go` file and add the following content. The example builds a client against your local Midaz stack with anonymous authentication, lists organizations, then creates a new one.

> [!NOTE]
>
> The example below targets a local Midaz stack with auth disabled. If you don't have one running yet, see [Getting started with Midaz](/en/start-here/getting-started) to spin one up before running the snippet.

```go Go expandable theme={null}
package main

import (
	"context"
	"fmt"
	"log"

	midaz "github.com/LerianStudio/midaz-sdk-golang/v6"
	"github.com/LerianStudio/midaz-sdk-golang/v6/models"
)

func main() {
	// Build a client. The SDK requires exactly one auth source: use
	// midaz.WithAnonymous() for a local stack, or midaz.WithAccessManager(...)
	// for a development or production environment.
	c, err := midaz.New(
		midaz.WithEnvironment(midaz.EnvironmentLocal),
		midaz.WithAnonymous(),
	)
	if err != nil {
		log.Fatalf("midaz.New: %v", err)
	}
	defer c.Shutdown(context.Background())

	ctx := context.Background()

	// List the first 5 organizations using a typed list-opts struct.
	page, err := c.V2.Organizations.List(ctx, models.OrganizationsListOpts{
		PageListOpts: models.PageListOpts{Limit: 5},
	})
	if err != nil {
		log.Fatalf("list organizations: %v", err)
	}

	for _, org := range page.Items {
		fmt.Printf("- %s (%s)\n", org.LegalName, org.ID)
	}

	// Create a new organization. midaz.CreateOrganizationInput is the same
	// type as models.CreateOrganizationInput, re-exported on the midaz package.
	dba := "Example Inc."
	org, err := c.V2.Organizations.Create(ctx, &midaz.CreateOrganizationInput{
		LegalName:       "Example Corporation",
		LegalDocument:   "123456789",
		DoingBusinessAs: &dba, // optional fields are *string
		Address: midaz.Address{
			Line1:   "123 Main St",
			City:    "New York",
			State:   "NY",
			ZipCode: "10001",
			Country: "US",
		},
	})
	if err != nil {
		log.Fatalf("create organization: %v", err)
	}

	fmt.Printf("Organization created: %s\n", org.ID)
}
```

This gives you access to:

* The Midaz client for calling each API service.
* Built-in data models (like `CreateOrganizationInput`).
* Auth via **Access Manager** (production) or **Anonymous** (local development).
* A typed configuration system that fails at construction time.

> [!TIP]
>
> For the full setup, see the [Authentication](#authentication) section.

### Step 5 – Run the project

Run the following command:

```bash Bash theme={null}
go run main.go
```

## SDK architecture

***

#### Layered design

| Layer | What it handles |
| :- | :- |
| **Client** | The main entry point. `midaz.New(...)` wires authentication, retries, and observability. |
| **Services** | Access to each Midaz domain, grouped by the API version that serves it. |
| **Models** | The data structures of the Midaz domain. The common ones are re-exported on the `midaz` package. |
| **Utility packages** | Helpers for config, errors, observability, retries, idempotency, and more. |

### Services

Midaz serves two ledger API versions: `/v1`, which is deprecated, and `/v2`. The SDK groups the ledger services by the version that serves them. **Build against `c.V2`.** A resource that one version does not serve is a compile error, not a 404.

```go Go theme={null}
orgs, err := c.V2.Organizations.List(ctx, opts)
account, err := c.V2.Accounts.Get(ctx, orgID, ledgerID, accountID)
tx, err := c.V2.Transactions.CreateDirect(ctx, orgID, ledgerID, input)

// /v1 only:
rate, err := c.V1.AssetRates.GetAssetRate(ctx, orgID, ledgerID, externalID)
```

| Group | Services |
| :- | :- |
| `c.V2` and `c.V1` | `Organizations`, `Ledgers`, `Accounts`, `AccountTypes`, `Assets`, `Balances`, `Operations`, `Portfolios`, `Segments`, `OperationRoutes`, `TransactionRoutes`, `Transactions`, `MetadataIndexes` |
| `c.V2` only | `Holders`, `Instruments`, `Encryption`, `Composition`, `ProtectionAudit`, `BillingPackages`, `FeePackages`, `FeeEstimates`, `BillingCalculations` |
| `c.V1` only | `AssetRates` |
| Tracer, on the client | `c.Rules`, `c.Limits`, `c.Validations`, `c.Reservations`, `c.AuditEvents` |

`Transactions` has a different contract on each version. On `/v1`, you create a transaction through one of four creation endpoints with a nested `send` body. On `/v2`, `c.V2.Transactions` creates transactions with a flat body through `CreateDirect`, `CreateHold`, `CreateBlock`, and `CreateUnblock`. It returns `models.TransactionV2`.

> [!NOTE]
>
> A `201` response means that Midaz applied the transaction to balances.

### Models

Each model type represents a business concept. You use them in each service call.

The most common model types are re-exported on the `midaz` package. `midaz.Account` and `models.Account` are the same type, so most code needs only one import.

#### Common model types

| Model | What it represents |
| :- | :- |
| `midaz.Organization` | A business entity that owns ledgers and accounts. |
| `midaz.Ledger` | A collection of accounts and transactions. |
| `midaz.Asset` | A unit of value (currency, token, etc.) that can be stored or moved. |
| `midaz.Account` | An account for tracking assets and balances. |
| `midaz.Portfolio` | A collection of accounts for grouping and management. |
| `midaz.Segment` | A categorization unit for granular organization. |
| `midaz.Transaction` | A financial event composed of multiple operations. |
| `midaz.Operation` | An individual debit or credit entry within a transaction. |
| `midaz.Balance` | The current state of an account's holdings. |

> [!TIP]
>
> For a type that is not re-exported, such as `models.TransactionV2`, import `github.com/LerianStudio/midaz-sdk-golang/v6/models` directly. The `midaz` aliases keep the type identity, so the two import paths work together.

### Utility packages

The `pkg` folder of the SDK holds utility packages. **Core** packages serve concerns that apply to the whole SDK. **Helper** packages give domain-specific or low-level utilities.

#### Core packages

| Package | What it solves |
| :- | :- |
| `auth` | Access Manager OAuth and the token lifecycle. |
| `config` | Config handling, environment loading, and custom service URLs. |
| `concurrent` | Tools for batching, rate-limiting, and worker pools. |
| `errors` | Structured error types, classifiers, and the `Retryable()` predicate. |
| `observability` | Tracing, metrics, and logs through one OpenTelemetry provider. |
| `retry` | Retry policy options with exponential backoff and jitter. |
| `sdkctx` | Per-request context flags, such as idempotency keys. |
| `validation` | Input validation with structured error messages. |

#### Helper packages

| Package | What it solves |
| :- | :- |
| `accounts` | Account-specific helpers and convenience functions. |
| `conversion` | Type conversion helpers between models and external formats. |
| `data` | Data utilities and faker helpers for testing and demos. |
| `format` | Utilities for formatting data the Midaz way (dates, times, etc.). |
| `generator` | Demo and mass-data generation for end-to-end scenarios. |
| `integrity` | Checksum and integrity verification utilities. |
| `performance` | Helpers for tuning bulk operations and high-throughput tasks. |
| `security` | Security utilities, including SSRF protection and TLS validation. |
| `stats` | Processing statistics and metrics aggregation. |
| `transaction` | Transaction helpers, such as the settlement wait. |
| `utils` | General-purpose helpers used across the SDK. |
| `version` | SDK version metadata and identification. |

## Authentication

***

The SDK requires exactly one authentication source at construction time. If you call `midaz.New(...)` with neither, it returns a typed configuration error.

You have two choices:

* **`midaz.WithAccessManager(...)`**: OAuth through the Lerian Access Manager. Use it for any non-local stack.
* **`midaz.WithAnonymous()`**: no authentication. Use it only for a local Midaz stack with auth disabled.

If you apply both options, the last one wins.

### Production: Access Manager

Put your Access Manager credentials in `midaz.WithAccessManager`. The SDK requests a token from your Access Manager, attaches it to each API call, and refreshes it when it expires.

> [!WARNING]
>
> Replace the values in the `// Configure Access Manager` block with your own credentials before running.

```go Go expandable theme={null}
package main

import (
	"context"
	"log"
	"os"

	midaz "github.com/LerianStudio/midaz-sdk-golang/v6"
)

func main() {
	// Configure Access Manager. Load ClientID and ClientSecret from
	// environment variables; do not hardcode them.
	c, err := midaz.New(
		midaz.WithEnvironment(midaz.EnvironmentProduction),
		midaz.WithAccessManager(midaz.AccessManager{
			Address:      "https://auth.example.com",
			ClientID:     os.Getenv("MIDAZ_CLIENT_ID"),
			ClientSecret: os.Getenv("MIDAZ_CLIENT_SECRET"),
		}),
	)
	if err != nil {
		log.Fatalf("midaz.New: %v", err)
	}
	defer c.Shutdown(context.Background())

	// Use c.V2.Organizations, c.V2.Ledgers, c.V2.Accounts, ...
}
```

### Local development: Anonymous

For a local Midaz stack with auth disabled, opt out explicitly:

```go Go theme={null}
c, err := midaz.New(
    midaz.WithEnvironment(midaz.EnvironmentLocal),
    midaz.WithAnonymous(),
)
```

### Configure via environment variables

You can also point the SDK at your Access Manager with environment variables. Export them in your shell or your process manager:

```bash Bash theme={null}
export PLUGIN_AUTH_ENABLED=true
export PLUGIN_AUTH_ADDRESS=https://your-auth-service.com
export MIDAZ_CLIENT_ID=your-client-id
export MIDAZ_CLIENT_SECRET=your-client-secret
```

> [!NOTE]
>
> `config.FromEnvironment()` reads the **process environment**, not a `.env` file. If you keep variables in a `.env` file during development, load them with a library like `godotenv` before calling `config.NewConfig(config.FromEnvironment())`.

Then opt in to environment loading at config time:

```go Go theme={null}
import "github.com/LerianStudio/midaz-sdk-golang/v6/pkg/config"

cfg, err := config.NewConfig(config.FromEnvironment())
if err != nil {
    log.Fatalf("config: %v", err)
}

c, err := midaz.New(midaz.WithConfig(cfg))
```

> [!NOTE]
>
> Environment loading is **explicit**. Put `config.FromEnvironment()` in the option chain. The SDK does not read environment variables during construction without it.

> [!TIP]
>
> For the full auth walkthrough, see the [Authentication guide](https://github.com/LerianStudio/midaz-sdk-golang/blob/main/docs/auth.md) in the SDK repo.

## Tenant scope

***

**Tenant scope comes from the Access Manager / JWT claims** used to obtain the token. The SDK has no tenant configuration and does not send a tenant header.

To run calls under a different tenant scope, use a separate set of Access Manager credentials, or build a second client with its own token context.

## Listing and iteration

***

Most list endpoints come in three methods. Pick the one that matches your use case.

| Method | Returns | Use when |
| :- | :- | :- |
| `List` | `*models.ListResponse[T]` (one page) | You want exactly one page and decide when to advance. |
| `All` | `iter.Seq2[T, error]` | You want each item. The SDK handles paging internally. |
| `Pages` | `iter.Seq2[*models.ListResponse[T], error]` | You need page-level metadata for checkpointing or batching. |

### Typed list options

Each list method takes a typed opts struct. The struct embeds one of two base structs, based on how the endpoint paginates:

| Pagination shape | Endpoints | Base struct |
| :- | :- | :- |
| **Page-based** | Organizations, Ledgers, Assets, Portfolios, Segments, Accounts, AccountTypes, FeePackages, BillingPackages | `models.PageListOpts{Limit, Page, SortDirection, StartDate, EndDate}` |
| **Cursor-based** | Transactions, Balances, Holders, Operations, OperationRoutes, TransactionRoutes, AssetRates | `models.CursorListOpts{Limit, Cursor, SortDirection, StartDate, EndDate}` |

Some endpoints also expose a typed `Filters` sub-struct. If you set a field of the wrong shape (for example, `Page` on a cursor endpoint), the code does not compile.

> [!WARNING]
>
> The transaction list does not filter by `Status`, `AssetCode`, `Reference`, `SourceAccount`, `DestinationAccount`, or `Route`. If you set one of these filters on `List`, the SDK refuses the call with an error. `Count` accepts `Status` and `Route`.

### Iterate every item with `All`

The simplest shape is a `range` loop over each item across each page. The SDK fetches the pages internally.

```go Go theme={null}
opts := models.AccountsListOpts{
    PageListOpts: models.PageListOpts{Limit: 100},
    Filters: models.AccountsFilters{
        Status:    "ACTIVE",
        AssetCode: "USD",
    },
}

for account, err := range c.V2.Accounts.All(ctx, orgID, ledgerID, opts) {
    if err != nil {
        return fmt.Errorf("list accounts: %w", err)
    }
    process(account)
}
```

### Iterate page envelopes with `Pages`

When you need page-level metadata (for checkpointing, batching, or stopping mid-page), iterate over `Pages`. Each entry is a `*models.ListResponse[T]` with its `Pagination` block.

```go Go theme={null}
opts := models.TransactionsListOpts{
    CursorListOpts: models.CursorListOpts{Limit: 50},
}

for page, err := range c.V2.Transactions.Pages(ctx, orgID, ledgerID, opts) {
    if err != nil {
        return fmt.Errorf("page iter: %w", err)
    }
    log.Printf("items=%d next_cursor=%q", len(page.Items), page.Pagination.NextCursor)

    for _, tx := range page.Items {
        process(tx)
    }

    if shouldStop(page) {
        break // The SDK stops paging.
    }
}
```

See the [Pagination guide](https://github.com/LerianStudio/midaz-sdk-golang/blob/main/docs/pagination.md) in the SDK repo for `NextCursor` handling and the page-vs-cursor decision table.

## Error handling

***

The SDK service layer returns errors as `*pkg/errors.Error` with structured fields:

| Field | What it carries |
| :- | :- |
| `Category` | The error class (validation, authentication, network, configuration, and so on). |
| `Code` | A stable string code for branching or telemetry. |
| `Operation` | The SDK operation that produced the error. |
| `Resource` | The resource family the error refers to, when relevant. |

You can branch with typed predicates, read fields with `errors.As`, or use the `Retryable()` method to drive retry policy.

### Branch with typed predicates

The SDK has a set of `Is*` predicates, so you can match errors without reading internals:

```go Go expandable theme={null}
import (
    "errors"
    "fmt"

    sdkerrors "github.com/LerianStudio/midaz-sdk-golang/v6/pkg/errors"
)

acc, err := c.V2.Accounts.Get(ctx, orgID, ledgerID, accountID)
if err != nil {
    switch {
    case sdkerrors.IsNotFoundError(err):
        return fmt.Errorf("account not found: %w", err)
    case sdkerrors.IsAuthError(err):
        return fmt.Errorf("auth failure: %w", err)
    case sdkerrors.IsValidationError(err):
        return fmt.Errorf("invalid input: %w", err)
    case sdkerrors.IsConflictError(err):
        return fmt.Errorf("already exists: %w", err)
    case sdkerrors.IsRateLimitError(err):
        return fmt.Errorf("rate limited: %w", err)
    case sdkerrors.IsNetworkError(err):
        return fmt.Errorf("transient transport: %w", err)
    case sdkerrors.IsConfigurationError(err):
        return fmt.Errorf("setup mistake: %w", err)
    }

    // Read the structured fields when you need them.
    var sdkErr *sdkerrors.Error
    if errors.As(err, &sdkErr) {
        log.Printf("op=%s resource=%s code=%s retryable=%v",
            sdkErr.Operation, sdkErr.Resource, sdkErr.Code, sdkErr.Retryable())
    }
}
```

### Drive retry decisions with `Retryable()`

The `Error.Retryable()` method derives from `Category`. Use it instead of your own classification.

```go Go theme={null}
var sdkErr *sdkerrors.Error
if errors.As(err, &sdkErr) && sdkErr.Retryable() {
    // Apply your retry logic: backoff, jitter, max attempts, etc.
}
```

### Wrap raw transport errors

If you call lower-level HTTP code outside the SDK and want the same structured error shape, use `ClassifyTransportError`:

```go Go theme={null}
import sdkerrors "github.com/LerianStudio/midaz-sdk-golang/v6/pkg/errors"

resp, err := httpClient.Do(req)
if err != nil {
    return sdkerrors.ClassifyTransportError("PaymentService.Charge", err)
}
```

### Local validation: FieldErrors

Local input validation returns `*pkg/validation.FieldErrors`, a collection of per-field errors that the SDK finds before any HTTP call. Use `errors.As` to read them.

```go Go theme={null}
import (
    "errors"
    "fmt"

    "github.com/LerianStudio/midaz-sdk-golang/v6/pkg/validation"
)

var fieldErrs *validation.FieldErrors
if errors.As(err, &fieldErrs) {
    for _, fe := range fieldErrs.Errs() {
        fmt.Printf("- %s: %s\n", fe.Field, fe.Message)
    }
}
```

> [!TIP]
>
> For the full category map, each code, and retry boundaries, see the [Error handling guide](https://github.com/LerianStudio/midaz-sdk-golang/blob/main/docs/errors.md) in the SDK repo.

## Retries

***

The default policy retries 3 times with exponential backoff and 25% jitter. It retries transport errors and the statuses `408`, `425`, `429`, `500`, `502`, `503`, and `504`. The SDK retries `POST`, `PUT`, `PATCH`, and `DELETE` only when the request has an `X-Idempotency` header.

```go Go theme={null}
import (
    "time"

    "github.com/LerianStudio/midaz-sdk-golang/v6/pkg/retry"
)

c, err := midaz.New(
    midaz.WithEnvironment(midaz.EnvironmentLocal),
    midaz.WithAnonymous(),
    midaz.WithRetryOptions(
        retry.WithMaxRetries(5),
        retry.WithInitialDelay(200*time.Millisecond),
    ),
)
```

Use `midaz.WithCustomRetryPolicy` for your own retry predicate. To turn retries off, use `midaz.WithoutRetries()`.

## Logging

***

**`*slog.Logger` is the logger surface of the SDK.** Wire it with `midaz.WithLogger(...)`. The SDK is **silent by default**: it uses `slog.DiscardHandler` until you opt in.

You decide the handler, the level, and the destination.

```go Go expandable theme={null}
package main

import (
    "context"
    "log"
    "log/slog"
    "os"

    midaz "github.com/LerianStudio/midaz-sdk-golang/v6"
)

func main() {
    logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
        Level: slog.LevelInfo,
    }))

    c, err := midaz.New(
        midaz.WithEnvironment(midaz.EnvironmentLocal),
        midaz.WithAnonymous(),
        midaz.WithLogger(logger),
    )
    if err != nil {
        log.Fatalf("midaz.New: %v", err)
    }
    defer c.Shutdown(context.Background())

    // SDK log lines now go to your handler.
}
```

charmbracelet/log, zap, and zerolog integrate through `slog.Handler`.

> [!TIP]
>
> The [Logging guide](https://github.com/LerianStudio/midaz-sdk-golang/blob/main/docs/logging.md) has adapter recipes for common logging libraries.

## Observability

***

One observability provider gives you spans, metrics, and OpenTelemetry-correlated logs through one wiring point.

Pass a provider that you build, or pass options that the SDK assembles for you.

### Wire a provider

```go Go expandable theme={null}
package main

import (
    "context"
    "log"

    midaz "github.com/LerianStudio/midaz-sdk-golang/v6"
    "github.com/LerianStudio/midaz-sdk-golang/v6/pkg/observability"
)

func main() {
    ctx := context.Background()

    provider, err := observability.New(ctx,
        observability.WithServiceName("payments-api"),
        observability.WithEnvironment("production"),
        observability.WithComponentEnabled(true, true, true), // tracing, metrics, logs
    )
    if err != nil {
        log.Fatalf("observability.New: %v", err)
    }
    defer provider.Shutdown(ctx)

    c, err := midaz.New(
        midaz.WithEnvironment(midaz.EnvironmentProduction),
        midaz.WithAccessManager(midaz.AccessManager{ /* ... */ }),
        midaz.WithObservabilityProvider(provider),
    )
    if err != nil {
        log.Fatalf("midaz.New: %v", err)
    }
    defer c.Shutdown(ctx)
}
```

### Or pass options inline

```go Go theme={null}
import "github.com/LerianStudio/midaz-sdk-golang/v6/pkg/observability"

c, err := midaz.New(
    midaz.WithEnvironment(midaz.EnvironmentProduction),
    midaz.WithAccessManager(am),
    midaz.WithObservabilityOptions(
        observability.WithServiceName("payments-api"),
        observability.WithComponentEnabled(true, true, true),
    ),
)
```

The SDK emits one HTTP span per outbound request with W3C `traceparent` propagation. Business log records carry safe IDs only: no payloads, names, addresses, or auth headers.

You can also wrap a block of business logic in a span with `Client.Trace`:

```go Go theme={null}
err = c.Trace("create-organization", func(ctx context.Context) error {
    _, err := c.V2.Organizations.Create(ctx, input)
    return err
})
```

> [!WARNING]
>
> `WithObservabilityOptions` and `WithObservabilityProvider` **replace** the installed provider. They do not merge. To start from a baseline, put `observability.WithDevelopmentDefaults` or `observability.WithProductionDefaults` first in the option chain.

> [!TIP]
>
> See the [`10-observability-otel` example](https://github.com/LerianStudio/midaz-sdk-golang/tree/main/examples/10-observability-otel) in the SDK repo for span attributes, metric names, and exporter setup.

## Idempotency

***

Auto-idempotency is **on by default**. The SDK sends an `X-Idempotency: <uuid>` header on each unsafe HTTP request (POST, PUT, PATCH, DELETE). A retry after a transient failure then does not create a resource twice.

You can override the generated key per call when you need a stable key of your own. This is typical for saga steps, outbox rows, or UI submissions.

### Set a stable key per request

```go Go theme={null}
import "github.com/LerianStudio/midaz-sdk-golang/v6/pkg/sdkctx"

ctx := sdkctx.WithIdempotencyKey(context.Background(), "tx-2026-05-06-001")

tx, err := c.V2.Transactions.CreateDirect(ctx, orgID, ledgerID, input)
```

### Suppress idempotency for one call

For rare administrative calls, suppress the header per request:

```go Go theme={null}
ctx := sdkctx.WithoutAutoIdempotency(context.Background())
```

Without the header, the SDK does not retry that unsafe request.

### Disable globally

To turn auto-idempotency off everywhere, turn it off at the client level:

```go Go theme={null}
c, err := midaz.New(
    midaz.WithEnvironment(midaz.EnvironmentLocal),
    midaz.WithAnonymous(),
    midaz.WithIdempotency(false),
)
```

You can also set `MIDAZ_IDEMPOTENCY=false` when you use `config.FromEnvironment()`.

## Environment variables

***

The SDK reads these variables only when `config.FromEnvironment()` is in your config option chain.

| Variable | Description |
| :- | :- |
| `MIDAZ_ENVIRONMENT` | Target environment (`local`, `development`, `production`). |
| `MIDAZ_BASE_URL` | Base URL for the Midaz services, used when the service-specific URLs are not set. Do not add a `/v1` or `/v2` suffix. |
| `MIDAZ_LEDGER_URL` | Ledger API URL. It serves the onboarding and transaction endpoints. |
| `MIDAZ_TRACER_URL` | Tracer API URL. |
| `MIDAZ_TRACER_API_KEY` | Optional API key for Tracer. When you do not set it, Tracer calls use the ledger bearer token. |
| `PLUGIN_AUTH_ENABLED` | Enable Access Manager authentication (`true` or `false`). |
| `PLUGIN_AUTH_ADDRESS` | Address of the Access Manager service. |
| `MIDAZ_CLIENT_ID` | Client ID for Access Manager authentication. |
| `MIDAZ_CLIENT_SECRET` | Client secret for Access Manager authentication. |
| `MIDAZ_TIMEOUT` | HTTP request timeout in seconds. |
| `MIDAZ_DEBUG` | Enable debug logs (`true` or `false`). |
| `MIDAZ_MAX_RETRIES` | Maximum retry attempts for failed requests. |
| `MIDAZ_IDEMPOTENCY` | Enable automatic idempotency keys for unsafe requests (`true` or `false`). |
| `MIDAZ_ERROR_EXPOSE_BODY` | Include the raw response body in `*pkg/errors.Error`. |
| `MIDAZ_ACCESS_MANAGER_ALLOW_INSECURE_HTTP` | Allow plain HTTP to the Access Manager. The SDK rejects it when `MIDAZ_ENVIRONMENT=production`. |
| `MIDAZ_ALLOW_INSECURE_HTTP` | Allow plain HTTP to the ledger and Tracer URLs on non-loopback hosts. The SDK rejects it when `MIDAZ_ENVIRONMENT=production`. |

For the full option matrix across `midaz`, `pkg/config`, and `pkg/sdkctx`, see the [Configuration guide](https://github.com/LerianStudio/midaz-sdk-golang/blob/main/docs/configuration.md) in the SDK repo.

## Example projects

***

> [!TIP]
>
> The SDK has a numbered set of focused tutorials (examples 01–10), plus advanced and reference examples. Each numbered example teaches one concept. Browse them in the [examples directory](https://github.com/LerianStudio/midaz-sdk-golang/tree/main/examples) on GitHub.

| Example | What it demonstrates |
| :- | :- |
| `01-hello-world` | Minimal init plus the first API call. |
| `02-auth` | Access Manager authentication (production setup). |
| `03-end-to-end` | Creating a transaction on `/v2` with `CreateDirect`. |
| `04-listing-cursor` | Cursor-based pagination with `iter.Seq2`. |
| `05-listing-pages` | Page-based pagination with `List`, `All`, and `Pages`. |
| `06-idempotency` | Auto, explicit, and suppressed idempotency modes. |
| `07-retries` | Default policy, custom policy, disabled retries. |
| `08-logging-slog` | `*slog.Logger` integration. |
| `09-testing-with-mocks` | A narrow interface of your own plus a hand-written mock. |
| `10-observability-otel` | Full OpenTelemetry surface (tracing + metrics + logs). |

The repository also includes reference examples: `concurrency`, `configuration`, `context`, `tracing`, `tracing-server`, `pkg-validation-demo`, `mass-demo-generator`, and `workflow-with-entities`.

## Explore the APIs

***

For more information about the APIs, refer to the following links:

> **[External API mapping](https://github.com/LerianStudio/midaz-sdk-golang/blob/main/docs/mapping/external_apis.md)**

> **[Internal API mapping](https://github.com/LerianStudio/midaz-sdk-golang/blob/main/docs/mapping/internal_apis.md)**

> **[Godoc documentation](https://pkg.go.dev/github.com/LerianStudio/midaz-sdk-golang/v6)**


# Midaz SDK for TypeScript
Source: https://docs.lerian.studio/en/products/midaz/midaz-sdk-typescript

Build typed financial integrations with the Midaz SDK for TypeScript: builder pattern, automatic retries, observability, and strict validation.

The Midaz SDK for TypeScript helps you build financial integrations. It gives you a typed interface over the Midaz financial services platform.

The SDK works with Organizations, Ledgers, Accounts, Transactions, and more.

### Why use the Midaz SDK for TypeScript?

* **Type-safe by design**: Full TypeScript support with precise type definitions.
* **Builder pattern**: Fluent, readable interfaces to construct complex objects.
* **Error handling**: Clear error signals.
* **Observability included**: Tracing, metrics, and logs, off by default.
* **Layered architecture**: Clean separation between client, entities, API, and models.
* **Automatic retries**: Retries for transient failures.
* **Concurrency controls**: Built-in tools to run tasks in parallel with controlled throughput.
* **Strict validation**: Catch invalid input early with clear error messages.

## Getting started

***

### Prerequisite

* The Midaz SDK for TypeScript **requires** Node.js **v18.18 to v24** and TypeScript **v5.8 or later**.

### Installing the SDK

Install the Midaz SDK for TypeScript with one of the following commands:

```bash npm theme={null}
npm install @lerianstudio/midaz-sdk
```

```bash yarn theme={null}
yarn add @lerianstudio/midaz-sdk
```

After you install it, follow the [*Quick Start Guide*](#quick-start-guide) to learn how to use the SDK.

## Authentication

***

The Midaz SDK for TypeScript authenticates through the Lerian Access Manager (OAuth). For a local stack with authentication disabled, you can build a client without it.

You never call a `createClient` factory. Build a configuration with `createClientConfigWithAccessManager()` (or `createClientConfigBuilder()` for a no-auth local stack) and pass it to `new MidazClient(config)`.

#### Access Manager authentication

To integrate with external identity providers over OAuth:

```typescript TypeScript theme={null}
import { createClientConfigWithAccessManager, MidazClient } from '@lerianstudio/midaz-sdk';

const client = new MidazClient(
  createClientConfigWithAccessManager({
    address: 'https://auth.example.com',
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
  }).withEnvironment('sandbox')
);
```

The Access Manager handles tokens for you: acquisition, caching, and renewal. You do not manage tokens manually.

#### Local development (no authentication)

For a local Midaz stack with authentication disabled, build a client without the Access Manager:

```typescript TypeScript theme={null}
import { createClientConfigBuilder, MidazClient } from '@lerianstudio/midaz-sdk';

const client = new MidazClient(
  createClientConfigBuilder().withBaseUrls({
    onboarding: 'http://localhost:3002',
    transaction: 'http://localhost:3002',
  })
);
```

> [!TIP]
>
> We offer an [Access Manager plugin](/en/platform/access-manager) that you can use. If you'd like to know more about it, [contact us](https://lerian.studio/contact).

## Quick start guide

***

The following sections give practical code examples for the Midaz SDK for TypeScript.

### Create a client

The client is your main entry point to the SDK. It handles authentication and gives you access to all entity services.

**Example:**

```typescript TypeScript theme={null}
import { createClientConfigBuilder, MidazClient } from '@lerianstudio/midaz-sdk';

const client = new MidazClient(
  createClientConfigBuilder().withEnvironment('sandbox') // Options: 'development', 'sandbox', 'production'
);
```

The `withEnvironment()` presets use example URLs. Set your Midaz address with `withBaseUrls()` or the `MIDAZ_ONBOARDING_URL` and `MIDAZ_TRANSACTION_URL` environment variables. Both URLs point to your Midaz ledger.

### Create an Asset

Create assets with the builder pattern and `createAssetBuilder`.

**Example:**

```typescript TypeScript theme={null}
import { createAssetBuilder } from '@lerianstudio/midaz-sdk';

const assetInput = createAssetBuilder('US Dollar', 'USD')
  .withType('currency')
  .withMetadata({ precision: 2, symbol: '$' })
  .build();

const asset = await client.entities.assets.createAsset('org_123', 'ledger_456', assetInput);
```

In this code, you add the required `name` and `code` fields to the builder `const assetInput = createAssetBuilder('US Dollar', 'USD')`. Then you add any other properties with `with*` methods.

### Create an Account

Create accounts with the builder pattern and `createAccountBuilder`.

**Example:**

```typescript TypeScript theme={null}
import { createAccountBuilder } from '@lerianstudio/midaz-sdk';

const accountInput = createAccountBuilder('Savings Account', 'USD', 'savings')
  .withAlias('personal-savings')
  .build();

const account = await client.entities.accounts.createAccount('org_123', 'ledger_456', accountInput);
```

In this code, you add the required `name`, `assetCode`, and account `type` to the builder `const accountInput = createAccountBuilder('Savings Account', 'USD', 'savings')`. Then you add any other properties with `with*` methods.

### Create a Transaction

Create transactions with a `CreateTransactionInput` object and `createTransaction`.

**Example:**

```typescript TypeScript expandable theme={null}
import type { CreateTransactionInput } from '@lerianstudio/midaz-sdk';

const transactionInput: CreateTransactionInput = {
  code: 'payment_001',
  chartOfAccountsGroupName: 'PAYMENTS',
  description: 'Monthly payment',
  metadata: { purpose: 'Monthly payment' },
  send: {
    asset: 'USD',
    value: '100.00',
    source: {
      from: [{ account: 'source-account-alias', amount: { asset: 'USD', value: '100.00' } }],
    },
    distribute: {
      to: [{ account: 'destination-account-alias', amount: { asset: 'USD', value: '100.00' } }],
    },
  },
};

const transaction = await client.entities.transactions.createTransaction('org_123', 'ledger_456', transactionInput);
```

In this code, `send` holds the amount. `source.from` lists the accounts that send it, and `distribute.to` lists the accounts that receive it. Each `account` is an account alias. Amounts are decimal strings.

### Clean up resources

```typescript TypeScript theme={null}
await client.destroy();
```

### Using Access Manager for authentication

```typescript TypeScript expandable theme={null}
import { createClientConfigWithAccessManager, MidazClient } from '@lerianstudio/midaz-sdk';

// Initialize the client with Access Manager authentication
const client = new MidazClient(
  createClientConfigWithAccessManager({
    address: 'https://auth.example.com', // Identity provider address
    clientId: 'your-client-id', // OAuth client ID
    clientSecret: 'your-client-secret', // OAuth client secret
    tokenEndpoint: '/v1/login/oauth/access_token', // Optional, this is the default
    refreshThresholdSeconds: 300, // Optional, defaults to 300 (5 minutes)
  })
    .withEnvironment('sandbox')
    .withApiVersion('v1')
);

// The SDK handles token acquisition and renewal
// You can now use the client as normal
const organizations = await client.entities.organizations.listOrganizations();

// Clean up resources when done
await client.destroy();
```

## SDK architecture

***

The Midaz SDK uses a multi-layered service architecture. It has three layers, shown in *Figure 1*.

* **Client interface**: This is the main entry point for SDK users. It manages configuration such as authentication and environments. It gives access to the entity services through `client.entities`.
* **Entity services layer**: This layer holds domain-specific services, such as Accounts, Assets, and Transactions. Most services offer create, get, update, delete, and list methods. Some services also add specialized operations for their entity.
* **Core services layer**: All entity services use these foundational utilities. They handle HTTP requests, input validation, error processing, observability, and configuration.

![Layered architecture of the Midaz SDK for TypeScript, with the client interface over the entity services layer over the shared core services layer](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/sdk-typescript-architecture.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=071bbf4a7b5211949f85b0a406301a77)

Figure 1. The layered architecture of the Midaz SDK for TypeScript.

The SDK architecture emphasizes:

* **Consistency** through shared patterns across services.
* **Scalability** via dependency injection and service factories.
* **Reliability** through enhanced error handling and typed responses.
* **Testability** with support for mocking and integration testing.

> [!TIP]
>
> For more information about the architecture, see the following pages:
>
> * [Midaz SDK architecture overview](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/architecture/overview.md).
> * [Client interface architecture](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/architecture/client-interface.md).
> * [Service layer architecture](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/architecture/service-layer.md).

## Builder pattern

***

The Midaz SDK for TypeScript uses a builder pattern to help you assemble complex objects in a safe, adaptable way. Instead of a fixed set of inputs, it gives you a step-by-step, fluent, chainable interface.

**Builder functions in the SDK:**

* Tell you the parameters in advance.
* Let you set optional fields with `.with*()` methods and chain them.
* Hide internal complexity for better readability.

### Example

```typescript TypeScript theme={null}
const assetInput = createAssetBuilder('USD Currency', 'USD')
  .withType('currency')
  .withMetadata({ precision: 2 })
  .build();
```

You can then pass this `assetInput` to the corresponding create method in the SDK.

> [!TIP]
>
> For more information, see the [Builder Pattern in Midaz SDK](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/core-concepts/builder-pattern.md) page.

## Working with entities

***

Each entity service covers a distinct part of the financial domain, such as accounts, assets, or transactions.

These services read and write data for each type of entity.

They also offer specialized features for each use case.

| Entity | Description |
| :- | :- |
| [**Organizations**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/organizations.md) | Manage business units and organizational data. |
| [**Ledgers**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/ledgers.md) | Structure and manage financial records. |
| [**Assets**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/assets.md) | Work with assets such as currencies, commodities, and other value units. |
| [**Accounts**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/accounts.md) | Create, retrieve, update, and delete accounts within a Ledger. |
| [**Segments**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/segments.md) | Group accounts within a Ledger. |
| [**Portfolios**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/portfolios.md) | Group accounts into collections. |
| [**Balances**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/balances.md) | Retrieve and update account balances. |
| **Transactions** | Create and manage transactions that move assets between accounts. |
| [**Operations**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/operations.md) | Manage atomic debits and credits that make up a transaction. |
| [**Asset Rates**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/entities/asset-rates.md) | Retrieve, create, and update exchange rates between assets. |
| **Account Types** | Create, retrieve, update, and delete account types within a Ledger. |
| **Transaction Routes** | Create, retrieve, update, and delete transaction routes within a Ledger. |
| **Operation Routes** | Create, retrieve, update, and delete operation routes within a Ledger. |

You access each service through the SDK client. They follow a consistent structure, so you build and maintain financial features more easily.

> [!TIP]
>
> For more information, see the [Entities pages](https://github.com/LerianStudio/midaz-sdk-typescript/tree/main/docs/entities).

## Using utilities

***

The SDK provides utility modules for common operations: performance, error handling, configuration, and observability.

| Utility | Description |
| :- | :- |
| [**Account Helpers**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/account-helpers.md) | Simplifies common account-related logic and transformations. |
| [**Concurrency**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/concurrency.md) | Helps coordinate and limit concurrent tasks safely and efficiently. |
| [**Config**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/config.md) | Centralized configuration setup and access. |
| [**Data**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/data.md) | Assists with data formatting and pagination tasks. |
| **Error Handling** | Offers error processing mechanisms. |
| [**HTTP Client**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/http-client.md) | Provides a low-level HTTP interface for direct API calls. |
| [**Network**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/network.md) | Adds high-level networking features like retries and backoff. |
| [**Observability**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/observability.md) | Captures traces, metrics, and logs to support monitoring and debugging. |
| [**Pagination**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/pagination.md) | Handles paginated responses with predictable, consistent helpers. |
| [**Validation**](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/docs/utilities/validation.md) | Validates input and output data to help maintain data integrity. |

> [!TIP]
>
> For more information, see the [Utilities pages](https://github.com/LerianStudio/midaz-sdk-typescript/tree/main/docs/utilities).

## Error handling

***

The Midaz SDK for TypeScript helps you handle errors clearly and consistently. When an SDK operation fails, the SDK throws an error. An API error response throws an `HttpError` with these fields:

* `status`: The HTTP status code.
* `statusText`: The HTTP status text.
* `response`: The error body from Midaz.

Invalid input throws a `ValidationError` before the request. Use `processError()` to read both types in one shape.

Handle an error like this:

```typescript TypeScript theme={null}
import { processError } from '@lerianstudio/midaz-sdk';

try {
  await client.entities.transactions.createTransaction('org_123', 'ledger_456', transactionInput);
} catch (err) {
  const info = processError(err);
  console.error(`Error (${info.statusCode}): ${info.message}`);
}
```

### Best practices

* **Validate input** before you call SDK methods.
* **Check your auth** when you get status `401` or `403`.
* **Retry** on transient issues like status `500` or `503`.
* **Use `statusCode` and `message`** to show debug info in development logs.

## CI/CD pipeline

***

We use GitHub Actions for automated, production-ready builds:

* Runs tests across multiple Node.js versions.
* Enforces code quality with ESLint and Prettier.
* Keeps dependencies up to date with Dependabot.
* Handles releases automatically with semantic versioning.
* Generates changelogs.

## Want to contribute?

***

To contribute to the Midaz SDK for TypeScript, start with our [contributing guide on GitHub](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/CONTRIBUTING.md).

## License

***

This project is licensed under the Apache License 2.0. For details, see the [License](https://github.com/LerianStudio/midaz-sdk-typescript/blob/main/LICENSE) page.


# Operations
Source: https://docs.lerian.studio/en/products/midaz/operations

Understand Operations as the smallest units of ledger activity in Midaz: single debit or credit entries on an Account, grouped into balanced Transactions.

An operation is the smallest unit of a transaction. A posted transaction has at least one debit and one credit operation. A pending transaction records only its source side until you commit it.

* A **Debit operation** records value that moves **out of** an account (the source).
* A **Credit operation** records value that moves **into** an account (the destination).

The effect on the stored balance depends on the balance `direction`. A normal account (the common case) shrinks on a debit and grows on a credit.

A transaction contains operations that must net to zero from the ledger's view. For example, a P2P payment with a fee includes:

* a **\$100 debit** from the sender's account.
* a **\$98 credit** to the recipient's account.
* a **\$2 credit** to the platform's fee account.

Midaz makes sure a transaction balances before it commits.

Operations also carry metadata such as timestamps and references to the transaction they belong to. You create a transaction through the Midaz JSON API. For each transaction, you specify a set of operations. Each operation has an amount, an asset, and a source or destination account.

## Key characteristics

***

* Each operation belongs to a transaction and references a specific account and asset.
* Operations include metadata like amount, direction (debit/credit), type, timestamps, references, and more.
* Midaz creates operations when you start a transaction and fills them with the data you provide.
* Midaz validates all operations against the configured rules before it commits them to the ledger.

> [!NOTE]
>
> Every operation has a **`direction`** (`debit` or `credit`) and a **`type`**. The `direction` is the debit or credit side described above. The `type` classifies the movement. Beyond the standard `CREDIT` and `DEBIT`, the `type` marks special movements:
>
> * `ON_HOLD` and `RELEASE`: two-phase fund reservations.
> * `OVERDRAFT`: system-generated companion operations on the internal overdraft balance.
> * `BLOCK` and `UNBLOCK`: the label applied to every operation of a transaction created through the dedicated [block and unblock endpoints](/en/products/midaz/transactions#blocking-and-unblocking-funds). The label overrides only the operation `type`, never its direction or amount.
> * `FEE_SETTLEMENT` and `FEE_REFUND`: the settlement of a [fee debt](/en/products/midaz/fees/fee-debt), and its refund on a revert.
>
> The `direction` always keeps its debit or credit meaning, regardless of `type`.

## Operation Routes

***

With Accounting Routes, each operation connects to structured validation logic. That logic lives in [Operation Routes](/en/products/midaz/transaction-routing-entities).

### What is an Operation Route?

An **Operation Route** is a validation rule. It defines which account types or specific accounts a transaction component can use. It also sets the accounting direction (source, destination, or bidirectional) and a descriptive annotation.

It is a validation layer between transaction input and ledger structure. Each operation you submit must meet the account requirements and business rules.

> [!NOTE]
>
> Transactions contain multiple operations. Operation Routes validate each operation against the configured validation rules.

### Operation > Operation Route relationship

When you submit a transaction to Midaz, it contains multiple **Operations**. With **Account Types and Accounting Routes enabled**, Midaz validates each operation against the rules in the Operation Routes. This makes sure that:

* The specified account matches the expected account type or specific account requirement.
* The operation direction (debit/credit) aligns with the route definition.

> [!CAUTION]
>
> If the operations you submit do not match the configured Operation Route requirements, Midaz fails the validation and rejects the transaction.

## Managing Operations

***

Midaz generates operations automatically as part of a transaction flow. You cannot create an operation directly. You can query an operation and update its description and metadata.

* [List Operations by Account](/en/reference/products/midaz/v2/get-all-operations-by-account): View all Operations linked to a specific Account.
* [Retrieve an Operation by Account](/en/reference/products/midaz/v2/get-operation-by-account): Get details of a specific Operation for that Account.
* [Update an Operation](/en/reference/products/midaz/v2/update-operation): Change the description and metadata of an Operation.


# Organizations
Source: https://docs.lerian.studio/en/products/midaz/organizations

Define the top-level Organization that owns your Midaz Ledgers. Represent banks, fintechs, and parent-child hierarchies for subsidiaries.

An **Organization** is the top-level entity in Midaz. It represents a financial institution, such as a bank or fintech. An Organization owns and governs the financial data of that institution. It is the primary container for all financial operations.

A bank or financial group registers as an Organization in Midaz.

> [!NOTE]
>
> **On Lerian Cloud**: Midaz scopes every Organization to your tenant automatically. When you list Organizations, you see only the ones in your account. You do not filter by tenant or add a tenant identifier to your requests.

### Sub-Organizations

Organizations support **parent-child hierarchies**. A bank uses them to represent subsidiaries, regional branches, or separate business units in one framework.

This structure fits financial groups that run several legal entities. Each entity owns its own [Ledgers](/en/products/midaz/ledgers) and stays operationally independent. The parent-child link records how the entities relate.

### Organization structure

* **Organization > Ledgers:** An Organization can own several Ledgers. Each Ledger holds its financial records, such as accounts and transactions, and belongs to one Organization.

### Key characteristics

* Organizations are the highest level in the hierarchy.
* Each Organization governs its own Ledgers and sets their operational boundaries.

## Flexible hierarchies

***

Midaz supports organizational hierarchies for complex structures.

If your company has several locations or divisions, you can create **child organizations** for specific branches, offices, or subdivisions. Each child organization connects to a **parent organization**.

Each Organization keeps its own data.

> [!NOTE]
>
> If a single group manages several Organizations, use this hierarchy to set clear boundaries between them.

### Example

**Company XPTO** is a Brazilian company with branches in São Paulo and New York. Its structure is as follows:

* **Parent Organization**: XPTO Ltda
* **Child Organizations**:
  * XPTO New York
  * XPTO São Paulo

With this structure, the company can:

* Set a distinct role for each branch.
* Track each branch separately.
* Adapt workflows to each branch.

## Benefits of organizational structuring

***

* **Scalability**: Add or change branches as the business grows.
* **Efficiency**: Manage all levels from one hierarchy.
* **Personalization**: Configure each branch on its own.

> [!TIP]
>
> Need help with your Midaz setup? Our consulting service can help you design the structure for your organization, from scratch or from an existing setup.
>
> [Contact us](https://lerian.studio/contact) to learn more.

## Managing Organizations

***

You manage your Organization through the API or Lerian Console.

### Via API

* [Create an Organization](/en/reference/products/midaz/v2/create-organization): Register a new Organization.
* [List Organizations](/en/reference/products/midaz/v2/list-organizations): View all Organizations in your workspace.
* [Retrieve an Organization](/en/reference/products/midaz/v2/get-organization-by-id): Get details of a specific Organization.
* [Update an Organization](/en/reference/products/midaz/v2/update-organization): Edit an existing Organization.
* [Delete an Organization](/en/reference/products/midaz/v2/delete-organization): Mark an Organization as deleted.

> [!NOTE]
>
> When you delete an Organization, Midaz does not remove it from the system.
>
> Midaz sets a `deletedAt` timestamp instead. Midaz then excludes the Organization from every read, and you can no longer use it. Midaz leaves its `status.code` unchanged, which preserves historical data for audit trails. Midaz rejects Organization deletion in a production environment.

### Via Lerian Console

You view, create, edit, and delete Organizations from the **Organizations** page in the Midaz Module of Lerian Console.

[**Learn more in the Managing Organizations guide.**](/en/products/midaz/console/managing-organizations)

> [!TIP]
>
> When you create your **first Organization** in the Console, you do it as part of the onboarding flow. To learn more, see the [Midaz Module onboarding](/en/products/midaz/console/midaz-console-onboarding) guide.


# Portfolios
Source: https://docs.lerian.studio/en/products/midaz/portfolios

Group Midaz Accounts under a single customer or business unit as a Portfolio to view the total client relationship and apply policies at the wallet level.

A **Portfolio** is a logical group of Accounts that belong to a single entity, such as a customer or business unit. It groups the related Accounts under one structure and makes them simpler to manage.

Think of a Portfolio as a **wallet** that holds multiple asset-specific Accounts for a customer.

For example, a retail banking customer might have a Portfolio that includes:

* A BRL checking account.
* A USD savings account.
* A credit card account.

With a Portfolio, an institution can view a customer’s total relationship across all accounts. The institution can also apply policies at the Portfolio level.

## Portfolio structure

***

* **Portfolio > Accounts**: A Portfolio groups Accounts. These Accounts usually link to one customer or entity.
* **Portfolio > Ledger > Organization**: A Portfolio belongs to an Organization through its Ledger.

## Key characteristics

***

* Portfolios commonly represent customers in a banking context.
* They simplify financial aggregation and give customer-level insights.
* You can also create internal Portfolios for operational use cases.

## Managing Portfolios

***

You can manage your Portfolios either through the API or through Lerian Console.

### Via API

* [List Portfolios](/en/reference/products/midaz/v2/list-portfolios): View all Portfolios in a Ledger.
* [Retrieve a Portfolio](/en/reference/products/midaz/v2/get-portfolio-by-id): Get details of a specific Portfolio.
* [Create a Portfolio](/en/reference/products/midaz/v2/create-portfolio): Register a new Portfolio.
* [Update a Portfolio](/en/reference/products/midaz/v2/update-portfolio): Edit an existing Portfolio.
* [Delete a Portfolio](/en/reference/products/midaz/v2/delete-portfolio): Remove a Portfolio.

### Via Lerian Console

You can view, create, edit, and delete Portfolios from the Portfolios page in the Midaz Module of Lerian Console.

[**Learn more in the Managing Portfolios guide.**](/en/products/midaz/console/managing-portfolios)


# Receiving Midaz events
Source: https://docs.lerian.studio/en/products/midaz/receiving-midaz-events

Consume Midaz events from Kafka, understand the legacy RabbitMQ surface, and check the current Streaming Hub compatibility boundary.

Midaz emits CloudEvents for ledger, CRM, Fees, and Tracer business facts. The public integration contract is the **Kafka** surface. Legacy RabbitMQ exchanges remain outside the public catalog.

## Current event surface: Kafka

***

Enable publication on each producing service:

```env theme={null}
STREAMING_ENABLED=true
STREAMING_BROKERS=<broker-list>
STREAMING_CLOUDEVENTS_SOURCE=ledger
```

Set `STREAMING_CLOUDEVENTS_SOURCE` when you enable streaming. Use `ledger` for the ledger, CRM, and Fees binary. Use `tracer` for Tracer. Each service rejects any other value at startup.

Midaz uses one v3 application fact topic per producing service:

* Ledger, CRM, and Fees: `lerian.streaming.ledger`
* Tracer: `lerian.streaming.tracer`

Examples:

* `organization.created` rides `lerian.streaming.ledger`
* `transaction.posted` rides `lerian.streaming.ledger`
* `fee_charge.applied` rides `lerian.streaming.ledger`
* `rule.created` rides `lerian.streaming.tracer`

The CloudEvents type is source-qualified as `studio.lerian.<source>.<resource>.<event>`. Headers `ce-resourcetype` and `ce-eventtype` carry the dispatch key separately. The `ce-tenantid` header is always present for Midaz. It carries your tenant ID, or the literal `default` when the event has no tenant.

The ledger and Tracer each serve their public JSON business-event catalog and topic mapping at:

```http theme={null}
GET /v1/streaming/manifest
```

The manifest route remains available even when you disable publication. Use it as the deployment-time contract instead of guessing topics. The [Midaz event reference](/en/reference/events/midaz) and [Tracer event reference](/en/reference/events/tracer) list every public business event and payload.

### Delivery semantics

Midaz publishes these business events directly after the state change. It does not persist them in a streaming outbox. Midaz logs publication failures and does not return them to the business command. Consumers must still be idempotent and deduplicate on `(ce-source, ce-id)` because broker delivery can repeat a published record. Money values use decimal strings. Never parse them as binary floating point.

### Consumer checklist

1. Read the producer manifest.
2. Subscribe to the producer's application topic.
3. Route on `ce-resourcetype` and `ce-eventtype`, not on payload shape.
4. Validate `ce-schemaversion` before decoding.
5. Persist your deduplication key before acknowledging the record.

## Legacy RabbitMQ surface

***

Midaz also maintains legacy RabbitMQ exchanges for selected overdraft and audit events. This is not the complete Kafka catalog.

The bundled example configuration ships these outbound exchanges disabled. If you enable them, you own queue bindings, `ack`/`nack`, dead-lettering, retries, and consumer isolation. The internal async transaction balance-operation pipeline controlled by `RABBITMQ_TRANSACTION_ASYNC` is not a public event feed.

Use the Kafka surface for new integrations unless you explicitly depend on a legacy RabbitMQ contract.

## Streaming Hub compatibility

***

Streaming Hub follows the v3 Midaz application topics `lerian.streaming.ledger` and `lerian.streaming.tracer`. A subscription can therefore receive Midaz facts when you enable the producer, hub ingest, and destination runtime. Match on the event key from `ce-resourcetype` and `ce-eventtype`. Do not expect a per-event Kafka topic.

## Decision

***

| Need | Use |
| - | - |
| Public Midaz business-event catalog | Direct Kafka consumption or Streaming Hub |
| Existing compatibility integration on selected exchanges | Legacy RabbitMQ |
| Managed webhook, pull, SQS, RabbitMQ, or EventBridge delivery | Streaming Hub subscription |


# Recommended workflow
Source: https://docs.lerian.studio/en/products/midaz/recommended-workflow

Follow the recommended Midaz onboarding workflow to create your Organization, Ledgers, Assets, Account Types, and Accounts in the correct order, step by step.

Follow the steps below in order. They set up your Organization, Ledgers, Assets, Account Types, and Accounts.

## Setting up and managing Ledgers

***

When you onboard to Midaz, follow these steps:

![Workflow for setting up and managing ledgers when onboarding to Midaz](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/setup-ledgers.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=b6880cb23b58e3a4c0883d387bf0dffa)

Figure 1. Workflow for setting up and managing ledgers.

### Step 1: [Set up the Organization](/en/reference/products/midaz/v2/create-organization)

Your organization in Midaz represents your bank or business entity. If you have not created it yet, set it up in the Console or API. Make sure the core details are accurate, such as the legal name and identifiers.

### Step 2: [Create the Ledgers](/en/reference/products/midaz/v2/create-ledger)

Create a Ledger under your organization to hold financial records. Most setups start with a primary ledger for all customer-facing operations (for example, "Main Banking Ledger"). At first it contains no accounts. It is the base layer for all financial activity.

### Step 3: [Define Asset types](/en/reference/products/midaz/v2/create-asset)

Register the assets your ledger supports. These can include currencies (for example, BRL, USD), points, or crypto tokens. You use these assets across your account and transaction configuration. You can add more assets as your product portfolio grows.

### Step 4: [Create Account Types](/en/reference/products/midaz/v2/create-account-type)

To enforce account classification rules, define your **Account Types**. These are categories, for example `user_wallet`, `treasury`, or `revenue`. You reference them later during account creation or transaction validation.

> [!NOTE]
>
> When you enable Account Type validation, each new account must use a registered Account Type. By default, Account Types are optional. This keeps classification consistent across your ledger.

Each Account Type has a `keyValue`. The `keyValue` must be unique and alphanumeric, with dashes and underscores allowed. You use these identifiers in validation flows and transaction routes.

### Step 5: Configure Accounting Routes

Use **Operation Routes** and the **Transaction Route** (the `transactionRoute` resource in the API) to define and enforce validation for your transactions.

* First, [**create the Operation Routes**](/en/reference/products/midaz/v2/create-operation-route). Each Operation Route validates one leg of the transaction. For example, the debit must come from an account of type `user_wallet`, and the credit must go to the alias `@external/BRL`.
* Then, [**create the Transaction Route**](/en/reference/products/midaz/v2/create-transaction-route). It combines the individual operation routes into a complete flow. An example is a cashout transaction with specific debit and credit validations.

> [!WARNING]
>
> After you configure routing and enable validation on the ledger, all transactions must match the defined routing structure. Midaz rejects any transaction that does not match.
>
> The `routeId` field in the transaction payload must include the ID of the **Transaction Route** you created.

### Step 6: Manage your Ledgers

Keep your ledgers clean and scalable with the following best practices:

* Use Access Manager to assign permissions by resource and action.
* Plan separate ledgers when needed, for example "Testing", "Internal", or "Multi-entity". Document their ownership.
* Review and reconcile ledger data regularly, especially when you integrate with external settlement systems.
* Midaz enforces double-entry logic, so every movement is fully traceable. Do not change balances manually.

## Configuring Accounts, Portfolios, and Segments

***

This section shows how to structure customer data and product entitlements in Midaz.

![Workflow for configuring accounts, portfolios, and segments to structure customer data and product entitlements in Midaz](https://mintcdn.com/lerian-49cb71fc/SFzzdxyH5SN7w_fC/images/en/d2/accounts-portfolios-segments.svg?fit=max\&auto=format\&n=SFzzdxyH5SN7w_fC\&q=85\&s=12a217ce289cfa30aa50c40ba9c45b86)

Figure 2. Workflow for configuring Accounts, Portfolios, and Segments.

### Step 1: [Create a customer Portfolio](/en/reference/products/midaz/v2/create-portfolio)

Create a **Portfolio** for each new customer. Portfolios are the logical containers for accounts. Link each portfolio to your CRM or internal system through its `entityId` field.

### Step 2: [Set up customer Accounts](/en/reference/products/midaz/v2/create-account)

Each financial product or asset the customer holds becomes a separate **Account** under their portfolio.

* A checking account in BRL and a savings account in USD are separate accounts.
* If you enable [Account Types](/en/reference/products/midaz/v2/create-account-type), the `type` field must match one of the pre-registered values.
* Use account aliases to simplify downstream operations.

> [!TIP]
>
> Account Types standardize account categorization across your ecosystem. They improve routing, reporting, and integrations.

### Step 3: [Apply segmentation](/en/reference/products/midaz/v2/create-segment)

Use Segments to categorize accounts (for example, `standard`, `vip`, `enterprise`). Fee packages can target a segment, so each segment can get its own fees.

### Step 4: Establish sub-accounts (optional)

For organizations or special cases, you can configure sub-accounts. Use clear naming conventions to keep traceability (for example, "Acme USD - Payroll").

### Step 5: [Set the initial balance](/en/reference/products/midaz/v2/create-transaction-direct)

Use the **Transactions API** to add the opening balance. This keeps traceability and double-entry compliance:

* Debit the funding source.
* Credit the new account.
* Do not update balances manually. Midaz tracks every value through transactions.

### Step 6: Verify and review

Before you run operations, check the following:

* Confirm each account has the correct assets and types.
* Validate account balances.
* Check that you applied segmentation.
* Confirm the setup in the API or the Console.

### Step 7: Ongoing Account management

Manage lifecycle operations through the API or Console to keep system integrity:

* Update account details as needed.
* Close accounts only once the balance reaches zero.
* Reclassify accounts if segmentation changes.

## Implementing double-entry transaction management

***

Midaz guarantees ledger integrity through strict enforcement of double-entry logic.

![Workflow for implementing double-entry transaction management](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/double-entry-transaction-management.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=dec47b42992268288fda31e26bab0337)

Figure 3. Workflow for implementing double-entry transaction management

### Step 1: Structure the transaction

Structure your **Transaction** object:

* After you configure your Transaction Route, insert its ID into the `routeId` field of your transaction payload.
* Define the source and destination accounts, with their asset and value details.
* Add descriptive metadata to keep traceability and clarity.

### Step 2: Choose your integration method

Use the **Transactions API** for programmatic transaction creation.

### Step 3: Enforce double-entry validation

Midaz checks that the sum of credits matches the sum of debits. Midaz rejects a transaction that has a mismatch or a structural violation.

### Step 4: Implement idempotency

Use idempotency keys to prevent duplicates from network retries. When a retry repeats the key with the same request, Midaz replays the original response instead of processing the request twice.

### Step 5: Track and reconcile transactions

Use built-in tools to:

* Track submitted and posted transactions.
* Audit metadata and timestamps.

### Step 6: Submit corrections via reversals

Do not edit or delete transactions. Submit a reversal instead. Midaz links each reversal to its original transaction for full traceability.

### Step 7: Optimize complex workflows

Use multi-operation transactions to:

* Process interest accruals.
* Execute batched payouts.

Midaz keeps atomicity across all legs. Either the full transaction posts, or nothing does.


# Rest API
Source: https://docs.lerian.studio/en/products/midaz/rest-api

Integrate with Midaz through a versioned REST API: JSON payloads, explicit versioning, and a predictable, resource-based design.

The Midaz REST API gives you programmatic access to the ledger. It uses standard HTTP methods and status codes.

## REST design, JSON format, and versioning

***

* **RESTful design**: The API follows REST principles for a predictable structure.
* **JSON format**: The documented API uses JSON for requests and responses.
* **Versioning**: Explicit version prefixes keep changes backward-compatible.

The API exposes the core Midaz resources: organizations, ledgers, accounts, assets, portfolios, transactions, and operations. Each resource has its own endpoints.

> [!TIP]
>
> For technical details on the available endpoints, see the [API Reference](/en/reference/introduction).


# Scalability strategies
Source: https://docs.lerian.studio/en/products/midaz/scalability-strategies

Scale Midaz to millions of Accounts and Transactions per day with partitioning by Ledgers, horizontal service scaling, and read replicas.

Midaz handles millions of accounts and transactions per day. You start small and scale horizontally as demand grows, with no re-architecture. For a business overview, see [About Midaz](/en/products/midaz/about-midaz).

How you deploy and use Midaz affects its performance. To handle large banking operations, use ledgers to segment workloads and scale each service on its own.

## Structuring entities for High Transaction Volumes

***

### Partitioning by Organizations, Ledgers, and Accounts

If your bank processes millions of transactions each day, distribute the workload across many accounts, ledgers, or organizations. For example, segment customers by last-name initial, or assign a separate ledger to each region.

Each Midaz ledger is an independent book.

### Lock-oriented Operations

Midaz applies the balance changes of each transaction in a single Redis Lua script. The script checks every balance against live state before it writes, so a refused transaction changes no balance.

The `@external` account skips the balance-floor and overdraft checks. It can go negative without limit, so transactions against it never fail on available funds. Each transaction still commits atomically. All operations apply, or none do.

### Horizontal scaling of services

The Midaz ledger runs as one service that holds onboarding, transactions, CRM, and Fees. You scale it by adding instances. Start small and add instances as demand grows.

For high loads, deploy several instances of the ledger service behind a load balancer. Use Kubernetes (K8s) pod scaling.

### CQRS and read replicas

Midaz uses CQRS (Command Query Responsibility Segregation) to separate write and read operations. You optimize each path on its own.

Route heavy reporting and query loads to read replicas. This keeps transaction commits fast.

### Batching and N:N transactions

Where possible, batch related operations into a single transaction. This reduces overhead. Use N:N transactions for bulk work such as mass payouts.

For example, one batch of 100 debits and 100 credits is often faster than 100 separate transactions. This works when the operations belong to the same logical set. Midaz processes these N:N transactions in one atomic commit.

### Monitoring and iterative scaling

Monitor the key metrics: transaction latency, throughput, resource use (CPU and memory), and database performance. Use the Midaz observability tools (OpenTelemetry and Grafana), or send the metrics to your own monitoring stack.

Scale out or up before you reach a performance threshold. Midaz is modular, so you deploy the parts you need.

## Handling multi-currency and multi-entity Operations

***

### Multi-currency strategies

Midaz supports multiple currencies with a separate account for each currency. Each transaction moves one asset. To scale well:

* Configure every currency asset you need.
* Handle currency-specific logic (such as rounding and conversion rates) in your integration layer.
* For frequent currency conversion, such as forex trading, run the conversion in a separate service. Midaz records the debits and credits, but an external FX-rate service supplies the rates.
* You rarely need a separate ledger per currency, unless policy requires it. Instead, use account types and the transaction-routing API to group accounts by currency for clear reporting.
* If one currency covers most transactions, keep all currencies in the same ledger. If multi-currency operations grow too complex, split them into a separate ledger per currency group.

### Multiple Entities: Consolidation and separation

For a bank that operates across countries or legal entities:

* Use the organization hierarchy to segment entities. Give each entity its own base currency, local assets, and ledgers.
* Model inter-entity transactions as external movements. One organization credits its external account, and the other debits its own.
* You can run several organizations on one Midaz instance. Allocate enough resources: the same ledger instances process the requests of every organization, so total volume matters.
* You can deploy a separate Midaz instance per isolated entity, but you lose unified visibility. One cluster with internal organization separation is usually more practical.

## Performance optimization best practices

***

### Indexing and queries

Use the Midaz APIs to read data, not direct database queries. These APIs carry predefined indexes for the core identifiers: accounts, portfolios, and transactions.

### Indexing custom metadata fields

Create the indexes you need explicitly through the Metadata Index API.

By default, Midaz does not index custom metadata fields. Clients fill these fields as flat key-value pairs.

Frequent queries or filters on non-indexed fields can trigger full collection scans. These scans slow down as the data volume grows.

Create an index when you regularly use a custom metadata field in search filters. With an index, MongoDB finds the documents fast and cuts query response time.

**Recommendations:**

* Index only the metadata fields you query often.
* Do not index rarely-accessed fields, because each extra index adds write overhead.

Manage metadata indexes through dedicated APIs:

* [Create a Metadata Index](/en/reference/products/midaz/v2/create-metadata-index)
* [List Metadata Indexes](/en/reference/products/midaz/v2/get-all-metadata-indexes)
* [Delete a Metadata Index](/en/reference/products/midaz/v2/delete-metadata-index)

### Testing at scale

Before full deployment, simulate high traffic with load-testing tools. Create millions of accounts, run heavy transaction volumes, and monitor performance.

The Midaz architecture targets high-scale operations, but real-world tests help you tune your setup.


# Segments
Source: https://docs.lerian.studio/en/products/midaz/segments

Group Accounts into Segments to deliver tailored benefits: VIP rates, student perks, fee waivers, and personalized rules across Portfolios.

A **Segment** is a group of Accounts that share a characteristic, such as a product tier or a customer type. Financial institutions use Segments to apply tailored rules, services, and conditions to each group.

Each Segment has a **Segment ID**, a unique identifier. Financial institutions use this ID to track and manage each Segment.

#### Examples

* **Black or diamond (Cards)**: a premium group of card accounts for customers who want exclusive benefits.
  * Included benefits: VIP lounge access, insurance coverage, a dedicated concierge, and loyalty rewards.

* **Student account (Banking Accounts)**: a group of banking accounts for students.
  * Included benefits: no account fees, cashback on education purchases, and discounts on cinemas and events.

## Segment structure

***

* **Segment > Accounts:** You tag each Account with a `segmentId` (a Segment UUID) to add it to a Segment.
* A Segment belongs to one Ledger. Accounts in different Portfolios can share the same Segment.

## Key characteristics

***

* Segments give you a scalable way to apply tailored policies to Accounts.
* A Segment can include many Accounts.

## Managing Segments

***

You manage your Segments through the API or Lerian Console.

### Via API

* [List Segments](/en/reference/products/midaz/v2/list-segments): View all Segments in a Ledger.
* [Retrieve a Segment](/en/reference/products/midaz/v2/get-segment-by-id): Get the details of a specific Segment.
* [Create a Segment](/en/reference/products/midaz/v2/create-segment): Register a new Segment.
* [Update a Segment](/en/reference/products/midaz/v2/update-segment): Edit an existing Segment.
* [Delete a Segment](/en/reference/products/midaz/v2/delete-segment): Remove a Segment you no longer use.

### Via Lerian Console

You view, create, edit, and delete Segments on the Segments page in the Midaz Module of Lerian Console.

[**Learn more in the Managing Segments guide.**](/en/products/midaz/console/managing-segments)


# Structuring bank operations with Midaz
Source: https://docs.lerian.studio/en/products/midaz/structuring-bank-operation

Design Organizations, Ledgers, Portfolios, and Segments for retail and corporate banking, with best practices for scalable hierarchies.

Midaz supports retail and corporate banking through a clear entity hierarchy. This page gives best practices to structure organizations, ledgers, accounts, portfolios, and segments. A good structure keeps operations simple as you scale.

## Hierarchy of Organizations and Ledgers

***

### Single vs. multiple Organizations

A bank that operates as a single legal entity needs one Organization in Midaz. For a banking group with subsidiaries, use a parent organization over several child organizations. This structure matches your corporate governance. It also isolates data per entity.

> [!NOTE]
>
> The organization structure should reflect your corporate structure.

### Using multiple Ledgers

Within an organization, choose the number of ledgers from your operational needs. Keep a **primary ledger** for customer transactions. Add ledgers for special purposes, such as treasury operations or regulatory segmentation.

> [!NOTE]
>
> Use multiple ledgers only when necessary to keep complexity low. A transaction can move funds between ledgers only when each ledger enables `crossLedger.enabled`. See [Ledgers](/en/products/midaz/ledgers).

## Account structuring for retail and corporate banking

***

### Retail customers – Portfolio per customer

For retail banking, create a Portfolio for each customer. Each portfolio holds the customer's accounts, such as checking, savings, or credit card. This structure makes balances easy to read per customer.

> [!TIP]
>
> Use [CRM](/en/products/midaz/crm/crm-data-security) to manage personal data such as tax IDs, addresses, and banking aliases, all in one place.

### Corporate clients – hierarchical accounts

For corporate banking, use **child accounts** within portfolios to reflect internal structure. A company can hold a parent account for its main funds. It can add child accounts for subdivisions, such as payroll or expense tracking.

### Internal accounts

Create internal accounts for revenue, expenses, and settlement flows. Named accounts like "Fee Income – USD" or "Interest Expense – USD" keep financial reporting clear.

## Worked example: a typical digital bank

***

This example shows how a digital bank can structure its Midaz deployment. The bank offers checking accounts, savings, and Pix transfers.

```
Organization: "Neobank S.A."
│
├── Ledger: "Main Ledger (BRL)"
│   │
│   ├── Segments
│   │   ├── "Standard" (default tier)
│   │   ├── "VIP" (premium customers)
│   │   └── "Business" (corporate accounts)
│   │
│   ├── Account Types
│   │   ├── "checking" → everyday transactions
│   │   ├── "savings" → interest-bearing deposits
│   │   ├── "settlement" → internal clearing
│   │   └── "fee-revenue" → bank fee collection
│   │
│   ├── Internal Accounts
│   │   ├── Settlement Account (clearing for Pix, TED)
│   │   ├── Fee Revenue Account
│   │   └── Interest Expense Account
│   │
│   └── Customer Portfolios
│       ├── Portfolio: "Maria Silva"
│       │   ├── Checking Account (BRL) — Segment: VIP
│       │   └── Savings Account (BRL) — Segment: VIP
│       │
│       └── Portfolio: "Tech Corp Ltda."
│           ├── Main Checking (BRL) — Segment: Business
│           ├── Payroll Account (BRL) — Segment: Business
│           └── Expense Account (BRL) — Segment: Business
│
└── Ledger: "Treasury"
    └── FX and interbank positions
```

### How a Pix transfer flows through this structure

**1. Transaction initiated**

Maria sends R\$ 500 via Pix from her checking account.

**2. Transaction Route validates**

The "Pix Out" Transaction Route applies. It defines a debit from Maria's checking account and a credit to the Settlement Account. It can also add a fee operation.

**3. Operations execute**

Midaz creates four operations atomically. It debits R$ 500 from Maria and credits R$ 500 to Settlement. It also debits a R$ 0.50 fee from Maria and credits R$ 0.50 to Fee Revenue.

**4. Event published**

When streaming is enabled, `STREAMING_BROKERS` and the Ledger CloudEvents source are configured, and the transaction reaches an eligible lifecycle state, Midaz emits a transaction lifecycle CloudEvent. The bank's notification service reads the event and sends Maria a push notification.

**5. External settlement**

An external integration reconciles the Settlement Account with the central bank's Pix infrastructure.

### Decision guide: when to split ledgers

| Scenario | Recommendation |
| :- | :- |
| Single currency, single business unit | One ledger is enough |
| Multiple currencies with occasional FX | One ledger, separate asset accounts per currency |
| Separate legal entities or subsidiaries | One ledger per entity, under separate organizations |
| Regulatory requirement for data isolation | Separate ledgers, or separate organizations for full isolation |
| Treasury and trading operations | Dedicated treasury ledger alongside operational ledger |

> [!TIP]
>
> When in doubt, start with a single ledger. You can split later as operational complexity grows. If you split too early, you add orchestration overhead without clear benefit.


# Accounting Routes
Source: https://docs.lerian.studio/en/products/midaz/transaction-routing-entities

Validate every Transaction with Accounting Routes and Operation Routes. Enforce structure and business rules before recording any movement.

Accounting Routes are Midaz's two-layer validation system for financial transactions. **Accounting Routes** define the full transaction pattern. **Operation Routes** validate each operation inside that pattern. Together they keep every transaction structurally correct and compliant with your business rules.

> [!NOTE]
>
> **Naming:** The Lerian Console and product documentation call this concept **Accounting Routes**. In the API and SDKs, the `transactionRoute` resource represents the transaction-level route, with `transaction-route` endpoints. The two terms refer to the same thing.

* **Accounting Routes** define the complete structure of a transaction: the required sequence of operations that forms a valid financial event.
* **Operation Routes** define the rules for each operation (or "leg") of that transaction. Each rule sets the expected account type or specific account, the accounting annotation, and the debit or credit side.

When you enable route validation on a Ledger, Midaz validates each transaction in two layers. The Accounting Routes layer checks that the overall structure matches the predefined pattern. The Operation Routes layer checks that each component meets account requirements and business rules.

If any part of the transaction fails these checks, Midaz rejects it before it records the transaction.

> [!NOTE]
>
> You define the validation patterns through Operation Routes and Accounting Routes.

## What are Accounting Routes for?

***

Accounting Routes provide structured control over your financial operations by separating transaction logic from business code. Instead of hardcoding validation rules in your application, you configure reusable patterns. These patterns make every financial movement follow your organization's requirements.

These entities link Transactions and Operations from the Midaz ledger to higher-level abstractions. These abstractions help you integrate specialized plugins and external systems, especially for accounting and treasury. The structured annotations and classifications create a standardized vocabulary that other components can understand and use.

This approach delivers:

* **Consistency**: All transactions follow predefined structures regardless of where they originate.
* **Flexibility**: Adapt your ledger design to match your business needs without code changes.
* **Integrity**: Automatic validation prevents malformed transactions from affecting your ledger.
* **Maintainability**: Centralized configuration makes it easier to update financial rules as your business evolves.
* **Interoperability**: Business-semantic fields let you integrate accounting plugins and external financial systems.

## Working with Accounting Routes

***

To use Accounting Routes, you complete a one-time setup and then execute transactions.

### Initial Setup

#### 1. Configure Ledger for transaction route validation

To activate transaction route validation for a specific Ledger, enable the validation settings through the [Ledger Settings API](/en/products/midaz/ledgers#ledger-settings). This controls whether transactions in that Ledger must comply with your configured routes.

```json PATCH /v2/organizations/{organization_id}/ledgers/{ledger_id}/settings theme={null}
{
  "accounting": {
    "validateRoutes": true,
    "validateAccountType": true
  }
}
```

* **`validateRoutes`**: When enabled, every transaction must reference a valid transaction route.
* **`validateAccountType`**: When enabled, Midaz rejects an account whose `type` is not a registered Account Type. This gates **account creation**, not transactions. `validateRoutes` enforces the `account_type` rule on an Operation Route, independent of this flag.

#### 2. Create Operation Routes

Create Operation Routes that define validation rules and behavior for individual transaction components.

**Key fields:**

* **title**: Brief label that identifies the operation route.

* **code** (deprecated): a legacy external reference kept for backward compatibility. The engine does **not** write it to operations. Instead, it records the resolved rubric's `code` (from `accountingEntries`) as `routeCode` on each operation.

* **description**: Optional detailed explanation.

* **metadata**: Key-value pairs for business context and custom categorization.

* **operationType**: The accounting direction for this route (`source`, `destination`, or `bidirectional`).
  * `source`: identifies accounts where funds originate (debit side).
  * `destination`: identifies accounts that receive funds (credit side).
  * `bidirectional`: applies to both sides of the transaction, as both source and destination.

* **account**: Optional validation rules that set a required account type or a specific account.
  * **ruleType**: Type of account validation rule (`account_type`, `alias`).
  * **validIf**: The expected value that must match for validation to pass.

* **accountingEntries**: Optional accounting entries for each action type. With route validation enabled, a transaction can use the route only for the actions that have an entry. See [Accounting Entries](#4-configure-accounting-entries-actions) below.

Configure account rules based on your needs:

**Option A: No Account Rule**

If you don't need account validation for the operation route, omit the account object:

```json JSON theme={null}
 {
    "title": "Fee Collection",
    "description": "Operation route for collecting service fees from user transactions",
    "metadata": {
        "businessUnit": "payments",
        "category": "revenue"
    },
    "operationType": "source"
}
```

**Option B: Account Validation Rule**

If you need account validation for the operation, configure account rules based on your ledger setup:

* **Target Specific Account**

Validate against a specific account using its alias.

```json JSON theme={null}
{
    "title": "Fee Revenue Collection",
    "description": "Operation route for crediting collected fees to revenue account",
    "metadata": {
        "businessUnit": "payments",
        "category": "revenue"
    },
    "operationType": "destination",
    "account": {
        "ruleType": "alias",
        "validIf": "@external/BRL"
    },
    "accountingEntries": {
        "direct": {
            "credit": {
                "code": "3.1.001",
                "description": "Fee revenue"
            }
        }
    }
}
```

* **Target Account Type**

Validate against specific account types.

```json JSON theme={null}
{
    "title": "User Cashout Fee",
    "description": "Operation route for collecting fees from user cashout transactions",
    "metadata": {
        "businessUnit": "payments",
        "category": "fee"
    },
    "operationType": "source",
    "account": {
        "ruleType": "account_type",
        "validIf": ["user_wallet", "asset"]
    },
    "accountingEntries": {
        "direct": {
            "debit": {
                "code": "1.1.1.001",
                "description": "User wallet fee"
            }
        }
    }
}
```

**Option C: With Accounting Entries**

Attach accounting entries directly to the operation route through the `accountingEntries` field. This field maps each transaction-lifecycle stage to the correct double-entry accounting codes. See [Configure Accounting Entries (Actions)](#4-configure-accounting-entries-actions) below for the full action-type model, the debit/credit requirements, and the validation matrix.

A route with accounting entries configured:

```json JSON theme={null}
{
    "title": "Pix Cash-out - Current Account",
    "description": "Operation route for sending Pix payments from current account",
    "operationType": "source",
    "accountingEntries": {
        "direct": {
            "debit": {
                "code": "1.1.001",
                "description": "Cash - Available funds"
            },
            "credit": {
                "code": "3.1.001",
                "description": "Service Revenue"
            }
        },
        "hold": {
            "debit": {
                "code": "1.1.002",
                "description": "Clearing Values"
            },
            "credit": {
                "code": "2.1.001",
                "description": "Pending Obligations"
            }
        },
        "commit": {
            "debit": {
                "code": "2.1.001",
                "description": "Pending Obligations"
            },
            "credit": {
                "code": "3.1.001",
                "description": "Service Revenue"
            }
        },
        "cancel": {
            "debit": {
                "code": "2.1.001",
                "description": "Pending Obligations"
            },
            "credit": {
                "code": "1.1.002",
                "description": "Clearing Values"
            }
        }
    },
    "account": {
        "ruleType": "alias",
        "validIf": "@current_account"
    },
    "metadata": {
        "channel": "pix"
    }
}
```

> [!NOTE]
>
> The `operationType` field also supports `bidirectional`. A bidirectional route operates in both directions. Use it for routes that both send and receive, or for operations that you may need to reverse.

#### 3. Build Accounting Routes

Complete your setup by combining Operation Routes into Accounting Routes (the `transactionRoute` resource in the API). These define your complete transaction patterns. Each pattern maps how operations work together to form balanced financial events that match your business processes.

An Accounting Route needs at least one source and one destination Operation Route (errors `0153` and `0154`). A bidirectional route counts as both.

```json JSON theme={null}
{
    "title": "Fee Transaction",
    "description": "Complete transaction for collecting fees from user cashout operations",
    "metadata": {
        "transactionType": "cashout_fee",
        "businessFlow": "withdrawal_processing"
    },
    "operationRoutes": [
        "0197e6aa-1695-734a-a8c3-8c79e0ad32c2",
        "0197e675-37cc-71d7-96c2-f58000f33aa0"
    ]
}
```

#### 4. Configure Accounting Entries (Actions)

Each Operation Route can include **Accounting Entries**. These structured rubrics define how Midaz records debit and credit entries for each transactional event: `direct`, `hold`, `commit`, `cancel`, and `revert`. Four supplementary keys (`overdraft`, `block`, `unblock`, and `crossLedger`) describe accounting impact but are **not** valid transaction-route actions. The entries determine the `routeCode` and `routeDescription` annotations on each operation.

The `accounting.validateRoutes` setting in the [Ledger Settings](/en/products/midaz/ledgers#ledger-settings) controls this behavior. When you enable it, Midaz rejects a transaction whose legs do not match the entries of its Accounting Route. When you disable it, Midaz resolves no rubric, and `routeCode` stays empty.

> [!NOTE]
>
> The **[Accounting Entries](/en/products/midaz/accounting-entries)** page documents the full model in detail. This includes the accounting-entry actions, the debit/credit requirements per operation type, the graceful and strict validation modes, and configuration examples. This section covers only how rubrics attach to Operation Routes.

At the route level, you supply accounting entries through the `accountingEntries` block. See **Option C** under [Create Operation Routes](#2-create-operation-routes) above. Each action takes one entry with a `debit` rubric, a `credit` rubric, or both, depending on the route's `operationType`:

* **Source** routes require the **debit** rubric.
* **Destination** routes require the **credit** rubric.
* **Bidirectional** routes require **both** debit and credit rubrics.

##### Accounting entries validation matrix

Not every combination of `operationType` and action is valid. Midaz enforces a strict validation matrix when you create or update an Operation Route. If the rules do not match, Midaz rejects the request before it persists the route.

An invalid combination returns error `0166` (field required) or `0162`/`0165` (scenario not allowed for the direction).

**source**

| Action | Debit | Credit | Notes |
| :- | :- | :- | :- |
| `direct` | Required | Optional | Standard one-step transaction at origin |
| `hold` | Required | Required | Reserves funds (moves available → on\_hold) |
| `commit` | Required | Optional | Finalizes a two-phase transaction |
| `cancel` | Required | Required | Releases reserved funds (moves on\_hold → available) |
| `revert` | — | — | Not allowed (error `0165`). Use `bidirectional` instead |

**destination**

| Action | Debit | Credit | Notes |
| :- | :- | :- | :- |
| `direct` | Optional | Required | Standard one-step transaction at destination |
| `hold` | — | — | Not allowed (error `0162`) |
| `commit` | Optional | Required | Finalizes a two-phase transaction |
| `cancel` | — | — | Not allowed (error `0162`) |
| `revert` | — | — | Not allowed (error `0165`). Use `bidirectional` instead |

**bidirectional**

| Action | Debit | Credit | Notes |
| :- | :- | :- | :- |
| `direct` | Required | Required | Both sides of the double entry |
| `hold` | Required | Required | Both sides of the double entry |
| `commit` | Required | Required | Both sides of the double entry |
| `cancel` | Required | Required | Both sides of the double entry |
| `revert` | Required | Required | Only direction that supports revert |

> [!CAUTION]
>
> If an entry has neither `debit` nor `credit`, Midaz rejects it, regardless of operation type or action.

**Additional rules:**

* **Reserve group atomicity**: On `source` and `bidirectional` routes, if you define `hold`, you must also define `commit` and `cancel` (and vice versa). These three actions form an atomic group there. You can't configure one without the others (error `0163`). On `destination` routes, `hold` and `cancel` are not allowed (error `0162`), so `commit` can be configured without them. It still requires `direct` per the rule below.
* **Direct is mandatory**: If you define `hold`, `commit`, `cancel`, `revert`, or `overdraft`, you must also define `direct` (error `0164`). It is the baseline entry for the operation route.
* **`overdraft` requires both rubrics** on every `operationType`, including `source` and `destination`.
* **`block` and `unblock` mirror `direct`**: debit on a `source` route, credit on a `destination` route, both on `bidirectional`.
* **`crossLedger`** classifies the External Account legs that Midaz adds when a transaction spans Ledgers. It requires both rubrics and a `bidirectional` route (error `0162`) with no other entry (error `0256`). An Accounting Route links at most one such route.
* Any key outside these nine is rejected with error `0053` (Unexpected Fields).

> [!TIP]
>
> When you design your operation routes, start with the `direct` action. Add `hold`/`commit`/`cancel` only if you need two-phase transaction support. Add `revert` only on `bidirectional` routes.

### Ongoing Operations

#### 5. Execute Validated Transactions

With your routing configuration in place, you can now submit transactions. In the transaction request, set **`routeId`** to the ID of the Accounting Route you created, and **`operationRouteId`** on each leg. Midaz then validates the transaction against your routing patterns.

For the Accounting Route and Operation Routes configured above, Midaz composes the following validation structure:

```bash text theme={null}
Transaction Route: "Fee Transaction" (ID: 5656daa5-5b2a-4637-955f-e43bafceaf5d)

├── Operation Route 1: "User Cashout Fee" (ID: 0197e6aa-1695-734a-a8c3-8c79e0ad32c2)
│   ├── Type: source
│   ├── Account Rule: account_type ["user\_wallet", "asset"]
│   └── Validates: source operations in transactions
└── Operation Route 2: "Fee Revenue Collection" (ID: 0197e675-37cc-71d7-96c2-f58000f33aa0)
    ├── Type: destination
    ├── Account Rule: alias "@external/BRL"
    └── Validates: destination operations in transactions
```

A matching request to [create a direct transaction](/en/reference/products/midaz/v2/create-transaction-direct):

```json JSON expandable theme={null}
{
    "routeId": "5656daa5-5b2a-4637-955f-e43bafceaf5d",
    "description": "Cashout fee collection transaction",
    "asset": "BRL",
    "amount": "10",
    "debits": [
        {
            "alias": "@user_wallet_123",
            "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
            "amount": "10",
            "description": "Fee debit from user wallet",
            "operationRouteId": "0197e6aa-1695-734a-a8c3-8c79e0ad32c2"
        }
    ],
    "credits": [
        {
            "alias": "@external/BRL",
            "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
            "amount": "10",
            "description": "Fee credit to revenue account",
            "operationRouteId": "0197e675-37cc-71d7-96c2-f58000f33aa0"
        }
    ]
}
```

When you submit this transaction, Midaz checks that the `@user_wallet_123` account has one of the account types in the `account_type` rule. It also checks that the credited account is `@external/BRL`.

##### Route fields on operations

When you enable route validation and configure accounting entries, every processed operation includes two extra fields. Midaz populates these fields from the matched rubric:

* **routeCode**: the `code` of the resolved `AccountingRubric` for that operation's action and direction.
* **routeDescription**: the description of the resolved accounting rubric. Midaz populates it alongside `routeCode`.

These fields link each operation to its accounting classification. Downstream systems such as [Reporter](/en/products/reporter/what-is-reporter) can then produce accurate financial reports without extra lookups.

## Managing Operation and Accounting Routes

***

To configure your Operation Routes, use the following endpoints:

* [Create an Operation Route](/en/reference/products/midaz/v2/create-operation-route): define a new accounting rule for your operations.
* [List Operation Routes](/en/reference/products/midaz/v2/list-operation-routes): view all configured Operation Routes.
* [Retrieve an Operation Route](/en/reference/products/midaz/v2/get-operation-route-by-id): get detailed information on a specific Operation Route.
* [Update an Operation Route](/en/reference/products/midaz/v2/update-operation-route): modify existing accounting rules.
* [Delete an Operation Route](/en/reference/products/midaz/v2/delete-operation-route): remove an outdated or unused Operation Route.

To configure your Accounting Routes (the `transactionRoute` resource in the API), use the following endpoints:

* [Create a Transaction Route](/en/reference/products/midaz/v2/create-transaction-route): define new routing logic to connect transactions to accounting operations.
* [List Transaction Routes](/en/reference/products/midaz/v2/list-transaction-routes): view all configured Transaction Routes.
* [Retrieve a Transaction Route](/en/reference/products/midaz/v2/get-transaction-route-by-id): get details of a specific Transaction Route.
* [Update a Transaction Route](/en/reference/products/midaz/v2/update-transaction-route): modify existing routing criteria.
* [Delete a Transaction Route](/en/reference/products/midaz/v2/delete-transaction-route): remove routes that are no longer applicable.

Routes belong to the Organization. A transaction in any Ledger of the Organization can use a route, whatever Ledger you created it under. To create a route without a Ledger, use [Create an organization Operation Route](/en/reference/products/midaz/v2/create-organization-operation-route) and [Create an organization Transaction Route](/en/reference/products/midaz/v2/create-organization-transaction-route).


# Transactions
Source: https://docs.lerian.studio/en/products/midaz/transactions

Record financial events with Midaz double-entry Transactions: multiple Balances, debits, credits, and full traceability across Accounts.

A **Transaction** in Midaz records a complete financial event. A transaction often uses multiple accounts and balances. Midaz runs on a double-entry accounting system that keeps every financial movement balanced.

With the **multiple balances** feature, each operation specifies the account and the **balance key** to use. You can then debit or credit different logical balances of the same account (for example, `credit`, `operational`, or `collateral`).

> [!NOTE]
>
> If you do not provide a `balanceKey`, the transaction uses the **default balance**.

## Double-entry accounting

***

The double-entry system follows one principle. A posted transaction has at least one debit and one credit operation. A pending transaction records only its source side until you commit it. This structure records all financial activity and keeps your accounts balanced.

Each transaction uses two kinds of entries:

* **Debits** show the value received or the resources consumed.
* **Credits** show the value given or the resources provided.

Midaz rejects a transaction whose debits and credits do not balance.

### Example

In this example, you transfer R\$1000 from one account to another. The transaction has two operations:

* One operation to debit R\$1,000.00 from the source account.
* One operation to credit R\$1,000.00 to the destination account.

Midaz captures both entries automatically. You can view and analyze these movements through the API or Lerian Console.

## N:N Transactions (Many-to-Many)

***

Traditional financial systems limit transactions to one-to-one or one-to-many relationships. Midaz supports N:N transactions. A single transaction can use multiple source and destination accounts.

### Examples

* **Marketplace payout**: a single escrow account pays multiple sellers, and each seller pays a platform fee.
* **Peer-to-peer with fees**: one transaction debits the payer and credits both the payee and a fee account.

Midaz processes each case as a single atomic transaction. It debits and credits all parties together.

## Atomicity and integrity

***

Transactions are atomic. **Either all operations succeed, or none do.** Partial financial events do not occur.

If any part of a transaction fails validation (for example, one account has insufficient funds), Midaz does not apply the transaction. The ledger stays consistent.

## Transaction source

***

A transaction in Midaz can start from a single source or from multiple sources.

> [!CAUTION]
>
> The sum of the values in `source` must equal the value after `send`. It must also equal the sum of the values in `distribute`.

### Single source

In a single-source transaction, Midaz takes the amount from one source account. You can also name a specific balance.

#### Example

In this example (*Figure 1*):

* Midaz takes BRL 30.00 from `@account1` (balance `credit`).
* It sends 100% to `@destinationAccount1` (balance `operational`)

![Single-source transaction moving BRL 30.00 from one source account to a single destination account](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/single-source.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=8867866e614ebd29f2abc801b03ad894)

Figure 1. Example of a single source transaction.

**Code examples**

```json JSON Example expandable theme={null}
{
  "description": "single source transaction",
  "send": {
    "asset": "BRL",
    "value": "30.00",
    "source": {
      "from": [
        {
          "accountAlias": "@account1",
          "balanceKey": "credit", // optional
          "amount": {
            "asset": "BRL",
            "value": "30.00"
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@destinationAccount1",
          "balanceKey": "operational", // optional
          "share": {
            "percentage": 100
          }
        }
      ]
    }
  }
}
```

### Multi-source

In a multi-source transaction, Midaz draws funds from multiple accounts or balances.

#### Example

In this example (*Figure 2*):

* Midaz sends BRL 30.00 to the destination account (`@destinationAccount1`).
  * BRL 15.00 from `@account1` (balance `default`).
  * BRL 15.00 from `@account2` (balance `investment`).
* The destination account receives 100% of the amount.

![Multi-source transaction where BRL 30.00 is drawn from two source accounts and sent to a single destination account](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/multi-source.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=a662de8e32affc1346da13432daabcd8)

Figure 2. Example of a multi-source transaction.

**Code examples**

```json JSON Example theme={null}
{
  "description": "multi-source transaction",
  "send": {
    "asset": "BRL",
    "value": "30.00",
    "source": {
      "from": [
        {
          "accountAlias": "@account1",
          "balanceKey": "default",
          "amount": {
            "asset": "BRL",
            "value": "15.00"
          }
        },
        {
          "accountAlias": "@account2",
          "balanceKey": "investment",
          "amount": {
            "asset": "BRL",
            "value": "15.00"
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@destinationAccount1",
          "share": {
            "percentage": 100
          }
        }
      ]
    }
  }
}
```

## Transaction destination

***

Like sources, destinations can be single or multiple.

### Single destination

In a single-destination transaction, Midaz sends the amount to only one destination account.

#### Example

In this example (*Figure 3*):

* Midaz takes BRL 30.00 from an external account (`@external/BRL`).
* It sends 100% to the destination account (`@destinationAccount1`).

![Single-destination transaction moving BRL 30.00 from an external account to one destination account](https://mintcdn.com/lerian-49cb71fc/Cb_meREQqa6luqbJ/images/en/d2/single-destination.svg?fit=max\&auto=format\&n=Cb_meREQqa6luqbJ\&q=85\&s=c027a71eaa987cc22a90171bbb326cc2)

Figure 3. Example of a single destination transaction.

**Code examples**

```json JSON Example theme={null}
{
   "description":"single destination transaction",
   "send":{
      "asset":"BRL",
      "value":"30.00",
      "source":{
         "from":[
            {
               "accountAlias":"@external/BRL",
               "amount":{
                  "asset":"BRL",
                  "value":"30.00"
               }
            }
         ]
      },
      "distribute":{
         "to":[
            {
               "accountAlias":"@destinationAccount1",
               "share":{
                  "percentage":100
               }
            }
         ]
      }
   }
}
```

### Multi-destination

In a multi-destination transaction, Midaz divides the amount among multiple destination accounts. You can distribute values by shares, fixed amounts, or the remaining amount.

#### Example

In this example (*Figure 4*):

* Midaz takes BRL 100 from the source account (`@account1`).
* 38% of the amount goes to account 2 (`@account2`).
* 50% goes to account 3 (`@account3`).
* A fixed BRL 2.00 goes to account 4 (`@account4`).
* The remaining amount goes to account 5 (`@account5`).

![Multi-destination transaction splitting BRL 100.00 from one source account across five destination accounts by percentage and fixed amounts](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/multi-destination.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=fc0a0dff5a1a99b2ffda26988f3fed47)

Figure 4 Example of a multi-destination transaction.

**Code example**

```json JSON Example theme={null}
{
   "description":"multi-destination transaction",
   "send":{
      "asset":"BRL",
      "value":"100.00",
      "source":{
         "from":[
            {
               "accountAlias":"@account1",
               "amount":{
                  "asset":"BRL",
                  "value":"100.00"
               }
            }
         ]
      },
      "distribute":{
         "to":[
            {
               "accountAlias":"@account2",
               "share":{
                  "percentage":38
               }
            },
            {
               "accountAlias":"@account3",
               "share":{
                  "percentage":50
               }
            },
            {
               "accountAlias":"@account4",
               "amount":{
                  "asset":"BRL",
                  "value":"2.00"
               }
            },
            {
               "accountAlias":"@account5",
               "remaining":"remaining"
            }
         ]
      }
   }
}
```

## Multi-source and multi-destination

***

These transactions use multiple sources and multiple destinations. They are useful for cases like a crowdfunding campaign. Midaz pools the contributions and distributes them among multiple recipients.

#### Example

In this example (*Figure 5*):

* The donation is BRL 4,000.00. Midaz takes it from four different accounts.
  * 25% comes from account 1 (`@account1`).
  * 25% comes from account 2 (`@account2`).
  * 40% comes from account 3 (`@account3`)
  * 10% comes from account 4 (`@account4`).
* Midaz distributes the donations to four separate accounts. Each account receives a 25% share of the total.

![Multi-source and multi-destination transaction drawing BRL 4,000.00 from four accounts and distributing it evenly across four destination accounts](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/multi-source-destination.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=bc6796fc6414907407362317958eb382)

Figure 5. Example of a multi-source and multi-destination transaction.

**Code examples**

```json JSON Example theme={null}
{
   "description":"multi-source and multi-destination transaction",
   "send":{
      "asset":"BRL",
      "value":"4000.00",
      "source":{
         "from":[
            {
               "accountAlias":"@account1",
               "share":{
                  "percentage":25
               }
            },
            {
               "accountAlias":"@account2",
               "share":{
                  "percentage":25
               }
            },
            {
               "accountAlias":"@account3",
               "share":{
                  "percentage":40
               }
            },
            {
               "accountAlias":"@account4",
               "share":{
                  "percentage":10
               }
            }
         ]
      },
      "distribute":{
         "to":[
            {
               "accountAlias":"@donation1",
               "share":{
                  "percentage":25
               }
            },
            {
               "accountAlias":"@donation2",
               "share":{
                  "percentage":25
               }
            },
            {
               "accountAlias":"@donation3",
               "share":{
                  "percentage":25
               }
            },
            {
               "accountAlias":"@donation4",
               "share":{
                  "percentage":25
               }
            }
         ]
      }
   }
}
```

## Transaction statuses

***

Every transaction in Midaz has a status. The status reflects its current stage in the lifecycle. You need these statuses to design transaction flows, configure event consumers, and read ledger data.

| Status | What it means | Affects balances? | How it's created |
| :- | :- | :- | :- |
| `CREATED` | Midaz posted the transaction at once. Only the create response carries this status. Midaz stores the transaction as `APPROVED`. | Yes | Create response of a transaction that is neither pending nor an annotation, reversals included |
| `APPROVED` | The transaction completed successfully. Funds have been moved between accounts. | Yes | Stored status of a `CREATED` transaction, or commit of a `PENDING` transaction |
| `PENDING` | A two-phase transaction is awaiting confirmation. Funds are reserved in `on_hold` but not yet transferred. | Yes (reservation) | [Create a Transaction](/en/reference/products/midaz/v1/create-transaction-json) with `"pending": true` |
| `CANCELED` | A two-phase transaction was canceled. Reserved funds are released back to `available`. | Yes (release) | [Cancel a Pending Transaction](/en/reference/products/midaz/v2/cancel-transaction) |
| `NOTED` | An annotation transaction recorded in the ledger without affecting balances. Operations preserve the double-entry structure but all balance fields are zeroed. | No | [Create a Transaction Annotation](/en/reference/products/midaz/v1/create-transaction-annotation) |

> [!TIP]
>
> Use the `NOTED` status to import legacy transactions, record audit trails, and log compliance events. It fits any case where the transaction must exist in the ledger but the balances settled elsewhere already.

### Status transitions

Transactions follow predictable paths through these statuses:

* **Standard flow:** → `APPROVED` (single step)
* **Two-phase flow:** → `PENDING` → `APPROVED` (commit) or `CANCELED` (cancel)
* **Annotation flow:** → `NOTED` (terminal, no transitions)

> [!NOTE]
>
> Once a transaction reaches `NOTED` or `CANCELED`, it cannot transition further. Both are terminal statuses.

## Transaction flow

***

When a transaction starts, Midaz validates:

* The accounts involved.
* The specified balances (`balanceKey`, or `default` if not given).
* Permissions (`allowSending`, `allowReceiving`).
* Sufficient available funds in the selected balance.

If validation passes and the transaction is **not** pending (Two-Phase Transaction flow), Midaz transfers the amount **immediately**. It moves the amount from the source account to the destination account, from the available balance.

On success, the transaction status becomes `APPROVED`.

> [!CAUTION]
>
> Initiate this type of transaction **only** if you intend to commit it to the ledger immediately.

For transactions that need validation or approval first, use the `pending` flag to create a **Two-Phase Transaction**.

## Two-Phase Transaction

***

In this flow, Midaz creates the transaction with status `PENDING`. Midaz does not move funds right away. Instead, it reserves the amount in the correct balance (`balanceKey`, or `default` if you do not provide one).

* The destination balance does not change until you commit.
* You must explicitly `commit` to execute the transfer, or `cancel` to release the funds.
* Midaz refuses an external account that you send as a source of a pending transaction (error `0098`).

> [!TIP]
>
> The Two-Phase Transaction feature supports [Flowker](/en/products/flowker/what-is-flowker). You reserve funds at the start of a workflow and run validations later.

In *Figure 6*, you can see an example of a two-phase transaction with anti-fraud.

![Two-phase transaction in an anti-fraud workflow, reserving funds first and committing or cancelling them after validation](https://mintcdn.com/lerian-49cb71fc/Wqp8NG2BwBLM-rZd/images/en/d2/two-phase-transaction.svg?fit=max\&auto=format\&n=Wqp8NG2BwBLM-rZd\&q=85\&s=308c052f9967a35d6334888a2c9fb256)

Figure 6. Anti-fraud workflow example

### Two-Phase Transaction flow

#### 1. Create a Two-Phase Transaction

* Use the [Create a Transaction using JSON](/en/reference/products/midaz/v1/create-transaction-json) endpoint with `"pending": true`.

Midaz validates accounts, the specified balances (`balanceKey`), permissions (`allowSending`, `allowReceiving`), and available funds. If valid:

* Midaz reserves funds in the correct balance.
* Midaz sets the transaction status to `PENDING`.
* Midaz stores the metadata.

#### 2. Commit or cancel the pending transaction

* **Commit**: finalizes the transaction. Funds move from `on_hold` to the destination balance.
  * Use the [Commit a Pending Transaction](/en/reference/products/midaz/v2/commit-transaction) endpoint.
  * Status: `APPROVED`.
* **Cancel**: releases the reserved funds back to `available` in the same balance.
  * Use the [Cancel a Pending Transaction](/en/reference/products/midaz/v2/cancel-transaction) endpoint.
  * Status: `CANCELED`.

## Past Transactions

***

Midaz also supports past transactions. Institutions can import legacy financial events and keep historical accuracy.

* Use the optional `transactionDate` field to set the original date of the transaction.
* `transactionDate` does not change balance history. Balance history uses the time when Midaz records the transaction.
* Transactions created through the [Create a Transaction Annotation](/en/reference/products/midaz/v1/create-transaction-annotation) endpoint validate structure but do **not** affect balances. They suit audits, compliance, and imports where balances must stay unchanged.

### Example

```json theme={null}
{
  "description": "past transaction example",
  "transactionDate": "2025-01-01T13:38:31.064Z", // optional
  "send": {
    "asset": "BRL",
    "value": "1000",
    "source": {
      "from": [
        {
          "accountAlias": "@external/BRL",
          "amount": {
            "asset": "BRL",
            "value": "1000"
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@account1_BRL",
          "amount": {
            "asset": "BRL",
            "value": "1000"
          }
        }
      ]
    }
  }
}
```

## Transactions with no financial impact

***

Midaz can create transactions that it records in the ledger but that do not affect account balances. These transactions keep structural integrity and leave balances unchanged.

This feature is useful when you need to:

* Import legacy transactions but keep balances unchanged.
* Record audit or compliance events.
* Add business operations that the ledger must track but that do not move funds.

### How does it work?

When you create a transaction without financial impact:

* Midaz stores the `balance` and `balanceAfter` fields as 0 to preserve double-entry validation.
* Each operation has a `balanceAffected` (boolean) field:
  * true → the operation affects the account balance.
  * false → Midaz records the operation in the ledger but does not change balances.

> [!CAUTION]
>
> Even when Midaz updates no balances, it enforces double-entry rules. This keeps consistency across all transactions in the ledger.

#### Example

```json theme={null}
{
  "description": "annotation example",
  "transactionDate": "2025-01-01T13:38:31.064Z",
  "send": {
    "asset": "BRL",
    "value": "1000",
    "source": {
      "from": [
        {
          "accountAlias": "@external/BRL",
          "amount": {
            "asset": "BRL",
            "value": "1000"
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@account1_BRL",
          "amount": {
            "asset": "BRL",
            "value": "1000"
          }
        }
      ]
    }
  }
}
```

#### Related endpoint

* [Create a Transaction Annotation](/en/reference/products/midaz/v1/create-transaction-annotation): record a transaction without financial impact in the ledger.

## Real-time event publishing

***

Midaz publishes transaction lifecycle events through its Kafka-compatible streaming surface. You can track your transactions as they change.

After you enable it, Midaz emits `transaction.posted`, `transaction.committed`, `transaction.canceled`, and `transaction.reverted`. A new `PENDING` transaction and a `NOTED` transaction emit no event. A transaction that spans Ledgers also emits group events; see [Event publisher](/en/products/midaz/event-publisher).

For more about how to publish and consume transaction events, see the [Event publisher](/en/products/midaz/event-publisher) page.

## Inflows, outflows, and external accounts

***

Midaz uses a double-entry ledger. All value that enters or leaves the system must pass through one special account: the **External Account**. Midaz represents this account as `@external/{{assetCode}}`. It is the bridge between Midaz and the external financial world (banks, PSPs, payment rails, and so on).

### Bringing funds into Midaz

When you first initialize the ledger, all accounts, including `@external`, start with a zero balance. To reflect real-world balances, such as institutional funds held outside Midaz, you must initiate a transaction that injects funds into Midaz accounts and debits the external account.

This is the only way to bring funds into Midaz.

### Inflows – Adding value into the Ledger

To credit an internal account from outside the ledger:

* **Source**: `@external/{{assetCode}}` (e.g., `@external/BRL`).
* **Destination**: One or more internal accounts (e.g., `@organization.main`).

**Example: First deposit into the Ledger**

Your institution holds R\$10,000 in a real-world bank and wants to bring it into Midaz.

You create a transaction:

| Source | Destination | Amount |
| :- | :- | :- |
| @external/BRL | @accountA | BRL 10,000 |

This debits the external account and credits your internal account. The external account now shows a negative balance. This is expected: it represents the total amount your organization brought into the ledger.

### Outflows – Moving value out of the Ledger

To move value from the ledger to an external destination:

* **Source**: One or more Midaz accounts.
* **Destination**: `@external/{{assetCode}}`.

**Example: A Pix transfer from Ledger to an external bank**

| Source | Destination | Amount |
| :- | :- | :- |
| @accountA | @external/BRL | BRL 1,000 |

This debits `@accountA` and credits the external account. Your system then transfers the funds to the recipient through SPI or another integration.

### Behavior and balance rules

> [!NOTE]
>
> All value that moves between the outside world and the Midaz ledger must go through the external account.
>
> Nothing enters or leaves the system without a formal transaction.

## Setting a custom transaction date

***

The `transactionDate` field lets you set a custom date for a transaction, independent of when you submit it to the API.

* **Optional.** If you omit it, Midaz uses the current timestamp.
* **Accepted formats:**
  * ISO 8601 with timezone: `2026-01-15T10:30:00Z`
  * ISO 8601 without timezone: `2026-01-15T10:30:00`
  * Date only: `2026-01-15`
* **Constraint:** you cannot use a future date. A future date returns error `0121`.
* **Constraint:** you cannot use it on `PENDING` transactions. A `transactionDate` with `"pending": true` returns error `0122`.

### Use cases

* Record transactions that occurred in the past (for example, same-day corrections)
* Import historical financial data into a new ledger
* Reconcile with external systems that use a different posting date

## Transaction Routes

***

The **Transaction Routes** API enables structured, validated transaction processing in Midaz.

> [!NOTE]
>
> The Lerian Console and product documentation call this concept **Accounting Routes**. The API resource and endpoints keep the `transactionRoute` / Transaction Routes name. Both refer to the same transaction-level route.

The Transactions API runs financial events: debits and credits between accounts. Transaction Routes define templates for **how** to structure and validate these events. This keeps them consistent and correct.

The Transaction Routes API is the validation layer. It makes business transactions follow predefined patterns and keep a proper financial structure.

For example, a fee, a deposit, or a payout may need different account types, validation rules, and structures. Instead of handling validation separately for each transaction, you configure predefined rules. These rules tell Midaz: "*When the user submits this type of transaction, validate it against these account requirements and structure patterns.*"

Each Transaction Route combines multiple **Operation Routes**. An Operation Route defines one component of a transaction. It sets the account requirements, the direction (source, destination, or bidirectional), and the validation rules for each "leg" of the financial event.

> [!WARNING]
>
> Do not use the `route` field in v1 `from` and `to` entries. Use `routeId` instead. `routeId` accepts a UUID that references an Operation Route created through the Operation Routes API. Midaz accepts `route` but does not use it in validation.

### What you do with Transaction Routes

With **Transaction Routes**, you:

* Keep a consistent transaction structure across your application.
* Validate financial events against predefined patterns.
* Configure transaction templates without code changes.
* Maintain data integrity through structured validation.

## Initiating a transaction

***

> [!WARNING]
>
> When you create transactions through the API, always implement **idempotency** to prevent duplicate processing. Midaz provides built-in idempotency support through the `X-Idempotency` header. Validate the `X-Idempotency-Replayed` response header to tell new transactions from cached replays. See [Retries and idempotency](/en/reference/retries-idempotency) for details.

Use the JSON transaction API to initiate a transaction.

### JSON request shape in v2

The v2 [`direct`](/en/reference/products/midaz/v2/create-transaction-direct), [`hold`](/en/reference/products/midaz/v2/create-transaction-hold), [`block`](/en/reference/products/midaz/v2/create-transaction-block), and [`unblock`](/en/reference/products/midaz/v2/create-transaction-unblock) endpoints share one body. The required `debits` and `credits` arrays hold the legs of each side. The legs of each side must sum to the request-level `amount`.

Each leg requires `alias`, `organizationId`, `ledgerId`, and exactly one value expression: `amount` or `share`. The `remaining` expression is not accepted in v2. Each array accepts 1 to 500 legs. `share.percentage` is 1–100; `share.percentageOfPercentage` is 0–100, where `0` means no narrowing. V2 create requests have a 1 MiB body limit.

### Using the JSON endpoint

* To create a transaction with JSON, use the [Create a Transaction using JSON](/en/reference/products/midaz/v1/create-transaction-json) endpoint.

> [!CAUTION]
>
> If you need to reserve funds **before** you complete the transfer, set the `pending` field to `true` (Two-Phase Transaction flow).

## Reverting a transaction

***

Midaz supports transaction reversal. You can undo an approved transaction. Midaz creates a mirror transaction that inverts the original debits and credits. This mechanism keeps full audit trails and cancels the financial impact on account balances.

> [!NOTE]
>
> Reversal creates a **new transaction** that compensates for the original. The original transaction remains in the ledger history for complete traceability.

> [!WARNING]
>
> Revert sends no idempotency key of its own, so Midaz derives one. Read the `X-Idempotency-Replayed` response header: `true` means you received a cached reverse rather than a freshly created one. Treat a replay as a signal to verify the origin's state before retrying.

### How does it work?

When you revert a transaction, Midaz automatically:

1. **Inverts operations**:
   * CREDIT operations become source operations (`from`).
   * DEBIT operations become destination operations (`to`).

2. **Creates a new transaction** with:
   * Same amount and asset code.
   * Same description and metadata.
   * Inverted operations (recipients become senders, senders become recipients).
   * Status: `CREATED` in the create response, stored as `APPROVED`.
   * `parentTransactionId` that references the original transaction.

3. **Processes the reversal** through the standard transaction flow: validation, balance updates, and history recording.

### Example

**Original transaction**:

* Account A (debit -100) → Account B (credit +100)

**Reversal transaction created**:

* Account B (debit -100) → Account A (credit +100)

**Result**:

* Account A returns to its previous balance (receives back the -100).
* Account B returns to its previous balance (loses the +100).
* Both transactions remain in the ledger history for audit purposes.
* The reversal transaction includes a `parentTransactionId` that points to the original.

### Reversal restrictions

Midaz enforces strict rules to keep ledger integrity. A reversal fails in these cases:

#### 1. Transaction already has a reversal

* Midaz allows only one reversal per transaction.
* This prevents multiple reversals of the same transaction.

#### 2. Transaction is already a reversal

* You cannot revert a transaction that is itself a reversal.
* This prevents "reversals of reversals."

#### 3. Transaction status is not APPROVED

* You can revert only approved transactions.
* You cannot revert a transaction with status `PENDING`, `CANCELED`, or `NOTED`.

#### 4. Transaction cannot be reverted

* This happens when the transaction has no valid operations to invert.
* For example, a transaction without standard CREDIT or DEBIT operations.
* A [fee debt](/en/products/midaz/fees/fee-debt) collection cannot be reverted.

#### 5. An operation route on the transaction is not bidirectional

* Every operation that carries a `routeId` must reference an Operation Route whose `operationType` is `bidirectional`.
* A `source` or `destination` route cannot be reverted: Midaz returns error `0150` (Route Not Bidirectional).
* Plan for this when you design routes. See [Accounting Routes](/en/products/midaz/transaction-routing-entities).

#### 6. The fee-debt record is not complete

* Midaz refuses the revert of a transaction that opened a fee debt while the record of that debt is not complete.
* Midaz returns error `0529` (HTTP 409) and moves nothing. Try again later.

> [!CAUTION]
>
> It does not reverse ON\_HOLD or RELEASE operations.

### Use cases

Transaction reversal helps in several operational scenarios:

#### 1. Incorrect payment reversal

A customer paid BRL 500 to the wrong supplier.

* Revert the transaction.
* Funds return to the customer's account.
* The customer can start a new payment to the correct supplier.

#### 2. Purchase cancellation

A store processed a BRL 1,000 sale, but the customer cancels the purchase.

* Revert the sale transaction.
* Funds return to the customer's account.

#### 3. Operational error correction

An operator created a transaction with the wrong amount.

* Revert the incorrect transaction.
* Create a new transaction with the correct amount.

#### 4. Product return

A customer purchased and paid BRL 200, but returned the product.

* Revert the payment transaction.
* The customer receives a refund.

#### 5. Integration failure compensation

A transaction is approved but fails in an external system.

* Revert to undo the accounting operation.
* Balances return to their previous state.

## Blocking and unblocking funds

***

Some scenarios require you to flag funds as **blocked** (a compliance hold, a court order, a fraud investigation) and later **release** them. Midaz supports this with two dedicated endpoints. These endpoints create transactions whose operations are typed `BLOCK` and `UNBLOCK`.

These transactions accept the same body as the [Create a Transaction using JSON](/en/reference/products/midaz/v1/create-transaction-json) endpoint, with two key differences:

* **Always posted immediately.** Midaz ignores the `pending` field in the request body and overrides it to `false`. Block and unblock transactions are never two-phase. They go straight to `APPROVED`.
* **Operations are typed `BLOCK` or `UNBLOCK`.** This classification distinguishes them in the ledger and in operation queries. You can audit blocked-fund movements without a look at the metadata.

Midaz is agnostic about the business reason to block or unblock funds. Record the reason in the `metadata` field.

> [!NOTE]
>
> A Block transaction records a **ledger movement** with `BLOCK`-typed operations. This differs from the balance-level controls in [Balances](/en/products/midaz/balances): permission flags (`allowSending` / `allowReceiving`) and collateral balances. Those controls restrict movement but record no transaction. Use a collateral balance for a standing operational restriction. Use a Block transaction when you need an auditable ledger entry.

* Use the [Create a Block Transaction](/en/reference/products/midaz/v1/create-transaction-block) endpoint to block funds.
* Use the [Create an Unblock Transaction](/en/reference/products/midaz/v1/create-transaction-unblock) endpoint to release previously blocked funds.

## Managing transactions

***

You can manage your Transactions through the API or Lerian Console.

### Via API

* [Create a Transaction using JSON](/en/reference/products/midaz/v1/create-transaction-json): submit a transaction directly using a JSON payload.
* [Commit a pending transaction](/en/reference/products/midaz/v2/commit-transaction): finalize a reserved transaction.
* [Cancel a pending transaction](/en/reference/products/midaz/v2/cancel-transaction): release reserved funds without executing.
* [Revert a Transaction](/en/reference/products/midaz/v2/revert-transaction): create a reversal transaction to undo an approved transaction.
* [Create an Inflow Transaction](/en/reference/products/midaz/v1/create-transaction-inflow): register incoming funds from external sources into the Ledger.
* [Create an Outflow Transaction](/en/reference/products/midaz/v1/create-transaction-outflow): move funds from internal accounts to the external world.
* [Create a Block Transaction](/en/reference/products/midaz/v1/create-transaction-block): flag funds as blocked with `BLOCK`-typed operations.
* [Create an Unblock Transaction](/en/reference/products/midaz/v1/create-transaction-unblock): release previously blocked funds with `UNBLOCK`-typed operations.
* [List Transactions](/en/reference/products/midaz/v2/get-all-transactions): view all Transactions in your workspace.
* [Retrieve a Transaction](/en/reference/products/midaz/v2/get-transaction): get details of a specific Transaction.
* [Update a Transaction](/en/reference/products/midaz/v2/update-transaction): edit the metadata of an existing Transaction.
* [Create a Transaction Annotation](/en/reference/products/midaz/v1/create-transaction-annotation): record a transaction without financial impact in the ledger.

### Via Lerian Console

You can view and create Transactions through Lerian Console.

Learn more in the [Managing Transactions](/en/products/midaz/console/managing-transactions) guide.


# Transactions
Source: https://docs.lerian.studio/en/products/midaz/transactions-overview

Overview of Transactions in Midaz: balances, overdraft, events, async processing, bulk recording, and operations that keep financial value moving safely.

Transactions are where financial value moves. This section covers balances, transaction processing, events, and operations.

## Content

***

* [**Balances**](/en/products/midaz/balances): The value an account holds. Balances reflect every operation over time and support multiple balance keys to segment funds within one account.

* [**Balance Overdraft**](/en/products/midaz/balance-overdraft): Controlled negative balances.

* [**Transactions**](/en/products/midaz/transactions): Complete financial events built on Midaz's double-entry accounting. Every transaction pairs debits and credits, and they must balance before Midaz commits it.

* [**Transaction amount**](/en/products/midaz/amount): Which amount field each transaction endpoint version uses, and in which format.

* [**Event publisher**](/en/products/midaz/event-publisher): Publish eligible transaction lifecycle CloudEvents through the Kafka-compatible streaming surface.

* [**Receiving events from Midaz**](/en/products/midaz/receiving-midaz-events): Consume ledger events from the Kafka-compatible streaming surface or through Streaming Hub.

* [**Async transaction processing**](/en/products/midaz/async-transaction-processing): How Midaz decouples transaction writes with RabbitMQ for higher throughput and lower latency. It covers sync and async modes, built-in resilience, and balance synchronization.

* [**Bulk Recorder**](/en/products/midaz/bulk-recorder): Batch transaction processing that groups multiple writes into one bulk operation. It reduces database round trips and increases throughput for high-volume workloads.

* [**Operations**](/en/products/midaz/operations): The smallest unit of financial activity. It is a single ledger entry, either a debit or a credit on a specific account. Operations form the building blocks of every transaction.


# Midaz use cases
Source: https://docs.lerian.studio/en/products/midaz/use-cases

Explore Midaz use cases across banking, multi-account customers, account closure, global portfolios, academic records, and supply chain traceability scenarios.

See how organizations across industries use Midaz to solve operational problems, from banking and payments to supply chain traceability and academic records.

Each use case shows what changes with Midaz. It maps the platform's entities to the domain and gives step-by-step transaction examples.

### Content

* [**Banking**](/en/products/midaz/midaz-in-banking): Understand how Midaz supports banking operations.

* [**Midaz for multi-account customers**](/en/products/midaz/midaz-for-multi-account-customers): Model multiple accounts under a single customer, with segregated balances, rules, and statements.

* [**Closing a customer account**](/en/products/midaz/closing-a-customer-account): How to close a customer account in line with BACEN account-closure rules.

* [**Global portfolio**](/en/products/midaz/midaz-in-a-global-portfolio): Configure a global account structure similar to those at major banks.

* [**Academic records**](/en/products/midaz/midaz-for-academic-record-management): Manage academic records for an educational institution.

* [**Supply chain**](/en/products/midaz/midaz-for-supply-chain-management): Manage the supply chain for a manufacturing company.

> [!TIP]
>
> See [Pix use cases](/en/interfaces/pix/pix-use-cases) for scenarios that combine Midaz with Pix.


# What is Midaz?
Source: https://docs.lerian.studio/en/products/midaz/what-is-midaz

Learn what Midaz is: Lerian's core ledger for double-entry accounting, multi-currency operations, and audit trails.

**Midaz** is Lerian's core ledger (The core financial book that records all transactions, balances, and operations for an organization. It is the single source of truth for a business unit's finances.) for financial infrastructure. It covers account management, transaction processing, and multi-currency operations.

You configure your financial structure once (organizations, ledgers, accounts, and transaction rules). Midaz handles the rest: double-entry accounting (Every financial movement is recorded as at least two operations: a debit from one account and a credit to another, so the system always balances.), balance tracking, audit trails (A chronological, immutable record of every action and transaction in the system, essential for regulatory compliance and dispute resolution.), and event-driven integrations.

## Why use Midaz

***

A legacy core means rigid schemas, vendor lock-in, and slow release cycles. Every new product or regulation requires months of integration work.

Midaz solves this:

* **Move fast**: Modular architecture lets you add products and integrations without re-architecting
* **Stay compliant**: Immutable audit trails (A chronological, immutable record of every action and transaction in the system, essential for regulatory compliance and dispute resolution.) and double-entry enforcement
* **Scale confidently**: Handle thousands to millions of transactions per day with horizontal scaling

## What Midaz does

***

* **Central ledger**: Real-time account and transaction management with double-entry guarantees
* **Multi-currency support**: Manage traditional currencies, digital assets, and loyalty points in the same ledger
* **Accounting Routes**: Define reusable transaction templates (A complete transaction blueprint composed of multiple Operation Routes. It defines all the debits and credits involved in a transaction type, so each transaction of that type complies with double-entry rules. Exposed as transactionRoute in the API.) that enforce business rules automatically
* **Automated triggers**: Respond to transactions in real time. Trigger notifications, compliance workflows, or analytics feeds
* **Plugin ecosystem**: Extend with Pix, TED, and more, or build your own

### Built for every financial player

* **Fintechs**: Run digital wallets, credit platforms, and embedded finance products
* **Banks**: Modernize legacy systems incrementally without full migration risk
* **Enterprises**: Simplify payments and collections

## Common use cases

***

> **Digital banking**
>
> Launch checking accounts, savings products, and instant transfers. Structure your accounts with portfolios per customer and enforce business rules through transaction routes.

> **Global portfolios**
>
> Manage multi-currency accounts for international customers. Each currency gets its own asset (A unit of value tracked in the ledger: traditional currencies (BRL, USD), digital currencies (BTC), or custom units like loyalty points. Every account is linked to exactly one asset.) accounts while portfolios (A grouping of accounts belonging to the same account holder, business unit, or purpose. It ties together checking, savings, and investment accounts for a unified view.) tie everything together for a unified customer view.

> **Pix and instant payments**
>
> Offer Pix (Brazil's instant payment system operated by the Central Bank (BACEN), for real-time transfers 24/7 between individuals, businesses, and government entities.) connectivity with automated fee management. Combine Midaz's ledger and Fees Engine with the Pix plugin to process instant payments, calculate fees, and maintain settlement accounts, all in real time.

> **Marketplace payouts**
>
> Handle complex multi-party settlements (The process of finalizing a financial transaction by transferring actual funds between institutions. Settlement accounts act as clearing points where money is held temporarily before reaching its final destination.) where a single payment splits into seller payouts, platform fees, and tax withholdings, all processed atomically as one transaction.

> **Non-financial ledgers**
>
> Use Midaz beyond finance: track academic credits, supply chain materials, loyalty points, or carbon credits. Midaz fits any domain that needs immutable, auditable tracking of units of value.

## How Midaz works

***

**1. Structure**

Create your Organization, Ledgers, Assets, and Account Types (A classification defining the nature and purpose of an account, such as checking, savings, escrow, or settlement. Account types enable proper transaction routing.) to reflect your business model.

**2. Onboard**

Set up customer Portfolios (A grouping of accounts belonging to the same account holder, business unit, or purpose. It ties together checking, savings, and investment accounts for a unified view.) and Accounts. Group them into Segments (A classification applied to accounts that share characteristics, like account holder tiers (VIP, Student) or regional divisions. Rules and pricing can differ by segment.) for differentiated rules and pricing.

**3. Define rules**

Configure Accounting Routes and Operation Routes to define how money moves. Midaz validates transactions against these routes only when `accounting.validateRoutes` is enabled in the Ledger settings. (Accounting Routes are exposed as `transactionRoute` in the API.)

**4. Transact**

Process transactions through the API. Midaz validates and updates the balances of each transaction in one atomic step, then records its operations.

**5. React**

Enable event publishing to trigger downstream systems (notifications, analytics, compliance workflows) the moment a transaction completes.

**6. Report**

Use Reporter to generate regulatory and business reports from your ledger data, or query balances and transactions directly via the API.

## Integrations with the Lerian ecosystem

***

Midaz is a stand-alone product that can optionally integrate with other components of the Lerian ecosystem.

| Product | Integration |
| - | - |
| [Matcher](/en/products/matcher/what-is-matcher) | Optional: Reconcile (The process of comparing two sets of records (for example, your internal ledger against bank statements) to verify they match and flag discrepancies.) ledger transactions against external data sources |
| [Reporter](/en/products/reporter/what-is-reporter) | Optional: Generate regulatory and business reports from ledger data |
| [Flowker](/en/products/flowker/what-is-flowker) | Optional: Orchestrate pre-ledger validation workflows (anti-fraud, approvals) |
| [Tracer](/en/products/tracer/what-is-tracer) | Optional: Real-time transaction validation and spending controls |

> [!NOTE]
>
> Midaz works independently or as part of the Lerian ecosystem.

## Next steps

***

> **[About Midaz](/en/products/midaz/about-midaz)**
>
> Understand Midaz's domains, entities, and how they relate to each other.

> **[Quick start](/en/products/midaz/midaz-setup)**
>
> Install and configure Midaz to start building your financial infrastructure.

> **[Use cases](/en/products/midaz/use-cases)**
>
> Explore detailed use cases for banking, global portfolios, Pix, and more.

> **[Explore the Midaz API](/en/reference/products/midaz/quick-start-guide)**
>
> Browse endpoints, request/response schemas, and try the API directly.


# Products, platform, and plans
Source: https://docs.lerian.studio/en/products/products-and-plugins

How Lerian's offering is structured: products, platform services, Brazil Rails, Interfaces, and their licensing.

Lerian is a complete, modular core banking platform. You choose what you adopt, and when.

## The catalog

***

Lerian has six products: Midaz, Tracer, Matcher, Flowker, Lender, and Reporter. Each product covers one financial domain end to end. Each product also deploys and evolves on its own.

Console, Access Manager, Streaming Hub, Multi-tenancy, and Observability are platform services. They serve every product and are not products themselves.

[Explore the products →](/en/products/about-products) · [Explore the platform →](/en/platform/platform-introduction)

## Licensing

***

Lerian licenses every product to institutions. Midaz versions released under the Elastic License 2.0 (ELv2), including Tracer, keep that license.

Tracer ships in the Midaz repository and release, and it stays a separate runtime and deployment. Reporter, Matcher, and Flowker work with a ledger, either Midaz or another one, and they do not depend on one. Lender runs its credit journeys on the Midaz ledger. After you license a product, you can also operate it from the Console.

## Plans and what's included

***

There are two ways to adopt Lerian:

* **The Midaz core.** You can self-host Midaz and build on the core ledger and its embedded CRM under the license terms. The same terms cover Tracer.
* **The Enterprise plan.** Enterprise bundles consulting for Midaz, the Midaz plugins such as Pix and TED, and the Lerian Console. The Console is the web interface that manages it all. Lerian does not sell the Console on its own. It comes with Enterprise.

> [!NOTE]
>
> Pricing depends on your setup and scale. [Talk to our team](https://lerian.studio/contact) to find the right plan for your use case.

## Brazil Rails and Interfaces

***

A Brazil rail is Lerian-owned messaging software that connects your institution to BACEN or to a market infrastructure, with no intermediary. An interface is the product surface over a rail.

Pix Lerian is an application plugin that uses a connectivity adapter and Midaz. It is not the native Lerian SPI rail. Pix JD, Pix BTG, TED JD, and Payments BTG are partner interfaces that ship as separately deployed Midaz plugins. Pix Lerian v1.0.0 is available for integration and testing with the mock provider adapter. Native SPI connectivity is not available in this release.

[Explore Brazil Rails →](/en/rails/what-are-brazil-rails) · [Explore Interfaces →](/en/interfaces/introduction) · [Explore the plugins →](/en/products/about-plugins)


# Core Banking vision
Source: https://docs.lerian.studio/en/start-here/about-lerian/core-banking-vision

Understand Lerian's vision for modern core banking, structured around four pillars: Ledger, transactional services, governance, and connectivity.

Core banking should be a programmable platform.

Four pillars work together to give you control, scalability, and long-term architectural flexibility.

## The four pillars of modern Core Banking

***

### 1. Ledger

The ledger is the foundation of any financial system. It manages accounts, balances, and transactions with precision and consistency.

Powered by Midaz, our ledger is designed for high throughput, reliability, and operational clarity.

**Key capabilities:**

* Real-time transaction processing
* Multi-currency support
* Immutable audit trails
* High-performance architecture that scales as transaction volume grows

### 2. Transactional services

Transactional services orchestrate how money moves.

From instant payments to interbank transfers and card settlement, this layer ensures consistent, secure debit and credit execution across channels and networks.

**Transaction types documented today:**

* Instant payments: [Pix](/en/interfaces/pix/pix-overview), including scheduled (Pix Agendado) and agreement-based automatic debits (Pix Automático)
* Interbank wire transfers: [TED](/en/interfaces/ted/ted-overview), settled through BACEN's STR
* Boletos and bill payments: [issuing and paying](/en/interfaces/payments-btg/boleto-and-bill-payment) boletos, DARF taxes, and utility invoices
* Card-settlement messaging: [Lerian SLC](/en/rails/slc/what-is-lerian-slc) operates Núclea's ASLC messaging, while [Lerian SILOC](/en/rails/siloc/what-is-lerian-siloc) provides the participant-side gateway and card-domain relay

### 3. Governance

Governance ensures that growth does not compromise control.

This layer integrates compliance, risk management, accounting, and reporting into the operational flow as structural components.

**Governance capabilities:**

* KYC/AML integrations through Flowker and third-party providers
* Fraud detection and prevention
* Regulatory reporting
* Accounting integration
* Audit and compliance tooling

### 4. Connectivity infrastructure

Our connectivity infrastructure supports integration with external networks, partners, and internal systems.

**Integration capabilities:**

* Built for integration: every capability is accessible through standard interfaces
* Runs on modern cloud infrastructure with automated scaling and recovery
* Supports multiple communication protocols
* Real-time data synchronization
* Secure communication channels

## What the modular architecture allows

***

Traditional core banking platforms are monolithic and difficult to evolve.

Lerian’s modular architecture allows institutions to:

* Adopt components incrementally
* Integrate with existing systems
* Scale based on operational demand
* Avoid vendor lock-in

You stay in control of your architecture and your roadmap.


# Our values
Source: https://docs.lerian.studio/en/start-here/about-lerian/our-values

Learn Lerian's mission and the values that guide our work: strength, courage, integrity, audacity, and leadership in financial infrastructure.

At Lerian, we combine technology and financial expertise to help institutions manage their operations through a modular platform.

We help institutions build systems they can control as their needs evolve.

## Our Mission

***

We help financial institutions adopt a modular platform that supports independent operations and evolution.

We design adaptable financial software anchored by Midaz, our core ledger. Institutions assemble the products and platform services they need.

## Our Commitment

***

We design for scale, so our software grows with our clients' needs. We believe in building technology that adapts to your needs.

## Our Values

***

### Be Your Own Strength

Pursue excellence, face challenges with resilience, and embrace growth. True strength comes from the ability to adapt, learn, and overcome obstacles.

### Be Your Own Courage

Navigate uncertainty boldly and embrace risk with confidence. Courage means taking calculated risks and pushing boundaries.

### Be Your Own Integrity

Uphold transparency, ethics, and trust in every decision. Integrity is not negotiable. It underpins everything we build and every relationship we nurture.

### Be Your Own Audacity

Innovate fearlessly, push boundaries, and take initiative. Audacity drives us to challenge conventions and create solutions that others might consider impossible.

### Be Your Own Leader

Forge your own path with vision, self-development, and confidence. Leadership means you take ownership, inspire others, and create lasting impact.


# Our release cycle
Source: https://docs.lerian.studio/en/start-here/about-lerian/release-cycle

Understand how Lerian plans, builds, tests, and releases, from continuous weekly delivery to production releases, so teams know what to expect.

Lerian plans and reviews work on a weekly rhythm, delivering improvements continuously as release candidates. Production releases follow a separate, more deliberate cadence to keep environments stable.

We're refining this cadence, so production timing may change.

We evolve all our products, improving existing capabilities and, when applicable, developing new products. We validate every change before it reaches production.

## How it works

***

* **Planning**: We align scope, priorities, and technical direction. We define requirements and shape the roadmap.
* **Development**: The team builds and iterates on new features, enhancements, and platform improvements based on the planned scope.
* **Testing and validation**: We test and validate changes for reliability, performance, and consistency across the platform.
* **Release**: We consolidate changes into a production release. We publish documentation and release notes with the rollout.


# 2025 release schedule
Source: https://docs.lerian.studio/en/start-here/about-lerian/release-cycle-2025

Track Lerian's 2025 release cycles with the planned start and end dates for each stage so you can align your delivery and rollouts.

In 2025, our release cycles were:

## First cycle

***

| Stage | Start Date | End Date |
| :- | :- | :- |
| **Weeks 1–6** | April 7 | May 16 |
| **Weeks 7–8** | May 19 | May 30 |

## Second cycle

***

| Stage | Start Date | End Date |
| :- | :- | :- |
| **Weeks 1–6** | June 2 | July 11 |
| **Weeks 7–8** | July 14 | July 25 |

## Third cycle

***

| Stage | Start Date | End Date |
| :- | :- | :- |
| **Weeks 1–6** | July 28 | September 5 |
| **Weeks 7–8** | September 8 | September 19 |

## Fourth cycle

***

| Stage | Start Date | End Date |
| :- | :- | :- |
| **Weeks 1–6** | September 22 | October 31 |
| **Weeks 7–8** | November 3 | November 14 |

## Fifth cycle

***

| Stage | Start Date | End Date |
| :- | :- | :- |
| **Weeks 1–6** | November 17 | December 26 |
| **Weeks 7–8** | December 29 | January 9, 2026 |


# Our release schedule
Source: https://docs.lerian.studio/en/start-here/about-lerian/release-schedule

Track Lerian's release schedules, organized by year.

This page links Lerian's release schedules by year.

To understand how our release cycle works, see the [Our release cycle](/en/start-here/about-lerian/release-cycle) page.

> **[2025 schedule](/en/start-here/about-lerian/release-cycle-2025)**
>
> Cycles completed in 2025 with dates for each stage.


# Version governance
Source: https://docs.lerian.studio/en/start-here/about-lerian/versioning-governance

Understand Lerian's versioning governance: how changes are communicated, how dependencies stay compatible, and our backward-compatibility promise.

This page covers how we communicate changes, how we manage dependencies, and our long-term commitment to backward compatibility.

## Communication of changes

***

We communicate every change so teams can prepare.

* **Release notes** include new features, improvements, bug fixes, and breaking changes with migration paths.
* **Documentation updates** reflect API changes, new configurations, and updated behaviors.
* We share **pre-release announcements** in advance for major versions.

## Versioning of dependencies

***

We version dependencies with the same principles to ensure stability and compatibility.

* **Internal dependencies** follow the same versioning scheme as Midaz.
* We manage **external dependencies** to stay compatible throughout a major version lifecycle.

## Backward compatibility commitment

***

This versioning policy applies to every new release. We commit to maintaining the defined support windows for all future versions.

By preserving backward compatibility, we reduce the risk of breaking changes and let you plan upgrades on your own schedule.

> [!TIP]
>
> For details about timelines and schedules, see the [Release cycle](/en/start-here/about-lerian/release-cycle) page.


# Versioning process
Source: https://docs.lerian.studio/en/start-here/about-lerian/versioning-process

Understand how versioning works in Lerian: what to expect between releases, how semantic versioning is automated, and how to plan upgrades across majors.

Versioning follows an automated process that ensures consistency across releases. This section explains how automation drives version generation, how support timelines are defined, and what to expect when moving between versions.

## Versioning automation

***

To ensure an automated and predictable versioning process, we follow **semantic versioning** principles.

### How it works

***

**Step 1**

Identifies commits made since the last version.

**Step 2**

Determines the new version based on predefined rules.

**Step 3**

Automatically generates and publishes the new version.

## Version support timeline

***

Midaz follows a support policy that defines what you can expect from each version throughout its lifecycle.

* **Active support (current major version):** includes feature enhancements, bug fixes, and security patches.
* **Security support (post-active support):** limited to critical security patches only.

> [!CAUTION]
>
> Older versions do not receive further updates or support.

## Upgrade path recommendations

***

Follow these recommendations when you upgrade Midaz versions.

* **Minor version upgrades** (`1.0.0 → 1.1.0`) require little effort.
* **Major version upgrades** (`1.2.0 → 2.0.0`) may involve planning and testing.
* Every major version comes with an **upgrade guide**.


# Versioning scheme
Source: https://docs.lerian.studio/en/start-here/about-lerian/versioning-scheme

Learn how Lerian applies semantic versioning, how we manage breaking changes, and how to interpret release candidate designations used for pre-release builds.

The versioning scheme describes how we assign and increment version numbers. It clarifies the meaning of major, minor, and patch releases, how we handle breaking changes, and the role of pre-release tags.

## Semantic versioning

***

We follow a **modified semantic versioning** scheme in the format **X.Y.Z \[-designation]**, where:

| Version type | Increment frequency | Characteristics | Example |
| - | - | - | - |
| **X (Major Version)** | Evaluated every two development cycles, but **only released if there are significant changes**. | **May introduce breaking changes**.   Requires explicit upgrade steps. | *1.0.0 → 2.0.0* |
| **Y (Minor Version)** | Every development cycle | **Maintains backward compatibility**.    Introduces new features and functionality. | *1.0.0 → 1.1.0* |
| **Z (Patch Version)** | As needed, outside the regular cycle | **For hotfixes, security patches, and critical updates**.    Maintains backward compatibility. | *1.1.0 → 1.1.1* |

## Breaking changes

***

A breaking change happens when an update alters or removes behavior in a way that is not fully compatible with previous versions.

To keep this process predictable, we follow strict rules and communicate early.

* We introduce breaking changes **only in a major version**.
* They are **announced in advance**, always with migration guides and examples.
* Deprecated features **emit warnings** before removal, so teams have time to adjust.
* We aim to **minimize disruption** by grouping breaking changes together and providing alternative solutions whenever possible.

### Examples

* **Field replacement**: `routeId` (UUID) superseded the free-text `route` field in transaction payloads. v1 still accepts `route` when `routeId` is absent. v2 accepts only `routeId`.
* **Validation rules**: The Ledger Settings API replaced the `ACCOUNT_TYPE_VALIDATION` and `TRANSACTION_ROUTE_VALIDATION` environment variables. The API controls accounting validation per ledger without redeployment.
* **Deprecation cycle**: We removed the `scale` field from transaction amounts in v3, when amount handling moved to a numeric system.

## Pre-release designations

***

We use the following pre-release designations **when applicable**:

| Designation | Description | Characteristics | Example |
| :- | :- | :- | :- |
| **-alpha.N** | Early development builds. | **Potentially unstable, not for production use**.    May contain incomplete features. | *1.1.0-alpha.1* |
| **-beta.N** | Feature-complete builds undergoing testing. | **Suitable for testing environments.**   Feature-frozen, focusing on stability and bug fixes. | *1.1.0-beta.1* |
| **-rc.N** | Release Candidates. | **Expected to be stable and production-ready**.    Only critical bug fixes applied before the final release. | *1.1.0-rc.1* |

### Examples

**Potential releases**

* *1.0.0* → Initial stable release
* *1.0.1* → Patch with bug fixes
* *1.1.0-alpha.1* → Alpha for next minor
* *1.1.0-beta.1* → Beta for next minor
* *1.1.0-rc.1* → Release candidate
* *1.1.0* → Stable minor release
* *1.2.0* → Next minor release
* *2.0.0* → New major version


# Our versioning strategy
Source: https://docs.lerian.studio/en/start-here/about-lerian/versions

Understand Lerian's versioning strategy: increments, pre-release tags, automation, upgrade paths, and how changes are communicated.

Our versioning strategy defines how we increment versions, how we apply pre-release tags, and how automation keeps everything consistent across the system. Each release follows a [clear cycle](/en/start-here/about-lerian/release-cycle).

Alongside the technical rules, we provide guidance on upgrade paths, outline our support policy, and communicate changes.


# Who we are
Source: https://docs.lerian.studio/en/start-here/about-lerian/who-we-are

Learn about Lerian's mission, identity, and the principles that guide our approach to modern, open financial infrastructure and core banking software.

At Lerian, we build financial infrastructure that gives institutions control. We combine deep financial expertise with modern, open technology to help organizations operate independently, scale confidently, and adapt without friction.

We believe in clarity, ownership, and long-term autonomy.

## What we do

***

We help financial institutions design and operate modern core banking ecosystems using open technologies. By providing a programmable, modular foundation, we enable teams to move faster without compromising control over their operations or their architecture.

We built our platform for institutions that demand more than off-the-shelf solutions:

* **Digital banks** launching new financial products
* **Traditional banks** modernizing legacy cores incrementally
* **Fintechs** building embedded finance and payment platforms
* **Enterprises** consolidating payments, collections, and reconciliation across business units

## Our principles

***

Three principles guide how we build financial software:

#### Independence over vendor lock-in

We build systems that you control. We use standard interfaces and open formats, so no single vendor dictates your roadmap.

#### Transparency over opacity

Financial systems require absolute clarity. We design our infrastructure to be inspectable and auditable, so it has no hidden logic or opaque behaviors that introduce systemic risk.

#### Architecture over shortcuts

We prioritize scalable design over quick fixes. Our solutions handle real-world complexity, so your infrastructure grows with your business without constant re-platforming.

## Explore further

***

> **[Why Lerian](/en/start-here/about-lerian/why-lerian)**
>
> Understand the problems we solve and how our platform helps financial institutions regain control.

> **[Our values](/en/start-here/about-lerian/our-values)**
>
> Discover the core values and commitments that drive our team and shape our culture.

## Get in touch

***

Talk to us about your questions, a partnership, or your architecture.

> **[Contact us](https://lerian.studio/en/contact)**
>
> Reach out to our team to discuss how Lerian can support your infrastructure needs.


# Why Lerian
Source: https://docs.lerian.studio/en/start-here/about-lerian/why-lerian

Understand how Lerian helps financial institutions modernize core banking without vendor lock-in: modular products and flexible deployment.

Modern financial institutions face a common set of challenges. Legacy systems cost too much to maintain, and they adapt too slowly. They also lock you into vendors who dictate the roadmap.

Lerian gives you back control.

> [!NOTE]
>
> **New to core banking?** If terms like *Ledger*, *debit and credit*, or *chart of accounts* are new to you, start with the fundamentals first. They make everything here easier to follow.
>
> **[Begin with Core Banking Fundamentals](/en/start-here/fundamentals/core-banking/what-is-core-banking)**

## The problems we solve

***

| Challenge | How Lerian helps |
| :- | :- |
| **Slow time-to-market** | Modular platform lets you launch new products in weeks, not months |
| **Compliance burden** | Built-in audit trails, regulatory reporting, and immutable records reduce manual compliance work |
| **Reconciliation errors** | Automated reconciliation replaces manual spreadsheet matching and catches discrepancies |
| **Operational cost** | Replace multiple disconnected systems with one composable platform |
| **Scaling limitations** | Handle millions of transactions per day without re-platforming |

## What the platform includes

***

| Business need | Lerian product | What it does |
| :- | :- | :- |
| Central financial record-keeping | **Midaz** | Manages accounts, balances, and transactions with full audit trails |
| Regulatory and business reporting | **Reporter** | Generates compliance reports (BACEN) and business analytics automatically |
| Transaction reconciliation | **Matcher** | Compares internal records against bank statements and payment processors, and flags discrepancies |
| Real-time transaction controls | **Tracer** | Validates transactions against spending limits and business rules before they execute |
| Workflow automation | **Flowker** | Automates approval flows, anti-fraud checks, and payment orchestration |
| Credit products and loan management | **Lender** | Defines loan products and manages the loan lifecycle: applications, disbursement, and interest accrual |

Console, Access Manager, Streaming Hub, Multi-tenancy, and Observability are platform services. They are not products themselves.

| Platform service | What it does |
| :- | :- |
| **Console** | Operates Lerian products from one web interface, with one login |
| **Access Manager** | Controls human and machine access, and issues access tokens |
| **Streaming Hub** | Delivers platform events to your webhooks, cloud queues, or pull consumers |
| **Multi-tenancy** | Serves independent institution contexts from one deployment |
| **Observability** | Collects metrics, traces, and logs from Lerian workloads through OpenTelemetry |

## Deployment flexibility

***

You choose how to run the platform:

* **Fully managed (SaaS)**: Lerian handles everything. Your team focuses on configuration and business logic. Fastest path to production.
* **Your infrastructure (BYOC)**: Deploy in your own cloud or on-premises. Full control over data residency, security, and compliance boundaries.

Choose based on your regulatory requirements and operational maturity.

[Compare deployment models in detail →](/en/start-here/evaluate-and-deploy/deployment-models)

## Built for trust and independence

***

* **No vendor lock-in**: Standard interfaces and open formats across the platform. You can always move
* **Compliance-ready**: Immutable audit trails, double-entry enforcement, and regulatory reporting ship built in
* **Incremental adoption**: Start with one product and expand as needed. No big-bang migration required

## Who uses Lerian

***

* **Digital banks** launching new financial products
* **Traditional banks** modernizing legacy cores incrementally
* **Fintechs** building embedded finance and payment platforms
* **Enterprises** consolidating payments, collections, and reconciliation across business units

## Next steps

***

> **[Our Core Banking vision](/en/start-here/about-lerian/core-banking-vision)**
>
> Understand the four pillars that form our architectural philosophy.

> **[Getting started](/en/start-here/getting-started)**
>
> Choose your path: evaluate the platform or start building.

> **[Deployment models](/en/start-here/evaluate-and-deploy/deployment-models)**
>
> Understand the differences between fully managed and self-hosted deployment.

> **[Talk to us](https://lerian.studio/en/contact)**
>
> Talk to us about your questions or a partnership.


# Lerian Cloud (SaaS) and BYOC
Source: https://docs.lerian.studio/en/start-here/evaluate-and-deploy/deployment-models

Understand how Lerian can be deployed, in Lerian Cloud (SaaS) or through BYOC in your own infrastructure, and choose the model that fits your compliance and scale needs.

Lerian supports two deployment models for its complete, modular platform: **Lerian Cloud (SaaS)** and **BYOC** (Bring Your Own Cloud). The deployment model defines who operates the infrastructure. Your license and commercial agreement define which modules are available.

Choose the model that fits your operational maturity, compliance requirements, and team structure. Availability depends on the permitted license and commercial arrangement.

## Lerian Cloud (SaaS): Fully managed by Lerian

***

In Lerian Cloud, Lerian hosts and operates the platform for you. Your team focuses on building financial products. We handle everything underneath.

**What Lerian manages:**

* Cloud infrastructure (compute, storage, networking)
* Database provisioning, backups, and scaling
* Security patches and OS-level updates
* Application upgrades and version management
* Monitoring, alerting, and incident response
* High availability and disaster recovery

**What you manage:**

* Business configuration (organizations, ledgers, accounts, rules)
* API integrations with your systems
* User access and permissions within the platform
* Compliance obligations specific to your institution

> [!TIP]
>
> Lerian Cloud is ideal if you want the fastest path to production without building or maintaining infrastructure. Lerian operates the platform for you from day one.

## BYOC (Bring Your Own Cloud)

***

In the BYOC model, you deploy and operate Lerian in your own infrastructure. That can be a public cloud (AWS, GCP, Azure), a private cloud, or on-premises.

You have full control over the environment. Lerian provides the software, Helm Charts (A pre-configured package for deploying software on Kubernetes. Think of it as a ready-to-use installation template that automates setup and configuration.), Terraform templates (An infrastructure automation tool that provisions and manages cloud resources (servers, databases, networks) through configuration files instead of manual setup.), and tooling to make deployment and lifecycle management straightforward.

**What Lerian provides:**

* Application software (container images, Helm Charts)
* [Terraform templates](/en/products/midaz/midaz-terraform-foundation) for infrastructure provisioning
* [Lifecycle Management](/en/platform/lifecycle-management) (Enterprise): an agent in your cluster, through which Lerian installs and upgrades products
* Security patches and application updates (delivered by Lerian, and applied by you or by Lerian through Lifecycle Management)
* Technical support (Enterprise)

**What you manage:**

* Cloud infrastructure and Kubernetes (A platform for running and managing software applications at scale. It automatically handles deployment, scaling, and recovery across multiple servers.) clusters
* Database administration, backups, and scaling
* Network security (firewall rules, network isolation, and traffic routing)
* OS and container-level patching
* Monitoring and observability pipelines
* Encryption, secrets management, and access control

> [!TIP]
>
> BYOC is ideal if your organization requires full data sovereignty, has strict regulatory constraints on where data lives, or has an established platform engineering team.

### Why Helm for BYOC deployments

Lerian publishes official Helm charts (A pre-configured package for deploying software on Kubernetes. Think of it as a ready-to-use installation template that automates setup and configuration.) for the products and platform components supported through its Helm repository. Helm is the recommended way to deploy, configure, and manage the platform in your infrastructure.

* **Reproducibility**: Every deployment from the same chart version produces the same result. No "it works on my cluster" surprises across staging, production, or disaster recovery environments.
* **Rollback**: Helm keeps a history of every release. Rolling back to a previous version is a single command. You do not need to reconstruct the previous state manually.
* **Reduced operational risk**: Charts encode configuration details (environment variables, ports, dependencies), so your team does not have to remember them. Review your values and rendered manifests. Helm does not eliminate operational risk.
* **Faster time to production**: Instead of writing Kubernetes manifests from scratch, start with Lerian's official charts and adjust a single values file. Days of YAML editing become an afternoon of parameter tuning.
* **GitOps-ready**: Charts integrate naturally with GitOps workflows (ArgoCD, Flux). Deployment configuration lives in version control, changes go through pull requests, and every deployment is traceable to a specific commit.

For step-by-step installation instructions, see the [Midaz chart README](https://github.com/LerianStudio/helm/blob/main/charts/midaz/README.md#install-midaz-helm-chart).

### BYOC variations

For products and Enterprise entitlements that support multi-tenancy, BYOC supports two configurations:

| Configuration | Description | Best for |
| :- | :- | :- |
| **Single-Tenant** | One dedicated environment per institution | Large institutions with strict isolation requirements |
| **Multi-Tenant** | One environment serving multiple subsidiaries or clients | Institutions operating as a platform or managing subsidiaries |

> [!NOTE]
>
> Lerian Cloud is operated as a multi-tenant environment managed by Lerian. If you need dedicated, isolated infrastructure, choose BYOC Single-Tenant.

## How your deployment model affects Midaz API integration

***

The Midaz API surface is identical across deployment models: same endpoints, same payloads, same responses. The difference is in how authentication and tenant scoping work.

**Lerian Cloud and BYOC Multi-Tenant (Midaz)**

Your tenant context is established automatically through your authentication token. There is no tenant header to pass and no tenant ID to manage manually.

* You authenticate via [Access Manager](/en/platform/access-manager) and receive a JWT.
* That token includes your tenant context.
* Every API call is automatically scoped to your tenant: organizations, ledgers, accounts, and transactions are all isolated.
* You never interact with data from other tenants, and they never interact with yours.

**BYOC Single-Tenant (Midaz)**

Configure authentication with `PLUGIN_AUTH_ENABLED`. It defaults to `false` for local and development onboarding. Production deployments must set it to `true`. BYOC Multi-Tenant deployments also require it. In a permitted non-production single-tenant environment with authentication disabled, API calls do not require a token.

> [!TIP]
>
> For a deeper look at how tenant isolation works, see [Multi-tenancy](/en/platform/multi-tenancy).

## At a glance

***

| | **Lerian Cloud (SaaS)** | **BYOC** |
| :- | :- | :- |
| **Who manages infrastructure?** | Lerian | Your team |
| **Where does data live?** | Lerian-managed cloud | Your cloud or on-premises |
| **Time to production** | Weeks | Depends on your provisioning timeline |
| **Operational effort** | Low: Lerian handles operations | Higher: your team operates the platform |
| **Best for** | Teams that want to focus on product, not infrastructure | Organizations with strict data residency or compliance requirements |

> [!TIP]
>
> Not sure which model fits? Jump to ["Which model is right for you?"](#which-model-is-right-for-you) below.

## Comparing the models

***

| | **Lerian Cloud (SaaS)** | **BYOC** |
| :- | :- | :- |
| **Infrastructure** | Managed by Lerian | Managed by you |
| **Data location** | Lerian-managed cloud | Your cloud or on-premises |
| **Data sovereignty** | Data hosted in Lerian-managed cloud infrastructure | Data is hosted in your environment; you control residency and egress according to your architecture and contracted services. |
| **Security responsibility** | Shared (Lerian manages infra + app) | Shared (you manage infra, Lerian manages app) |
| **Time to production** | Weeks: no infrastructure setup required | Depends on your team's provisioning timeline |
| **Operational overhead** | Low: Lerian handles operations | Higher: your team operates the platform |
| **Customization** | Standard configuration | Full control over infrastructure and networking |
| **Compliance** | Lerian's environment meets security standards | You ensure your environment meets your regulatory requirements |
| **Updates** | Applied by Lerian | Applied by you with Helm, or by Lerian through Lifecycle Management |
| **Scalability** | Managed by Lerian | Managed by you |

## Which model is right for you?

***

**Choose Lerian Cloud if:**

* You want to go live quickly without provisioning infrastructure
* Your team prefers to focus on product and integration, not operations
* You don't have strict requirements for data to remain in your own environment

**Choose BYOC if:**

* Regulatory or compliance rules require data to stay in your infrastructure
* You need full control over networking, encryption, and access policies
* Your organization has a platform or DevOps team ready to operate Kubernetes workloads
* You want to integrate Lerian into an existing cloud environment with specific architectural constraints

## Deployment and licensing

***

Deployment and licensing are related dimensions, but not every pairing is available. Lerian Cloud is Enterprise-only. Community supports self-managed Midaz BYOC. See [Community and Enterprise](/en/products/midaz/midaz-models).

| | **Community** | **Enterprise** |
| :- | :- | :- |
| **Lerian Cloud (SaaS)** | Not available | Available |
| **BYOC** | Available for Midaz only (self-managed) | Available (with Lifecycle Management and support) |

> [!NOTE]
>
> Lerian Cloud requires Lerian to manage infrastructure, operations, and lifecycle on your behalf. Those capabilities are part of the Enterprise offering. That's why it is not available under the Community model.

* **Community + BYOC**: You deploy and manage Midaz using the published Midaz Helm charts and documentation. Community support via GitHub and Discord.
* **Enterprise + BYOC**: Full BYOC with Lifecycle Management, dedicated support, SLA, onboarding, and access to plugins.
* **Enterprise + Lerian Cloud**: Lerian manages everything. You get the licensed platform modules without infrastructure responsibilities.

## What's next

***

> **[Community and Enterprise](/en/products/midaz/midaz-models)**
>
> Understand the licensing differences and what's included in each model.

> **[Getting started](/en/start-here/getting-started)**
>
> Follow the step-by-step guide to set up your first Ledger and run transactions.

> **[Security](/en/products/midaz/security)**
>
> Learn how the shared responsibility model works for each deployment option.

> **[Deployment strategies](/en/products/midaz/deployment)**
>
> Explore Kubernetes, Helm, and Terraform options for BYOC deployments.


# Before you begin
Source: https://docs.lerian.studio/en/start-here/evaluate-and-deploy/getting-started

Review the sandbox, Try It, and licensing pages before integrating with Lerian APIs so you know how to authenticate, test, and access each product.

This section covers the tools and policies you should know before integrating with Lerian's APIs. Use the sandbox to test your requests safely, and review the licensing page to understand usage rights.

## Available pages

***

> **[Using our Sandbox](/en/start-here/evaluate-and-deploy/using-our-sandbox)**
>
> Test your integrations in a secure, isolated environment with simulated data.

> **[Using the Try It feature](/en/start-here/evaluate-and-deploy/using-try-it)**
>
> Interact with our APIs directly from the documentation.

> **[Lerian's License](/en/start-here/evaluate-and-deploy/lerians-license)**
>
> Understand how Lerian's software license works, including usage rights and conditions.


# Initiating with Enterprise Model
Source: https://docs.lerian.studio/en/start-here/evaluate-and-deploy/initiating-with-enterprise-model

Set up Lerian Enterprise in the right order to onboard product, engineering, and ops teams across Midaz, Access Manager, and Reporter.

> [!NOTE]
>
> This guide is for **Enterprise Model** users with access to **Midaz** and **Access Manager**. It also shows how to configure the **Fees Engine** and **CRM** capabilities that ship inside Midaz, and how to add **Reporter**.

## Getting started: Setup order

***

Follow this setup order:

![Recommended setup order for the Enterprise Model, sequencing Midaz, Access Manager, and the optional Fees, CRM, and Reporter capabilities](https://mintcdn.com/lerian-49cb71fc/svQbQMf9Iz90q0Cc/images/en/d2/enterprise-model.svg?fit=max\&auto=format\&n=svQbQMf9Iz90q0Cc\&q=85\&s=0a4b51b9c2763c1a87cb07f849de8eb2)

Figure 1. Enterprise Model setup order.

### Step 1: Configure Midaz Core

Start with the [Midaz recommended workflow](/en/products/midaz/recommended-workflow). It covers these tasks:

* Create your Organization and Ledger(s).
* Define assets and account types.
* Set up portfolios, accounts, and segments.
* Configure Accounting Routes for validation.
* Build double-entry transaction workflows.

### Step 2: Activate Access Manager

**Access Manager** centralizes authentication and role-based access control (RBAC) for Midaz and its plugins.

* Define roles and their permissions.
* Assign permissions to roles or users.
* Control access to operations by role.

> [!TIP]
>
> Start with the [Access Manager Setup](/en/platform/access-manager) page.

### Step 3: Configure CRM

**CRM** ships inside the Midaz ledger process and manages `Holder` and `Instrument` records. Instruments link Holders to ledger accounts, and accounts can optionally belong to portfolios.

* Register customers as `Holder` objects.
* Create Instruments to link Holders to ledger accounts, or use `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/holders/{holder_id}/accounts` to open a holder-owned account in one call.
* Add metadata for compliance, segmentation, and insights.

This links each customer to the right ledger accounts.

> [!TIP]
>
> Start with the [CRM Setup](/en/products/midaz/crm/crm-overview) page.

### Step 4: Configure Fees Engine

Use the **Fees Engine** to automate pricing and monetization rules across your operations.

* Define fee packages with flat or percentage calculations.
* Attach fees to operations like transfers or withdrawals.
* Control when and how the Fees Engine calculates and charges each fee.

> [!TIP]
>
> Start with the [Fees Engine Setup](/en/products/midaz/fees/fees-engine-overview) page.

### Step 5: Design with Reporter templates

Use **Reporter** and its template engine to generate content such as:

* Transaction summaries
* Regulatory documents
* Customer notifications

Use it to standardize documents and messages with context data from Midaz and CRM.

> [!TIP]
>
> Start with the [Reporter quick start](/en/products/reporter/reporter-quick-start) page.

## Final recommendations

***

After you set up all systems:

* Review the integration points between Midaz and each capability.
* Create automated workflows that combine ledger events, customer data, and fee logic.
* Apply permission rules with Access Manager to control access at scale.

> [!TIP]
>
> Lerian capabilities are modular. Activate and expand them progressively.


# Lerian's License
Source: https://docs.lerian.studio/en/start-here/evaluate-and-deploy/lerians-license

Lerian licenses authorize access to paid products and plugins with organization-scoped and global license types, plus activation and validation rules.

A **license** is a key that authorizes access to Lerian features or services under specific contractual conditions, typically aligned with billing cycles (e.g., monthly, annual). This mechanism is similar to how software products like Microsoft Office or GitHub Enterprise manage access through activation keys.

In Lerian's ecosystem, licenses:

* Confirm that institutions remain in good standing before they access paid features, such as products, plugins or enterprise features.
* Manage which features are available per client.
* Let Lerian scale support and sales operations.

Only clients with valid licenses, as defined in their contracts, can access specific software components.

## License types

***

In Lerian’s ecosystem, licenses can have two different scopes:

### Organization-specific licenses (non-global)

Applies to the organizations listed in `ORGANIZATION_IDS`.

### Global licenses

Valid for multiple organizations.

## License usage workflow

***

The steps below apply to both license types:

**1. Submit a license request to Lerian.**

* **For organization-specific licenses**: provide the IDs of the organizations that will use the license.
* **For global licenses**: inform Lerian that you need a global license. You do not need to provide organization IDs.

**2. License generation and activation by Lerian**

Lerian’s team follows the internal process to create and activate the license using the provided details.

**3. License key delivery**

Lerian sends the **License Key** (`LICENSE_KEY`) to the client.

**4. Environment configuration**

Once you receive your license key, you must configure your `.env` file so the system knows which license to validate and which organizations it applies to.

> [!WARNING]
>
> Always configure the correct environment variables before using a plugin. Incorrect or missing values will result in license validation errors.

**Organization-specific licenses (non-global)**

```bash Bash theme={null}
# LICENSE
LICENSE_KEY=your-license-key
ORGANIZATION_IDS=organization-id-1,organization-id-2
```

* **LICENSE\_KEY**: The key provided by Lerian.
* **ORGANIZATION\_IDS**: The IDs of the organizations the license covers, separated by commas.

**Global licenses**

```bash Bash theme={null}
# LICENSE
LICENSE_KEY=your-license-key
ORGANIZATION_IDS=global
```

* **LICENSE\_KEY**: The key provided by Lerian.
* **ORGANIZATION\_IDS**: Use the value `global` for global licenses.

## License-related errors

***

For the error codes a product returns when license validation fails, see [License Manager error list](/en/platform/licensing/license-manager-error-list).

> [!TIP]
>
> For more information about your license or to request an upgrade, please contact the Lerian commercial team.


# Using our Sandbox
Source: https://docs.lerian.studio/en/start-here/evaluate-and-deploy/using-our-sandbox

An isolated Lerian environment that mirrors production behavior and powers the Try It experience inside the documentation for safe hands-on API testing.

The sandbox helps you explore Lerian’s APIs in a safe and predictable environment. It mirrors production behavior while keeping your real data untouched.

The sandbox powers the Try It experience. If you haven't seen how the Try It feature works yet, check out the [Using the Try It feature](/en/start-here/evaluate-and-deploy/using-try-it) page.

## Base URLs

***

| Service | Sandbox Base URL |
| - | - |
| Midaz | `https://ledger.sandbox.lerian.net` |
| Access Manager | `https://auth.sandbox.lerian.net` (Auth APIs) `https://identity.sandbox.lerian.net` (Identity APIs) |
| Reporter | `https://reporter.sandbox.lerian.net` |

## What you can do

***

The sandbox lets you:

* Run live requests from the documentation
* Inspect request and response structures
* Understand authentication headers and data formats
* Learn how each API behaves without setting up your own environment

> [!TIP]
>
> Click **Try It** on an endpoint to run a live request and check how the API responds.

## Limitations

***

The sandbox is designed for exploration. Some restrictions are intentional:

* Data resets frequently
* Some endpoints use fixed or sample responses
* Some APIs can use simpler authentication rules

For full integration tests, use your own environment or reach out to our team to request a dedicated development space.


# Using the Try It feature
Source: https://docs.lerian.studio/en/start-here/evaluate-and-deploy/using-try-it

Send live requests directly from the documentation with real API responses in a controlled environment, with no local setup required.

The **Try It** feature lets you interact with our APIs directly from the documentation. It gives you an embedded playground where you can test real requests and responses in a controlled environment.

If you want to understand how the sandbox works under the hood, check the page [Using our Sandbox](/en/start-here/evaluate-and-deploy/using-our-sandbox).

## What you can do

***

With **Try It**, you can:

* Send live requests
* Inspect full HTTP request and response details
* Adjust headers, parameters, and body payloads
* Test different authentication tokens or organization IDs
* Explore error handling and validation scenarios with mock data

## Before you start

***

You will need the required headers for each API. Examples include `Authorization` or `X-Organization-Id`. Each endpoint specifies exactly which headers you must use.

> [!CAUTION]
>
> The sandbox resets automatically every day.
>
> Any entity you create, such as Organizations, Ledgers, or Portfolios, will be deleted within 24 hours.
>
> When testing dependent endpoints, create the required entities again before sending new requests.
>
> For example, you must create an Organization before creating a Ledger. Use the returned `id` as the `organization_id` in the Ledger path.

## How to use it

***

> [!WARNING]
>
> The **Try It** feature is available on endpoint pages in the **API Reference**.
>
> If the Try It button does not appear, reload the page or check that you are in the API Reference section.

**Step 1**

Open any endpoint in the **API Reference**.

**Step 2**

Click the **Try It** button next to the endpoint path.

**Step 3**

Fill in the input fields such as query parameters, body content, or headers.

**Step 4**

Click **Send Request** to run the call.

**Step 5**

Review the response body, status code, and headers shown below the request.

> [!TIP]
>
> You can copy your request as `curl` or `fetch` using the code tabs. It is a simple way to move from testing in the docs to running calls in your local environment.


# The accounting cycle
Source: https://docs.lerian.studio/en/start-here/fundamentals/accounting/accounting-cycle

How transactions, journal entries, the ledger, trial balance, and financial statements fit together as one repeating cycle that keeps the books trustworthy.

You've met the pieces one at a time: [debits and credits](/en/start-here/fundamentals/accounting/debits-and-credits), [journal entries](/en/start-here/fundamentals/accounting/journal-entries), the [chart of accounts](/en/start-here/fundamentals/accounting/chart-of-accounts), the [financial statements](/en/start-here/fundamentals/accounting/financial-statements). The **accounting cycle** puts them in a line. It is a routine that repeats. It turns a single real-world event into a report you can trust, then starts over.

## One event, all the way through

***

Every figure on a financial statement started life as something tiny and concrete: a sale, a payment, a bill. The cycle is the path that event travels, step by step, until it shows up in a report.

* **Transaction**: something happens. A customer pays, you cover the rent, a bill arrives.
* **Journal entry**: you write it down as matching debits and credits, so you record both sides of the movement.
* **Ledger**: you sort each entry into the right account, so every account gathers its own running history.
* **Trial balance**: you add up all the accounts and check that total debits still equal total credits.
* **Financial statements**: the balanced totals form the Balance Sheet, Income Statement, and Cash Flow Statement.

Then the cycle repeats for the next transaction, the next day, the next period.

```mermaid theme={null}
flowchart LR
  T["Transaction<br/>something happens"] --> J["Journal entry<br/>debits = credits"]
  J --> L["Ledger<br/>sorted by account"]
  L --> TB["Trial balance<br/>check it still balances"]
  TB --> FS["Financial statements<br/>the reports"]
  FS -.->|"next transaction · next period"| T
  classDef bal fill:#fff8e1,stroke:#f4b400,color:#333;
  class TB,FS bal;
```

## Walking one transaction around the loop

***

Say a customer pays you \$2,000 for a sale you make right then, so you earn the revenue at that moment. Follow it through:

1. **Transaction.** The sale happens and the customer pays.
2. **Journal entry.** You record it: **Cash** debited \$2,000, **Revenue** credited \$2,000. Debits equal credits, so the entry balances.
3. **Ledger.** That \$2,000 debit joins the running history of the Cash account. The \$2,000 credit joins the Revenue account. Do this for every entry and each account always knows its own total.
4. **Trial balance.** Add every account's debits and credits across the whole book. If the two grand totals match, the records are internally consistent, a quick health check before you report anything.
5. **Financial statements.** The Cash balance feeds the Balance Sheet. The Revenue feeds the Income Statement. It is the same \$2,000, now part of the big picture.

The cycle invents nothing new along the way. Each step reorganizes the same balanced movement into a more useful shape. It goes from a single event, to a record, to a sorted history, to a verified total, to a readable report.

## Why the order matters

***

Each step depends on the one before it, so the sequence never changes:

* You can't sort an entry into the **ledger** until you've written the **journal entry**.
* The **trial balance** is only meaningful once every entry has landed in the ledger.
* The **financial statements** are only trustworthy once the trial balance confirms debits equal credits.

The balancing rule from [double-entry](/en/start-here/fundamentals/accounting/double-entry-bookkeeping) rides along at every stage. A mistake therefore shows up early (at the trial balance) instead of hiding inside a finished report.

> [!NOTE]
>
> **See also in Core Banking**
>
> See how this whole flow lands in a real ledger system in [Designing your ledger plan](/en/start-here/fundamentals/core-banking/designing-your-ledger-plan) and [Where to go next](/en/start-here/fundamentals/core-banking/where-to-go-next).

## Next steps

***

> [!NOTE]
>
> **Next up**
>
> See how these ideas map onto a real ledger system in [Accounting in Lerian](/en/start-here/fundamentals/accounting/accounting-in-lerian).


# Accounting in Lerian
Source: https://docs.lerian.studio/en/start-here/fundamentals/accounting/accounting-in-lerian

How core accounting ideas map onto real Lerian and Midaz entities (accounts, transactions, operations, and routes) so the concepts and the product line up.

Everything in this guide covers accounting in general. Midaz implements that same accounting. The terms you've already learned have direct counterparts in the product.

## The same ideas, renamed for a ledger

***

From here on, the words get more product-specific. The accounting ideas stay the same and only the names change. In the table below, each accounting idea on the left maps to something concrete in Midaz on the right.

| Accounting idea | In Lerian / Midaz |
| - | - |
| [Chart of accounts](/en/start-here/fundamentals/accounting/chart-of-accounts) | The **account hierarchy** inside a Ledger |
| The five account families (assets, liabilities, equity, revenue, expense) | How you **structure and group** accounts in that hierarchy |
| [Journal entry](/en/start-here/fundamentals/accounting/journal-entries) | A **transaction** made of **operations** |
| A single debit or credit line | One **operation** |
| Which accounts a kind of entry may touch | An **accounting route** |

```mermaid theme={null}
flowchart LR
    subgraph ACC["Accounting"]
        direction TB
        CA["Chart of Accounts"]:::a
        JE["Journal Entry"]:::a
        DC["Debit / Credit rule"]:::a
    end
    subgraph MID["Lerian / Midaz"]
        direction TB
        AH["Account Hierarchy"]:::m
        TO["Transaction + Operations"]:::m
        AB["Always Balanced"]:::m
    end
    CA --> AH
    JE --> TO
    DC --> AB
    classDef a fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
    classDef m fill:#dcfce7,stroke:#16a34a,color:#14532d
```

## Chart of accounts → the account hierarchy

***

A [chart of accounts](/en/start-here/fundamentals/accounting/chart-of-accounts) organizes the buckets a business sorts its money into. In Midaz, an [account](/en/start-here/fundamentals/core-banking/building-blocks) belongs to one asset code and can have one or more keyed [balance](/en/start-here/fundamentals/core-banking/building-blocks) records. Accounts form a hierarchy, not a flat list. You can nest and group them to mirror the structure of a real business. The five accounting families (assets, liabilities, equity, revenue, expenses) are the kind of grouping that hierarchy expresses.

A [Ledger](/en/start-here/fundamentals/core-banking/building-blocks) is one self-contained book of records, and an Organization can hold several. So your chart of accounts lives as the structured set of accounts inside a Ledger. It is the same map of "where value lives," given room to scale.

## Journal entry → transaction + operations

***

A [journal entry](/en/start-here/fundamentals/accounting/journal-entries) records one event as matching debits and credits. Midaz splits that single idea into two precise words you'll see everywhere in [how money moves](/en/start-here/fundamentals/core-banking/how-money-moves):

* A **transaction** is one complete movement of value: the whole event, start to finish. That's the journal entry.
* An **operation** is one part of that movement: the smallest Midaz record of a balance effect. Non-pending transfers can produce debit and credit operations. Pending or canceled flows can also include `ON_HOLD` or `RELEASE`.

So when you recorded "Cash debited \$2,000, Revenue credited \$2,000" as a journal entry, the Midaz version is one transaction made of two operations. It is the same event and the same two sides, in the product's vocabulary.

```mermaid theme={null}
flowchart TD
    A["Journal entry<br/><i>accounting</i>"]:::acc --> B["Transaction<br/><i>the whole movement</i>"]:::mid
    B --> C["Operation<br/>debit"]:::mid
    B --> D["Operation<br/>credit"]:::mid
    C --> E["Debits total"]:::tot
    D --> F["Credits total"]:::tot
    E --> G["Transaction balances"]:::bal
    F --> G
    classDef acc fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
    classDef mid fill:#dcfce7,stroke:#16a34a,color:#14532d
    classDef tot fill:#f3f4f6,stroke:#6b7280,color:#111827
    classDef bal fill:#fde68a,stroke:#d97706,color:#78350f
```

## Double-entry → transactions always balance

***

Midaz builds the iron rule of accounting, [debits must equal credits](/en/start-here/fundamentals/accounting/debits-and-credits), into its processing. Midaz validates resolved source, destination, and transaction totals before processing. If they differ, the movement will not go through.

Midaz validates every accepted movement with a clear source and a clear destination. The system enforces this instead of a person. The [core-banking explanation of how the ledger records money](/en/start-here/fundamentals/core-banking/double-entry-explained) covers this from the ledger's side.

## Accounting routes → which accounts may take part

***

In plain accounting you decide by judgment which accounts a given kind of entry should touch. Midaz captures that judgment once as an [accounting route](/en/start-here/fundamentals/core-banking/routes-and-fees). The route is a reusable rule for who can send, who can receive, and which debits and credits a movement should record. With route validation enabled for the Ledger, Midaz checks transactions against that rule. A **fee** means more balanced operations on the same transaction.

For example, a wallet transfer's route defines which customer account may be debited, which customer account may be credited, and which fee accounts join in when a fee applies. With route validation enabled, Midaz checks those rules. The [core-banking guide to routes and fees](/en/start-here/fundamentals/core-banking/routes-and-fees) walks through it in full.

## A note on holders and accounts

***

In Midaz the [account](/en/start-here/fundamentals/core-banking/holders-accounts-aliases) is the balance container. The real-world owner is a separate **holder** record and friendly nicknames are **aliases**, kept separate so the Ledger's record of value stays clean. If that distinction matters for your work, [who owns what](/en/start-here/fundamentals/core-banking/holders-accounts-aliases) untangles it.

## Next steps

***

> [!NOTE]
>
> **Go deeper**
>
> To see these entities in full, continue into the [Core banking fundamentals](/en/start-here/fundamentals/core-banking/what-is-core-banking), or revisit any idea from the [Accounting overview](/en/start-here/fundamentals/accounting/what-is-accounting).


# Accrual vs. cash accounting
Source: https://docs.lerian.studio/en/start-here/fundamentals/accounting/accrual-vs-cash

Why revenue isn't always money in the bank and profit isn't the same as cash: the difference between accrual and cash accounting, explained in plain language.

When does a sale count? The moment you agree to it and send the bill, or the moment the money lands in your account? Your answer decides whether you're doing **accrual** or **cash** accounting, and it changes how every report reads.

## Two moments, not one

***

Every sale has *two* moments:

```mermaid theme={null}
flowchart LR
    M1["📋 Moment 1<br/>Work done · Invoice sent<br/><b>March</b>"]:::moment
    M2["💵 Moment 2<br/>Cash received<br/><b>May</b>"]:::moment
    M1 -->|"time passes"| M2
    ACC(["Accrual records the sale here"]):::accrual
    CASH(["Cash records the sale here"]):::cash
    ACC -.-> M1
    CASH -.-> M2
    classDef moment fill:#eef2ff,stroke:#4f46e5,color:#312e81
    classDef accrual fill:#dcfce7,stroke:#16a34a,color:#14532d
    classDef cash fill:#fef3c7,stroke:#d97706,color:#78350f
```

* The moment you **earn** it: you deliver the goods, finish the work, send the invoice.
* The moment you **get paid**: the cash arrives.

Sometimes these happen together (you buy coffee, you pay at the counter). Often they don't: you finish a job in March but the customer pays in May. The two methods disagree about which moment to record.

## Cash accounting: record when money moves

***

**Cash accounting** is the simple one: you record a transaction **only when the cash changes hands**. You write down money in and money out, and you record nothing until money moves.

It works like your personal bank statement. You don't note that a friend *promised* to pay you back. You note it when they actually do. Small businesses like it because it's easy and it mirrors the bank balance you can see.

It can mislead you about timing. Do \$50,000 of work in December but get paid in January, and cash accounting says December earned **nothing**. That's tidy for taxes but a poor picture of what the business did.

## Accrual accounting: record when it's earned

***

**Accrual accounting** records a transaction **when it's earned or incurred, not when the cash moves**. Finish the work and send the invoice, and that's revenue *now*, even if payment is weeks away. Receive a bill for electricity you've already used, and that's an expense *now*, even if you pay it later.

It captures *promises* as well as cash:

* Accrual records money customers owe you (but haven't paid) as revenue and as an asset called **accounts receivable**.
* It also records bills you owe (but haven't paid) as expenses and as a liability called **accounts payable**.

This gives a truer picture of how the business is *really* doing in a period. That is because it matches the income to the work that earned it. That's why larger businesses (and the rules they answer to) use it.

| | **Cash accounting** | **Accrual accounting** |
| - | - | - |
| **Records revenue when** | Cash arrives | Work is done / invoice sent |
| **Records expenses when** | Cash is paid | Bill is incurred |
| **Shows you** | What's in the bank | What you've really earned and owe |
| **Best for** | Simplicity, small operations | An accurate picture over time |

This is the same job, **\$50,000 of work done in December, paid in January**, booked under each method:

| The \$50,000 job | December *(work done)* | January *(customer pays)* |
| - | - | - |
| **Cash accounting** records revenue | \$0 | \$50,000 |
| **Accrual accounting** records revenue | \$50,000 | None *(cash just arrives)* |

The sale and the \$50,000 are the same, but the methods book them in different months. Accrual ties the revenue to the **work** in December. Cash waits for the **money** in January.

## Why revenue isn't "money in the bank"

***

Under accrual accounting, **revenue means money earned, not money received**. You can book \$10,000 of revenue this month and have **none of it** in your account yet, because the customers haven't paid.

So when you read an [Income Statement](/en/start-here/fundamentals/accounting/financial-statements) and see revenue, don't picture a full bank account. Picture *work that has been done and billed*. The cash may already be here, may arrive next month, or may never arrive at all if someone fails to pay.

## Why profit isn't cash

***

The same gap explains why **a profitable business can still run out of cash.**

Profit is revenue minus expenses. Under accrual, both can include things where no cash has moved yet. So your Income Statement can show a healthy profit while your bank account runs dry, because customers are slow to pay. The reverse happens too: you can have plenty of cash (a big upfront payment) yet little profit.

That's why there are two different reports. The Income Statement shows **profit**. The [Cash Flow Statement](/en/start-here/fundamentals/accounting/financial-statements) shows the **actual cash**. You need both to understand a business.

## Next steps

***

> [!NOTE]
>
> **Next up**
>
> See how these pieces run together, period after period, in [The accounting cycle](/en/start-here/fundamentals/accounting/accounting-cycle).


# Assets, liabilities & equity
Source: https://docs.lerian.studio/en/start-here/fundamentals/accounting/assets-liabilities-equity

The accounting equation explained with everyday analogies: what you own, what you owe, what's yours, and why Assets = Liabilities + Equity always balances.

Every business (and honestly, every person) can describe its financial life with three words: **assets**, **liabilities**, and **equity**. Get these three and the accounting equation falls into place.

Let's use a house.

## The three words, in plain terms

***

* **Assets**: everything you **own** that has value. Your house, your car, the cash in your account, the money customers still owe you.
* **Liabilities**: everything you **owe** to someone else. Your mortgage, your car loan, an unpaid bill.
* **Equity**: what's **yours** after you pay off the debts. It's the leftover.

Say your house is worth \$300,000 (an asset). You still owe \$200,000 on the mortgage (a liability). The part that's truly yours (your **equity**) is \$100,000.

What you own, minus what you owe, is what's yours:

$$
Assets - Liabilities = Equity
$$

| Term | Plain meaning | House example |
| - | - | - |
| **Asset** | What you own | The \$300,000 house |
| **Liability** | What you owe | The \$200,000 mortgage |
| **Equity** | What's left over for you | The \$100,000 that's yours |

## The equation that ties them together

***

You just saw the equation one way. Move `Liabilities` to the other side and you see the same idea in reverse. This is the form accountants use, called the **accounting equation**:

$$
\underset{\$300{,}000\ \text{house}}{\text{Assets}} \:=\: \underset{\$200{,}000\ \text{mortgage}}{\text{Liabilities}} \:+\: \underset{\$100{,}000\ \text{yours}}{\text{Equity}}
$$

It's the same sentence written two ways. The first asks *what's truly mine?* The second asks *how did I fund everything I own?* Nothing changes but the order.

The business paid for everything it **owns** in one of two ways: with **money it borrowed** (liabilities) or with **money that's its own** (equity). So the total value of what you own always equals the sum of those two sources.

## Why it always balances

***

The equation can **never** be out of balance, by design. If something changes on one side, something else has to change to keep it even.

* **You buy a \$20,000 car with a loan.** Assets go up by \$20,000 (the car). Liabilities go up by \$20,000 (the loan). Still balanced.
* **You pay off \$5,000 of that loan with cash.** Assets drop by \$5,000 (cash leaves). Liabilities drop by \$5,000 (debt shrinks). Still balanced.
* **The business earns \$10,000 in profit.** Assets go up by \$10,000 (cash). Equity goes up by \$10,000 (it's yours to keep). Still balanced.

Every real-world event touches the equation in a way that keeps both sides equal. That is the rule that makes accounting trustworthy. If your books *don't* balance, you know immediately that something in the records is wrong.

## Next steps

***

> [!NOTE]
>
> **Next up**
>
> You've got what a business owns, owes, and keeps. The other half of the picture is what it earns and spends. See [Revenue, expenses & costs](/en/start-here/fundamentals/accounting/revenue-and-expenses), and how profit feeds back into equity.


# Chart of accounts
Source: https://docs.lerian.studio/en/start-here/fundamentals/accounting/chart-of-accounts

What a chart of accounts is, why it keeps financial data organized, how it ties accounting together, and how it maps to the account hierarchy in Midaz.

Think of accounting as a giant filing cabinet of money movements. The **chart of accounts** is the labels on the drawers. It's the organized list of every "bucket" a business uses to sort its transactions. Without it, the records would be an unsearchable pile.

## What a chart of accounts is

***

A **chart of accounts** lists, in a defined structure, all the accounts a business uses to record its financial activity. Each account is a category: a place to put a certain kind of transaction.

Think of how you might organize your own money into labeled envelopes: *Rent*, *Groceries*, *Salary*, *Savings*. A chart of accounts is the same idea, more complete and consistent. You file every transaction into one of these named buckets, so you always know what it was for.

## How it's organized

***

The chart groups accounts to match the concepts you've already met. Most charts follow the same five families:

| Group | What goes here | Examples |
| - | - | - |
| **Assets** | What the business owns | Cash, equipment, money owed to you |
| **Liabilities** | What the business owes | Loans, unpaid bills |
| **Equity** | What's left for the owners | Owner's stake, retained profit |
| **Revenue** | Money earned | Sales, service income |
| **Expenses** | Money spent | Rent, salaries, supplies |

The first three feed the [Balance Sheet](/en/start-here/fundamentals/accounting/financial-statements). The last two feed the Income Statement. So the chart of accounts is the bridge between raw transactions and the reports everyone reads.

In practice, a simple one looks like this. Each family gets its own range of numbers, with individual accounts slotted inside:

```
1000  Assets
  1010  Cash
  1020  Accounts receivable
  1030  Equipment

2000  Liabilities
  2010  Loans payable
  2020  Taxes payable

3000  Equity
  3010  Owner's equity
  3020  Retained earnings

4000  Revenue
  4010  Product sales
  4020  Service income

5000  Expenses
  5010  Rent
  5020  Salaries
  5030  Supplies
```

The numbers keep accounts in a fixed order and leave room to add new ones (a `1040` for inventory, say) without disturbing the rest.

## How it makes financial data usable

***

A good chart of accounts is what makes financial data **usable**:

* **Consistency**: the same kind of expense always lands in the same place, so reports are reliable.
* **Clarity**: anyone can see, at a glance, where money goes.
* **Scale**: whether you have ten transactions or ten million, they all have a clear home.

Without it, [double-entry](/en/start-here/fundamentals/accounting/double-entry-bookkeeping) entries would have nowhere consistent to land, and no one could assemble the [financial statements](/en/start-here/fundamentals/accounting/financial-statements).

## How it connects in Lerian

***

In accounting, the chart of accounts is the structure that organizes your records. In a **ledger system**, that same idea becomes an **account hierarchy**, a tree that groups balances, movements, and the business entities behind them:

```mermaid theme={null}
flowchart TD
    A["Chart of accounts"]:::root --> B["Assets"]:::family
    A --> C["Liabilities"]:::family
    A --> D["Equity"]:::family
    A --> E["Revenue"]:::family
    A --> F["Expenses"]:::family
    B --> B1["Cash"]:::leaf
    B --> B2["Accounts receivable"]:::leaf
    B --> B3["Equipment"]:::leaf
    F --> F1["Rent"]:::leaf
    F --> F2["Salaries"]:::leaf
    F --> F3["Supplies"]:::leaf
    classDef root fill:#f3f4f6,stroke:#6b7280,color:#111827
    classDef family fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
    classDef leaf fill:#eff6ff,stroke:#93c5fd,color:#1e3a8a
```

In **Midaz**, that hierarchy lives inside a Ledger, so you can group and nest accounts to mirror the structure of a real business. [Accounting in Lerian](/en/start-here/fundamentals/accounting/accounting-in-lerian) shows how this idea and the other accounting ideas map onto the product.

> [!NOTE]
>
> **See also in Core Banking**
>
> This same structure becomes an account hierarchy in a ledger. See [The building blocks](/en/start-here/fundamentals/core-banking/building-blocks) and [Designing your ledger plan](/en/start-here/fundamentals/core-banking/designing-your-ledger-plan).

## Next steps

***

> [!NOTE]
>
> **Next up**
>
> Once you file every transaction into the right account, those totals roll up into reports. Meet them in [Financial statements](/en/start-here/fundamentals/accounting/financial-statements).


# Debits and credits
Source: https://docs.lerian.studio/en/start-here/fundamentals/accounting/debits-and-credits

What debit and credit mean in a banking system: the two ends of a money movement, and why one balance is a wallet to you and a liability to the ledger.

Two words trip up almost everyone the first time they read a banking system: **debit** and **credit**. They sound like accounting jargon, but they name the two ends of a money movement. A debit is where money comes **from**. A credit is where it **goes**.

## Debit is out, credit is in

***

Every movement of money leaves one account and arrives in another. Those two ends have names:

* A **debit** is the account money moves **out of** (the **source**).
* A **credit** is the account money moves **into** (the **destination**).

When you send R\$100 to a merchant, your account is **debited** (money out) and the merchant's account is **credited** (money in). One movement has two sides.

```mermaid theme={null}
flowchart LR
    S["Your account<br/>(source)"]:::debit
    M(("Movement<br/>R$100")):::bal
    D["Merchant account<br/>(destination)"]:::credit
    S -->|"debit · R$100 out"| M
    M -->|"credit · R$100 in"| D
    classDef debit fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
    classDef credit fill:#fde68a,stroke:#d97706,color:#78350f
    classDef bal fill:#f3f4f6,stroke:#6b7280,color:#111827
```

This is how your bank statement already reads: money leaving your account shows as a debit, money arriving shows as a credit.

## Your wallet is not the whole story

***

The everyday intuition and the accounting meaning part ways here.

In your **wallet**, money in is good, and money out leaves you with less. When your bank says it **credited** your account, your balance went **up**. A **debit** took money away. So it's tempting to read *credit = add, debit = subtract*.

But that's your wallet's point of view. The **ledger** that holds your money sees the same balance another way. To the institution, your balance is money it **owes you**, not something it owns. Whether a debit or credit grows or shrinks a balance depends on that balance's persisted direction, not account type alone.

So keep the two ideas apart:

* **Wallet thinking** asks: did *my* number go up or down?
* **Accounting thinking** asks: which account did this movement leave (**debit**), and which did it arrive in (**credit**)?

The accounting meaning is the reliable one, and it never changes: **a debit is the source, a credit is the destination**. Whether that raises or lowers a given balance is a *separate* question. The direction persisted on that balance answers it.

## Assets and liabilities: the two sides of the ledger

***

Each balance in a Ledger has a **direction**. That direction, not an account category alone, decides whether a debit or credit changes its available amount.

In Midaz, a balance direction is `debit` or `credit`:

* A balance with direction **`debit`** increases its available amount on a debit and decreases it on a credit.
* A balance with direction **`credit`** decreases its available amount on a debit. On a credit, Midaz repays the [overdraft](/en/products/midaz/balance-overdraft) in use first, and any remainder increases its available amount.

An account type can supply a default direction, but Midaz applies the direction persisted on the balance. For every **[asset](/en/products/midaz/assets)** you define (BRL, USD, a loyalty point), the Ledger automatically keeps an external account named after it (`@external/BRL`, `@external/USD`). You can also define your own named external accounts.

> [!NOTE]
>
> The same R\$100 is an **asset** in your wallet and a **liability** on the institution's Ledger. Both are right. They are the two sides of the same movement. [The outside world](/en/start-here/fundamentals/core-banking/external-accounts-and-reconciliation) follows the asset side across the boundary.

## Debits always equal credits

***

**Total debits always equal total credits**. Every movement is recorded on both sides at once: the same amount out of the source and into the destination. The two sides match exactly. If they don't, something is wrong, and the books say so.

Take that R\$100 payment. R\$100 leaves your account as a debit and R\$100 arrives in the merchant's account as a credit. One event makes two entries with equal totals:

```mermaid theme={null}
flowchart LR
    D["Your account<br/>DEBIT R$100"]:::debit
    C["Merchant account<br/>CREDIT R$100"]:::credit
    D --- BAL{{"Total debits R$100<br/>= Total credits R$100"}}:::bal
    C --- BAL
    classDef debit fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
    classDef credit fill:#fde68a,stroke:#d97706,color:#78350f
    classDef bal fill:#dcfce7,stroke:#16a34a,color:#14532d
```

The money didn't appear or vanish. It moved from one account to another, and the matching debit and credit prove it. This matching is the basis of **double-entry bookkeeping**, which records every movement twice, once as it leaves and once as it arrives.

> [!TIP]
>
> An **[operation](/en/products/midaz/operations)** is the smallest Midaz record of a balance effect. A non-pending transfer can produce a source debit and destination credit. Pending or canceled flows can also include `ON_HOLD` or `RELEASE` operations.

> [!NOTE]
>
> **See also in Core Banking**
>
> See what debit and credit mean from the ledger's side in [How money is recorded](/en/start-here/fundamentals/core-banking/double-entry-explained).

## Next steps

***

> [!NOTE]
>
> **Next up**
>
> Debits and credits only make sense as a pair. See how they work together in [Double-entry bookkeeping](/en/start-here/fundamentals/accounting/double-entry-bookkeeping).


# Double-entry bookkeeping
Source: https://docs.lerian.studio/en/start-here/fundamentals/accounting/double-entry-bookkeeping

Why every transaction touches two accounts so nothing gets lost or invented: the idea behind double-entry bookkeeping, with simple everyday examples.

**Double-entry bookkeeping** sounds technical, but you already understand the idea: **money never vanishes or appears. It always moves from somewhere to somewhere else.** Double-entry is the habit of recording *both* ends of that movement, every time.

## One event, two sides

***

Think about handing a friend \$10 for lunch. Two things happened at once: **your** wallet went down by \$10, and **their** wallet went up by \$10. One event, two effects.

Accounting insists you write down **both**. Every transaction touches **at least two accounts**: one giving, one receiving. That's why it's called *double*-entry. Equal value on the other side must match the **value** recorded on one side. The movement is not always physical cash, but the two amounts always agree.

So a transaction is **one event with two connected effects**, not a single line floating on its own. Recording both keeps everything in balance:

```mermaid theme={null}
flowchart LR
    A["One business<br/>event"]:::event --> B["Effect 1<br/>one account changes"]:::effect
    A --> C["Effect 2<br/>another account changes"]:::effect
    B --> D["Equal value<br/>on both sides"]:::equal
    C --> D
    D --> E["Books stay<br/>balanced"]:::balanced
    classDef event fill:#f3f4f6,stroke:#6b7280,color:#111827
    classDef effect fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
    classDef equal fill:#fde68a,stroke:#d97706,color:#78350f
    classDef balanced fill:#dcfce7,stroke:#16a34a,color:#14532d
```

This is the same balance rule from [debits and credits](/en/start-here/fundamentals/accounting/debits-and-credits): one account gets a debit, another gets a credit, and the two totals agree.

## Why bother recording it twice?

***

Recording both sides feels like extra work. It is also a lie detector.

* **Nothing gets lost.** If money left an account, it *must* show up somewhere else. You can't misplace it without the books refusing to balance.
* **Nothing gets invented.** Money can't appear out of thin air. For it to land somewhere, it had to come from somewhere.
* **Errors reveal themselves.** If the two sides don't match, you know instantly that something's wrong, before it becomes a real problem.

A single-entry list (just "money in, money out") can't do any of this. Double-entry turns the record into something you can **trust and prove**, which is why banks and ledger systems build on it.

## A simple example

***

**Paying rent, \$1,000 in cash:**

```mermaid theme={null}
flowchart LR
    Cash["Cash (an asset)<br/><b>− $1,000</b><br/><i>money left</i>"]:::cash
    Rent["Rent Expense<br/><b>+ $1,000</b><br/><i>where it went</i>"]:::rent
    Cash -->|"$1,000 moves"| Rent
    classDef cash fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
    classDef rent fill:#fee2e2,stroke:#dc2626,color:#7f1d1d
```

| Account | Effect |
| - | - |
| **Cash** (an asset) | Goes **down** \$1,000: money left |
| **Rent expense** | Goes **up** \$1,000: that's what the money was for |

The \$1,000 didn't disappear. It moved from your cash into the cost of rent: two accounts, one matched movement, a clear source and a clear destination.

Money coming *in* works the same way in reverse. Take a \$2,000 customer payment: **Cash** goes up, and **Revenue** goes up to record where it came from. You'll write both of these out properly (debit and credit, side by side) in [Journal entries](/en/start-here/fundamentals/accounting/journal-entries).

## How it keeps the equation balanced

***

Remember **Assets = Liabilities + Equity**? Double-entry is what keeps that equation true after every transaction. Because you record each event with equal and opposite effects, the two sides of the equation can never drift apart. The bookkeeping habit and the balancing rule are the same idea, viewed from two angles.

> [!NOTE]
>
> **See also in Core Banking**
>
> Core banking uses this same both-sides rule. See [How money is recorded](/en/start-here/fundamentals/core-banking/double-entry-explained).

## Next steps

***

> [!NOTE]
>
> **Next up**
>
> See how you write a transaction down, step by step, in [Journal entries](/en/start-here/fundamentals/accounting/journal-entries).


# Financial statements
Source: https://docs.lerian.studio/en/start-here/fundamentals/accounting/financial-statements

The three reports that summarize a business's money (the Balance Sheet, Income Statement, and Cash Flow Statement) and what each answers, in plain language.

All those carefully recorded transactions add up to **financial statements**. These are the summaries that turn thousands of tiny entries into a picture anyone can read. There are three main ones, and each answers a different question about the business.

You don't need to know how to build them, just what each one tells you.

## The three statements at a glance

***

| Statement | The question it answers | Think of it as |
| - | - | - |
| **Balance Sheet** | What do we own and owe *right now*? | A snapshot |
| **Income Statement** | Did we make a profit *over a period*? | A highlight reel |
| **Cash Flow Statement** | Where did the cash actually *move*? | A bank-account story |

## The Balance Sheet: a snapshot in time

***

The **Balance Sheet** is a photograph of the business at a single moment. It lists everything the company **owns** (assets), everything it **owes** (liabilities), and what's **left over for the owners** (equity). It's the [accounting equation](/en/start-here/fundamentals/accounting/assets-liabilities-equity) (*Assets = Liabilities + Equity*) printed as a report. If you want to know how healthy a business is *today*, this is where you look.

## The Income Statement: profit over time

***

The **Income Statement** (also called the *Profit & Loss* or *P\&L*) covers a stretch of time: a month, a quarter, a year. It starts with the **money earned** (revenue), subtracts the **money spent** (expenses), and shows whether the business ended up with a **profit or a loss**. Where the Balance Sheet is a snapshot, this is the story of what happened *between* two snapshots.

## The Cash Flow Statement: where the cash moved

***

The **Cash Flow Statement** tracks **cash and cash equivalents** (shortened to *cash* on this page) going in and out over a period. A business can look profitable on paper yet still run out of cash, for example if customers haven't paid their bills yet. Accrual accounting recognizes revenue when a business earns it, and expenses when the business incurs them, not when cash moves. Cash-flow reporting tracks whether the business has the liquidity to pay its bills.

## How they fit together

***

The three are views of the same reality:

```mermaid theme={null}
flowchart TD
    A["Income Statement<br/><i>Did we make a profit?</i>"]:::is --> B["Profit changes<br/>equity"]:::link
    D["Cash Flow Statement<br/><i>Where did cash move?</i>"]:::cf --> E["Cash balance<br/>changes"]:::link
    B --> C["Balance Sheet<br/><i>What do we own & owe now?</i>"]:::bs
    E --> C
    classDef is fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
    classDef cf fill:#fef3c7,stroke:#d97706,color:#78350f
    classDef bs fill:#dcfce7,stroke:#16a34a,color:#14532d
    classDef link fill:#f3f4f6,stroke:#6b7280,color:#111827
```

* The **Income Statement** shows whether you earned a profit.
* That profit flows into **equity** on the **Balance Sheet**.
* The **Cash Flow Statement** explains why the cash on that Balance Sheet went up or down.

Read together, they tell you whether a business is profitable, solid, and able to pay its bills. Anyone who lends money or makes a decision needs those three facts.

> [!NOTE]
>
> **See also in Core Banking**
>
> See how a ledger's records are proved against the outside world in [The outside world](/en/start-here/fundamentals/core-banking/external-accounts-and-reconciliation).

## Next steps

***

> [!NOTE]
>
> **Next up**
>
> See why profit and cash differ, and when each one enters the records, in [Accrual vs. cash accounting](/en/start-here/fundamentals/accounting/accrual-vs-cash).


# Journal entries
Source: https://docs.lerian.studio/en/start-here/fundamentals/accounting/journal-entries

How you record a transaction, step by step: from debits and credits to writing it down, with T-accounts and real examples like paying rent.

You've met [debits and credits](/en/start-here/fundamentals/accounting/debits-and-credits) and [double-entry](/en/start-here/fundamentals/accounting/double-entry-bookkeeping) as ideas. You write a transaction down as a **journal entry**, the basic unit of recording.

## What a journal entry is

***

A **journal entry** is the record of a single transaction. It names the accounts involved, gives the amount, and marks which side (debit or credit) each account is on.

Think of it as the sentence accounting uses to describe an event. Every entry has the same three parts:

* **Which accounts** are affected (at least two).
* **How much** the amount is.
* **Which side** each account sits on: debit (left) or credit (right).

And it follows one unbreakable rule you already know: **total debits must equal total credits**. If they don't, the entry is wrong before you've even finished writing it.

## The steps, every single time

***

Recording any transaction is the same short routine. Walk through it slowly the first few times and it becomes automatic.

1. **What happened?** Describe the event in plain words: "we paid rent," "a customer paid us."
2. **Which accounts does it touch?** Every event hits at least two. One gives, one receives.
3. **Does each account go up or down?** Decide the direction for each.
4. **Translate up/down into debit/credit.** Use the account type to know which side that means.
5. **Check the balance.** Debits on the left, credits on the right. The two totals must match.

```mermaid theme={null}
flowchart TD
    A["1 · What happened?"]:::step --> B["2 · Which accounts<br/>are affected?"]:::step
    B --> C["3 · Did each account<br/>go up or down?"]:::step
    C --> D["4 · Translate into<br/>debit or credit"]:::step
    D --> E["5 · Check:<br/>debits = credits"]:::check
    classDef step fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
    classDef check fill:#dcfce7,stroke:#16a34a,color:#14532d
```

Step 4 is the one that trips people up, so keep the cheat sheet from [debits and credits](/en/start-here/fundamentals/accounting/debits-and-credits) handy:

| Account type | To increase it | To decrease it |
| - | - | - |
| **Assets** (what you own) | Debit | Credit |
| **Liabilities** (what you owe) | Credit | Debit |
| **Equity** (what's yours) | Credit | Debit |
| **Revenue** (money earned) | Credit | Debit |
| **Expenses** (money spent) | Debit | Credit |

## T-accounts in practice

***

A **T-account** is a way to picture one account as a big letter **T**: debits on the left, credits on the right. A journal entry is what you get when you write down the matching halves of two (or more) T-accounts at once.

```
       Cash (an asset)              Rent expense
   -----------------------     -----------------------
   Debit (+)  |  Credit (-)    Debit (+)  |  Credit (-)
   -----------------------     -----------------------
              |   $1,000         $1,000   |
   -----------------------     -----------------------
```

The left side of one account lines up with the right side of another. That mirror is the entry.

## Example 1: paying rent in cash

***

**What happened:** the business paid \$1,000 for rent.

* It touches two accounts: **Cash** and **Rent expense**.
* **Cash** goes *down*: money left the business. Cash is an asset, so a decrease is a **credit**.
* **Rent expense** goes *up*: that's what the money was for. Expenses increase with a **debit**.

Written as a journal entry:

| Account | Debit | Credit |
| - | - | - |
| **Rent expense** | \$1,000 | |
| **Cash** | | \$1,000 |

Debits (\$1,000) equal credits (\$1,000). The entry balances. It reduces cash and recognizes rent expense for the period. Both effects are on the record.

## Example 2: receiving payment for a cash sale

***

**What happened:** a customer paid the business \$2,000 for a cash sale.

* It touches **Cash** and **Revenue**.
* **Cash** goes *up*: money arrived. Cash is an asset, so an increase is a **debit**.
* **Revenue** goes *up*: that's where the money came from. Revenue increases with a **credit**.

| Account | Debit | Credit |
| - | - | - |
| **Cash** | \$2,000 | |
| **Revenue** | | \$2,000 |

Again, debits equal credits, and the money has a clear source and destination. Cash was debited this time and credited last time. The same account moves in opposite directions, depending on whether money came in or went out. If the payment settles an earlier invoice, the credit is to Accounts Receivable rather than Revenue.

> [!NOTE]
>
> **See also in Core Banking**
>
> In a ledger system a journal entry becomes a transaction made of operations. See [How money moves](/en/start-here/fundamentals/core-banking/how-money-moves) and [The building blocks](/en/start-here/fundamentals/core-banking/building-blocks).

## Next steps

***

> [!NOTE]
>
> **Next up**
>
> Every entry posts to an account. See where that list of accounts comes from in the [Chart of accounts](/en/start-here/fundamentals/accounting/chart-of-accounts).


# Revenue, expenses & costs
Source: https://docs.lerian.studio/en/start-here/fundamentals/accounting/revenue-and-expenses

What revenue, expenses, and costs are, told apart in plain language: the words that drive the Income Statement and why the difference matters.

Two words show up everywhere in accounting: **revenue** and **expenses**. They're the money a business *earns* and the money it *spends*. Get these two straight and the [Income Statement](/en/start-here/fundamentals/accounting/financial-statements), the report that says whether you made a profit, reads like a simple subtraction.

## Revenue: the money you earn

***

**Revenue** is the amount a business earns from doing what it does: selling a product, providing a service, charging for a subscription. A business recognizes revenue when it earns it. That moment may differ from the moment cash arrives.

Picture a bakery. Every loaf it sells brings in revenue. Add up a day's sales and that total is the day's revenue. Everything else measures against that inflow.

Revenue is about what you earned, not necessarily the cash sitting in your account today. [Accrual vs. cash](/en/start-here/fundamentals/accounting/accrual-vs-cash) covers that difference. For now, think of revenue as *money earned from the work*.

## Expenses: the money you spend to earn it

***

An **expense** is a cost a business recognizes in a period to keep running and earn revenue: rent, salaries, electricity, flour for the bakery. It may or may not involve a cash payment in that same period.

Expenses are the fuel. You can't sell bread without buying flour and paying the baker. The point of accounting is to know what they are, so you can tell whether the revenue was worth it.

## Cost: close to expense, but not identical

***

People use **cost** and **expense** as if they mean the same thing, and in casual talk they nearly do. The distinction is small:

* A **cost** is what you *pay* for a resource: the price of acquiring it. Buying an oven for the bakery has a cost.
* An **expense** is a cost *counted against the revenue of a period*: the portion that's "used up" in earning this stretch's income. The flour baked into today's bread is an expense today.

A **cost** becomes an **expense** once it's used up in the work of earning revenue. The oven is a cost when you buy it. The slice of its wear-and-tear that helped make this month's bread becomes an expense this month.

| Term | Plain meaning | Bakery example |
| - | - | - |
| **Revenue** | Money earned from the work | Selling loaves |
| **Cost** | What you pay to acquire something | Buying the oven |
| **Expense** | A cost used up to earn this period's revenue | The flour baked today, the rent this month |

"Cost" leans toward *acquiring*, and "expense" leans toward *using up to earn revenue*. Follow one bag of flour through the bakery and the whole chain falls into place:

```mermaid theme={null}
flowchart LR
    A["Buy flour<br/><b>cost</b>"]:::cost --> B["Bake the bread<br/><b>expense</b>"]:::expense
    B --> C["Sell the bread<br/><b>revenue</b>"]:::revenue
    C --> D["Revenue − expenses<br/><b>profit or loss</b>"]:::profit
    classDef cost fill:#fef9c3,stroke:#ca8a04,color:#713f12
    classDef expense fill:#fed7aa,stroke:#ea580c,color:#7c2d12
    classDef revenue fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
    classDef profit fill:#dcfce7,stroke:#16a34a,color:#14532d
```

## Why they matter to the Income Statement

***

These two words are the entire engine of the [Income Statement](/en/start-here/fundamentals/accounting/financial-statements):

* Start with **revenue**: the amount recognized as earned.
* Subtract **expenses**: the costs recognized for that period.
* What's left is **profit** (or, if expenses were bigger, a **loss**).

A month at the bakery, in one line:

$$
\underbrace{\$1{,}000}_{revenue} - \underbrace{\$700}_{expenses} = \underbrace{\$300}_{profit}
$$

This is a simple view. Revenue minus expenses tells you whether the business reported profit or loss over a period. A full statement can group and present those amounts in more detail.

That profit flows into **equity**. Earn a profit and, before any distributions to owners, the owners' stake in the business grows. Run a loss and it shrinks on the same basis. This links back to [Assets, liabilities & equity](/en/start-here/fundamentals/accounting/assets-liabilities-equity): the Income Statement is the story of *how* equity changed over a period.

## Next steps

***

> [!NOTE]
>
> **Next up**
>
> See how you write down every change to the five account families in [Debits and credits](/en/start-here/fundamentals/accounting/debits-and-credits).


# What is accounting?
Source: https://docs.lerian.studio/en/start-here/fundamentals/accounting/what-is-accounting

The core idea behind accounting: a trustworthy record of money in, money out, and what a business owns versus what it owes.

**Accounting** is the practice of keeping a clear, honest record of a business's money. It covers everything of value the business owns or owes, cash on hand included. Think of it as a diary that answers three questions at any moment: what came in, what went out, and where do we stand right now.

A business wants to know what it owns, what it owes, and whether the two add up. Accounting is how it keeps that picture accurate, day after day.

## The three things every business tracks

***

Accounting watches three flows:

* **Money coming in**: sales, payments from customers, loans received, money the owners put in.
* **Money going out**: rent, salaries, supplies, loan repayments.
* **What's owned vs. what's owed**: the cash, equipment, and money others owe you, balanced against the debts you still have to pay.

A good record keeps these connected. If money moved, write it down. If something is owned or owed, account for it. Controls and reconciliation help identify missing or inconsistent records.

## Why it has to be trustworthy

***

Imagine running a shop where you *think* you have money but aren't sure. You can't pay suppliers with a guess, prove to a bank that you're worth lending to, or tell if you're making a profit.

Accounting uses records and controls to make financial information checkable. A balanced entry is an arithmetic check: it confirms the recorded sides match, but does not by itself prove authorization, classification, or completeness.

| Without good accounting | With good accounting |
| - | - |
| You guess how much you have | Your records show how much you have and why |
| Money can quietly go missing | Controls and reconciliation help catch missing records |
| You can't prove anything to others | Auditors and banks can verify it |
| Profit is a mystery | Profit is a number you can see |

> [!NOTE]
>
> **See also in Core Banking**
>
> Banking platforms exist to keep the same trustworthy-record promise. See [Core banking fundamentals](/en/start-here/fundamentals/core-banking/what-is-core-banking).

## Next steps

***

> [!NOTE]
>
> **Next up**
>
> See why accounting matters the moment software starts holding money in [Why accounting matters](/en/start-here/fundamentals/accounting/why-accounting-matters).


# Why accounting matters?
Source: https://docs.lerian.studio/en/start-here/fundamentals/accounting/why-accounting-matters

The "so what?" for builders: why double-entry is a system requirement, what balancing does and does not guarantee, and why financial systems rely on it.

You already know *what* accounting is: an honest record of money in, money out, and what's owned versus owed. That record matters for what you build: a ledger, a wallet, a payments flow, a banking platform. The moment software starts holding other people's money, it inherits accounting's rules whether it names them or not.

The same ideas that keep a shopkeeper's books honest keep your system from quietly losing or inventing a customer's balance.

## Money is a promise, and promises need a ledger

***

A balance in an app is a **promise**, not cash sitting in a box. The promise is a claim that some amount belongs to someone and can be moved or withdrawn. The only thing making that promise real is the record behind it. Lose the record, or let it drift, and the money effectively doesn't exist, or worse, exists twice.

That's why every financial product, underneath the UI, is a record-keeping problem first. Transfers, fees, settlement, and statements all sit on top of one question: who owns what, right now? Accounting is the discipline that has answered that question reliably for centuries.

## Why double-entry is a system requirement, not a convention

***

Imagine a customer moves \$50 from one wallet to another. If the first wallet goes down by \$50 *and* the second goes up by \$50, matching recorded totals let the system check its internal record of that transfer. If only one side gets recorded, the mismatch is a signal to investigate rather than proof that the business event was correct.

That's why double-entry exists. It gives a transaction a checkable constraint: the recorded sides must match.

Encode that as a rule and you get a consistency control:

* **A movement records its participating accounts.** The record identifies the accounts affected by the transaction.
* **The recorded sides must equal.** Matching totals make the entry arithmetically checkable.
* **A mismatch surfaces immediately.** If the recorded sides do not match, the transaction can be rejected before the inconsistency compounds.

Midaz applies this directly: it rejects a transaction when its resolved source, destination, and send totals differ. That check is valuable, but it does not prove authorization, account selection, classification, valuation, or complete business correctness.

## Balance is a consistency control

***

Balanced records make one part of a transaction continuously testable: the recorded amounts agree.

Matching debits and credits detects a recorded amount mismatch. In accounting, *Assets = Liabilities + Equity* is a statement-level equation, not a runtime assertion Midaz applies after each operation. Records can balance while an account is wrong, a transaction lacks authorization, a value has the wrong classification, or another required record does not exist.

Financial systems still rely on this control. Recording both sides gives balance a useful tripwire: when it breaks, the recorded amounts are inconsistent and the system must investigate before proceeding.

Balanced records keep the amounts behind a balance consistent. You still need reconciliation and separate controls to trust it fully:

```mermaid theme={null}
flowchart LR
    A["User sees<br/>a balance"]:::step --> B["System keeps<br/>ledger records"]:::step
    B --> C["Each movement<br/>has two sides"]:::step
    C --> D["Books stay<br/>balanced"]:::step
    D --> E["Recorded amounts<br/>are consistent"]:::trust
    classDef step fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
    classDef trust fill:#dcfce7,stroke:#16a34a,color:#14532d
```

## Financial systems are accounting systems wearing different clothes

***

Strip a core banking platform down to its foundation and you find a ledger. Strip the ledger down and you find double-entry accounting, enforced by code instead of by a clerk with a pen. The product vocabulary changes (*accounts*, *transactions*, *operations*, *balances*), but the same accounting ideas remain, now at scale and in real time.

That shapes what you build:

* **Accounting is the data model**. Accounts, entries, and balances are the app's source of truth.
* **The safety properties use accounting controls.** A balanced posting detects mismatched recorded amounts. Authorization, classification, and completeness require additional controls.
* **The hard problems come from accounting at scale**. You handle many transfers at once, keep every copy of the data in agreement, and prove what happened long after the fact. All of it comes down to keeping that balanced record correct across millions of movements.

Learn the accounting once and a lot of system design stops feeling arbitrary.

> [!NOTE]
>
> **See it in the product**
>
> These ideas have direct counterparts in Lerian and Midaz: accounts, transactions, operations, and balanced movements. See how they map in [Accounting in Lerian](/en/start-here/fundamentals/accounting/accounting-in-lerian), or step into the [Core banking fundamentals](/en/start-here/fundamentals/core-banking/what-is-core-banking).

## Next steps

***

> [!NOTE]
>
> **Next up**
>
> Start with [Assets, liabilities & equity](/en/start-here/fundamentals/accounting/assets-liabilities-equity), the equation everything rests on.


# The building blocks
Source: https://docs.lerian.studio/en/start-here/fundamentals/core-banking/building-blocks

The five core nouns of core banking (Organization, Ledger, Asset, Account, and Balance), each in one sentence, in the order they depend on each other.

Walk into a library and the structure is obvious before anyone explains it. There is the library itself, the catalog that organizes everything, and the shelves. There is also what sits on each shelf right now, and the *kind* of thing a shelf holds. A core banking system has five pieces that line up the same way.

You only need to see how each one rests on the one before it.

## They stack in order

***

Each block depends on the one above it: a shelf sits in a library, a balance sits in an account. Here they are, top to bottom.

* **Organization**: your company, the outer boundary of everything you run. The *library building itself*. All your records live inside it and belong to it.
* **Ledger**: one self-contained book of records. The *catalog*. You can keep more than one, say one per business line or per region. Each ledger keeps its own independent, balanced set of books.
* **Asset**: the *kind* of value you track, such as a currency like USD, loyalty points, or anything countable. The *category of thing on a shelf*. The system tracks the unit separately from the amount, so it knows that 100 of one thing isn't 100 of another.
* **Account**: a container tied to one asset. A non-external account can have one or more keyed balance records. An external account has exactly one `default` balance. A *single shelf*. Every movement of money has accounts on both sides.
* **Balance**: one keyed record of the amount an account holds, including available and held amounts. Each balance record has its own sending and receiving settings. What sits *on the shelf at this moment*.

> [!NOTE]
>
> An **Organization** can hold many **Ledgers**. A **Ledger** holds many **Accounts**. An **Account** always has one **Asset** and can carry one or more keyed **Balance** records. Read top to bottom, each block is the home of the next.

```mermaid mermaid theme={null}
flowchart TB
  O["Organization<br/>your company"]
  L["Ledger<br/>one book of records"]
  Acc["Account<br/>holds value, sends & receives"]
  Bal["Balance<br/>the amount held right now"]
  As["Asset<br/>the kind of value"]
  O --> L
  L --> Acc
  Acc --> Bal
  As -.-|"defines the unit"| Acc
  classDef box fill:#e8f0fe,stroke:#4285f4,color:#333;
  classDef bal fill:#fff8e1,stroke:#f4b400,color:#333;
  class O,L,Acc,As box;
  class Bal bal;
```

## A balance is a result, not a setting

***

A **balance** is the **result** of every movement into and out of the account, added up. You do not type it in or adjust it by hand. Money arrives, money leaves, and the balance is where that leaves you.

You cannot edit a balance directly, so the books stay trustworthy. Recorded movements with two sides each *move it into the shape it has*.

> [!TIP]
>
> A balance isn't always one single number you can spend. Part of it can be **available** (yours to use now) while part is **held**, set aside for a movement that hasn't finished.

## Next steps

***

> [!NOTE]
>
> **See it in Lerian**
>
> See the building blocks in practice: [Core entities](/en/products/midaz/core-entities), [Ledgers](/en/products/midaz/ledgers), [Accounts](/en/products/midaz/accounts), [Balances](/en/products/midaz/balances), and [Assets](/en/products/midaz/assets).


# Designing your ledger plan
Source: https://docs.lerian.studio/en/start-here/fundamentals/core-banking/designing-your-ledger-plan

How to model your own business as a set of accounts: a simple, worksheet-style method for designing a chart of accounts before you build anything.

By now you know the pieces: accounts, balances, movements, the rules that govern them. Now you put them to work on *your* business. The goal is to move from "I understand the terms" to "I can model what my company does".

A **ledger plan** (sometimes called a **chart of accounts**) is a *deliberate classification* of the accounts your business needs, and how they relate. It is not a list of accounts you rush to create. Designing it well, up front, saves you from painful restructuring later.

## Think rooms before you build

***

Imagine designing a house. Before you pour any concrete, you decide what each room is for (kitchen, bedroom, office) and who's allowed in. You don't start laying bricks and figure out the floor plan afterward.

A ledger plan works the same way. You decide what each account is *for*, what rules it follows, and how money flows between rooms, before you create anything. The four steps below are that method.

## Step 1: List your real-world actors

***

Start away from the software entirely. On paper, list every real-world party that touches money in your business. Don't worry about structure yet. Just name them.

A typical list looks like this:

* **Customers**: the people or companies who hold value with you
* **Treasury**: your own operating funds
* **Revenue**: money you earn
* **Fees**: charges you collect on movements
* **Settlement**: money in transit to or from the outside world
* **Expenses**: money you pay out

This is your raw material. Every business has its own version of this list.

## Step 2: Decide what needs its own truth

***

Not every actor needs its own account. The test is simple: **does this thing need its own separate, trustworthy balance, its own truth?**

If you need to know, at any moment, exactly how much value sits with this actor, it needs its own account. If it's just a label or a detail of something else, it doesn't.

> [!TIP]
>
> As a rule of thumb, if you'd ever want to ask "how much is in *here* right now?" then that's an account. If two things should never share a balance, they should never share an account.

## Step 3: Classify and group with three questions

***

For each account you kept, ask **three universal questions**. Together they tell you how to structure and group your accounts.

| Ask yourself | What it's about |
| - | - |
| Do these accounts need a **rule that validates** what they are or how they behave? | Classification: enforcing that an account is a certain *kind*, with its own constraints. |
| Do I need to **slice them for reporting**? | Labeling: tagging accounts so you can later filter and report by group (region, tier, department). |
| Do I need to **group them operationally** around a customer or wallet? | Operational grouping: bundling several accounts that belong together for one owner. |

These three questions are independent. An account might need all three, or just one. Keep them separate in your mind:

```mermaid mermaid theme={null}
flowchart TD
  A["An account in your plan"] --> Q1{"Needs a rule that<br/>validates its kind?"}
  Q1 -->|yes| C["Give it a classification"]
  A --> Q2{"Needs to be sliced<br/>for reporting?"}
  Q2 -->|yes| L["Give it a reporting label"]
  A --> Q3{"Belongs to a customer<br/>or wallet group?"}
  Q3 -->|yes| G["Put it in an operational group"]
  classDef q fill:#fff8e1,stroke:#f4b400,color:#333;
  class Q1,Q2,Q3 q;
```

The big mistake here is to collapse these three into one. A *classification* controls what kind an account can be. A *reporting slice* is how you group an account in a report. An *operational group* is which accounts belong to one customer. Each is different, and treating them as one tangled thing is how ledger plans become unmanageable.

## Step 4: Sketch the movements

***

Finally, draw the arrows. For each kind of movement your business makes, sketch which account is the source and which is the destination. That sketch is the input you'll need when you later define reusable rules for those movements.

## A worked example: a simple wallet business

***

Say you run a wallet app. Customers load money in, send it to each other, and you take a small fee on transfers. Walk the method:

**Actors:** customers, your fee/revenue account, and a settlement account for money entering from the outside world.

**Own truth?** Each customer wallet needs its own balance. So do the fees you collect. So does settlement, which mirrors the outside world.

**Three questions:**

* *Validation?* Customer wallets behave differently from your fee account, so they're a different **kind**. Classify them.
* *Reporting slice?* You want to report customers by country, so add a **label** for region.
* *Operational group?* A premium customer might hold several wallets, so **group** them together.

**Movements:** a transfer moves value from one customer wallet to another, plus a small part into the fee account. Money entering the app moves from settlement into a customer wallet.

```mermaid mermaid theme={null}
flowchart LR
  S["Settlement<br/>(outside world)"] -->|load| C1["Customer wallet A"]
  C1 -->|transfer| C2["Customer wallet B"]
  C1 -->|fee part| F["Fee / revenue"]
  classDef bal fill:#fff8e1,stroke:#f4b400,color:#333;
  class C1,C2,F,S bal;
```

That's a complete ledger plan for a small business, sketched before touching any tool.

## Common first-timer mistakes

***

* **Over-classifying.** Creating a dozen account kinds when two would do. Start coarse. Refine only when a real rule demands it.
* **Mixing reporting into structure.** Don't bake a reporting slice (like "region") into an account's *kind*. Keep how you classify separate from how you report.
* **Treating the plan as a list.** Rushing to create accounts before sketching movements leaves you reorganizing later.
* **Skipping the "own truth" test.** Giving everything its own account, or cramming unrelated things into one, both cause pain.

## Next steps

***

> [!NOTE]
>
> **See it in Lerian**
>
> Those three questions map onto how Lerian models accounts:
>
> * *Validation rule?* → **Account Types**
> * *Reporting slice?* → **Segments**
> * *Operational grouping?* → **Portfolios**
>
> See it all together in [Accounting in Midaz](/en/products/midaz/accounting-in-midaz), then put your plan to work with the console [Setup path](/en/products/midaz/console/midaz-console-setup-path) and [Concepts map](/en/products/midaz/console/midaz-console-concepts-map).


# How money is recorded
Source: https://docs.lerian.studio/en/start-here/fundamentals/core-banking/double-entry-explained

Why every movement of money has two sides, what debit and credit mean in a ledger, and how double-entry keeps every transaction balanced and auditable.

If you've ever looked at a banking system and felt lost the moment someone said "debit" and "credit", start here. You don't need an accounting background. You need one idea, and once it clicks, almost everything else in core banking falls into place.

**Money never appears out of nowhere, and it never vanishes.** Every time money moves, it leaves one place and arrives at another. Recording *both* sides of that movement is the whole idea behind **double-entry accounting**.

## Money always comes from somewhere

***

Think about pouring water between two buckets. The water that leaves the first bucket is exactly the water that fills the second. Nothing appears or disappears. It only changes place. You can always check that the amounts match.

A core banking system records money the same way. Every movement has two parts:

* **Where it came from**: the source
* **Where it went**: the destination

If a customer sends R\$100 to a merchant, the system doesn't just say "the merchant has R\$100 more". It records the *full story*: R\$100 **left** the customer and R\$100 **arrived** at the merchant. Two sides of one movement, always equal.

> [!NOTE]
>
> It's called double-entry because the system records every movement on both sides, once as it leaves and once as it arrives. A single-sided record makes mismatches harder to detect. Recording both sides gives the system an arithmetic constraint to check.

## The two sides have names: debit and credit

***

The two sides of a movement have traditional names. In this movement, they describe the recorded source and destination:

* A **debit** is the entry on the account that money moves **out of**.
* A **credit** is the entry on the account that money moves **into**.

When the customer pays the merchant, the system records a **debit** on the customer's side and a **credit** on the merchant's side. Same amount, opposite directions. In accounting more broadly, debit and credit are sides of an entry. Whether either increases or decreases a balance depends on the account type and its configured direction.

You'll sometimes see debit and credit described as "decrease" and "increase", but that's not always true. It depends on the kind of account. For the transfer shown here, **debit is the source and credit is the destination**. Don't treat that example as a universal rule for every account type.

## Why both sides are always required

***

Because the system records every movement on both sides, the totals always have to match. The sum of everything that left equals the sum of everything that arrived. If they don't balance, something is wrong. The system won't let the movement through.

```mermaid theme={null}
flowchart LR
  A["Customer account<br/>(source)"] -->|"– R$100 · debit"| T(("Movement<br/>R$100"))
  T -->|"+ R$100 · credit"| B["Merchant account<br/>(destination)"]
  classDef bal fill:#fff8e1,stroke:#f4b400,color:#333;
  class A,B bal;
```

This rule (*the two sides must balance*) is a consistency control. Midaz validates that the source total, the destination total, and the sent value all match. This check catches a recorded amount mismatch, but it does not by itself prove authorization, classification, or completeness. You can still trace every recorded movement to its source and destination.

> [!TIP]
>
> Each individual part of a movement, a single debit or a single credit, is an **operation**. A movement of money consists of operations that balance out.

## Next steps

***

> [!NOTE]
>
> **See it in Lerian**
>
> See these ideas in practice: [Transactions](/en/products/midaz/transactions) and the [Glossary](/en/start-here/glossary).


# The outside world
Source: https://docs.lerian.studio/en/start-here/fundamentals/core-banking/external-accounts-and-reconciliation

The doorway between your Ledger and the outside world: how external accounts work and how reconciliation proves your records match reality across systems.

Everything so far has lived neatly inside your Ledger. But money doesn't stay inside. It arrives from banks, card networks, and other systems, and it leaves to them too. Two ideas explain how a self-contained Ledger connects to the world outside, and how you *prove* your records still match what really happened out there.

Picture a building with a single front door. Everyone and everything coming in or going out passes through it. The door doesn't store anything itself. It just marks the boundary between inside and outside. Your Ledger has a door like this.

## External accounts: the doorway to the outside

***

An **external account** is the doorway between your Ledger and the world beyond it: banks, card networks, other systems. Money entering your Ledger comes *from* an external account. Money leaving goes *to* one. Every crossing of your boundary passes through it.

In Midaz, the default external account has `debit` direction. When R\$100 flows *in* to a customer, Midaz uses that external account as the source. Its debit increases the available amount and balances the credit on the receiving account. The direction does not mean the external account has a negative balance.

> [!NOTE]
>
> Think of the building's front door again. The external account is that door. Its direction tells Midaz how to apply a debit or credit. It does not label a balance as missing money.

```mermaid mermaid theme={null}
flowchart LR
  E["External account<br/>(the doorway)"] -->|"+ R$100 in"| A["Customer account<br/>(inside the Ledger)"]
  classDef bal fill:#fff8e1,stroke:#f4b400,color:#333;
  class A bal;
  classDef ext fill:#eef2ff,stroke:#6366f1,color:#333;
  class E ext;
```

## Reconciliation: proving the books match reality

***

Once you have a boundary, you need to check that what you recorded inside matches what the outside world recorded. That check is **reconciliation**: proving your internal records line up with external records (bank statements, processor reports, settlement files).

You compare the two, line by line, and confirm they agree. When they don't, reconciliation is how you catch it:

* **Missing** movements: something happened outside that your Ledger never recorded.
* **Duplicated** movements: the same thing recorded twice.
* **Mismatched** movements: amounts or details that don't line up.

The timing depends on your business: some reconcile **continuously** as records arrive, others at the **end of each day**. Either way, the moment you connect to the outside world, you take on the job of proving the two sides still agree.

> [!NOTE]
>
> Reconciliation is like **counting the till against the receipts** at the end of a shift. The cash drawer is your Ledger. The receipts are the outside record. Counting them against each other proves the books match what happened, and flags anything that doesn't.

## Next steps

***

> [!NOTE]
>
> **See it in Lerian**
>
> See these ideas in practice: [Transactions](/en/products/midaz/transactions) and the [Glossary](/en/start-here/glossary).


# Account roles: Holders, Accounts, Aliases & Instruments
Source: https://docs.lerian.studio/en/start-here/fundamentals/core-banking/holders-accounts-aliases

Understand the distinct roles of Holders, Ledger Accounts, account aliases, and CRM Instruments in Midaz.

Midaz keeps the balance record, the party context, and the identifiers used to find an account separate. That separation makes each concern explicit.

## Accounts hold balances and movements

An **Account** is the Ledger record that holds balances and receives movements. It is the transactional record.

## Holders represent people or companies

A **Holder** is the CRM record for a person or company. A Holder supplies the party context that can be associated with Ledger Accounts.

## Aliases identify Accounts

An **alias** is a friendly identifier for an Account. It helps people and systems refer to an Account without using its full identifier.

## Instruments associate CRM context with Accounts

An **Instrument** is the CRM record that associates a Holder with a Ledger Account. It carries the `ledgerId` and `accountId` for that association and can hold banking details, regulatory fields, metadata, and related parties.

An Instrument is not an alias. An alias identifies an Account. An Instrument associates Holder and CRM context with a Ledger Account.

```mermaid theme={null}
flowchart LR
  H["Holder<br/>(person or company)"] --> I["Instrument<br/>(CRM context)"]
  I --> ACC["Account<br/>(balance and movements)"]
  AL["Alias<br/>(friendly identifier)"] -.identifies.-> ACC
  classDef bal fill:#fff8e1,stroke:#f4b400,color:#333;
  class ACC bal;
```

## Next steps

> [!NOTE]
>
> **See it in Lerian**
>
> Explore [Accounts](/en/products/midaz/accounts) and [Instruments](/en/products/midaz/crm/alias-accounts).


# How money moves
Source: https://docs.lerian.studio/en/start-here/fundamentals/core-banking/how-money-moves

What counts as one movement of money, what its parts are called (transactions, operations, and holds), and where money sits before it finally settles.

You already know that money never appears or vanishes. It moves from a source to a destination, and both sides get recorded. Now for the *movement* itself: what one complete movement is, the names of its pieces, and where the money sits before a movement finishes.

Picture handing cash across a counter. The moment the cash leaves your hand and lands in the other person's, the whole exchange happened as one event. A banking system treats movement the same way, as one complete handover recorded in full at once.

## One movement, recorded in full

***

A **transaction** is one complete movement of value: the whole event, start to finish. When a customer sends R\$100 to a merchant, that single transaction *is* the R\$100 changing hands.

But you've already seen that every movement has two sides. So a transaction has smaller pieces:

* An **operation** is one part of the movement: a single debit or a single credit.

The R\$100 transfer is one transaction with two operations. One is a debit of R\$100 that leaves the customer. The other is a credit of R\$100 that arrives at the merchant. The two operations move the same amount in opposite directions, and the system records them together.

> [!TIP]
>
> An operation is one part of a movement. A transaction is the whole movement.

## The shapes a movement can take

***

The simplest movement has one source and one destination, but a single transaction can spread across more accounts. However many parts it has, it always balances. The common shapes:

* **One-to-one**: one source, one destination. A plain transfer: customer out, merchant in.
* **One-to-many**: one source, several destinations. The customer pays R\$103: R\$100 goes to the merchant and R\$3 to a fee account. Three operations, still balanced (R\$103 out = R\$100 + R\$3 in).
* **Many-to-one**: several sources, one destination. A few accounts pooling money into a single fund.
* **Many-to-many**: several sources and several destinations at once, like a marketplace splitting incoming payments across sellers and fees.

The rule never changes, no matter how many parts there are. Everything that leaves must equal everything that arrives.

> [!NOTE]
>
> Not every ledger supports all four shapes. Simpler systems may allow only one-to-one (or one-to-many) movements, while others handle the full many-to-many case in a single transaction. What's possible depends on the ledger you use.

> [!NOTE]
>
> A transaction is **all-or-nothing**. Either every operation succeeds together, or none of them happen. The books never stay half-recorded. The name for this property is **atomicity**.

## Money in transit: holds and two-phase movements

***

Many movements don't settle the instant they start. The system first **reserves** the amount: it's set aside, still in the account, but no longer free to spend. Then the transaction either **commits** (settles for good) or **cancels** (releases the reservation). This is a **two-phase** movement: reserve first, then commit or cancel.

An account's money has two parts:

* **Available balance**: what you can spend right now.
* **Held balance**: what's reserved for a movement that hasn't finished. It is still yours, frozen in place until it settles or releases.

> [!NOTE]
>
> Think of a hotel pre-authorization on your card. At check-in the hotel **reserves** an amount. It isn't gone, but you can't spend it. At check-out the charge **commits**, or the hold is **canceled** and the money frees up.

```mermaid mermaid theme={null}
flowchart LR
  R["Reserve<br/>amount held"] -->|"settles"| C["Commit<br/>moves to destination"]
  R -->|"released"| X["Cancel<br/>returns to available"]
  classDef bal fill:#fff8e1,stroke:#f4b400,color:#333;
  class R,C,X bal;
```

## Spending control

***

Once you can see money as *available* versus *held*, controlling spending becomes natural. At any moment, an account's money sits in one of three states:

* **Available**: free to spend.
* **Held**: reserved for a movement in progress (in transit).
* **Blocked**: frozen on purpose, set aside so it can't move at all.

On top of that, **limits** can cap movement. A limit sets a ceiling on how much can flow. Together, these answer a common question about why an account can't spend. Usually the reason is a hold, a block, or a limit, not missing money.

## Next steps

***

> [!NOTE]
>
> **See it in Lerian**
>
> See these ideas in practice: [Transactions](/en/products/midaz/transactions), [Operations](/en/products/midaz/operations), and [Balances](/en/products/midaz/balances).


# The rules that govern movement
Source: https://docs.lerian.studio/en/start-here/fundamentals/core-banking/routes-and-fees

The reusable transaction routes that keep each kind of money movement recorded correctly, and why a fee is just a few more operations on the same journey.

You know how money moves and how it's recorded. But who decides the *rules*? When a payment happens, something has to check that the right kinds of accounts take part. It must also record the right parts the same way every time. And when a fee shows up, where does it come from?

Think of a paper form built for one kind of request. Someone designed it once: the boxes it has, the line for who's allowed to sign, the rule for how it's filed. After that, any clerk just fills in the details, and every request of that kind comes out identical, with no guessing. That's the idea behind a route. You set the rule once, and it applies the same way every time.

## A route is a reusable rule for one kind of movement

***

A **route** is a reusable rule for one *kind* of movement. It answers three questions, once, so you don't answer them again on every transaction:

* **Who can be the source?** Which accounts may send.
* **Who can be the destination?** Which accounts may receive.
* **Which parts belong in the record?** Which debits and credits the movement should produce.

Define the rule once. When a Ledger has route validation enabled, it checks transactions of that kind against the route. A "customer payment" route spells out that a customer account sends, a merchant account receives, and exactly which operations to write.

When a Ledger has route validation enabled, it checks the record of each movement of that kind against the rule. It also checks that the participating accounts are valid for it. Without that setting, a route is still a reusable definition but does not enforce those checks.

> [!NOTE]
>
> A route is like a **form template** for one kind of transaction. It lays out the intended participants and booking. When a Ledger has route validation enabled, it checks movements against the route. A fee is just an extra line on that form.

## Fees are more operations

***

A transaction consists of **operations**, each one a single debit or credit. A fee is *more operations* in the same transaction, sending value into a fee or revenue account.

Take the one-to-many example from before. A customer pays **R\$103**:

* **R\$100** lands at the **merchant**.
* **R\$3** lands in a **fee account**.

That's one transaction with three operations. The customer's R\$103 leaving balances exactly against R\$100 + R\$3 arriving. No value appears and no value disappears. The fee is real money that moves to a real account, recorded like any other part.

```mermaid mermaid theme={null}
flowchart LR
  C["Customer<br/>– R$103"] --> R{{"Route<br/>(rule + parts)"}}
  R -->|"+ R$100"| M["Merchant"]
  R -->|"+ R$3"| F["Fee account"]
  classDef bal fill:#fff8e1,stroke:#f4b400,color:#333;
  class M,F bal;
```

## When you'd reach for routes and fees

***

You don't need a route for a one-off movement. You reach for one when a *kind* of movement repeats and you must book it the same way every time: payments, transfers, settlements. And you add a **fee** whenever a movement should also send a slice of value into a revenue or cost account. You define these deliberately up front, as part of the ledger plan that comes next.

## Next steps

***

> [!NOTE]
>
> **See it in Lerian**
>
> See these ideas in practice: [Accounting Routes entities](/en/products/midaz/transaction-routing-entities) and the [Fees Engine](/en/products/midaz/fees/fees-engine-overview).


# What is core banking?
Source: https://docs.lerian.studio/en/start-here/fundamentals/core-banking/what-is-core-banking

A plain definition of core banking, what it manages (accounts, balances, transactions), and the five responsibilities we use to explain a modern core system.

A **core banking system** is the central platform a financial institution runs on. It manages **accounts, balances, transactions, the customers behind them, and money moving in and out**, all in one place, as a single source of truth.

Underneath all of it sits a trustworthy record of **who owns what** and **what moved**. The other jobs all connect to it by feeding it, moving value through it, reading it, and proving it's right. Because of that record, money can never be quietly lost or invented.

## Why it's harder than it looks

***

Keeping that record right is deceptively hard, and it's the reason most of the system exists:

* **It must always balance**: money can't appear or disappear, ever.
* **It has to stay correct at scale**: millions of movements, all consistent with each other.
* **It must be provable**: to auditors and regulators, long after the fact.

## How we'll explain it: five jobs

***

There are many ways to describe a core banking platform. In this guide we use **five core responsibilities**. This is how we organize the topic for learning, not an official taxonomy.

| Job | What it does |
| - | - |
| **Record value** | Keeps the trustworthy record of who owns what, balanced so nothing is lost or invented. Everything else builds on this. |
| **Move value** | Brings money in, sends it out, and transfers it between accounts. |
| **Identify** | Registers the people and companies behind the accounts. |
| **Report** | Turns the raw record into statements and reports that you and regulators can read. |
| **Trace & prove** | Keeps an auditable trail of everything that happened. |

The **Ledger** is the foundation, but it's only **one of the five**. A complete core banking system is all five of them together, not a Ledger with extras bolted on. The other four build on the Ledger once it records value. Capabilities like **fees** attach to it to extend it.

You adopt these pieces one at a time, not as a single machine you switch on. The same handful of ideas (accounts, balances, movements) run through all of them. Learn those once, here, and the rest of the documentation gets much easier to follow.

## Next steps

***

> [!NOTE]
>
> **See it in Lerian**
>
> See how these jobs map to real solutions in the [Core banking vision](/en/start-here/about-lerian/core-banking-vision) and [Products and plugins](/en/products/products-and-plugins).


# Where to go next
Source: https://docs.lerian.studio/en/start-here/fundamentals/core-banking/where-to-go-next

How everything you learned about core banking shows up in Lerian and Midaz, and where to go next to start building, integrating, and running transactions.

You've gone from "lost the moment someone said debit and credit" to modeling your own business as a ledger plan. That's the whole foundation. Next, see how it shows up in Lerian and where to start.

## How the concepts show up in Lerian

***

Everything you just learned has a home in Lerian:

* **Recording value**: the accounts, balances, and assets you learned about, and the double-entry that keeps them in check, all live in [Midaz](/en/products/midaz/what-is-midaz), the Ledger. It's the foundation everything else builds on.
* **Moving value**: Midaz records transfers, operations, and holds as [transactions](/en/products/midaz/transactions). When value crosses the boundary with the outside world, [payment interfaces](/en/interfaces/introduction) such as Pix and TED carry it. Plenty of movement never crosses that boundary, and the Ledger records it. The routes and fees you saw come from Midaz's [transaction routing](/en/products/midaz/transaction-routing-entities) and the [Fees Engine](/en/products/midaz/fees/fees-engine-overview).
* **Identifying who owns what**: the holders behind your accounts live in [CRM](/en/products/midaz/crm/crm-overview).
* **Reading the record back**: you build [account statements](/en/products/midaz/building-account-statements) from Midaz operations, and [Reporter](/en/products/reporter/what-is-reporter) builds richer reports and templates for audits, analytics, and decisions.
* **Deciding what may happen**: [Tracer](/en/products/tracer/what-is-tracer) evaluates your rules and spending limits. It returns an allow, deny, or review decision before a transaction executes.

And when you design your own ledger plan, the three questions (validation, reporting slice, operational grouping) map to **Account Types, Segments, and Portfolios** in Midaz.

## Ready to start?

***

Pick the path that fits your team:

> **[Build with the API](/en/start-here/getting-started)**
>
> Integrate programmatically. Start here, then go deeper with the Guides and API Reference for the integration details.

> **[Set it up in the Console](/en/platform/console/about-lerian-console)**
>
> Prefer a UI? Do the whole setup by hand in the Lerian Console, no code required.

> [!NOTE]
>
> Need a term? The [Glossary](/en/start-here/glossary) defines every word from this section. Keep it bookmarked, and see how the pieces come together in [Building a complete core banking](/en/products/building-a-complete-core-banking).


# Where to start
Source: https://docs.lerian.studio/en/start-here/fundamentals/introduction

A quick map of the Fundamentals section of Start Here: two plain-language series, Core Banking and Accounting, and which one to read first.

The **Fundamentals** section of Start Here is where you build intuition before touching anything Lerian-specific. It holds two short, plain-language series that build a foundation for core banking from two angles. Accounting explains trustworthy financial records. Core Banking explains how a complete banking platform applies them.

> **[Accounting](/en/start-here/fundamentals/accounting/what-is-accounting)**
>
> Explains the language underneath it: assets, liabilities, debits, credits, and how the books stay balanced.

> **[Core Banking](/en/start-here/fundamentals/core-banking/what-is-core-banking)**
>
> Explains a complete core banking platform: its ledger foundation, accounts, balances, value movement, customer identity, reporting, and auditability.

They sit side by side because they answer different questions. Core Banking shows you the *machine*. Accounting shows you the *grammar* behind it.

## Which one first

***

| If you want to… | Start with |
| - | - |
| Understand how a complete core banking platform works, including its ledger foundation | **Core Banking** |
| Understand the accounting language behind it | **Accounting** |
| Understand both | **Accounting**, then **Core Banking** |

> [!TIP]
>
> If you're unsure, start with **Accounting**. The vocabulary it teaches makes everything in Core Banking (and the rest of the docs) easier to follow.


# Getting started
Source: https://docs.lerian.studio/en/start-here/getting-started

Begin with Lerian: evaluate the platform, choose a deployment model, and run your first double-entry transaction with Midaz.

Use this page to evaluate the platform or to start building.

> [!NOTE]
>
> **New to core banking?** If terms like *Ledger*, *debit and credit*, or *chart of accounts* aren't yet second nature, start with the fundamentals first. They make everything here easier to follow.
>
> **[Begin with Core Banking Fundamentals](/en/start-here/fundamentals/core-banking/what-is-core-banking)**

## Evaluating the platform

***

Follow these steps to understand the platform's capabilities, architecture, and deployment options.

**1. Understand why Lerian exists**

Learn what problems the platform solves and who we built it for, in business terms.

**[Why Lerian →](/en/start-here/about-lerian/why-lerian)**

**2. Explore the architecture**

Lerian organizes around four pillars (**Ledger**, **Transactional Services**, **Governance**, and **Connectivity**) that form a composable financial platform.

**[Read the Core Banking vision →](/en/start-here/about-lerian/core-banking-vision)**

**3. Choose a deployment model**

Decide between Lerian Cloud (SaaS), fully managed by Lerian, or self-hosted BYOC based on your compliance requirements and operational maturity.

**[Compare deployment models →](/en/start-here/evaluate-and-deploy/deployment-models)**

**4. See it in action**

Explore real-world use cases: digital banking, global portfolios, Pix, and more.

**[Browse use cases →](/en/products/midaz/use-cases)**

## Building with Lerian

***

Follow these steps to go from zero to your first double-entry transaction. Choose the path that matches your deployment model.

**SaaS (Lerian Cloud)**

**1. Receive your credentials**

Your Lerian onboarding team provides you with API credentials (client ID and secret) and the base URL for your environment.

**2. Authenticate and get your token**

Use the Access Manager Auth API to exchange your credentials for a JWT access token. This token contains your tenant context. You don't need to manage a tenant ID explicitly.

**[Learn how to authenticate →](/en/platform/access-manager/using-access-manager)**

**3. Make your first API call**

Include the token as a Bearer token in the `Authorization` header of every request. Your calls are automatically scoped to your tenant.

**[Make your first API call →](/en/reference/products/midaz/quick-start-guide)**

**4. Create your first organization**

Follow the same API flow as any Midaz deployment: create an organization, a ledger, assets, and accounts.

**[Follow the recommended workflow →](/en/products/midaz/recommended-workflow)**

> [!TIP]
>
> The API surface is identical across deployment models. Lerian Cloud requires a Bearer token and scopes requests to the authenticated tenant. A permitted non-production BYOC deployment can have authentication disabled.

**BYOC (self-hosted)**

**1. Choose your deployment model**

Decide how you want to run the platform. BYOC gives you full control over data, security, and networking, in your own cloud or on-premises.

**[Compare deployment models →](/en/start-here/evaluate-and-deploy/deployment-models)**

**2. Understand the architecture**

Lerian organizes around four pillars (**Ledger**, **Transactional Services**, **Governance**, and **Connectivity**) that form a composable financial platform. Understanding this helps you model integrations correctly from day one.

**[Read the Core Banking vision →](/en/start-here/about-lerian/core-banking-vision)**

**3. Install Midaz**

Midaz is Lerian's double-entry core ledger. Install it when you need to model accounts and record transactions. The other products stay modular, and you can adopt them one at a time.

**[Install Midaz →](/en/products/midaz/midaz-setup)**

**4. Create your first resources through the API**

With Midaz running, create the essential building blocks: an organization, a Ledger, assets, and accounts.

**[Make your first API call →](/en/reference/products/midaz/quick-start-guide)**

**5. Follow the recommended workflow**

Follow the end-to-end operational workflow, from resource setup to transaction routing and balance management.

**[Follow the recommended workflow →](/en/products/midaz/recommended-workflow)**

## What's next?

***

With your Ledger running and your first transactions created, pick the capability you want to add next.

> **[Reconcile transactions](/en/products/matcher/getting-started/matcher-quick-start)**
>
> Run your first automated reconciliation between a bank statement and your Ledger.

> **[Validate in real time](/en/products/tracer/getting-started)**
>
> Set up spending limits and validation rules to evaluate transactions before they proceed and return an ALLOW, DENY, or REVIEW decision for your authorization flow to act on.

> **[Generate reports](/en/products/reporter/using-reporter)**
>
> Create a report template and generate your first financial report from a configured data source. For Midaz data, connect Reporter to Midaz first.

> **[Integration diagrams](/en/diagrams/introduction)**
>
> Learn how the integration diagrams will show the messages of a Brazil rail combining into a journey.


# Glossary
Source: https://docs.lerian.studio/en/start-here/glossary

Key financial, ledger, and platform terms explained for non-technical audiences, a quick reference for language used across Lerian and Midaz docs.

This glossary defines the core financial and platform terms used throughout Lerian's documentation. It helps product managers, sales teams, and anyone new to financial infrastructure quickly understand the language used in our guides.

***

## A

***

### Account

The fundamental unit of value storage in a ledger. An account holds a balance denominated in a specific asset (e.g., BRL, USD). Accounts can represent account holders' accounts, internal settlement accounts, fee collection accounts, or any other container for tracking value.

### Account Type

A classification that defines the nature and purpose of an account, such as checking, savings, escrow, or settlement. Account types enable proper transaction routing and consistent business rules across account categories.

### Asset

A unit of value tracked in the ledger. Assets can be traditional currencies (BRL, USD, EUR), digital currencies (BTC, ETH), or custom units like loyalty points or academic credits. Every account links to exactly one asset.

### Atomic (Atomicity)

A property of transactions where all operations either succeed together or fail together. There is no partial execution. If a transaction involves three operations (a debit, a credit, and a fee), either all three happen or none do. This prevents incomplete financial events.

### Audit trail

A chronological record of every action and transaction in the system. Audit trails are immutable. Once recorded, an audit trail cannot change or be deleted. Regulatory compliance and dispute resolution require this.

***

## B

***

### Balance

The current amount of an asset held in an account. Midaz tracks the **available** amount (ready for immediate use) and the **on hold** amount (reserved for pending transactions).

### Blast radius

The scope of impact if a failure, misconfiguration, or security incident occurs. In multi-tenancy contexts, blast radius counts the tenants that suffer when something goes wrong in one tenant's scope. See also: **Tenant isolation**.

### BYOC (Bring Your Own Cloud)

A deployment model where you run Lerian software on your own infrastructure, whether public cloud (AWS, GCP, Azure), private cloud, or on-premises. This gives you full control over data residency, security, and scaling. See also: **SaaS**.

***

## C

***

### CEL (Common Expression Language)

A lightweight, type-safe expression language that Tracer uses for writing business rules. CEL lets analysts and compliance teams define validation logic without writing application code or requiring deployments. One example: "if transaction amount exceeds 10,000 and account type is personal, flag for review".

### Core banking

A complete banking platform that combines a ledger foundation with the capabilities required to operate financial products. Those capabilities are accounts and balances, value movement, account holder identity, reporting, governance, connectivity, and auditability. A ledger is foundational, but it is not the whole core banking platform.

### Child account

A sub-account created under a parent account, typically used for budgeting or organizational purposes. For example, an account holder's savings account might have child accounts for "Vacation Fund" and "Emergency Fund." Each child account tracks its own balance.

***

## D

***

### Double-entry accounting

An accounting principle where the ledger records every financial movement as at least two operations: a debit from one account and a credit to another. This ensures the system always balances. The total of all debits equals the total of all credits. Midaz enforces double-entry automatically on every transaction.

### DSL (Domain-Specific Language)

A simplified programming language designed for a specific domain. In Flowker, the DSL lets teams define workflow steps, conditions, and integrations using a structured format, without writing general-purpose code.

***

## E

***

### ERP (Enterprise Resource Planning)

A business management software system (such as SAP, Oracle, or NetSuite) that integrates core processes like accounting, procurement, and inventory. ERPs are common data sources for reconciliation with Matcher.

### External account

A special account in Midaz that represents value entering or leaving the system from outside. Its alias is `@external/` followed by the asset code, for example `@external/BRL`. External accounts are boundaries between your ledger and the outside world.

***

## F

***

### Fail closed

A safety posture where a system denies access by default when it cannot verify a required condition, rather than allowing access and risking a breach. In Lerian multi-tenancy, tenant resolution is fail-closed. When the JWT does not identify the tenant, or when the tenant configuration does not load, the system rejects the request. The request never falls back to a default or shared tenant. See also: **Tenant isolation**, **Multi-tenancy**.

***

## H

***

### Helm Chart

A pre-configured deployment package for Kubernetes. Helm Charts contain all the instructions needed to install, configure, and upgrade software in a Kubernetes cluster. Lerian provides Helm Charts for deploying products in BYOC (self-hosted) environments.

***

## I

***

### Idempotency

The property that an operation produces the same result whether executed once or multiple times. In financial systems, this prevents duplicate transactions. If you accidentally send a payment request twice, idempotency ensures the money only moves once.

### Immutable (Immutability)

A property meaning "cannot change or be deleted after creation." This guarantees data integrity for compliance and auditing.

***

## K

***

### Kubernetes

A platform for running and managing software applications at scale across multiple servers. Kubernetes automates deployment, scaling, and recovery, so applications stay available even when individual servers fail.

***

## L

***

### Ledger

The core financial book that records all transactions, balances, and operations for an organization. Think of it as the single source of truth for a business unit's finances. An organization can have multiple ledgers for different purposes (e.g., retail operations, treasury).

***

## M

***

### Metadata

Additional information attached to entities like accounts, transactions, or organizations. Metadata takes the form of key-value pairs. It does not affect ledger logic but enriches records for reporting and integration.

### Multi-tenancy

An operating model where one deployment serves independent institution contexts (called tenants) with product-specific request scoping and storage isolation. Lerian Cloud operates multi-tenant. See also: **Tenant**, **Tenant isolation**.

***

## O

***

### Onboarding domain

The part of Midaz responsible for structuring your financial ecosystem: creating organizations, ledgers, assets, accounts, portfolios, and segments. This is the "setup" phase before any transactions occur.

### Operation

The atomic unit of movement in the ledger: a single debit or credit. Every transaction consists of one or more operations, which gives precise traceability for compliance and reporting.

### Operation Route

A reusable template that defines the rules for one "leg" of a financial transaction. It specifies which accounts participate, in what direction (source/destination), and under what accounting annotation.

### Organization

The top-level business entity in Midaz, typically a bank, fintech, or subsidiary. Each organization holds its own ledgers.

***

## P

***

### Pix

Brazil's instant payment system, operated by the Central Bank of Brazil (BACEN). Pix enables real-time transfers 24/7 between individuals, businesses, and government entities.

### Portfolio

A grouping of accounts belonging to the same account holder, business unit, or purpose. For example, a single account holder may hold checking, savings, and investment accounts across different currencies. A portfolio ties them together for a unified view.

### Plugin

An optional extension that adds functionality to a specific Lerian product. Examples include Pix (instant payments), TED (bank transfers), and Payments (boletos and bill payment). All available plugins extend Midaz.

***

## R

***

### Reconciliation

The process of comparing two sets of records (for example, your internal ledger against bank statements) to verify they match. Matcher automates this process by applying matching rules and flagging discrepancies.

***

## S

***

### Lerian Cloud (SaaS)

Lerian's fully managed deployment model. Lerian operates the licensed platform modules and underlying infrastructure. Institutions use the supported product APIs and configuration surfaces. See also: **BYOC**.

### Segment

A classification applied to accounts that share characteristics, like account holder tiers (VIP, Student, Business) or regional divisions. Segments enable differentiated rules, pricing, and benefits across your account holders.

### Settlement

The process of finalizing a financial transaction, transferring the actual funds between institutions. Settlement accounts in Midaz are clearing points. Money waits there before it moves to its final destination (e.g., via Pix or TED to the central bank).

### Streaming Hub

Lerian's event-delivery service. It sits at the edge between the platform's internal event stream and the systems you run outside it. It delivers each event you care about to a destination you own: a webhook, a cloud queue, or a cursor you pull.

***

## T

***

### Tenant

A logically isolated institution context in a multi-tenant deployment. The supported product service defines its data model, authentication claims, routing, and backing resources. Do not assume one product's tenant model applies to another. See also: **Multi-tenancy**, **Tenant isolation**.

### Tenant isolation

The controls that prevent another tenant from using one tenant's supported product service, data, configuration, and operations. Authentication and routing controls remain product-specific. See also: **Multi-tenancy**, **Tenant**.

### Terraform

An infrastructure automation tool that provisions and manages cloud resources (servers, databases, networks, security groups) through declarative configuration files. Lerian provides Terraform templates for setting up BYOC infrastructure on AWS, GCP, or Azure.

### TED (Transferência Eletrônica Disponível)

A Brazilian electronic bank transfer system for high-value or same-day transfers between financial institutions. Unlike Pix, TED operates only during business hours. In the Lerian ecosystem, the TED plugin connects Midaz to the TED network.

### Transaction

A movement of value between accounts. Transactions can involve multiple operations (debits and credits), and Midaz processes them atomically. Either all operations succeed, or none do. This ensures no partial financial events occur.

### Transaction domain

The part of Midaz responsible for executing financial movements: processing transactions, updating balances, and maintaining audit trails.

### Accounting Route (Transaction Route)

A complete transaction blueprint composed of multiple Operation Routes. For example, a "Pix Transfer" route defines all the debits and credits involved, so every transaction of that type complies with double-entry accounting. Called **Accounting Route** in the Lerian Console and product docs. Exposed as `transactionRoute` in the API.

***

## W

***

### Webhook

An automated notification sent from one system to another when a specific event occurs.


# Welcome to our guides
Source: https://docs.lerian.studio/en/start-here/welcome-to-our-guides

Navigate the Lerian documentation, one tab per area of the platform, from the fundamentals to the products, the Brazil rails, the integration diagrams, and the API reference.

Lerian's guides sit next to the API reference, one area of the platform per tab. Use the top bar to pick an area, then use the left sidebar to move inside it.

## How to navigate

***

**1. Pick a tab in the top bar**

Start Here holds the fundamentals, the getting-started path, and the glossary. Lerian Products holds the products and the platform services. Brazil Rails holds the rails and the interfaces. Integration Diagrams shows how the messages of a rail combine into a journey. API Reference holds the endpoints, and News holds the release notes.

**2. Pick a section in the left sidebar**

Each tab splits into sections. Lerian Products holds one section per product, plus a Platform section. Brazil Rails holds one section per rail, plus an Interfaces section.

**3. Read the overview page first**

Each section opens with an overview page. Read it first. The pages after it carry the detail, such as how the software works, how to integrate with it, and how to operate it.


# About Midaz Console
Source: https://docs.lerian.studio/en/products/midaz/about-midaz-console

See how the standalone Midaz Console moved into the Lerian Console Midaz Module. Midaz v3.5.0 and later releases do not include the standalone Midaz Console.

The **Midaz Console** was the visual administrative interface for Midaz. You used it to configure organizations, ledgers, accounts, assets, and transactions, with no direct API calls.

From Midaz v3.5.0, the Midaz repository no longer includes the Console. Its features moved into the **Lerian Console** as the [Midaz Module](/en/products/midaz/console/midaz-module).

## What changed

***

The Midaz Console moved from a standalone source-available interface to an integrated module in the Lerian Console. This change separates Midaz, the core ledger engine, from the platform tools that manage it.

| Aspect | Before (prior to v3.5.0) | Now (v3.5.0+) |
| :- | :- | :- |
| **Distribution** | Bundled with the Midaz repository | Part of the Lerian Console |
| **License** | Source-available | Commercial (Lerian Console) |
| **Scope** | Standalone admin interface | Integrated product module with cross-product capabilities |
| **Development** | Community-driven | Maintained and developed by Lerian |

## For existing users

***

If you run a Midaz version before v3.5.0, the Console remains part of your source-available installation. It works as expected in those versions.

> [!WARNING]
>
> Midaz v3.5.0 and later releases do not include the standalone Midaz Console. Migrate to the Lerian Console.

## Moving forward

***

The [Midaz Module](/en/products/midaz/console/midaz-module) in the Lerian Console replaces the standalone Console. It adds unified authentication, cross-product navigation, and ongoing feature development.

To see what the Midaz Module offers, read the documentation:

> **[Midaz Module overview](/en/products/midaz/console/midaz-module)**
>
> Full documentation for the Midaz Module within the Lerian Console.

> **[Lerian Console](/en/platform/console/about-lerian-console)**
>
> Learn about the unified platform for managing all Lerian products.


# Auditability
Source: https://docs.lerian.studio/en/products/midaz/auditability

Understand the scoped audit mechanisms in Midaz: CRM protection events and optional Ledger transaction audit messages.

Midaz does not provide one universal audit trail for every platform action. Its audit behavior is specific to the mechanism that produces the data.

## CRM protection audit events

***

When CRM runs with envelope encryption, Midaz emits **Protection Audit Events** for encryption-protection activity. Midaz stores these events per Organization. You can read them through the [List Protection Audit Events](/en/reference/products/midaz/v2/get-audit-events) endpoint.

This mechanism is not available in legacy encryption mode. The audit writer is best-effort: a failed audit emission is logged, but it does not block the CRM operation.

Use protection audit events to investigate encryption-protection activity for an Organization. Do not interpret them as a complete record of every Ledger or platform action.

## Ledger transaction audit messages

***

The Ledger publishes transaction audit messages unless `AUDIT_LOG_ENABLED` is `false`. The built-in environment example sets this flag to `false`. Keep the flag set to `false` until you configure your downstream consumer, its retention, and its investigation workflows.

The Ledger sends these messages to the RabbitMQ exchange set in `RABBITMQ_AUDIT_EXCHANGE`, with the routing key set in `RABBITMQ_AUDIT_KEY`. Publishing is best-effort: Midaz logs a failed publish and does not block the transaction. Midaz does not expose them as a general queryable Ledger audit-record API. The receiving system owns retention, indexing, and investigation workflows.

## Designing your audit trail

***

Choose the mechanism that matches the data you need to observe:

* Use **Protection Audit Events** for CRM envelope-encryption activity.
* Enable **Ledger transaction audit messages** only after you configure your downstream consumer to retain and process them.
* Keep controls, retention, and evidence requirements in the system responsible for the data after Midaz emits it.

> [!NOTE]
>
> For help designing an audit and retention architecture around Midaz, [contact us](https://lerian.studio/contact).


# Setting up accounting in the Console
Source: https://docs.lerian.studio/en/products/midaz/console/accounting-setup-in-console

Walk through a Console-only guide to build your accounting model in Midaz, from planning a chart of accounts to running your first Pix payment.

This guide shows you how to set up accounting in the Midaz Module of the Lerian Console. You use only the screens and forms in the Console, and you write no code. It is the Console companion to the developer-focused [Accounting Walkthrough](/en/products/midaz/accounting-walkthrough). You reach the same result through Console forms instead of API calls.

It targets product managers, implementation teams, and developers who prefer to model their accounting in the UI.

> [!NOTE]
>
> You will not see any JSON or API calls here. You do everything below through Console forms. To automate the same setup later, follow the technical reference each section links to.

## What you are building

***

Configure your accounting routes deliberately. A route defines the source and destination Operation Routes for a direct transaction, or a Bidirectional Operation Route that covers both sides. With **Validate Routes** enabled, Midaz validates transactions against the configured route rules.

Route validation is disabled by default. Enable it only after you configure the routes your Ledger needs. Cancellation is a source-only lifecycle action: it releases held funds on the source Account and does not involve a destination Account.

Each layer builds on the one before it:

**1. Plan your chart of accounts**

Decide which balances your product needs (customer funds, fees, settlement, treasury, revenue).

**2. Create Account Types**

Define the categories that classify your accounts.

**3. Create Accounts**

Open the actual balance containers, each with a **Type** and an Asset. You select the Type for non-external Accounts. When you enable **External account**, the Type becomes `external` automatically. When **Validate Account Type** is enabled, the Type of every non-external Account must match a registered Account Type.

**4. Create Accounting Routes**

Set the rules for which accounts can join each transaction and how the ledger posts entries.

> [!TIP]
>
> Work top to bottom. Routes are much easier to build once you already know which accounts represent customers, treasury, fees, and settlement.

## Step 1: Plan your chart of accounts

***

In traditional accounting, a **Chart of Accounts (CoA)** is the master list of every account category your business uses: assets, liabilities, revenue, and expenses. It also defines how you classify each movement against those categories.

In Midaz there is no single "Chart of Accounts" screen to fill in. Instead, your CoA emerges from the building blocks you create in the Console: Assets, Account Types, and Accounts. You plan it up front, mostly as a paper (or whiteboard) exercise.

Before you open the Console, list the balances your product needs. For a typical payments product that might be:

| Balance you need | What it represents |
| - | - |
| Customer funds | Money your end users hold |
| Settlement | Funds waiting to clear |
| Fee revenue | Fees you collect |
| Fee expense | Fees you pay to providers |
| Treasury | Your own internal operating funds |

This list is your blueprint. The next steps turn each line into something concrete in the Console.

> [!NOTE]
>
> Before any account can exist, it needs an **Asset**, the unit of value it holds (for example `BRL`). If you have not created your assets yet, start with [Creating an Asset](/en/products/midaz/console/creating-an-asset).

## Step 2: Create your Account Types

***

**Account Types** are the categories that classify your accounts. Think of them as labels like `customer`, `treasury`, or `fee` that group accounts by their role. Later, Accounting Routes use these labels to decide which accounts a transaction can use.

In the Console you create one Account Type per category from your blueprint, not one per individual customer.

> **[Create an Account Type](/en/products/midaz/console/creating-an-account-type)**
>
> Open the New Account Type form and define a category with a clear name and a stable key value.

A typical payments setup uses these Account Types:

| Account Type | Use it for |
| - | - |
| `customer` | Liquid customer balances |
| `settlement` | Funds awaiting clearing |
| `fee` | Fees collected as revenue |
| `treasury` | Internal operations |
| `expense` | Fees paid out to providers |

> [!WARNING]
>
> The **Key Value** of an Account Type (for example `customer`) is what routes and accounts rely on. Keep it short, lowercase, and stable. You cannot change it later. To use a different key, create a new Account Type and recreate the accounts and routes that depend on it.

> [!NOTE]
>
> The Account Types menu appears only after you enable **Validate Account Type** in your Ledger settings. To turn it on, see [Managing Ledgers](/en/products/midaz/console/managing-ledgers-via-console#ledger-settings).

## Step 3: Create your Accounts

***

**Accounts** are the balance containers that hold value and that money moves between. Each account has a **Type** and one Asset (its currency). You select the Type for non-external Accounts. When you enable **External account**, the Type becomes `external` automatically. When **Validate Account Type** is enabled, the Type of a non-external Account must match a registered Account Type (external Accounts skip this check). A human-readable **alias** identifies it. `@customer_123_brl` is one common convention.

For each line in your blueprint, create one Account in the Console.

> **[Create an Account](/en/products/midaz/console/creating-an-account)**
>
> Open the New Account form, choose its Type and Asset, and give it a clear alias.

When you fill in the form, a few choices are permanent and worth getting right the first time:

| Field | Why it matters |
| - | - |
| **Account Alias** | The name routes and transactions use to find the account. Cannot be changed after creation. |
| **Type** | The Account Type that classifies it. Cannot be changed after creation. |
| **Asset** | The currency or unit it holds. Cannot be changed after creation. |

> [!WARNING]
>
> The Console locks Alias, Type, and Asset when you save the account. To change any of them, create a new account. Double-check before you save.

### Available and On Hold balances

When you open an account in the Console, Midaz splits its balance into two **buckets**. You always know what you can spend and what the ledger holds back:

| Bucket | What it means when you look at an account |
| - | - |
| **Available** | Money that is free to spend or send right now. This is the number that goes up and down with normal payments. |
| **On Hold** | Money that a pending operation has reserved but not yet finalized. It still belongs to the account. The ledger sets it aside, and you cannot spend it until the hold is confirmed or cancelled. |

Both amounts appear as exact decimal values (for example, `12.50`). There is no scale factor to apply when you read them.

> [!NOTE]
>
> **On Hold** powers two-step payments. When you authorize a payment but do not yet capture it, the amount moves from **Available** to **On Hold**. Confirming the payment releases it to the destination. Cancelling returns it to Available. You see each of these movements on the account at every stage.

## Step 4: Create your Accounting Routes

***

With **Validate Routes** enabled, each transaction must specify a valid Accounting Route in the ledger. An Accounting Route is a reusable rule for one kind of transaction, such as a *Pix transfer* or a *fee charge*. It answers three questions:

* Which accounts can send on the **source** side?
* Which accounts can receive on the **destination** side?
* Which debit and credit **entries** should the ledger post when it runs?

The Console builds these through a guided 3-step wizard, so you do not have to assemble anything by hand.

> **[Manage Accounting Routes](/en/products/midaz/console/managing-accounting-routes)**
>
> See how the Accounting Routes page works and what each part of the wizard does.

> **[Create an Accounting Route](/en/products/midaz/console/creating-an-accounting-route)**
>
> Walk through the 3-step wizard to define a route, its operation rules, and its entries.

To decide how to shape a route, see [Accounting rules](/en/products/midaz/console/mc-accounting). It explains the choices in plain terms.

> **Source, Destination, or Bidirectional?**
>
> Each rule inside a route applies to one side of a transaction:
>
> * **Source**: the sending side (where value comes from).
> * **Destination**: the receiving side (where value lands).
> * **Bidirectional**: the same rule applies to both sides, for cases where one kind of account can both send and receive.
>
> A valid route needs at least one Source **and** one Destination, or a single Bidirectional rule.

> **How should an account be validated?**
>
> Each rule checks accounts in one of two ways:
>
> * **Account Type**: the rule accepts any account of a given category (for example, any `customer` account can send). Use this for flexible, scalable flows.
> * **@Alias**: the rule accepts only one exact account (for example, only `@fee_revenue` can receive). Use this for fixed operational accounts like treasury, fees, or settlement.

> **Which accounting scenario?**
>
> Scenarios decide how the debit and credit entries get recorded:
>
> * **Direct Transaction**: a one-step movement, posted immediately.
> * **Two-Step Transaction**: a hold-then-commit flow. It uses separate entries to reserve, confirm, and cancel funds, and it drives the **On Hold** bucket.
> * **Reversal**: entries the ledger records to undo a completed transaction.
> * **Overdraft**: entries the ledger records when a debit exceeds the account's available funds and draws on an overdraft line.
> * **Block**: entries the ledger records when funds on an account are blocked or unblocked.

> [!WARNING]
>
> Turn on **Validate Routes** in Ledger settings **only after** the routes you need already exist. If validation is on but a matching route is missing, those transactions will fail.

## Example: a simple Pix payment

***

Let's run the whole flow in the Console for a basic **Pix cash-out**: a customer sends BRL out of their wallet to a settlement account. Assume your `BRL` asset already exists.

**1. Create the Account Types**

From the **Account Types** page, create:

* `customer`: for end-user balances.
* `settlement`: for funds leaving to the outside world.

See [Creating an Account Type](/en/products/midaz/console/creating-an-account-type).

**2. Create the Accounts**

From the **Accounts** page, create:

* `@customer_123_brl`: Type `customer`, Asset `BRL`. The customer's wallet.
* `@external_brl`: Type `settlement`, Asset `BRL`. Where funds settle when they leave the ledger.

See [Creating an Account](/en/products/midaz/console/creating-an-account).

> [!NOTE]
>
> `@external_brl` is a regular, ledger-owned settlement Account. This example uses it so the route can validate the `settlement` Account Type. It is not the canonical external Account `@external/BRL`, which Midaz creates automatically together with the `BRL` Asset. The `@external/` alias prefix is reserved, so you cannot create that Account yourself. For money that actually enters or leaves Midaz, use `@external/BRL`. See [Common mistakes to avoid](/en/products/midaz/common-mistakes-to-avoid).

**3. Create the Accounting Route**

From the **Accounting Routes** page, start the wizard and build a `Pix cash-out` route:

* A **Source** operation rule validating Account Type `customer` (the wallet sends).
* A **Destination** operation rule validating Account Type `settlement` (the settlement account receives).
* A **Direct Transaction** accounting scenario, with a debit entry on the source and a credit entry on the destination.

See [Creating an Accounting Route](/en/products/midaz/console/creating-an-accounting-route).

**4. Run a transaction**

Create a transaction that moves, say, `100.00 BRL` from `@customer_123_brl` to `@external_brl` using your `Pix cash-out` route. See [Creating a Transaction](/en/products/midaz/console/creating-a-transaction).

**5. Check the result**

Open each account and look at the balance:

* `@customer_123_brl`: **Available** drops by `100.00`.
* `@external_brl`: **Available** rises by `100.00`.

Both movements belong to the same transaction, so the audit trail stays balanced.

> [!TIP]
>
> For an authorize-then-capture flow, use a **Two-Step Transaction** scenario on the route. You see the amount move into **On Hold** when reserved, and out of it when you confirm or cancel.

## What to do next

***

To go deeper, use these technical references. They cover how to automate the setup, understand the entities, and turn ledger activity into reports:

> **[Accounting Walkthrough (developer)](/en/products/midaz/accounting-walkthrough)**
>
> The end-to-end developer version of this guide, including the data model and double-entry detail.

> **[Accounting overview](/en/products/midaz/accounting-in-midaz)**
>
> How the core accounting primitives relate to one another.

> **[Transaction Routing entities](/en/products/midaz/transaction-routing-entities)**
>
> The technical model behind Accounting Routes, operation routes, and entries.

> **[Balances](/en/products/midaz/balances)**
>
> The full balance model behind available and on-hold amounts.


# Adding a Portfolio to an Account
Source: https://docs.lerian.studio/en/products/midaz/console/adding-portfolio-to-account

Link a Midaz Account to a Portfolio from the Console, either from the Accounts list or the edit form, to group Accounts under one customer or wallet.

Use Portfolios to group Accounts that belong to the same Entity. To add an Account to a Portfolio, follow one of these procedures:

## Adding from the Accounts page

If the Account does not belong to a Portfolio yet, add it directly from the **Accounts** page. Follow these steps:

**Step 1**

Click the **Link portfolio** option in the **Portfolio** column of the Account you want to add.

**Step 2**

The Console displays the form to edit the Account.

**Step 3**

Switch to the **Portfolio** tab and select the **Portfolio** you want.

**Step 4**

Click the **Save** button to link the Account to the selected Portfolio.

## Add by editing the Account

You can also edit the **Account** to add or change its Portfolio:

**Step 1**

On the **Accounts** page, find the Account you want to edit. Click the three dots () in the **Actions** column. Select **Details** to open the Account details page.

**Step 2**

Click the **Edit** button. In the edit form, select the **Portfolio** you want.

**Step 3**

Click the **Save** button to confirm the procedure.

> **API equivalent**
>
> [Update an Account endpoint](/en/reference/products/midaz/v2/update-account)


# Adding a Segment to an Account
Source: https://docs.lerian.studio/en/products/midaz/console/adding-segment-to-account

Assign a Segment to an existing Account from the Console to classify it by shared characteristics and apply the associated benefits or business rules.

Segments group Accounts by shared characteristics and benefits. To learn more about Segments, see the [Segments](/en/products/midaz/segments) page.

To add a Segment to an Account, follow these steps:

**Step 1**

Open the **Accounts** page. Find the Account you want to add to the Segment. In the **Actions** column, click the three dots (). Select **Edit**.

**Step 2**

The edit sheet opens on the **Account Details** tab. Select the Segment from the **Segment** list.

**Step 3**

Click the **Save** button to confirm.

> **API equivalent**
>
> [Update an Account endpoint](/en/reference/products/midaz/v2/update-account)


# Checking Transaction details
Source: https://docs.lerian.studio/en/products/midaz/console/checking-transaction-details

Open the full details of a Transaction in the Console to audit its movements, review the Transaction Data tab, and edit its description when needed.

To check the details of a transaction, follow these steps:

**Step 1**

On the **Transactions** page, find the transaction to check. In its **Actions** column, click the three dots (). Select **See details**.

**Step 2**

A page opens with the transaction summary.

**Step 3**

Then select the **Transaction Data** tab to see more information.

> [!TIP]
>
> In the **Transaction Data** tab, edit the description if needed.


# Creating a Ledger
Source: https://docs.lerian.studio/en/products/midaz/console/creating-a-new-ledger

Create a new Ledger in the Console to isolate Assets, Accounts, Routes, and Transactions, and configure Account Type or Route validation while you set it up.

A Ledger isolates Assets, Accounts, Routes, and Transactions in one accounting workspace. Create a new Ledger when you need a separate balance domain, product line, environment, or accounting model.

## Before you start

***

You need an existing Organization. If this is the first setup, create the Organization first in [Creating an Organization](/en/products/midaz/console/creating-an-organization).

Decide what the Ledger boundary means before you create it. Do not use one Ledger for unrelated products that need different account structures, routes, or operational controls.

## Create the Ledger

***

**Step 1**

From the **Ledgers** page, click the **New Ledger** button in the top-right corner.

**Step 2**

The **New Ledger** form appears.

**Step 3**

In the **Ledger Details** tab, enter the Ledger name in the **Ledger Name** field.

**Step 4**

(Optional) To include metadata, select the **Metadata** tab. This tab displays two fields: **Key** and **Value**.

* To add more metadata, click the plus (+) icon next to the first row.

**Step 5**

(Optional) Select the **Settings** tab to configure validation rules for this Ledger.

* Enable **Validate Account Type** if Accounts must use registered Account Types.
* Enable **Validate Routes** if Transactions must follow pre-configured Accounting Routes.

**Step 6**

After you complete the form, click **Save**.

**Step 7**

A success message appears in the top-right corner. The main **Ledgers** page now lists the new Ledger.

## Field guide

***

| Field | What to enter | Example |
| - | - | - |
| Ledger Name | A clear name for the accounting workspace. Use a name that shows the product, country, environment, or business boundary. | `Brazil Payments Ledger` |
| Metadata Key | Optional classification or integration field name. | `environment` |
| Metadata Value | Value for the metadata key. | `production` |
| Validate Account Type | Optional setting. Turn on when every new non-external Account in this Ledger must use a previously registered Account Type. Leave off if you will not classify Accounts by type yet. | `Enabled` |
| Validate Routes | Optional setting. Turn on only after the Accounting Routes for this Ledger are planned or configured, because Transactions must match a valid route when this is enabled. | `Disabled` |

> [!TIP]
>
> The fields in the Metadata tab are open. The tab has no predefined keys or values. Use consistent key names across your Organization, such as `environment`, `businessLine`, or `region`, so you can filter and audit Ledgers later.

## Ledger settings

***

The **Settings** tab controls the validation rules for this Ledger.

### Validate Account Type

When you enable this setting, every new non-external Account must use an Account Type registered for this Ledger. Enable it when you want operators to classify Accounts consistently, such as `customer`, `merchant`, `treasury`, or `fee`.

> [!WARNING]
>
> After you enable **Validate Account Type**, the Ledger rejects any non-external Account without a valid Account Type.

### Validate Routes

When you enable this setting, Transactions must match the Accounting Routes configured for this Ledger. Enable it only after you plan or configure your route model.

> [!WARNING]
>
> If you enable **Validate Routes** before routes exist, any Transaction without a matching route fails validation.

## What to do next

***

After you create the Ledger:

1. Review whether **Validate Account Type** and **Validate Routes** are correct for this Ledger.
2. Create at least one Asset in [Creating an Asset](/en/products/midaz/console/creating-an-asset).
3. If you need to change the validation rules later, use the **Settings** tab described in [Managing Ledgers](/en/products/midaz/console/managing-ledgers-via-console#ledger-settings).

> **API equivalent**
>
> [Create a Ledger endpoint](/en/reference/products/midaz/v2/create-ledger)


# Creating a Portfolio
Source: https://docs.lerian.studio/en/products/midaz/console/creating-a-portfolio

Create a new Portfolio in the Console to group Accounts under a customer, business unit, or reporting boundary, and set an Entity ID for external systems.

A Portfolio groups Accounts under a customer, business unit, or reporting boundary.

## Before you start

***

You need an existing Organization and Ledger. Create a Portfolio when you want to group Accounts under a customer, business unit, product, or reporting boundary.

## Create the Portfolio

***

To create a Portfolio, follow these steps:

**Step 1**

From the **Portfolios** page, click the **New Portfolio** button.

**Step 2**

The **New Portfolio** form opens on the right side of the screen.

**Step 3**

Fill in the fields and click the **Save** button.

## Field guide

***

| Field | What to enter | Example |
| - | - | - |
| Portfolio Name | Required name for the customer, business unit, or reporting group. Minimum 3 characters. | `Acme Retail Portfolio` |
| Entity Id | Optional external entity or system identifier. The Console shows this field only when you create the Portfolio. You can update it later through the Portfolio update API when the new value is non-empty. | `customer_acme` |
| Metadata Key | Optional classification or integration field name. | `relationshipManager` |
| Metadata Value | Value for the metadata key. | `ops-team-1` |

## What to do next

***

Now link the Portfolio to Accounts from [Adding Portfolio to Account](/en/products/midaz/console/adding-portfolio-to-account). You can also create Accounts that belong to it in [Creating an Account](/en/products/midaz/console/creating-an-account).

> **API equivalent**
>
> [Create a Portfolio endpoint](/en/reference/products/midaz/v2/create-portfolio)


# Creating a Segment
Source: https://docs.lerian.studio/en/products/midaz/console/creating-a-segment

Create a new Segment in the Console to classify Accounts by shared characteristics, business rules, or reporting needs across your Ledger.

A Segment classifies Accounts by shared characteristics or business rules.

## Before you start

***

You need an existing Organization and Ledger. Create a Segment when a group of Accounts needs a shared classification for reporting, filtering, or fee rules.

## Create the Segment

***

To create a Segment, follow these steps:

**Step 1**

From the **Segments** page, click the **New Segment** button.

**Step 2**

The **New Segment** form opens on the right side of the screen.

**Step 3**

In the **Segment Details** tab, enter the **Segment Name**.

**Step 4**

(Optional) Select the **Metadata** tab to add metadata.

**Step 5**

When the details are complete, click the **Save** button.

**Step 6**

The Segment appears in the list of Segments for your Ledger.

## Field guide

***

| Field | What to enter | Example |
| - | - | - |
| Segment Name | Required name for a group of Accounts with shared characteristics or rules. | `Retail Customers` |
| Metadata Key | Optional classification or integration field name. | `region` |
| Metadata Value | Value for the metadata key. | `BR-SP` |

> [!TIP]
>
> The Metadata fields have no predefined keys or values. Use consistent key names across your Organization, such as `region`, `businessLine`, or `channel`. Consistent keys keep Segments useful for filtering and reporting.

## What to do next

***

After you create the Segment, link it to Accounts from [Adding Segment to Account](/en/products/midaz/console/adding-segment-to-account). You can also create Accounts that belong to it in [Creating an Account](/en/products/midaz/console/creating-an-account).

> **API equivalent**
>
> [Create a Segment endpoint](/en/reference/products/midaz/v2/create-segment)


# Creating a Transaction
Source: https://docs.lerian.studio/en/products/midaz/console/creating-a-transaction

Create a new Transaction in the Console using the 1:1 or n:n wizard to move Asset balances between source and destination Accounts by alias.

A Transaction moves value between Accounts in a Ledger. Create one only after the Asset, source account, destination account, and any required Accounting Route are ready.

## Before you start

***

Confirm that:

* The source and destination Accounts exist in the selected Ledger.
* Both Accounts use the Asset selected for the Transaction.
* You know each Account alias. A leading `@` is a common convention, not a requirement.
* Source accounts allow sending and destination accounts allow receiving.
* If **Validate Routes** is on, the Transaction must match an existing Accounting Route.

## Create the Transaction

***

**Step 1**

From the **Transactions** page, click the **New Transaction** button.

**Step 2**

The **New Transaction** modal will open. Select the type of transaction you want to create:

* **Simple 1:1** - Transactions using one source and one destination
* **Complex n:n** - Transactions using more than one source or destination

**Step 3**

After selecting the transaction type, the **New Transaction** page opens with a step-by-step form:

**1. Transaction Data**

Fill in the basic transaction information:

* (Optional) Add a **Transaction description**
* If **Validate Routes** is on, select the **Transaction Route**
* Enter the **Value** (amount) to transfer
* Select the **Asset** for the transaction
* (Optional) Turn on **Skip fees** to post the transaction without running the Fees Engine. The switch appears only when the Ledger allows skipping fees

**Step 2**

Click **Continue to the next step** to proceed to the accounts selection step.

**3. Source / Destination**

Specify the accounts involved:

* Search for the **source account** by alias and select it
* Search for the **destination account** by alias and select it
* For complex transactions, you can add multiple sources and/or destinations

> [!WARNING]
>
> You **must** use the account alias to perform transactions. Make sure you save it when you create your account.
>
> If you forget your alias, you can find it by [editing account information](/en/products/midaz/console/editing-account-information).

**Step 4**

Click **Continue to the next step** to proceed to the operations step.

**5. Operations**

Review and adjust the operation details:

* For simple transactions (1:1), the Console fills the amounts automatically
* For complex transactions (n:n), specify the amount for each source (debit) and destination (credit)
* Expand each operation to add an optional **Operation description**. If **Validate Routes** is on, select its **Operation Route**
* Add metadata in the **Transaction Metadata** section

> [!NOTE]
>
> For complex transactions, the sum of all source amounts must equal the sum of all destination amounts.

**Step 4**

When all the information is correct, click the **Go to Review** button.

**Step 5**

The Console shows a review page with a summary of all the transaction information:

* Transaction value and asset
* Source and destination accounts
* Individual debit and credit operations
* Metadata records (if any)

**Step 6**

Review the information carefully. If everything is correct:

* Click **Send Transaction** to submit the transaction
* Click **Send and Create another** to submit and immediately start a new transaction

**Step 7**

On success, the Console shows **Transaction created** with the operations the Ledger recorded. Click **View Transaction** to open the transaction details page.

## Field guide

***

**Transaction Data**

| Field | What to enter | Example |
| - | - | - |
| Transaction description | Optional business description of the movement. | `Customer payment to merchant` |
| Transaction Route | Shown when **Validate Routes** is on. Select the Transaction Route that the Transaction must match. | `Pix Transfer Route` |
| Asset | Asset used by the Transaction. It must match the selected Accounts. | `BRL` |
| Value | Total amount to move. For complex transactions, source totals must equal destination totals. | `100.00` |
| Skip fees | Shown when the Ledger allows skipping fees. Turn on to post the Transaction without running the Fees Engine. | `Disabled` |

**Source / Destination**

| Field | What to enter | Example |
| - | - | - |
| Source | Account alias that will be debited. | `@customer_123` |
| Destination | Account alias that will be credited. | `@merchant_456` |

**Operations**

| Field | What to enter | Example |
| - | - | - |
| Operation description | Optional description for the operation. | `Debit for the source account` |
| Operation Route | Shown when **Validate Routes** is on. Select the Operation Route that this transaction leg must match. | `Checking account validation for Pix` |
| Metadata Key | Optional classification or integration field name. | `externalReference` |
| Metadata Value | Value for the metadata key. | `order_98765` |

## Transaction types explained

***

### Simple Transaction (1:1)

Use for straightforward transfers between two accounts:

* One source account (debit)
* One destination account (credit)
* Same amount debited and credited

**Example**: Transfer \$100 from Customer A to Merchant B.

### Complex Transaction (n:n)

Use for transactions involving multiple parties:

* Multiple source accounts (debits) and/or multiple destination accounts (credits)
* You can distribute amounts across accounts
* Total debits must equal total credits

**Examples**:

* Payment with fees:
  * Customer pays \$103
  * Merchant receives \$100
  * Fee account receives \$3
* Consolidated payment: Multiple customers fund a single vendor payment

> [!TIP]
>
> The fields in the **Transaction Metadata** section are open. There are no default keys or values. Use consistent key names across your Organization, such as `externalReference`, `orderId`, or `channel`, to link Transactions back to source systems for reconciliation and audit.

## What to do next

***

After sending the Transaction, review the details page and confirm the status, source operation, destination operation, and account balances.

> **[Create a Transaction using JSON](/en/reference/products/midaz/v1/create-transaction-json)**
>
> Create a Transaction programmatically with the JSON endpoint.

> **[Retrieve a Transaction](/en/reference/products/midaz/v2/get-transaction)**
>
> Inspect the Transaction status and operations via API.


# Creating an Account
Source: https://docs.lerian.studio/en/products/midaz/console/creating-an-account

Create a new Account in the Console, tie it to an Asset, set its alias and type, and optionally link it to a Portfolio or add metadata during setup.

> [!WARNING]
>
> You **must** link an Account to an existing Asset. [Create the Asset](/en/products/midaz/console/creating-an-asset) before you create the Account.

## Before you start

***

You need an existing Organization, Ledger, and Asset. If the Ledger uses **Validate Account Type**, create the required Account Types before you open this form.

Decide what the account represents before you choose its type and alias. Common examples include customer, merchant, treasury, fee revenue, settlement, suspense, and expense accounts.

## Create the Account

***

To create an Account, follow these steps:

**Step 1**

From the **Accounts** page, click the **New Account** button.

**Step 2**

The **New Account** form will open on the right side of the screen with three tabs: **Account Details**, **Portfolio**, and **Metadata**.

**Step 3**

Fill in the required information in the **Account Details** tab.

For more information about the fields in the form, refer to the [Field guide](#field-guide) section.

**Step 4**

*(Optional)* Switch to the **Portfolio** tab to link this account to a portfolio for reports and management.

* Select a portfolio from the dropdown list
* If no portfolios exist, you can [create one first](/en/products/midaz/console/managing-portfolios)
* You can link or unlink accounts from portfolios at any time

**Step 5**

*(Optional)* Switch to the **Metadata** tab to add custom key-value pairs for additional context or integration purposes.

**Step 6**

Click the **Save** button to create the Account.

## Field guide

***

| Field | What to enter | Example |
| - | - | - |
| Account Name | Required descriptive name for the account, 3 to 255 characters. | `John Doe Checking Account` |
| Account Alias | Required unique human-readable identifier. Use letters, numbers, hyphens (`-`), underscores (`_`), `@`, and `:`. A leading `@` is a common convention, not a requirement. This cannot be changed after creation. | `@customer_john_checking` |
| Type | Account classification. Required. When Account Type validation is enabled, you select from the predefined Account Types; otherwise you type it freely. This cannot be changed after creation. | `customer` |
| External account | Switch available when creating an account. Turn it on to create an external account. The type is set to `external` automatically and represents balances held outside this ledger. | — |
| Entity ID | Optional external holder, customer, department, or partner identifier. | `customer_123` |
| Asset | Asset this account will use. Select an existing Asset. This cannot be changed after creation. | `BRL` |
| Segment | Optional grouping category, available when Segments exist. | `Retail` |
| Portfolio | Optional reporting or management group for this Account. | `Customer Portfolio` |
| Metadata Key | Optional classification or integration field name. | `costCenter` |
| Metadata Value | Value for the metadata key. | `BR_11101997` |

## Quick examples

***

**Customer Checking Account**

**Scenario**: Create a checking account for a customer.

| Field | Value |
| - | - |
| Account Name | `John Doe Checking` |
| Account Alias | `@customer_123_checking` |
| Type | `checking` |
| Entity ID | `customer_123` |
| Asset | `USD` |
| Allow Sending | `true` |
| Allow Receiving | `true` |

**Treasury Account**

**Scenario**: Create a main treasury account for company operations.

| Field | Value |
| - | - |
| Account Name | `Main Treasury` |
| Account Alias | `@treasury_main` |
| Type | `treasury` |
| Entity ID | `org_treasury_dept` |
| Asset | `USD` |
| Segment | `Finance` |
| Allow Sending | `true` |
| Allow Receiving | `true` |

**Department Budget Account**

**Scenario**: Create a budget account for the engineering department.

| Field | Value |
| - | - |
| Account Name | `Engineering Budget 2024` |
| Account Alias | `@eng_budget_2024` |
| Type | `expense` |
| Entity ID | `dept_engineering` |
| Asset | `USD` |
| Segment | `Engineering` |
| Allow Sending | `true` |
| Allow Receiving | `true` |

## Immutable fields, type validation and permissions

***

> **Fields that cannot be changed after creation**
>
> You cannot change the following fields after you create the account:
>
> * **Account Alias** - Choose it carefully, because transactions use the alias
> * **Type** - You cannot reclassify it after you set it
> * **Asset Code** - You cannot change the account's currency or commodity
>
> To change any of these fields, create a new account.

> **Account Type Validation**
>
> If your ledger uses Account Type validation:
>
> * You select the **Type** from your predefined Account Types instead of typing it freely
> * You must select from predefined account types or create them first
> * This ensures consistency across your organization's chart of accounts
>
> See [Managing Accounts](/en/products/midaz/console/managing-accounts#account-type-validation) for more information.

> **Allow Sending and Allow Receiving**
>
> These flags control transaction permissions:
>
> * **Allow Sending = false**: You cannot use the account as a source (debit side) in transactions
> * **Allow Receiving = false**: You cannot use the account as a destination (credit side) in transactions
>
> Both flags default to on. You can change them only after you create the account. Use these flags to:
>
> * Freeze an account temporarily
> * Create a receive-only account (for example, escrow)
> * Create a send-only account (rare case)

> [!NOTE]
>
> After you create an account, you can use it in transactions immediately. Make sure all the information is correct before you save, especially the immutable fields.

## What to do next

***

After you create the source and destination Accounts:

1. Create or review Accounting Routes in [Creating an Accounting Route](/en/products/midaz/console/creating-an-accounting-route).
2. Create a Transaction in [Creating a Transaction](/en/products/midaz/console/creating-a-transaction).

> **API equivalent**
>
> [Create an Account endpoint](/en/reference/products/midaz/v2/create-account)


# Creating an Account Type
Source: https://docs.lerian.studio/en/products/midaz/console/creating-an-account-type

Create a new Account Type in the Console to classify Accounts and enforce validation used by Accounting Routes when transactions are recorded.

Account Types classify Accounts. Accounting Routes use these types to define which accounts an operation can use. Create them before Accounts if you enabled **Validate Account Type** for the Ledger.

## Before you start

***

You need an existing Organization and Ledger. If you cannot see the Account Types menu, enable **Validate Account Type** in [Ledger Settings](/en/products/midaz/console/managing-ledgers-via-console#ledger-settings).

Define Account Types from the accounting model, not from individual customer names. Examples: `customer`, `merchant`, `treasury`, `fee`, `settlement`, `revenue`, `expense`.

## Create the Account Type

***

**Step 1**

From the **Account Types** page, click the **New Account Type** button.

**Step 2**

The **New Account Type** form will open on the right side of the screen.

**Step 3**

Fill in the information and click the **Save** button.

## Field guide

***

| Field | What to enter | Example |
| - | - | - |
| Account Type Name | Clear operator-facing name for this Account Type. | `Customer` |
| Description | Optional explanation of when operators should use this type. | `Accounts that represent end customers and can send or receive BRL payments.` |
| Key Value | Stable value used to classify Accounts and route rules. Use a short lowercase value that will remain stable. | `customer` |

> [!TIP]
>
> Accounts and Accounting Routes reference the **Key Value**. Keep it short, lowercase, and aligned with your accounting model. You cannot change it after you create the Account Type. To use a different value, create a replacement Account Type, recreate dependent Accounts with the new type, and update dependent routes.

## What to do next

***

After creating Account Types, create Accounts and select the correct type in [Creating an Account](/en/products/midaz/console/creating-an-account).

> **API equivalent**
>
> [Create an Account Type endpoint](/en/reference/products/midaz/v2/create-account-type)


# Creating an Accounting Route
Source: https://docs.lerian.studio/en/products/midaz/console/creating-an-accounting-route

Create a new Accounting Route in the Console using the 3-step wizard to define transaction routes, operation routes, and accounting scenarios.

You create an Accounting Route through a guided 3-step wizard. The wizard walks you through the transaction route, the operation routes with their accounting scenarios, and a final review.

## Before you start

***

Create the Account Types and Accounts that the route validates. If you have not chosen the operation type, the validation type, and the accounting scenarios yet, read [Accounting rules](/en/products/midaz/console/mc-accounting) first.

> [!WARNING]
>
> If you enable **Validate Routes** for the Ledger, every transaction must match an existing route. Do not enable route validation until the required Accounting Routes are ready.

The sidebar shows **Accounting Routes** only when **Validate Routes** is on for the Ledger. When it is off, open the page from the Console page search (**Search pages...**).

## Step 1: Basic information

***

**Step 1**

From the **Accounting Routes** page, click **New Route**.

**Step 2**

The creation wizard opens on the **Transaction Route** step.

**Step 3**

Fill in the basic information:

* **Route Title** (required): a descriptive name for this transaction route. You must fill in this field to continue.
* **Description** (optional): a description of the route's purpose. If you leave it empty, the wizard submits and stores an empty description.

**Step 4**

Click **Next** to proceed to Step 2.

## Step 2: Operation Routes

***

In this step, you add and configure the operation routes. Operation routes define how the ledger validates accounts and records accounting entries.

> [!NOTE]
>
> A **Bidirectional** operation route is both source and destination. When you later create a transaction, the ledger matches a bidirectional route on both the source side and the destination side. A single route can then validate both ends of the flow.

**Step 1**

Click **Add Operation Route** to create your first operation route card.

**Step 2**

Configure the operation route:

* **Title** (required): a name for this operation route. The operation route has a single required text field and no separate description field. You cannot advance to the next step until you fill it in.
* **Type**: **Source**, **Destination**, or **Bidirectional**.
* **Validation Type**: **Account Type** or **@Alias**. The wizard requires at least one Account Type or an alias for each operation route.
* **Account Type or Alias**: the selected Account Type values or the specific account alias.

**Step 3**

Configure **Accounting Scenarios** to define how the ledger records entries. **Direct Transaction** is always on, and you must fill in its entries. Toggle on the other scenarios you need:

**Direct Transaction**

Standard one-step transaction. Define the **Account Code** and **Description** for:

* **Debit**: The account code debited on execution
* **Credit**: The account code credited on execution

> [!TIP]
>
> For Direct Transactions, which sides appear depends on the operation type. Source routes show debit only, destination routes show credit only, and bidirectional routes show both.

**Two-Step Transaction**

Transactions with a hold-then-commit cycle. Configure entries for each phase:

* **Hold (Value Reserve)**: Entries that record reserved funds
* **Commit (Reservation Confirmation)**: Entries that confirm the reservation
* **Cancel (Reservation Cancellation)**: Entries that cancel the reservation. Fill these fields too: the ledger validates Hold, Commit, and Cancel as an atomic group and rejects the route when the Cancel mapping is absent.

The available entry fields vary by operation type:

* **Source**: Hold and Cancel show both debit and credit fields. Commit shows debit only.
* **Destination**: Only the Commit phase appears, with credit only. Hold and Cancel are not available.
* **Bidirectional**: All phases show both debit and credit fields.

**Reversal**

Entries that record the reversal of a completed transaction. Define the debit and credit account codes and descriptions for the reversal entries.

> [!NOTE]
>
> The Reversal scenario is only available for **Bidirectional** operation routes.

**Overdraft**

Entries that apply when a debit exceeds the account's available funds and draws on an overdraft line. Define the debit and credit account codes and descriptions for the overdraft draw and later repayment.

> [!NOTE]
>
> Overdraft is available for **Source** and **Bidirectional** operation routes.

**Block**

Entries that record blocking and unblocking funds on an account. Configure two independent sections, **Block** and **Unblock**. Each section is all-or-nothing: leave it empty to use the default entries, or fill in both the account code and the description for every visible side.

> [!NOTE]
>
> Block is available for all operation types. Source routes show debit entries only, destination routes show credit entries only, and bidirectional routes show both.

**Step 4**

*(Optional)* Click **Add Operation Route** again to add more operation routes to this Accounting Route.

> [!WARNING]
>
> You must add at least one source and one destination operation route, or at least one bidirectional route. The wizard will not proceed without a valid route configuration.

**Step 5**

Click **Next** to proceed to Step 3.

## Step 3: Review

***

**Step 1**

Review the complete configuration:

* Transaction route title and description
* Each operation route with its type, validation rules, and accounting entries
* Accounting scenarios with debit and credit entries per transaction type

**Step 2**

To adjust anything, click **Previous** to go back.

**Step 3**

Click **Create Transaction Route** to create the Accounting Route.

## Field guide

***

### Basic information

| Field | What to enter | Example |
| - | - | - |
| Route Title | Required route name. Keep it short and specific to the business flow. | `Pix Transfer Route` |
| Description | Optional explanation of what the route validates or records. | `Handles Pix transfers between customer accounts.` |

### Operation route

| Field | What to enter | Example |
| - | - | - |
| Title | Required name for this operation route card. Must be filled before advancing; there is no separate description field. | `Checking account validation for Pix` |
| Type | Accounting side this operation route applies to: **Source**, **Destination**, or **Bidirectional**. This cannot be changed after creation. | **Bidirectional** |
| Validation Type | Required account-validation rule. Use **Account Type** for account classes or **@Alias** for a specific account. | **Account Type** |
| Account Type or Alias | Account Types or aliases accepted by this operation route. | `customer` |
| Accounting Scenarios | Transaction scenarios this route should record: Direct, Two-Step, Reversal, Overdraft, or Block. | `Direct Transaction` |
| Account Code | Accounting code used in the debit or credit entry for the selected scenario. | `1.1.1.001` |
| Entry Description | Entry-level description shown in the scenario configuration. | `Customer checking - outbound` |

## Quick example

***

> **Pix Transfer with a Direct scenario**
>
> **Transaction Route**
>
> | Field | Value |
> | - | - |
> | Title | `Pix Transfer Route` |
> | Description | `Handles Pix instant transfers between checking accounts` |
>
> **Operation Route 1: Bidirectional**
>
> | Field | Value |
> | - | - |
> | Title | `Checking account validation for Pix` |
> | Type | **Bidirectional** |
> | Validation Type | **Account Type** |
> | Account Types | `checking` |
>
> **Direct Transaction scenario**
>
> | Side | Account Code | Description |
> | - | - | - |
> | Debit | `1.1.1.001` | `Customer checking — outbound` |
> | Credit | `1.1.1.002` | `Customer checking — inbound` |

## What to do next

***

After you create the route, create a transaction that matches the same account types, aliases, and scenario in [Creating a Transaction](/en/products/midaz/console/creating-a-transaction).

> **[Create Transaction Route](/en/reference/products/midaz/v2/create-transaction-route)**
>
> Create the transaction-level route via API.

> **[Create Operation Route](/en/reference/products/midaz/v2/create-operation-route)**
>
> Create operation-level routing rules via API.


# Creating an Asset
Source: https://docs.lerian.studio/en/products/midaz/console/creating-an-asset

Create a new Asset in the Console (currency, crypto, commodity, or custom) and set the code that Accounts and Transactions use.

An Asset defines the unit of value that Accounts and Transactions use inside a Ledger. Create Assets before you create Accounts, because every Account uses one Asset.

## Before you start

***

You need an existing Organization and Ledger. Decide whether the Asset is a currency, crypto asset, commodity, or another custom unit of value.

> [!WARNING]
>
> Choose Asset codes carefully. Accounts and Transactions depend on them.

## Create the Asset

***

**Step 1**

From the **Assets** page, click the **New Asset** button.

**Step 2**

The **New Asset** form opens on the right side of the screen.

**Step 3**

Select the **Type** of Asset.

* *Crypto*: for cryptocurrencies such as Bitcoin, Ethereum, and Ripple.
* *Commodity*: for tradable raw materials such as gold, natural gas, soybeans, and corn.
* *Currency*: for currencies such as Brazilian Real, US Dollar, and Euro.
* *Others*: for any other type of Asset.

> [!CAUTION]
>
> You cannot reuse an Asset name or code in the same Ledger. Both the name and the code must be unique.

**Step 4**

Specify the **Asset Name**.

**Step 5**

Specify the **Code** for the Asset. Use uppercase letters only.

* If the Asset is a currency, select its code from the [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) list.

**Step 6**

\[Optional] Select the **Metadata** tab to add custom metadata.

**Step 7**

After you fill in the fields, click the **Save** button.

**Step 8**

The Asset appears in the list of available Assets for your Ledger.

> [!NOTE]
>
> Saving an Asset also provisions a system-managed External Account when one does not already exist for that Asset code. Its canonical alias is `@external/<asset-code>`.

> [!TIP]
>
> The fields in the Metadata tab are open. There are no predefined keys or values. Use consistent key names across your Organization, such as `country`, `settlementNetwork`, or `regulatoryClass`, so you can filter and audit Assets later.

## Field guide

***

| Field | What to enter | Example |
| - | - | - |
| Type | Asset category. Use `Currency` for fiat money, `Crypto` for crypto assets, `Commodity` for tradable commodities, or `Others` for custom units. | `Currency` |
| Asset Name | Human-readable Asset name shown to operators. | `Brazilian Real` |
| Code | Asset code in uppercase letters. For currencies, use the ISO 4217 code. | `BRL` |
| Metadata Key | Optional classification or integration field name. | `settlementNetwork` |
| Metadata Value | Value for the metadata key. | `pix` |

## What to do next

***

After creating the Asset, create Accounts that use it in [Creating an Account](/en/products/midaz/console/creating-an-account).

> **API equivalent**
>
> [Create an Asset endpoint](/en/reference/products/midaz/v2/create-asset)


# Creating an Organization
Source: https://docs.lerian.studio/en/products/midaz/console/creating-an-organization

Create a new Organization in the Midaz Module to set the business boundary that will own your Ledgers, Assets, Accounts, and Transactions.

An Organization is a container for Midaz operations. It can be a top-level Organization or a child of another Organization. Create it before you create Ledgers, Assets, Accounts, or Transactions.

## Before you start

***

Decide which business boundary this Organization represents. In most setups, it maps to the company, business unit, or regulated entity that owns one or more Ledgers.

> [!NOTE]
>
> If you set up Midaz for the first time, follow the [Setup path](/en/products/midaz/console/midaz-console-setup-path) before you create downstream entities.

## Create the Organization

***

**Step 1**

Go to the **Organizations** page. Click the **New Organization** button.

**Step 2**

The **New Organization** page opens.

**Step 3**

Fill in the required details about the Organization.

* **Optional**: To include metadata, expand the **Metadata** section. The section then shows the **Key** and **Value** fields.
  * To add more metadata entries, click the plus (+) sign next to the first row.

> [!TIP]
>
> See the [Field guide](#field-guide) section for details about each field.

**Step 4**

After you enter all the details, click **Save**.

**Step 5**

Your new Organization appears on the Organizations page. You can now manage and configure it.

## Field guide

***

| Field | What to enter | Example |
| - | - | - |
| Legal Name | Official registered name. Use a name operators will recognize later. | `Lerian Payments Brazil` |
| Trade Name | Commercial or customer-facing name. | `Lerian` |
| Document | Official tax ID or registration number. Enter the identification document number. | `12345678000190` |
| Address | Street name, number, and main address line. | `Avenida Paulista, 1234` |
| Complement | Extra address details, such as suite, floor, or apartment. | `CJ 123` |
| Country | Select the country where the Organization is registered. | `Brazil` |
| State | Select the state, province, or region of the selected country. | `São Paulo` |
| City | City where the Organization is registered. | `São Paulo` |
| ZIP Code | Postal code, digits only, up to 12 digits. | `04696040` |
| Parent Organization | Optional. Select the Organization that this Organization is affiliated with, to create it as a child. | `Acme Holding` |

### Metadata

Metadata is optional key-value data. Use it for internal classification, integration references, or reporting.

| Field | What to enter | Example |
| - | - | - |
| Key | The metadata field name. | `costCenter` |
| Value | The value for that metadata field. | `BR_11101997` |

## What to do next

***

After you create the Organization, create its first Ledger in [Creating a new Ledger](/en/products/midaz/console/creating-a-new-ledger).

> **API equivalent**
>
> [Create an Organization endpoint](/en/reference/products/midaz/v2/create-organization)


# Creating an Alias from the Holder
Source: https://docs.lerian.studio/en/products/midaz/console/crm-alias-from-holder

Create an Alias Account directly from the Holders page in the Console so the Holder ID is preset and the new Alias is linked to its owner in one step.

You can also create an Alias Account from the **Holders** page. To do so, follow these steps:

**Step 1**

On the **Holders** page, find the Holder that you want to link to the Alias Account.

**Step 2**

In the Actions column, click the three dots () and select **Create Alias Account**.

**Step 3**

The Console opens the Alias Accounts page and shows the New Alias Account form.

**Step 4**

Fill in the fields as required, then click **Create Alias Account**.

> [!NOTE]
>
> The Console pre-fills the **Holder ID** field. You cannot change it.

With Access Manager, the **Create Alias Account** action needs the create permission on instruments.


# Creating a Holder
Source: https://docs.lerian.studio/en/products/midaz/console/crm-creating-a-holder

Create a new Holder in the Midaz Module as an Individual or Corporate record to represent the person or company that owns one or more Accounts.

A Holder represents the person or company behind one or more Accounts. Create the Holder before you create Alias Accounts. An Alias Account connects customer-facing account information to a ledger Account.

## Before you start

***

Decide whether the Holder is an **Individual** or **Corporate** record. The type you choose controls which identity and registration fields the form shows.

## Create the Holder

***

**Step 1**

Go to the **Holders** page. Click the **New Holder** button.

**Step 2**

A window opens. Choose the Holder type you want to create.

* If you select **Individual** (Natural Person), the **New Holder** page opens for you to enter the individual's information.
* If you select **Corporate** (Legal Person), the **New Holder** page opens for you to enter the company's information.

**Step 3**

Follow the on-screen instructions to enter the required information. Click **Create Holder**.

**Step 4**

When the creation succeeds, you see a confirmation message. The list refreshes and shows the new Holder.

## Field guide

***

### Individual

**Basic Information**

| Field | What to enter | Example |
| - | - | - |
| External ID | Optional ID from your CRM, core banking, KYC, or customer system. | `customer_123` |
| Type | A read-only field that indicates the type of Holder. | `Natural Person` |
| Name | The full name of the Holder. | `John Doe` |
| Document | Tax ID, national ID, or company registration number expected by your operation. | `12345678900` |

**Contact Information**

| Field | What to enter | Example |
| - | - | - |
| Primary Email | The main email used to contact the Holder. | `john.doe@example.com` |
| Secondary Email | An alternative email used to contact the Holder. | `john.doe2@example.com` |
| Mobile Phone | Contact phone number, including country or area code when required. | `+5511999999999` |
| Other Phone | An alternative phone number, including country or area code when required. | `+551188888888` |

**Addresses**

| Field | What to enter | Example |
| - | - | - |
| Address Line 1 | Street name and building number. | `Rua Botucatu 10` |
| Address Line 2 | Extra address details, for example, apartment or suite number. | `Casa B` |
| Zip Code | Postal or ZIP code. | `04023060` |
| City | City where the address is located. | `São Paulo` |
| State | State, province, or region. | `SP` |
| Country | Two-letter country code (ISO 3166-1 alpha-2). | `BR` |

**Personal Details**

| Field | What to enter | Example |
| - | - | - |
| Favorite Name | Nickname or preferred name. | `Johnny` |
| Social Name | Social name, if different from the legal name. | `Johnny Doe` |
| Gender | Gender identity of the person. | `Male` |
| Birth Date | Date of birth in YYYY-MM-DD format. | `1990-01-01` |
| Civil Status | Civil status, for example: Single, Married, or Divorced. | `Married` |
| Nationality | Nationality, for example, Brazilian. | `Brazilian` |
| Mother's Name | Mother's full name. | `Jane Doe` |
| Father's Name | Father's full name. | `Richard Doe` |
| Status | Current status of the individual in the system. | `Active` |

**Metadata**

| Field | What to enter | Example |
| - | - | - |
| Key | Optional classification or integration field name. | `kycStatus` |
| Value | Value for the metadata key. | `approved` |

### Corporate

**Basic Information**

| Field | What to enter | Example |
| - | - | - |
| External ID | Optional ID from your CRM, core banking, KYC, or customer system. | `company_123` |
| Type | A read-only field that indicates the type of Holder. | `Legal Person` |
| Name | The name of the company in the system. | `ACME` |
| Document | Tax ID, national ID, or company registration number expected by your operation. | `59014899000183` |

**Contact Information**

| Field | What to enter | Example |
| - | - | - |
| Primary Email | The main email used to contact the company. | `acme@example.com` |
| Secondary Email | An alternative email used to contact the Holder. | `acme2@example.com` |
| Mobile Phone | Contact phone number, including country or area code when required. | `+5511999999999` |
| Other Phone | An alternative phone number, including country or area code when required. | `+551188888888` |

**Addresses**

| Field | What to enter | Example |
| - | - | - |
| Address Line 1 | Street name and building number. | `Rua Silva 100` |
| Address Line 2 | Extra address details, for example, apartment or suite number. | `Cj 12` |
| Zip Code | Postal or ZIP code. | `04013060` |
| City | City where the address is located. | `São Paulo` |
| State | State, province, or region. | `SP` |
| Country | Two-letter country code (ISO 3166-1 alpha-2). | `BR` |

**Company Details**

| Field | What to enter | Example |
| - | - | - |
| Trade Name | The registered business name of the company, if applicable. | `ACME BR` |
| Activity | The type of business or activity the company engages in. | `Electronic devices development` |
| Legal Type | The legal structure of the company. | `Limited Liability` |
| Founding Date | The date when the company was established, in YYYY-MM-DD format. | `2025-01-01` |
| Company Size | The size classification of the company. | `Medium` |
| Status | Current status of the company in the system. | `Active` |
| Representative Name | The legal representative's name. | `Jane Doe` |
| Representative Document | The document number of the legal representative. | `43522116992` |
| Representative Email | The email address of the legal representative. | `janedoe@corporate.com` |
| Role | The role of the legal representative within the company. | `CFO` |

**Metadata**

| Field | What to enter | Example |
| - | - | - |
| Key | Optional classification or integration field name. | `kycStatus` |
| Value | Value for the metadata key. | `approved` |

## What to do next

***

After you create the Holder, create an Alias Account to connect the Holder to a Midaz ledger Account. See [Creating an Alias Account](/en/products/midaz/console/crm-creating-alias-account).

> **API equivalent**
>
> [Create Holder endpoint](/en/reference/products/midaz/v2/create-holder)


# Creating an Alias Account
Source: https://docs.lerian.studio/en/products/midaz/console/crm-creating-alias-account

Create a new Alias Account in the Midaz Module to link a Holder to a Midaz Account with banking, regulatory, and customer-facing account details.

An Alias Account links a Holder to an underlying Midaz Account and stores customer-facing account identifiers separately from ledger balances.

## Before you start

***

You need an existing Holder and an existing Midaz Account. Keep the Account ID available because this page connects Holder information to the ledger Account.

## Create the Alias Account

***

**Step 1**

Go to the **Alias Accounts** page and click the **New Alias Account** button.

**Step 2**

A window will open where you can specify the information about the account.

**Step 3**

Fill in all the necessary information and click **Create Alias Account**.

**Step 4**

If the creation is successful, you will receive a confirmation message, and the list will refresh to show the new Alias Account.

## Field guide

***

**Alias Account Details**

| Field | What to enter | Example |
| - | - | - |
| Holder ID | The unique identifier of the Holder that owns or controls this Alias Account. | `019ed1d9-7694-7bba-a721-d8e53911ab08` |
| Account ID | The unique identifier of the Account for which you want to create the Alias Account. | `019ed1eb-21f8-781c-a30f-f5fca470497d` |
| Ledger | The name of the Ledger of which the account is part. | `Test Ledger` |

**Banking Details**

| Field | What to enter | Example |
| - | - | - |
| IBAN | International Bank Account Number (IBAN) tied to the account. | `US12345678901234567890` |
| Bank ID | Bank identifier used to link the account to its institution. | `12345` |
| Branch | Branch number or code where the account is held. | `0001` |
| Account | Customer-facing account number or external account identifier. | `1234567` |
| Type | ISO 20022 account type code (for example, CACC for a current account or SVGS for savings). | `CACC` |
| Opening Date | Date when the account was opened. | `2010-01-01` |
| Country Code | ISO 3166-1 alpha-2 country code where the bank is based. | `US` |

**Regulatory**

The related party fields below (Document, Name, Role, Start Date, and End Date) belong to a repeatable **Related Parties** group. Click **Add related party** to add each related party entry.

| Field | What to enter | Example |
| - | - | - |
| Participant Document | The document number of the participant institution (e.g., CNPJ for Brazilian financial institutions). Optional field. | `---` |
| Document | Identification document of the related party (e.g., CPF or CNPJ). | `98765432100` |
| Name | Full legal name of the related party. | `Jane Doe` |
| Role | The type of relationship between the related party and the Alias Account. The select shows **Primary Holder**, **Legal Representative**, and **Responsible Party**. | `Legal Representative` |
| Start Date | Start date of the relationship with the Alias Account. | `2024-01-01` |
| End Date | End date of the relationship with the Alias Account. If not provided, the relationship is considered ongoing. | `2025-01-01` |

## What to do next

***

After creating the Alias Account, use it to identify the customer account in operational flows, or return to [Managing Alias Accounts](/en/products/midaz/console/managing-crm-alias-accounts) to review the record.

> **API equivalent**
>
> [Create Alias Account endpoint](/en/reference/products/midaz/v2/create-instrument)


# Deleting a Holder
Source: https://docs.lerian.studio/en/products/midaz/console/crm-deleting-a-holder

Delete a Holder from the Midaz Module only after the Holder has no linked Alias Accounts or Accounts, within your deployment's data-retention and compliance policies.

> [!CAUTION]
>
> Confirm your data-retention, compliance, and regulatory policies before you delete a Holder. In regulated environments, you may need to retain Holder records to meet legal, regulatory, audit, reporting, or compliance obligations.

To delete a Holder, follow these steps:

**Step 1**

On the **Holders** page, find the Holder you want to delete.

**Step 2**

In the **Actions** column, click the three dots (). Select **Delete**.

**Step 3**

A confirmation dialog appears.

**Step 4**

Click **Confirm** to delete the Holder.

## Data deletion options

***

> [!WARNING]
>
> **Regulated deployments**
>
> In environments under financial regulation (for example, BACEN, LGPD, or GDPR), mandatory retention periods can apply to Holder records tied to financial transactions. Before you hard delete in production, ask your Legal and Compliance team to review the action.

When you delete a Holder in the Console, the Midaz Module performs a **soft delete**. It marks the Holder as deleted and keeps the record in the database. The record stays available for audit.

A **hard delete** (permanently removing the record from the database) is available only through the API. Use the `?hard_delete=true` query parameter on the delete Holder endpoint. This action is irreversible, so use it only when your retention policy allows it.

> [!NOTE]
>
> Deletion fails while the Holder still has linked Alias Accounts or Accounts. Delete them before you delete the Holder.

For more information about data security and deletion, see [CRM Data Security](/en/products/midaz/crm/crm-data-security).


# Deleting an Alias Account
Source: https://docs.lerian.studio/en/products/midaz/console/crm-deleting-alias-account

Delete an Alias Account from the Midaz Module. Your deployment's data-retention and compliance policies can keep the underlying record.

> [!CAUTION]
>
> When you delete an Alias Account, the Midaz Module removes it from the active list. Your deployment's data-retention and compliance policies still apply. In a regulated environment, the underlying record can stay for audit, regulatory, or reporting purposes. Confirm your retention policy before you delete.

To delete an Alias Account, follow these steps:

**Step 1**

From the **Alias Accounts** page, find the alias account to delete.

**Step 2**

In the Actions column, click the three dots ().

**Step 3**

Select **Delete**.

**Step 4**

A confirmation dialog opens.

**Step 5**

Click **Confirm** to delete the alias account.


# Editing a Holder
Source: https://docs.lerian.studio/en/products/midaz/console/crm-editing-a-holder

Edit an existing Holder in the Midaz Module to update personal, corporate, contact, or address information and keep customer records accurate.

To edit the information of a Holder, follow these steps:

**Step 1**

From the **Holders** page, find the Holder that you want to edit.

**Step 2**

Click the three dots () from the Actions column, and select **Edit**.

**Step 3**

The Holders form will open.

**Step 4**

Edit the information as needed and click **Update Holder**.

> [!NOTE]
>
> The **Document** field stays read-only when you edit a Holder. You cannot change it after you create the Holder.


# Editing an Alias Account
Source: https://docs.lerian.studio/en/products/midaz/console/crm-editing-alias-account

Edit an existing Alias Account in the Midaz Module to update banking details or regulatory data.

To edit the information of an Alias Account, follow these steps:

**Step 1**

From the **Alias Accounts** page, find the alias account that you want to edit.

**Step 2**

Click the three dots () from the Actions column, and select **Edit**.

**Step 3**

The Alias Account form will open.

**Step 4**

Edit the information as needed and click **Update Alias Account**.


# Deleting a Ledger
Source: https://docs.lerian.studio/en/products/midaz/console/deleting-a-ledger

Delete a Ledger from your Organization in the Console when it is no longer used. Data retention and compliance policies may keep audit records available.

To delete a Ledger, follow these steps:

> [!CAUTION]
>
> Check your data retention and compliance policy before you delete a Ledger. The Console removes the Ledger from active listings, but keeps the underlying record. Your retention policy controls how long the record stays available for audit, regulatory, or reporting purposes.

**Step 1**

On the **Ledgers** page, find the Ledger you want to delete.

**Step 2**

Click the three-dot menu () in the **Actions** column. Select **Delete**.

**Step 3**

A confirmation dialog will appear.

**Step 4**

Click **Confirm** to delete the Ledger.

> [!WARNING]
>
> Midaz rejects Ledger deletion when `ENV_NAME=production`.

> [!NOTE]
>
> After you delete a Ledger, you can no longer use it. Its data may stay available for audit, regulatory, or reporting purposes, based on your retention policy.

> **API equivalent**
>
> [Delete a Ledger endpoint](/en/reference/products/midaz/v2/delete-ledger)


# Deleting a Portfolio
Source: https://docs.lerian.studio/en/products/midaz/console/deleting-a-portfolio

Delete a Portfolio from the Console when its Accounts no longer need to be grouped together, subject to your deployment's data retention rules.

> [!CAUTION]
>
> Check your data retention policy before you delete a Portfolio. The Console removes it from active listings. Your deployment can keep the underlying record for audit, regulatory, or reporting purposes.

To delete a Portfolio, follow these steps:

**Step 1**

On the **Portfolios** page, find the Portfolio to delete.

**Step 2**

In the **Actions** column, click the three-dot menu () and select **Delete**.

**Step 3**

A confirmation dialog opens.

**Step 4**

Click **Confirm** to delete the Portfolio.

> **API equivalent**
>
> [Delete a Portfolio endpoint](/en/reference/products/midaz/v2/delete-portfolio)


# Deleting a Segment
Source: https://docs.lerian.studio/en/products/midaz/console/deleting-a-segment

Delete a Segment from the Console when it no longer classifies any Accounts, subject to your deployment's data retention and compliance policies.

> [!CAUTION]
>
> When you delete a Segment, the Console removes it from active listings. Deletion follows your deployment's data retention and compliance policies. In regulated environments, the underlying record remains for audit, regulatory, or reporting purposes. Confirm your retention policy first.

To delete a Segment, follow these steps:

**Step 1**

On the **Segments** page, find the Segment to delete. In the **Actions** column, click the three dots (). Select **Delete**.

**Step 2**

A confirmation dialog opens.

**Step 3**

Click **Confirm** to delete the Segment.

**Step 4**

After you confirm, the Console removes the Segment from active listings.

> **API equivalent**
>
> [Delete a Segment endpoint](/en/reference/products/midaz/v2/delete-segment)


# Deleting an Account
Source: https://docs.lerian.studio/en/products/midaz/console/deleting-an-account

Delete an Account from your Ledger in the Console when it is no longer used. External Accounts cannot be removed and retention policies still apply.

> [!CAUTION]
>
> When you delete an Account, Midaz removes it from active listings. Your deployment's data retention and compliance policies apply. In regulated environments, your deployment can keep the record for audit, regulatory, or reporting purposes. Review your retention policy before you delete an Account.

To delete an Account, follow these steps:

**Step 1**

On the **Accounts** page, find the Account to delete. In the **Actions** column, click the three dots (), then select **Delete**.

**Step 2**

A confirmation dialog appears.

**Step 3**

Click **Confirm** to delete the Account.

**Step 4**

Midaz removes the Account from active listings. Your deployment's data retention and compliance policies still apply.

> [!NOTE]
>
> Before deleting an Account, ensure every balance has `available`, `onHold`, and `overdraftUsed` equal to zero. Otherwise, Midaz rejects the deletion.

> [!WARNING]
>
> You cannot directly delete or modify External Accounts. Midaz creates them automatically with each Asset. Deleting an Asset soft-deletes active External Accounts with the same Asset code in the same Organization and Ledger.

> **API equivalent**
>
> [Delete an Account endpoint](/en/reference/products/midaz/v2/delete-account)


# Deleting an Asset
Source: https://docs.lerian.studio/en/products/midaz/console/deleting-an-asset

Delete an Asset from your Ledger in the Console when it is no longer used. Your deployment's data retention and compliance policies still apply.

> [!CAUTION]
>
> When you delete an Asset, Midaz removes it from active listings. Your deployment's data retention and compliance policies apply. In regulated environments, your deployment can keep the record for audit, regulatory, or reporting purposes. Review your retention policy before you delete an Asset.

To delete an Asset, follow these steps:

**Step 1**

On the **Assets** page, find the Asset to delete. In the **Actions** column, click the three dots (), then select **Delete**.

**Step 2**

A confirmation dialog appears.

**Step 3**

Click **Confirm** to delete the Asset.

**Step 4**

Midaz removes the Asset from active listings. Your deployment's data retention and compliance policies still apply.

> [!NOTE]
>
> Deleting an Asset soft-deletes all active External Accounts with the same Asset code in that Organization and Ledger.

> **API equivalent**
>
> [Delete an Asset endpoint](/en/reference/products/midaz/v2/delete-asset)


# Deleting an Organization
Source: https://docs.lerian.studio/en/products/midaz/console/deleting-an-organization

Remove an Organization from the Midaz Module, subject to your deployment's data retention and compliance policies.

To delete an Organization in **Midaz Module**, follow these steps:

> [!CAUTION]
>
> When you delete an Organization, you cannot use it anymore. It no longer appears in active listings. Your deployment's data retention and compliance policies govern the record after that. In regulated environments, the record remains for audit, regulatory, or reporting purposes. Confirm your retention policy before you delete.

**Step 1**

On the **Organizations** page, find the Organization you want to delete.

**Step 2**

In the **Actions** column, click the three-dot menu ( ). Then select **Delete**.

**Step 3**

A confirmation dialog will appear.

**Step 4**

Click **Confirm** to delete the Organization.

> [!WARNING]
>
> Midaz rejects Organization deletion when `ENV_NAME=production`.

> **API equivalent**
>
> [Delete an Organization endpoint](/en/reference/products/midaz/v2/delete-organization)


# Editing a Ledger
Source: https://docs.lerian.studio/en/products/midaz/console/editing-a-ledger

Edit a Ledger from the Console to update its name, metadata, or the Validate Account Type and Validate Routes settings without any redeployment.

To view or edit the details of a Ledger, follow these steps:

**Step 1**

On the **Ledgers** page, locate the Ledger you want to view or update. Click the three dots () in the **Actions** column and select **Edit**.

**Step 2**

The edit panel opens with three tabs: **Ledger Details**, **Metadata**, and **Settings**. Use the **Ledger Details** tab to edit the Ledger name, and the **Metadata** tab to manage custom key-value pairs. Click **Save** to apply the name and metadata changes.

**Step 3**

To configure validation rules for this Ledger, click the **Settings** tab. From there you can enable **Validate Account Type** and **Validate Routes** for this Ledger. Each switch saves when you change it, and the Console shows **Ledger settings updated successfully**. The **Settings** tab has no **Save** button.

> **[Ledger Settings](/en/products/midaz/console/managing-ledgers-via-console#ledger-settings)**
>
> Learn how to enable Validate Account Type and Validate Routes for this Ledger.

> **API equivalent**
>
> [Update a Ledger endpoint](/en/reference/products/midaz/v2/update-ledger)
>
> [Update Ledger Settings endpoint](/en/reference/products/midaz/v2/update-ledger-settings)


# Editing Account information
Source: https://docs.lerian.studio/en/products/midaz/console/editing-account-information

Edit an existing Account in the Console to update its name, metadata, or other details. External Accounts created with an Asset cannot be changed.

To edit an Account, follow these steps:

**Step 1**

On the **Accounts** page, find the Account that you want to edit. In the **Actions** column, click the three dots () and select **Edit**.

**Step 2**

The edit sheet opens with three tabs: **Account Details**, **Portfolio**, and **Metadata**.

**Step 3**

Edit the information as needed and click **Save**.

> [!WARNING]
>
> You cannot edit External Accounts. Midaz creates one automatically for each Asset.

> **API equivalent**
>
> [Update an Account endpoint](/en/reference/products/midaz/v2/update-account)


# Editing an Account Type
Source: https://docs.lerian.studio/en/products/midaz/console/editing-account-type

Edit the name, description, and metadata of an existing Account Type from the Console.

To edit the information of an Account Type, follow these steps:

**Step 1**

From the **Account Types** page, find the Account Type that you want to edit, click the three dots (  ) from the **Actions** column, and select **Details**.

**Step 2**

The **Edit** form will open on the right side of the screen.

**Step 3**

Edit the information as needed and click **Save**.

> [!NOTE]
>
> You cannot change the **Key Value** when editing an Account Type. Only the name, description, and metadata are editable.

> **API equivalent**
>
> [Update an Account Type endpoint](/en/reference/products/midaz/v2/update-account-type)


# Editing an Accounting Route
Source: https://docs.lerian.studio/en/products/midaz/console/editing-an-accounting-route

Edit an existing Accounting Route in the Console to update its operation routes, validation rules, and accounting scenarios.

You can edit an existing Accounting Route. The Console edit flow changes its operation routes.

**Step 1**

Go to the **Accounting Routes** page. Find the Accounting Route to edit. Click the three dots () on the route's card. Select **Details**.

**Step 2**

A detail sheet opens on the right side of the screen. It shows the route configuration: all operation routes, their types, validation rules, and accounting entries.

**Step 3**

Click **Edit** at the bottom of the detail sheet.

**Step 4**

The edit form opens with the existing configuration already filled in. It uses the same multi-step layout as the creation wizard.

**Step 5**

Change the information as needed:

* Edit existing operation routes (title, validation type, account types or alias, accounting scenarios)
* Add new operation routes
* Remove an operation route with the delete button on its card

> [!NOTE]
>
> You cannot change the transaction route **Title** or **Description** in the Console edit flow. The edit wizard skips the basic-info step and submits operation-route changes only. You set the title and description at creation. To change them later, use the [Update Transaction Route](/en/reference/products/midaz/v2/update-transaction-route) API.

> [!WARNING]
>
> You cannot change the **Operation Type** (Source, Destination, or Bidirectional) of an existing operation route. To change the direction, delete the operation route and create a new one.

**Step 6**

Click **Update Transaction Route** to apply your changes.

## Viewing route details

***

To view an Accounting Route without editing it:

**Step 1**

Go to the **Accounting Routes** page. Click the three dots () on the route's card. Select **Details**.

**Step 2**

A detail sheet opens on the right side of the screen. It shows the route configuration: all operation routes, their types, validation rules, and accounting entries. If an operation route has a **Code** assigned (set via API), the detail sheet also shows it.

> [!TIP]
>
> You can also expand a route's card in the Accounting Routes list. The card shows a summary of its operation routes in the card-accordion view.

## Removing individual operation routes

***

You can remove a single operation route from an Accounting Route without affecting the rest of the configuration:

**Step 1**

Open the Accounting Route in **Edit** mode (via **Details** → **Edit**).

**Step 2**

Find the operation route card to remove. Click the delete button.

**Step 3**

Click **Confirm** in the dialog. The Console removes the card from the form.

**Step 4**

Click **Update Transaction Route**. The removal applies only at this step.

After the update, the Console tries to delete each removed operation route. When the ledger keeps one, the Console shows a warning with the reason. For example, another Accounting Route still uses it.

> [!WARNING]
>
> When editing, the resulting Accounting Route must contain 2–100 Operation Routes. It must include a Source and a Destination route, or at least one Bidirectional route. Midaz rejects a change that breaks this rule.

> **[Update Transaction Route](/en/reference/products/midaz/v2/update-transaction-route)**
>
> Update the transaction-level route via API.

> **[Update Operation Route](/en/reference/products/midaz/v2/update-operation-route)**
>
> Update operation-level routing rules via API.


# Editing an Organization
Source: https://docs.lerian.studio/en/products/midaz/console/editing-an-organization

Edit an Organization in the Midaz Module through the icon shortcut or the Organizations page to update legal name, address, metadata, or avatar.

There are two ways of editing the details of an Organization in **Midaz Module**.

## Editing via icon

***

To edit the Organization via the icon, follow these steps:

**Step 1**

Select the Organization switcher at the top of the left sidebar.

**Step 2**

Select **Edit** from the displayed window.

**Step 3**

You can update the following supported Organization fields:

* **Legal and Trade names**
* **Address information**
* **Parent Organization**
* **Metadata**
* **Avatar**: an image of 2 MB or less
* **Accent color**

**Step 4**

After making your changes, click **Save** to persist the supported changes.

## Editing via the Organization page

***

**Step 1**

Go to the **Organizations** page and locate the Organization you want to update.

**Step 2**

Click the three-dot menu (  ) in the **Actions** column, then select **Edit**.

**Step 3**

The Organization edit page opens, where you can edit the supported Organization fields.

**Step 4**

After making your changes, click **Save** to apply them.

> **API equivalent**
>
> [Update an Organization endpoint](/en/reference/products/midaz/v2/update-organization)


# Editing an Asset
Source: https://docs.lerian.studio/en/products/midaz/console/editing-asset-information

Edit an existing Asset from the Console to update its name or metadata without affecting balances. The Asset type itself cannot be changed later.

To edit the information of an Asset, follow these steps:

**Step 1**

From the **Assets** page, find the Asset that you want to edit, click the three dots () from the **Actions** column, and select **Edit**.

**Step 2**

The edit form opens on the right side of the screen.

**Step 3**

Edit the information as needed and click **Save**.

* You cannot change the type or the **Code** of the Asset after creation. You can edit the name and metadata.

> **API equivalent**
>
> [Update an Asset endpoint](/en/reference/products/midaz/v2/update-asset)


# Editing Portfolio information
Source: https://docs.lerian.studio/en/products/midaz/console/editing-portfolio-information

Edit an existing Portfolio in the Console to update its name, metadata, or details and keep your Account groupings accurate over time.

To edit the information of a Portfolio, follow these steps:

**Step 1**

From the **Portfolios** page, find the Portfolio that you want to edit, click the three dots () from the **Actions** column, and select **Details**.

**Step 2**

The **Portfolio Details** form will open on the right side of the screen.

**Step 3**

Edit the information as needed and click **Save**.

> **API equivalent**
>
> [Update a Portfolio endpoint](/en/reference/products/midaz/v2/update-portfolio)


# Editing Segment information
Source: https://docs.lerian.studio/en/products/midaz/console/editing-segment-information

Edit an existing Segment in the Console to update its name or metadata and refine how Accounts are classified for reporting and business rules.

To edit the information of a Segment, follow these steps:

**Step 1**

From the **Segments** page, find the Segment that you want to edit, click the three dots () from the **Actions** column, and select **Details**.

**Step 2**

The **Segment Details** form will open on the right side of the screen.

**Step 3**

Edit the information as needed and click **Save**.

> **API equivalent**
>
> [Update a Segment endpoint](/en/reference/products/midaz/v2/update-segment)


# Managing Account Types
Source: https://docs.lerian.studio/en/products/midaz/console/managing-account-types

Manage Account Types from the Midaz Module: enable Validate Account Type on a Ledger, then create and edit the categories that classify Accounts.

You use the Midaz Module to manage Account Types. Account Types classify accounts by their role in your Organization’s financial structure.

For more details, refer to the **Account Types** section on the [Accounts](/en/products/midaz/accounts#account-types) page.

### Enabling Account Type validation

You enable Account Type validation for a specific Ledger from the **Lerian Console**. You do not edit environment configuration files.

**1. Open the Ledger Settings**

On the **Ledgers** page, click the three dots () next to the Ledger. Select **Edit**. In the edit panel, click the **Settings** tab.

**2. Enable Validate Account Type**

Toggle on the **Validate Account Type** switch. The Console saves the change when you toggle the switch.

> [!WARNING]
>
> The Type field is required whether or not validation is on. Validation changes the Type field from free text to a dropdown restricted to the registered Account Types.

## Accessing the Account Types page

***

To open the **Account Types** page, select the **Account Types** option in the **Foundation** section of the left sidebar menu.

> [!NOTE]
>
> The **Account Types** menu item appears only when you enable **Validate Account Type** for the active Ledger. If validation is off, the menu item is hidden.

The **Account Types** page lists all Account Types you created for the current Ledger.

> [!WARNING]
>
> **Account type validation disabled**. If **Validate Account Type** is off, a banner appears at the top of this page. You can view and edit the registered account types. The Ledger does not validate these rules when you create accounts. To enforce the rules, turn on **Validate Account Type** in the Ledger settings.

### Available actions

From the **Account Types** page, you can:

> **[Create an Account Type](/en/products/midaz/console/creating-an-account-type)**

> **[Edit an Account Type](/en/products/midaz/console/editing-account-type)**


# Managing Accounting Routes
Source: https://docs.lerian.studio/en/products/midaz/console/managing-accounting-routes

Manage Accounting Routes in the Console: create, edit, or delete Source, Destination, and Bidirectional operation routes and accounting scenarios.

Use the **Midaz Module** to manage **Accounting Routes**, the configuration for transaction routing in Midaz. A guided wizard walks you through three steps: define the transaction route, add the operation routes, and review the setup.

An Accounting Route defines the full routing logic for a transaction. It has three parts:

* The transaction-level metadata is the title and description.
* The operation routes set which accounts participate and in which direction.
* The accounting scenarios control how the ledger records entries for each transaction type.

> **[Accounting rules](/en/products/midaz/console/mc-accounting)**
>
> Start here if you need to decide whether to use Source, Destination, Bidirectional, Account Type validation, alias validation, Direct, Two-Step, or Reversal scenarios.

For technical details on the underlying entities, refer to the [Accounting Routes entities](/en/products/midaz/transaction-routing-entities) page.

## Key concepts

***

### Operation route types

Each operation route within an Accounting Route has one of three types:

* **Source**: defines validation rules for accounts where funds originate (debit side)
* **Destination**: defines validation rules for accounts that receive funds (credit side)
* **Bidirectional**: applies to both sides of the transaction as both source and destination

> [!NOTE]
>
> A valid Accounting Route requires at least one source and one destination operation route, or at least one bidirectional route.

> [!TIP]
>
> A bidirectional route works as both source and destination.

### Validation types

Each operation route validates accounts by one of two methods:

* **Account Type**: validates against one or more account type categories (e.g., `checking`, `savings`). Use when any account of a certain type is valid.
* **@Alias**: validates against a specific account alias (e.g., `@treasury_main`). Use when you need to target an exact account.

### Accounting scenarios

Accounting scenarios define how the ledger records debit and credit entries for each operation route. You can configure entries for five transaction types:

* **Direct Transaction**: standard one-step transaction. Define the debit and credit account codes and descriptions for immediate settlement.
* **Two-Step Transaction**: transactions that go through a hold-then-commit cycle. Configure entries for:
  * **Hold (Value Reserve)**: entries recorded when the ledger reserves funds
  * **Commit (Reservation Confirmation)**: entries recorded when you confirm the reservation
  * **Cancel (Reservation Cancellation)**: entries recorded when you cancel the reservation
* **Reversal**: entries recorded when you reverse a completed transaction
* **Overdraft**: entries recorded when a debit exceeds the account's available funds and draws on an overdraft line. Available for Source and Bidirectional operation routes, and requires both debit and credit entries on every supported route type. When you enable it, the Console also enables the Direct scenario.
* **Block/Unblock**: entries recorded when you hold and release funds on the account's balance. The scenario tab label is **Block**. Available for all operation route types.

Each scenario entry includes an **Account Code** and a **Description** for both the debit and credit sides.

> [!TIP]
>
> The available entry sides depend on the operation route type and the scenario phase. The general rule is:
>
> * **Source**: debit entries in Direct, Hold, Commit, and Cancel. Credit entries only in Hold and Cancel.
> * **Destination**: credit entries only, in Direct and Commit. Hold and Cancel are not available.
> * **Bidirectional**: both debit and credit entries in all phases, including Reversal.
> * **Block/Unblock**: available for all route types. It holds and releases funds on the account's balance.

## Accessing the Accounting Routes page

***

> [!NOTE]
>
> The **Accounting Routes** menu appears only when you enable the **Validate Routes** setting for the current Ledger. To enable it, select **Edit** for the Ledger, go to the **Settings** tab, and toggle the **Validate Routes** switch.

> [!WARNING]
>
> **Accounting Routes validation disabled**. If you open this page by URL while **Validate Routes** is off, a banner appears at the top of the screen. The Ledger does not yet process the accounting routes registered here. Entries follow these rules only after you enable **Validate Routes** in the Ledger settings. You can still view and edit routes, but they have no effect until you enable validation.

To open the **Accounting Routes** page, select **Accounting Routes** in the **Accounting** section of the left sidebar menu.

The **Accounting Routes** page displays your routes for the current Ledger as a **card-accordion list**. Each transaction route is a collapsible card. The card shows its title, transaction route ID, and an operation-count badge.

Expand a card to view its operation routes. Each one shows its ID, title, code, and operation type. The Console color-codes operation types: **source** in red, **destination** in green, and **bidirectional** in gray. A route with no operation routes appears as a static (non-expandable) card.

### Available actions

From the **Accounting Routes** page, you can:

> **[Create an Accounting Route](/en/products/midaz/console/creating-an-accounting-route)**
>
> Define a new transaction route with operation routes and accounting scenarios.

> **[Edit an Accounting Route](/en/products/midaz/console/editing-an-accounting-route)**
>
> Modify an existing accounting route and its operation routes.

## Common use cases

***

> **Pix transfers**
>
> Create an Accounting Route with a bidirectional operation route that validates `checking` and `savings` account types. Enable Direct Transaction scenarios with the appropriate chart of accounts codes for Pix settlement entries.

> **Two-step payment authorization**
>
> Create an Accounting Route with separate source and destination routes. Enable Two-Step Transaction scenarios to record the hold (reservation), commit (confirmation), and cancel (cancellation) entries. On the source route, the ledger validates the hold, commit, and cancel entries as an atomic group.

> **Treasury operations with reversal**
>
> Create an Accounting Route with a bidirectional operation route that uses alias validation (`@treasury_main`). Enable both Direct Transaction and Reversal scenarios to handle standard movements and their reversals. Reversal entries require a bidirectional route.

## Best practices

***

**1. Use descriptive titles**

Name your Accounting Routes clearly to indicate the type of transaction they handle (e.g., `Pix Transfer Route` instead of `Route 1`).

**2. Choose the right operation type**

Use **Bidirectional** when the same validation rules apply to both sides. Use separate **Source** and **Destination** routes when each side has different account requirements.

**3. Configure accounting scenarios early**

Define your chart of accounts entries during route creation. This ensures that transactions processed through the route produce correct accounting records from the start.

**4. Review before confirming**

The wizard includes a Review step. Use it to verify all operation routes, validation rules, and accounting entries before you create the route.


# Managing Accounts
Source: https://docs.lerian.studio/en/products/midaz/console/managing-accounts

Manage Accounts from the Lerian Console: create, edit, and delete internal Accounts, view balances, and classify them by type, portfolio, or segment.

Use **Midaz Module** to manage **Accounts** associated with your Ledger. Accounts hold balances and participate in transactions within your financial system.

## What are Accounts?

***

Accounts represent individual balance holders within your ledger structure. Each account:

* **Holds balances** in a specific asset
* **Participates in transactions** as sources or destinations of funds
* **Belongs to an entity** such as a customer, business unit, or external party
* **Supports portfolios, segments, and account types** for organization and reporting
* **Tracks history** with complete audit trails of all movements

Accounts can be classified as:

* **Internal Accounts** - Accounts you create and manage for your organization's operations
* **External Accounts** - Represent external assets or liabilities. Midaz creates one when you create an Asset, and you can create others with the **External account** option

For technical details, refer to the [Accounts](/en/products/midaz/accounts) page.

## Key concepts

***

* **Account Types** - Classify accounts according to your organization's financial structure (e.g., `checking`, `savings`, `revenue`). Enable validation to enforce account type rules.

* **Account Alias** - A unique, human-readable identifier (e.g., `@customer_john_doe`) that makes it easier to reference accounts in transactions and queries.

* **Portfolios** - Group related accounts together for reporting and management purposes. Useful for tracking customer portfolios or business divisions.

* **Segments** - Group accounts by cost center, department, or region.

## Accessing the Accounts page

***

To open the **Accounts** page, select the **Accounts** option in the **Accounts** section of the left sidebar menu.

The **Accounts** page displays a table with all Accounts in the current Ledger, including:

* **Account Name** - The account's display name
* **ID** - The account's unique identifier
* **Account Alias** - The unique, human-readable alias (if set)
* **Assets** - The asset the account holds
* **Metadata** - The number of custom key-value pairs on the account
* **Portfolio** - The portfolio the account belongs to (if any)
* **Actions** - The three-dots menu with the available actions. External accounts show a padlock icon  instead

> [!NOTE]
>
> The padlock icon  marks an **external account**, which you cannot edit or delete.

### Available actions

From the **Accounts** page, you can:

> **[Create an Account](/en/products/midaz/console/creating-an-account)**
>
> Add internal accounts for customers, departments, or business operations

> **[Edit Account information](/en/products/midaz/console/editing-account-information)**
>
> Modify account details, metadata, and organizational settings

> **[Delete an Account](/en/products/midaz/console/deleting-an-account)**
>
> Delete accounts you no longer need (internal accounts only)

## Account organization strategies

***

> **Customer Account structure**
>
> Create separate accounts for each customer, organized by account type and asset code.
>
> **Example**:
>
> * Customer checking account: `@customer_123_checking` (Type: `checking`, Asset: `USD`)
> * Customer savings account: `@customer_123_savings` (Type: `savings`, Asset: `USD`)
> * Group both under a Portfolio: `Customer 123 Portfolio`

> **Treasury and float management**
>
> Create dedicated treasury accounts to manage liquidity and operational funds.
>
> **Example**:
>
> * Main treasury: `@treasury_main` (Type: `treasury`, Asset: `USD`)
> * Reserve fund: `@treasury_reserve` (Type: `reserve`, Asset: `USD`)
> * Float account: `@float_operations` (Type: `float`, Asset: `USD`)

> **Multi-currency operations**
>
> Create separate accounts for each currency your organization handles.
>
> **Example**:
>
> * USD operations: `@ops_usd` (Type: `operations`, Asset: `USD`)
> * EUR operations: `@ops_eur` (Type: `operations`, Asset: `EUR`)
> * BRL operations: `@ops_brl` (Type: `operations`, Asset: `BRL`)

> **Department cost centers**
>
> Use segments and account types to track departmental expenses.
>
> **Example**:
>
> * Engineering expenses: `@eng_expenses` (Type: `expense`, Segment: `Engineering`)
> * Marketing expenses: `@mkt_expenses` (Type: `expense`, Segment: `Marketing`)

## Account type validation

***

Account type validation makes each account follow your organization's financial structure.

### Enabling Account type validation

Account type validation is a per-ledger setting. To turn it on in the Console: on the **Ledgers** page, select **Edit** for the Ledger, click the **Settings** tab, and toggle on **Validate Account Type**.

As a programmatic alternative, send a `PATCH` request to `/v1/organizations/{organization_id}/ledgers/{ledger_id}/settings` with this body:

```json theme={null}
{
  "accounting": {
    "validateAccountType": true
  }
}
```

For more information about managing account types, see [Managing Account Types](/en/products/midaz/console/managing-account-types).

## Best practices

***

**1. Use descriptive names and aliases**

Name accounts clearly and use aliases for easy reference (e.g., `@customer_john_checking` instead of UUID references).

**2. Use account types**

Enable account type validation to enforce your chart-of-accounts structure and prevent misclassification.

**3. Organize with portfolios**

Group related accounts into portfolios for better reporting and management, especially for customer relationships.

**4. Plan your asset codes**

Use consistent asset code conventions (ISO 4217 for currencies) to simplify multi-currency operations.

**5. Document with metadata**

Use metadata fields to store additional context like customer IDs, department codes, or integration references.


# Managing Assets
Source: https://docs.lerian.studio/en/products/midaz/console/managing-assets

Manage the Assets registered in your Ledger from the Midaz Module: create, edit, and delete the currencies, tokens, or commodities you use.

You can manage the Assets associated with your Ledger directly from **Midaz Module**.

## Accessing the Asset page

***

To open the **Assets** page, select the **Assets** option in the **Foundation** section of the left sidebar menu.

The **Assets** page will display a list of **Assets** created for the current Ledger.

### Available actions

From the **Assets** page, you can:

> **[Create an Asset](/en/products/midaz/console/creating-an-asset)**

> **[Edit an Asset](/en/products/midaz/console/editing-asset-information)**

> **[Delete an Asset](/en/products/midaz/console/deleting-an-asset)**


# Managing Balances
Source: https://docs.lerian.studio/en/products/midaz/console/managing-balances

Manage Account Balances from the Lerian Console: list, read, and create balances, and control sending and receiving permissions without leaving the interface.

Use the **Midaz Module** to manage the **Balances** in your Accounts. A balance tracks one asset in one account. It records the available amount and the on-hold amount. You find balances in the **Balances** section of the account details page.

## What you can do

* **List balances** for an account to see the available and on-hold amounts per balance key.
* **Read a balance** to inspect its current state and metadata.
* **Create an additional balance** for an account under a new balance key. The balance inherits the account's asset.
* **Update a balance** to toggle whether it can send or receive funds (**Send** and **Receive** in **Balance Details**).

> [!NOTE]
>
> You manage overdraft limits through the update-balance API, not the Console.

> [!NOTE]
>
> The Console UI does not support balance history or balance deletion.


# Managing Alias Accounts
Source: https://docs.lerian.studio/en/products/midaz/console/managing-crm-alias-accounts

Manage Alias Accounts in the Midaz Module: create, edit, and delete customer-facing account records that link Holders to their underlying Accounts.

Use **Midaz Module** to manage **Alias Accounts**. Alias Accounts create the link between Holders and Midaz ledger accounts. They add business context such as bank account numbers and financial institution details.

## What are Alias Accounts?

***

An **Alias Account** connects a Holder (individual or company) to a specific Midaz ledger account. In Midaz Module, each alias account stores:

* **Account identification** - Bank ID, branch, account, and type
* **Holder reference** - Link to the associated holder (Natural or Legal Person)
* **Ledger account link** - Connection to the underlying Midaz account
* **Banking details** - Opening date, IBAN, country code, and the Participant Document under Regulatory
* **Related parties** - People linked to the account, each with a role and a start date, under Regulatory
* **Custom metadata** - Additional fields for integration and business-specific needs

Alias Accounts let you keep customer-facing account information separate from the transactional ledger. This supports multi-bank scenarios and external system integration.

For technical details about the underlying CRM capabilities, refer to the [CRM Overview](/en/products/midaz/crm/crm-overview) page.

## Accessing the Alias Accounts page

***

To open the **Alias Accounts** page, select the **Alias** option from the Accounts section of the left-side menu.

With Access Manager, this page needs the read permission on instruments. To create, edit, or delete an alias account, you need the create, update, or delete permission on instruments.

The **Alias Accounts** page displays a table listing the Alias Accounts of the current Organization, including:

* **Holder Name** - The associated holder name
* **Holder ID** - The identifier of the associated holder
* **Account ID** - The identifier of the linked ledger account
* **Ledger** - The ledger the linked account belongs to
* **Type** - Classification of the account (checking, savings, etc.)
* **Actions** - The actions available for each alias account

> [!NOTE]
>
> If you do not have any Alias Accounts, the list will appear empty with a prompt to create your first alias account.

### Available actions

From the **Alias Accounts** page, you can:

> **[Create an Alias Account](/en/products/midaz/console/crm-creating-alias-account)**
>
> Link a holder to a Midaz ledger account with bank details

> **[Edit an Alias Account](/en/products/midaz/console/crm-editing-alias-account)**
>
> Update account information and financial details

> **[Delete an Alias Account](/en/products/midaz/console/crm-deleting-alias-account)**
>
> Remove the link between a holder and ledger account

## Common use cases

***

> **Linking customer accounts**
>
> When a customer opens an account:
>
> 1. Create a Holder with customer information (Natural or Legal Person)
> 2. Create an Alias Account linking the holder to a Midaz ledger account
> 3. Add banking details (bank ID, branch, account, type)

> **Multi-bank scenarios**
>
> When customers have accounts at multiple institutions:
>
> * Create multiple Alias Accounts for the same Holder
> * Each alias account references a different Midaz ledger account
> * Track different account numbers and bank relationships
> * Maintain clear separation between institutional relationships

> **External system integration**
>
> When integrating with external banking systems:
>
> * Use Alias Accounts to map external account numbers to internal ledger accounts
> * Store regulatory identifiers such as the Participant Document

## Best practices

***

**1. Create holders before alias accounts**

Always create the Holder record first, then create Alias Accounts to link them to ledger accounts.

**2. Use consistent account numbering**

Follow your institution's account numbering standards when creating alias accounts to avoid confusion and integration issues.

**3. Keep financial institution details accurate**

Ensure Bank IDs and other banking details are correct for proper payment routing and regulatory compliance.


# Managing Holders
Source: https://docs.lerian.studio/en/products/midaz/console/managing-crm-holders

Manage Holders in the Midaz Module: create, edit, and delete individuals or companies with their identity, contact, and address information.

Use the **Midaz Module** to manage **Holders**. Holders represent the people or organizations behind your accounts. In the console, you create, view, edit, and manage their information.

## What are Holders?

***

A **Holder** represents an individual (Natural Person) or a company (Legal Person) linked to your Midaz accounts. Each holder stores:

* **Identity information** - Name, document number (CPF/CNPJ), and an optional free-text status
* **Contact details** - Email addresses and phone numbers for communication
* **Address information** - Primary and additional addresses with complete location data
* **Person-specific data** - Personal details for individuals or business information for companies
* **Custom metadata** - Additional fields for integration and business-specific needs

Holders connect to ledger accounts through Alias Accounts. This keeps customer data separate from transactional operations.

For technical details about the underlying CRM capabilities, refer to the [CRM Overview](/en/products/midaz/crm/crm-overview) page.

## Accessing the Holders page

***

To open the **Holders** page, select the **Holders** option from the Accounts section of the left-side menu.

The **Holders** page shows a table with the Holders of the current Organization.

### Available actions

From the **Holders** page, you can:

> **[Create a Holder](/en/products/midaz/console/crm-creating-a-holder)**
>
> Add new individuals or companies as Holders

> **[Edit a Holder](/en/products/midaz/console/crm-editing-a-holder)**
>
> Update holder information, contact details, and status

> **[Delete a Holder](/en/products/midaz/console/crm-deleting-a-holder)**
>
> Remove holders (soft delete). Hard delete is available only through the API (`?hard_delete=true`)

## Understanding Holder types

***

When you create a Holder, you select the holder type. The type determines which fields you can manage:

### Natural Person (Individual)

For individual customers, the console shows fields for:

* **Basic information**: Full name, document (CPF), contact details
* **Personal details**: Favorite name, social name, gender, birth date
* **Family information**: Civil status, mother's name, father's name
* **Demographics**: Nationality

### Legal Person (Company)

For corporate customers, the console shows fields for:

* **Basic information**: Company name, document (CNPJ), contact details
* **Business details**: Trade name, company activity, founding date
* **Structure**: Company size, company type, business status
* **Legal representation**: Representative name, document, role, contact

## Managing Holder status

***

**Status** is an optional free-text field on the holder form. Use it to record any classification your business needs, such as `active` or `under-review`.

> [!NOTE]
>
> To change the status, edit the holder. The holders list shows the **Name**, **ID**, **Type**, and **Primary E-mail** columns. Open a holder to see its status.

## Common use cases

***

> **Setting up individual customers**
>
> To onboard individual customers in the console:
>
> 1. Create a Natural Person holder with personal details
> 2. Add primary address and contact information
> 3. Link to checking/savings accounts via Alias Accounts
> 4. Use metadata for customer-specific attributes (loyalty tier, risk profile, etc.)

> **Managing business customers**
>
> To manage corporate accounts in the console:
>
> 1. Create a Legal Person holder with company information
> 2. Add legal representative details for compliance
> 3. Include business addresses and contact points
> 4. Link to corporate treasury and operational accounts
> 5. Track company size and activity sector for reporting

> **Integrating with external systems**
>
> Use the External ID field in the console to keep systems in sync:
>
> * Map each holder to your existing CRM using External ID
> * Keep document numbers consistent across systems
> * Use metadata for integration-specific fields
> * Update status in the console to reflect external system changes

## Best practices

***

**1. Choose the correct holder type at creation**

Select Natural Person for individuals and Legal Person for companies. You cannot change the type later. The type sets which fields the console forms show.

**2. Keep document numbers accurate**

Document numbers (CPF, CNPJ) must be unique and correctly formatted. The document field is required, but the console does not validate its format. Verify the numbers yourself for regulatory compliance.

**3. Maintain updated contact information**

Update email addresses and phone numbers in the console regularly.

**4. Use External ID for integration**

When you create a holder, fill in the External ID field. It maps the holder to your existing customer database.

**5. Use metadata for custom needs**

Use the Metadata step in the holder form to store extra information. You do not change the core structure.

**6. Keep the status field meaningful**

If you use the optional status field, define a consistent set of values for your team and update it to reflect customer relationship changes before deletion.


# Managing Ledgers
Source: https://docs.lerian.studio/en/products/midaz/console/managing-ledgers-via-console

Manage Ledgers in your Organization from the Midaz Module: create, edit, and delete them, and enable Validate Account Type or Validate Routes.

A Ledger groups the Accounts and Transactions in your Organization. You manage these Ledgers from the **Midaz Module**.

## Current Ledger

***

The name of the current Ledger appears in the header of the home page (*Figure 1*).

![Home page header section displaying the name of the currently selected Ledger](https://mintcdn.com/lerian-49cb71fc/yneNeAhnXdrrmE3_/images/en/console/home-header-ledger.png?fit=max\&auto=format\&n=yneNeAhnXdrrmE3_\&q=85\&s=2b259ca02ffe000365bc5159be069b74)

Figure 1. Section displaying the name of the current Ledger.

## Accessing the Ledgers page

***

To open the **Ledgers** page, click the **Ledgers** option in the **Foundation** section of the left sidebar menu.

The **Ledgers** page lists the Ledgers in your Organization and marks the current one with **(current)**.

### Available actions

From the **Ledgers** page, you can:

> **[Create a new Ledger](/en/products/midaz/console/creating-a-new-ledger)**

> **[Edit a Ledger](/en/products/midaz/console/editing-a-ledger)**

> **[Delete a Ledger](/en/products/midaz/console/deleting-a-ledger)**

## Ledger settings

***

Each Ledger has a **Settings** tab where you can enable validation rules for Accounts and Transactions.

**1. Open the Ledger edit panel**

On the **Ledgers** page, find the Ledger you want to configure. Click the three dots () in the **Actions** column. Select **Edit**.

**2. Open Settings**

In the edit panel, click the **Settings** tab.

**3. Update validation rules**

Enable or disable **Validate Account Type** and **Validate Routes** for this Ledger. The Console saves each change when you toggle the switch.

### Available settings

| Setting | What it controls | When to enable |
| - | - | - |
| Validate Account Type | Requires new Accounts to use an Account Type registered for this Ledger. | Enable when Accounts must follow a controlled classification model. |
| Validate Routes | Requires Transactions to match configured Accounting Routes. | Enable after your Accounting Routes are planned or configured. |

> [!WARNING]
>
> Do not enable **Validate Routes** before your Accounting Routes exist. A Transaction that does not match a route fails validation.


# Managing the Metadata Index
Source: https://docs.lerian.studio/en/products/midaz/console/managing-metadata-index

Manage the Metadata Index from the Lerian Console: list, create, and remove indexed metadata keys to speed up searches across your Midaz entities.

Use the **Midaz Module** to manage the **Metadata Index**. Metadata indexes let you efficiently query entities by the custom key/value metadata you attach to organizations, ledgers, accounts, transactions, and other resources.

## What you can do

* **List indexes** to see which metadata keys have an index.
* **Create an index** on a metadata key to speed up lookups and filters on that key.
* **Remove an index** when you no longer query that metadata key.

To open the page, select **Metadata Indexes** in the **Settings** section of the left sidebar menu. To create an index, choose an **Entity Name** and enter a **Metadata Key**. **Unique** is off by default. **Sparse** is on by default.

Keep the index focused on the keys you query. This keeps search fast and predictable.


# Managing Operation Routes
Source: https://docs.lerian.studio/en/products/midaz/console/managing-operation-routes

Manage Operation Routes in the Console: list, create, edit, and delete the rules that select the accounts on each side of a transaction.

Use the **Midaz Module** to manage the **Operation Routes** of the current Ledger. An operation route is a rule for one side of a transaction. It sets which accounts can take part in that side.

You can also create operation routes inside an Accounting Route. For the full routing model, refer to [Managing Accounting Routes](/en/products/midaz/console/managing-accounting-routes) and [Accounting Routes entities](/en/products/midaz/transaction-routing-entities).

## Accessing the Operation Routes page

***

> [!NOTE]
>
> The **Accounting** section of the sidebar appears only when you enable the **Validate Routes** setting for the current Ledger. To enable it, select **Edit** for the Ledger, go to the **Settings** tab, and toggle the **Validate Routes** switch.

To open the page, select **Operation Routes** in the **Accounting** section of the left sidebar menu.

> [!WARNING]
>
> **Operation Routes validation disabled**. If you open this page by URL while **Validate Routes** is off, a banner appears at the top of the screen. The Ledger does not process the operation routes registered here. Entries follow these rules only after you enable **Validate Routes** in the Ledger settings.

The page lists the operation routes of the current Ledger in a table:

| Column | Content |
| - | - |
| **Title** | The name of the operation route. |
| **Description** | The description of the operation route. |
| **Operation Type** | The side of the transaction that the route validates. |
| **Rule Type** | The validation rule. Hover over the value to see the alias or the Account Types that the rule accepts. |
| **Metadata** | The metadata of the operation route. |
| **Actions** | The menu with the **Details** and **Delete** options. |

If the Ledger has no operation routes, the page shows the message **You haven't created any Operation Routes yet.** and a **New Operation Route** button.

## Creating an operation route

***

**1. Open the form**

Select **New Operation Route**. A side panel opens with two tabs: **Operation Route Details** and **Metadata**.

**2. Fill in the details**

On the **Operation Route Details** tab, fill in the fields in the table below.

**3. Add metadata (optional)**

On the **Metadata** tab, add key-value pairs.

**4. Save the route**

Select **Save**. A message confirms that the Console created the operation route.

| Field | Required | Description |
| - | - | - |
| **Operation Route Name** | Yes | The title of the operation route. |
| **Description** | No | A description of the operation route. |
| **Operation Type** | Yes | **Source** or **Destination**. You cannot change it after you create the route. |
| **Rule Type** | Yes | **Alias** or **Account Type**. |
| **Account Alias** | Yes, for the **Alias** rule | Search for the account by its alias and select it. |
| **Account Types** | Yes, for the **Account Type** rule | Select one or more Account Types of the Ledger. |
| **Code** | No | A code for the operation route. |

> [!NOTE]
>
> This form has no **Bidirectional** option and no accounting scenarios. To set them, use the wizard in [Creating an Accounting Route](/en/products/midaz/console/creating-an-accounting-route).

## Editing an operation route

***

**1. Open the route**

In the row of the operation route, click the three dots () and select **Details**. The edit panel opens with the current values.

**2. Change the fields**

Change the fields on the **Operation Route Details** and **Metadata** tabs. You cannot change the **Operation Type** field.

**3. Save the changes**

Select **Save**. A message confirms that the Console updated the operation route.

## Deleting an operation route

***

**1. Select Delete**

In the row of the operation route, click the three dots () and select **Delete**.

**2. Confirm the deletion**

In the confirmation dialog, select **Confirm**. A message confirms that the Console deleted the operation route.

## Permissions

***

With Access Manager, this page needs the read permission on operation routes. To create, edit, or delete an operation route, you need the create, update, or delete permission on operation routes.


# Viewing Operations
Source: https://docs.lerian.studio/en/products/midaz/console/managing-operations

View the Operations that make up a Transaction in the Lerian Console: inspect each balance movement per account and its metadata.

Use the **Midaz Module** to review the **Operations** that compose each Transaction. Operations are individual balance movements. Depending on the transaction lifecycle, their type can be `DEBIT`, `CREDIT`, `ON_HOLD`, `RELEASE`, `OVERDRAFT`, `BLOCK`, or `UNBLOCK`.

## What you can do

* **View operation details** to see the type, direction, asset, amount, status, balance key, and accounting route. The details also show the balance before and after the operation, along with any metadata.

> [!NOTE]
>
> You cannot edit the operation details sheet. To update operation metadata, use the update-operation API.

Operations always belong to a parent Transaction. You open them from the transaction detail view or from the **Operations Statement** section on the account details page.


# Managing Organizations
Source: https://docs.lerian.studio/en/products/midaz/console/managing-organizations

Manage Organizations in the Midaz Module: create, edit, delete, and switch between the top-level entities that own your Ledgers and Accounts.

The Midaz module lets you manage your Organizations directly. You can create, edit, delete, and switch between them.

## Accessing the Organizations page

***

To open the **Organizations** page, click the **Organizations** option in the **Foundation** section of the left sidebar menu.

The **Organizations** page lists all your Organizations.

### Available actions

From the **Organizations** page, you can:

> **[Create an Organization](/en/products/midaz/console/creating-an-organization)**

> **[Edit an Existing Organization](/en/products/midaz/console/editing-an-organization)**

> **[Delete an Organization](/en/products/midaz/console/deleting-an-organization)**

## Multiple Organizations

***

You can also open the **Organizations** page from the navigation bar. Click the Organization icon in the left navigation bar. Then select **Organizations** in the pop-up window (*Figure 1*).

![Alternative way to open the Organizations page, using the organization icon in the left navigation bar](https://mintcdn.com/lerian-49cb71fc/yneNeAhnXdrrmE3_/images/en/console/organizations_menu_alt.png?fit=max\&auto=format\&n=yneNeAhnXdrrmE3_\&q=85\&s=a4af7abcf3575db2fe6517eb995ff14a)

Figure 1. Alternative options to open the Organizations page for multiple Organizations.

### Changing Organizations

To work on a different Organization, use the same pop-up window. It lists up to three other Organizations that you can select directly. To see all of them, select the cog icon ().

The **Organizations** page opens. Find the Organization you want. Click the three dots () in the **Actions** column. Then select **Switch to this organization**.


# Managing Portfolios
Source: https://docs.lerian.studio/en/products/midaz/console/managing-portfolios

Manage Portfolios from the Lerian Console: create, edit, and delete the containers that group related Accounts under a customer or business unit.

Use **Midaz Module** to manage **Portfolios** that group your accounts. A Portfolio gives your accounts a higher-level structure. You manage a set of accounts as a single unit.

## What are Portfolios?

***

A **Portfolio** is a container that groups related accounts within a ledger. In Midaz Module, portfolios enable you to:

* **Group related accounts** - Organize accounts that belong together logically or operationally
* **Associate with external entities** - Link portfolios to external system identifiers via Entity ID
* **Simplify account management** - Manage multiple accounts as a single unit
* **Add custom context** - Store additional information through metadata for integration and reporting

Portfolios are ledger-specific. Each ledger has its own set of portfolios.

For technical details about portfolios in Midaz, refer to the [Portfolios documentation](/en/products/midaz/portfolios).

## Accessing the Portfolios page

***

To open the **Portfolios** page, select the **Portfolios** option from the Accounts section of the left-side menu.

The **Portfolios** page displays a table of all Portfolios in your Ledger.

> [!NOTE]
>
> If you have no Portfolios, the list is empty and shows a prompt to create your first Portfolio.

### Available actions

From the **Portfolios** page, you can:

> **[Create a Portfolio](/en/products/midaz/console/creating-a-portfolio)**
>
> Add a new portfolio to group your accounts

> **[Edit a Portfolio](/en/products/midaz/console/editing-portfolio-information)**
>
> Update portfolio name and metadata

> **[Delete a Portfolio](/en/products/midaz/console/deleting-a-portfolio)**
>
> Remove a portfolio from your ledger

## Common use cases

***

> **Customer account grouping**
>
> Create portfolios to group all accounts belonging to a single customer:
>
> * Portfolio: `Customer-12345` with Entity ID linking to your CRM
> * Contains: Checking account, savings account, investment accounts
> * Use metadata for customer tier, relationship manager, onboarding date

> **Product-based organization**
>
> Organize accounts by financial product:
>
> * `Checking Accounts Portfolio` - All customer checking accounts
> * `Savings Accounts Portfolio` - All customer savings accounts
> * `Business Accounts Portfolio` - All commercial/business accounts
> * `Investment Accounts Portfolio` - All investment-related accounts

> **Institutional portfolios**
>
> Group accounts by institution or partner:
>
> * `Partner Bank A` - Accounts related to Partner Bank A operations
> * `Partner Bank B` - Accounts for Partner Bank B integration
> * Use Entity ID to link to partner identifiers in your system

> **Operational grouping**
>
> Create portfolios for operational purposes:
>
> * `Treasury Operations` - Internal treasury and liquidity accounts
> * `Settlement Accounts` - Accounts used for settlement operations
> * `Suspense Accounts` - Temporary holding accounts for reconciliation
> * `Fee Collection` - Accounts for collecting and managing fees

## Best practices

***

**1. Plan your portfolio structure**

Design your portfolio structure before you create accounts. Decide how to group the accounts and which Entity IDs to use for external systems.

**2. Use Entity ID for integration**

Set the Entity ID during creation when a portfolio links to an external system (CRM, core banking). External systems can then match the portfolio to their own records.

**3. Choose meaningful names**

Use portfolio names that clearly indicate the purpose or contents of the portfolio.

**4. Use metadata for context**

Use the Metadata tab to store extra details. Add business unit codes, cost centers, or integration references that do not fit in the standard fields.

**5. Keep portfolios focused**

Each portfolio should have a clear purpose. Do not create catch-all portfolios. Instead, create a specific portfolio for each use case.

## Portfolios vs Segments

***

Both Portfolios and Segments help organize accounts, but they serve different purposes:

| Feature | Portfolio | Segment |
| - | - | - |
| **Purpose** | Group related accounts as a unit | Classify accounts by category |
| **Entity ID** | Yes - links to external entities | No |
| **Use Case** | Customer accounts, product grouping | Departmental, regional classification |
| **Relationship** | One-to-many (portfolio contains accounts) | One-to-many (segment classifies accounts) |

You can use portfolios and segments together to organize accounts. For example, accounts in a customer portfolio can also belong to a segment (checking, savings, investment).


# Managing Segments
Source: https://docs.lerian.studio/en/products/midaz/console/managing-segments

Manage Segments from the Console: create, edit, and delete the classifications used to group Accounts by department, region, or business function.

Use **Midaz Module** to manage **Segments** that help you organize and categorize your accounts. Segments group accounts by business purpose, department, region, or any other classification relevant to your organization.

## What are Segments?

***

A **Segment** is an organizational unit that helps you classify and group accounts within a ledger. In Midaz Module, segments enable you to:

* **Organize accounts by purpose** - Group accounts by business function, department, or product line
* **Apply business classifications** - Use segments to filter and analyze accounts by classification
* **Maintain flexibility** - Add custom metadata for integration and business-specific needs

Segments are ledger-specific. Each ledger can have its own set of segments.

For technical details about segments in Midaz, refer to the [Segments documentation](/en/products/midaz/segments).

## Accessing the Segments page

***

To open the **Segments** page, select the **Segments** option on the Accounts section of the left-side menu.

The **Segments** page displays a table listing all Segments in your Ledger.

> [!NOTE]
>
> If you do not have any Segments, the list will appear empty with a prompt to create your first segment.

### Available actions

From the **Segments** page, you can:

> **[Create a Segment](/en/products/midaz/console/creating-a-segment)**
>
> Add a new segment to organize your accounts

> **[Edit a Segment](/en/products/midaz/console/editing-segment-information)**
>
> Update segment name and metadata

> **[Delete a Segment](/en/products/midaz/console/deleting-a-segment)**
>
> Remove a segment from your ledger

## Common use cases

***

> **Departmental organization**
>
> Create segments to represent different departments or cost centers:
>
> * `Finance` - For treasury and financial operations accounts
> * `Operations` - For operational and transactional accounts
> * `HR` - For payroll and employee-related accounts
> * `Sales` - For revenue and customer-related accounts

> **Product line separation**
>
> Organize accounts by product or service offering:
>
> * `Checking Products` - All checking account-related segments
> * `Savings Products` - Savings and investment account segments
> * `Loans` - Credit and lending product segments
> * `Cards` - Credit and debit card operation segments

> **Regional organization**
>
> Group accounts by geographic region:
>
> * `North Region` - Accounts for northern operations
> * `South Region` - Accounts for southern operations
> * `International` - Cross-border and international accounts

> **Compliance and reporting**
>
> Create segments for regulatory and reporting purposes:
>
> * `Regulatory Reserve` - Accounts subject to reserve requirements
> * `Audit Trail` - Accounts requiring special audit tracking
> * `Tax Reporting` - Accounts with specific tax reporting needs

## Best practices

***

**1. Plan your segment structure**

Plan your segments before you create accounts.

**2. Use clear, descriptive names**

Choose segment names that clearly indicate their purpose.

**3. Add metadata for context**

Use the Metadata tab to store additional information like cost center codes, department IDs, or integration references.

**4. Keep segments consistent across ledgers**

If you have multiple ledgers, consider using consistent segment naming conventions for easier cross-ledger reporting.

**5. Review segments regularly**

Periodically review your segment structure to ensure it still aligns with your organizational needs.

## Segments and transaction rules

***

Segments classify accounts for organization, filtering, and reporting. Fee packages and Tracer limits can use a segment as a scope. Route validation in [Accounting Routes](/en/products/midaz/console/managing-accounting-routes) supports only account types and aliases. There is no segment-based routing. Use segments to keep your account structure organized and to slice reports by department, region, or product line.


# Managing Transactions
Source: https://docs.lerian.studio/en/products/midaz/console/managing-transactions

Manage Transactions from the Midaz Module: create new Transactions between Accounts and inspect approved or canceled records in your Ledger.

Use the **Midaz Module** to view, create, and monitor **Transactions** in a visual interface. The Transactions page shows every financial movement in your Ledger. You can track balances, review operations, and create transactions without writing code.

> [!NOTE]
>
> See the [Transactions](/en/products/midaz/transactions) reference documentation for transaction structures, double-entry accounting, N:N transactions, and API integration.

## Accessing the Transactions page

***

Select the **Transactions** option in the left-side menu to open the **Transactions** page.

The **Transactions** page shows a table of all Transactions in your Ledger.

> [!NOTE]
>
> If your Ledger has no Transactions, the list is empty and shows a prompt to create your first transaction.

### Available actions

From the **Transactions** page, you can:

> **[Create a Transaction](/en/products/midaz/console/creating-a-transaction)**
>
> Record a new asset movement between accounts

> **[Check Transaction details](/en/products/midaz/console/checking-transaction-details)**
>
> See complete transaction information and operations

## Transaction status

***

Transactions in Midaz have the following statuses:

* **CREATED** - Only the create response carries this status. Midaz stores the transaction as `APPROVED`
* **PENDING** - A two-step transaction holding funds, awaiting commit or cancel
* **APPROVED** - Midaz posted the transaction
* **CANCELED** - Midaz canceled the transaction
* **NOTED** - An annotation-only transaction with no balance changes. Its operations remain with all balance fields zeroed

> [!NOTE]
>
> After Midaz approves a transaction, you cannot edit its operations or amounts, and you cannot delete it. To reverse it, create a reversal transaction. This protects the integrity of your financial records.

## Common use cases

***

> **Simple transfer between two accounts**
>
> A basic transaction moving funds from one account to another:
>
> * **Source**: Customer checking account (debit \$100)
> * **Destination**: Merchant account (credit \$100)
> * Single source, single destination, equal amounts

> **Payment with fees**
>
> A transaction that splits funds between multiple destinations:
>
> * **Source**: Customer account (debit \$103)
> * **Destinations**:
>   * Merchant account (credit \$100)
>   * Fee collection account (credit \$3)
> * Single source, multiple destinations

> **Consolidated payment**
>
> Multiple sources funding a single destination:
>
> * **Sources**:
>   * Primary account (debit \$500)
>   * Secondary account (debit \$300)
> * **Destination**: Vendor account (credit \$800)
> * Multiple sources, single destination

> **Complex multi-party transaction**
>
> Multiple sources and destinations in a single transaction:
>
> * **Sources**:
>   * Customer A (debit \$200)
>   * Customer B (debit \$300)
> * **Destinations**:
>   * Vendor account (credit \$450)
>   * Tax account (credit \$50)
> * Multiple sources, multiple destinations

## Best practices

***

**1. Write clear transaction descriptions**

Include a clear description of the purpose of each transaction.

**2. Verify account balances before transacting**

Make sure the source account has enough balance before you create a transaction. This avoids rejections.

**3. Use metadata for integration context**

Store external reference IDs, order numbers, or other system identifiers in the transaction metadata for traceability.

**4. Group related operations logically**

When possible, combine related transfers into one transaction instead of several separate transactions.

**5. Review transactions before confirming**

Double-check the source accounts, destination accounts, and amounts before you submit. After you create a transaction, you can edit only its description and metadata.

## Accounting Routes integration

***

Midaz can validate Transactions against [Accounting Routes](/en/products/midaz/console/managing-accounting-routes) before it processes them. Accounting Routes define which accounts can transact with each other.


# Accounting rules
Source: https://docs.lerian.studio/en/products/midaz/console/mc-accounting

Learn how Accounting Routes decide which Accounts join a transaction and how debit and credit entries are posted for each transaction type in Midaz.

The **Accounting** section is where you define optional rules for transactions. The sidebar shows the **Accounting** section only when the current Ledger has **Validate Routes** on.

You do this through **Accounting Routes**. An Accounting Route is a reusable rule for one kind of transaction, such as a *Pix transfer*, a *card purchase*, or a *fee charge*. Each route answers three questions:

* Which accounts can act on the source side?
* Which accounts can act on the destination side?
* Which debit and credit entries does the route post when the transaction runs?

**Example.** A `Pix transfer` route can require a `customer` account on the source side and a `merchant` account on the destination side. The route then defines direct debit-and-credit entries between them. When you enable route validation, a Pix transaction that references the route validates the accounts and applies the configured rules.

Accounting Routes provide optional route validation. Midaz enforces them only when you enable the Ledger setting `accounting.validateRoutes` (default `false`). When enabled, transactions must reference valid routes and operations must match configured rules. Routes are easier to model when you already know which accounts represent customers, treasury, fees, settlement, revenue, and expenses.

## How the pieces fit together

***

![How accounts, account types, and accounting routes fit together so a transaction request is validated and posted as debit-and-credit entries](https://mintcdn.com/lerian-49cb71fc/SFzzdxyH5SN7w_fC/images/en/d2/accounting-route-flow.svg?fit=max\&auto=format\&n=SFzzdxyH5SN7w_fC\&q=85\&s=a504463da029fe875e18198b63546708)

| Piece | What it controls | Example |
| - | - | - |
| Accounting Route | The transaction-level route that groups the operation rules. | `Pix transfer route` |
| Operation Route | The account side and validation rule. | `Source must be customer`, `Destination must be merchant` |
| Validation rule | How Midaz decides whether an account can be used. | Account Type `customer` or alias `@treasury_main` |
| Accounting scenario | Which debit and credit entries are posted for the transaction lifecycle. | Direct, Two-Step, Reversal, Overdraft, Block/Unblock |

## Choosing the operation type

***

> **Use Source when the rule applies only to the sending side**
>
> Use **Source** for accounts where value originates.
>
> Example: a customer account can send funds in a payment flow.

> **Use Destination when the rule applies only to the receiving side**
>
> Use **Destination** for accounts where value lands.
>
> Example: a merchant account can receive funds in a payment flow.

> **Use Bidirectional when the same rule applies to both sides**
>
> Use **Bidirectional** when the same account class can send and receive.
>
> Example: checking accounts can transfer value to other checking accounts.

> [!NOTE]
>
> A route must include a Source and a Destination operation route, or at least one Bidirectional operation route.

## Choosing the validation rule

***

| Validation type | Use when | Example |
| - | - | - |
| Account Type | Any account in a class should be valid. | Any `customer` account can send. |
| Alias | Only one exact account should be valid. | Only `@treasury_main` can send. |

Each Operation Route in the Console needs an account rule: registered Account Types or an `@Alias`. Midaz enforces the rule when you enable route validation. Use Account Type validation for scalable flows. Use alias validation for fixed operational accounts, such as treasury, fee, settlement, or suspense accounts.

## Common route patterns

***

### Customer to merchant

Use separate Source and Destination routes when each side has a different role.

| Operation route | Validation |
| - | - |
| Source | Account Type `customer` |
| Destination | Account Type `merchant` |

### Peer-to-peer transfer

Use a Bidirectional route when the same account type can be both source and destination.

| Operation route | Validation |
| - | - |
| Bidirectional | Account Type `customer` |

### Fee collection

Use a Destination route with alias validation when fees must always land in one operational account.

| Operation route | Validation |
| - | - |
| Source | Account Type `customer` |
| Destination | Alias `@fee_revenue` |

## Accounting scenarios

***

| Scenario | Use when | What the user configures |
| - | - | - |
| Direct Transaction | The movement is executed in one step. | Debit and credit entries for immediate posting. |
| Two-Step Transaction | The movement has hold, commit, and cancel phases. | Entries for reservation, confirmation, and cancellation. |
| Reversal | A completed transaction may need to be reversed. | Debit and credit entries for the reversal event. |
| Overdraft | A debit may exceed the account's available funds, drawing on an overdraft line. | Debit and credit entries for the overdraft draw and later repayment. |
| Block/Unblock | Funds need to be held and later released on the account's balance. Available for all route types (tab label "Block"). | Entries for the block (hold) and unblock (release) events. |

> [!WARNING]
>
> Do not enable route validation in Ledger settings until the required routes exist. If you enable it without matching routes, transactions fail validation.

## Available pages

***

> **[Setting up accounting in the Console](/en/products/midaz/console/accounting-setup-in-console)**
>
> A step-by-step, Console-first guide to building your accounting model, from chart of accounts to a working Pix payment. No API calls required.

> **[Manage Accounting Routes](/en/products/midaz/console/managing-accounting-routes)**
>
> Configure accounting routes with operation rules and accounting scenarios in one wizard.


# Account management
Source: https://docs.lerian.studio/en/products/midaz/console/mc-accounts

Explore how Accounts, Holders, Aliases, Segments, and Portfolios work together in the Midaz Module to organize your financial structure and ownership.

The **Accounts** section is where you open the accounts that hold balances, identify who owns them, and group them for reporting and control. Accounts can be linked to a Holder, Segment, and Portfolio. These persisted relationships support ownership, grouping, fee resolution, and scoped rules.

You will work with the following here:

* **Account**: the record that holds a balance of one asset and can send or receive that asset through transactions (for example, a customer's BRL account).
* **Holder**: the individual or entity that owns one or more accounts (for example, a customer or a merchant registered in CRM).
* **Alias Account**: an optional CRM Instrument linked to a Holder and an existing ledger Account. It stores banking details. This is different from the account's own **alias** field. The **alias** is a friendly identifier on the account itself. It lets you refer to the account by name instead of by ID (for example, `@treasury_main`).
* **Segment**: an optional ledger-scoped grouping for Accounts that can scope fee selection and Tracer limits.
* **Portfolio**: a ledger-scoped grouping of Accounts with an optional external `entityId`. It is not a direct Holder relationship.

## Available pages

***

> **[Manage Accounts](/en/products/midaz/console/managing-accounts)**
>
> Create and configure the accounts that hold and move assets within your ledgers.

> **[Manage Holders](/en/products/midaz/console/managing-crm-holders)**
>
> Register the individuals or entities that own accounts in your system.

> **[Manage Alias Accounts](/en/products/midaz/console/managing-crm-alias-accounts)**
>
> Link holders to ledger accounts with banking details.

> **[Manage Segments](/en/products/midaz/console/managing-segments)**
>
> Organize accounts into logical groupings for reporting and control.

> **[Manage Portfolios](/en/products/midaz/console/managing-portfolios)**
>
> Group accounts into portfolios for consolidated management.


# Foundation elements
Source: https://docs.lerian.studio/en/products/midaz/console/mc-foundation

Set up the Foundation of the Midaz Module: Organizations, Ledgers, Assets, and Account Types that every downstream Account and transaction depends on.

The **Foundation** section is the structure that the rest of Midaz builds on. Set up an Organization, Ledger, and Asset before opening an Account. Define Account Types when your configuration needs them. You can create and update Foundation resources.

You will work with four elements here:

* **Organization**: The top-level entity that owns one or more ledgers. Usually represents your company or business unit (for example, *Acme Bank*).
* **Ledger**: The isolated book of records where accounts, balances, and transactions live. Use one or more ledgers according to your product and operational needs.
* **Asset**: A currency or instrument that accounts can hold and move, identified by a code (for example, `BRL`, `USD`, or `USDC`). Each account holds one asset.
* **Account Type**: A registered classification for accounts (for example, `customer`, `treasury`, `fee`, or `revenue`). Registering Account Types is optional, but every account has a type.

## Available pages

***

> **[Manage Organizations](/en/products/midaz/console/managing-organizations)**
>
> Create and configure the top-level entities that group your ledgers.

> **[Manage Ledgers](/en/products/midaz/console/managing-ledgers-via-console)**
>
> Set up ledgers to organize and track your financial operations.

> **[Manage Assets](/en/products/midaz/console/managing-assets)**
>
> Register the currencies and instruments used across your ledgers.

> **[Manage Account Types](/en/products/midaz/console/managing-account-types)**
>
> Define the categories that classify your accounts within each ledger.


# Transaction basics
Source: https://docs.lerian.studio/en/products/midaz/console/mc-transactions

Use the Midaz Module to record Transactions that move Assets between Accounts with double-entry accounting, N:N support, and a full audit trail.

Use **Midaz Module** to manage **Transactions** that record the movement of assets between accounts. They record every financial movement in your system.

## What are Transactions?

***

A **Transaction** represents the transfer of assets from one or more source accounts to one or more destination accounts. In Midaz Module, transactions:

* **Move assets between accounts** - Record value movements through one or more Operations
* **Support multiple sources and destinations** - Handle complex transactions with multiple parties
* **Track status** - Midaz stores each transaction as `PENDING`, `APPROVED`, `CANCELED`, or `NOTED`. Only the create response carries `CREATED`
* **Maintain audit trail** - Record complete history with timestamps and metadata
* **Support accounting controls** - When enabled, Accounting Routes validate configured rules for the Transaction

A transaction is immutable. Once Midaz records the movement, you cannot change or delete it. You can still update the transaction description and metadata, or view it at any time. To commit or cancel a pending transaction, use the API.

For technical details about transactions in Midaz, refer to the [Transactions documentation](/en/products/midaz/transactions).

## Available pages

***

> **[Manage Transactions](/en/products/midaz/console/managing-transactions)**
>
> Create Transactions and inspect their details after processing.


# Concepts map
Source: https://docs.lerian.studio/en/products/midaz/console/midaz-console-concepts-map

Understand how Organizations, Ledgers, Assets, Accounts, Routes, and Transactions depend on each other before you start configuring the Midaz Module.

The Midaz Module uses a small set of core objects with explicit dependencies. Organization, Ledger, Assets, and Accounts are the core setup. You configure Account Types, CRM records, Portfolios, Segments, and Accounting Routes when the workflow needs them.

## Core hierarchy

***

![Core Midaz Module hierarchy, from Organization and Ledger down through Assets, Accounts, Routes, and Transactions](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/midaz-core-hierarchy.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=5f6cfdcad7c59f335dbac4f8f622b953)

### What each object means

***

| Object | What it represents | Why it exists first or later |
| - | - | - |
| `Organization` | The legal or operational owner of the setup | It is the top-level boundary. Nothing below exists without it. |
| `Ledger` | The accounting environment where balances and movements are recorded | It groups the structure that a team will operate day to day. |
| `Asset` | The unit of value moved in the ledger, such as `BRL` or `USD` | Accounts and transactions depend on it. |
| `Account` | A balance container that can send or receive value | Transactions happen between accounts. |
| `Account Type` | A registered classification such as `checking`, `treasury`, or `expense`. Registering one is optional, but every account has a type | Use it when configured account or route rules need it. |
| `Portfolio` | A grouping of accounts, often by customer or wallet structure | Useful for reporting and organization, but not a prerequisite for every account. |
| `Segment` | A ledger-scoped persisted grouping of accounts, such as by department, region, or tier | Useful when the business needs slicing or policy grouping. |
| `Holder` | The person or entity that owns accounts in CRM flows | Needed when account ownership matters operationally. |
| `Alias` | A human-readable identifier used to find or refer to an account | Especially important in transaction creation. |
| `Accounting Route` | An optional rule set for transaction participants and posting behavior | Midaz applies configured route rules when route validation is enabled. |
| `Transaction` | The balance movement recorded in the ledger | It is the output of the whole setup. |

## How a transaction depends on prior setup

***

![How creating a transaction depends on the prior setup of organization, ledger, assets, accounts, and accounting routes](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/midaz-transaction-dependency.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=9e9a12efb097f1569985402ec9b9b31c)

The required prerequisites depend on the Transaction and Ledger settings. A transaction requires Assets and Accounts. It requires an Accounting Route only when route validation is on.

## Practical reading of the UI

***

Use this interpretation when you guide users:

• `Foundation` defines where the system lives: Organization, Ledger, Asset, Account Types.

• `Accounting` defines optional participation and posting rules: Accounting Routes and Operation Routes.

• `Accounts` defines who holds balances and how you classify them: Accounts, Holders, Aliases, Segments, Portfolios.

• `Transactions` exercises the configured structure.

• `Plugins` extend the model after the core behavior already works.

## When users usually get lost

***

> **Account vs Holder vs Alias**
>
> The Account is the balance container. The Holder is the CRM identity. An Alias Account is an optional CRM Instrument linked to a Holder and an existing Ledger Account. The Account's own `alias` is its human-friendly identifier.

> **Account Type vs Segment vs Portfolio**
>
> Account Type is a registered classification, and registering one is optional. Segment and Portfolio are ledger-scoped persisted groupings of Accounts. They are not merely labels or direct Holder relationships.

> **Accounting Route vs Transaction**
>
> The Route is an optional reusable rule. The Transaction is the individual movement. Midaz checks it against configured route rules only when route validation is on.

> **Why the ledger matters so early**
>
> Almost every object below it is ledger-scoped. Users who treat the ledger as a cosmetic container usually misconfigure accounts and routes later.

> [!TIP]
>
> Pair this page with [Setup path](/en/products/midaz/console/midaz-console-setup-path) when you onboard new users. This page explains the model. Setup path explains the order.


# Onboarding
Source: https://docs.lerian.studio/en/products/midaz/console/midaz-console-onboarding

Follow the Midaz Module guided onboarding to create your first Organization and Ledger in a few minutes, with fields explained at every step.

The Midaz Module guides you through a step-by-step onboarding flow. It helps you set up your Organization and create your first Ledger.

## Onboarding process

***

The onboarding starts automatically when you have no Organization. This happens when you never created one, or when you deleted all your Organizations.

At each step, you see where you are and why the step matters.

In a few minutes, your Organization and your first Ledger are ready. You need both to access the full platform.

### Starting the process

Click the **Let's go** button on the first-steps window.

## Part 1: Creating your Organization

***

The first part of onboarding creates your Organization in three steps.

### Step 1 – Set up your Organization details

You enter the key details of your Organization.

**Required fields:**

* **Legal Name** – Your company's official registered name.
* **Document** – A registration number such as a CNPJ or EIN.

The step also has a **Trade Name** (DBA) field.

> [!WARNING]
>
> The **Document** is permanent. After you submit it, you cannot change it. You can still edit the Legal Name and Trade Name later in the Organization settings.

Click **Next** at the bottom of the screen.

### Step 2 – Add your Organization's address

This step adds the registered address of your Organization.

**Fields:**

* **Address** – Street address (line 1)
* **Complement** – Additional address information (optional)
* **Country** – Select from the dropdown
* **State** – Select from the dropdown, based on country (optional)
* **City** – Your city name
* **ZIP Code** – Postal code, numbers only

> [!TIP]
>
> You can update your address at any time in the Organization settings.

Click **Next** at the bottom of the screen.

### Step 3 – Add a theme (optional)

Upload your Organization's **Icon** to personalize the Midaz Module.

**Icon format:**

* SVG or PNG file
* 256x256 px

When you submit this step, Midaz creates your Organization and returns a unique `organizationId`.

> [!TIP]
>
> You can skip this step and add the icon later. A confirmation dialog asks if you want to finish without a theme.

Click **Finish** to continue.

### Organization created

Your Organization is ready. You see a confirmation dialog. Click **Continue** to create your first Ledger.

## Part 2: Creating your first Ledger

***

After Midaz creates your Organization, the flow guides you to create your first Ledger.

The Ledger is a core part of Midaz. It is where you manage Accounts, balances, and Transactions. Create Assets separately in the Ledger, then use them when you create Accounts.

**Required field:**

* **Ledger Name** – A unique name for your Ledger.

You can also turn on **Validate Account Type** and **Validate Routes** in this step.

> [!NOTE]
>
> You can configure additional metadata later. An alert on the page reminds you of this option.

Enter a name for your Ledger. Click **Finish** to complete the setup.

## What's next?

***

With onboarding complete, you can configure the rest of the Midaz Module:

> **[Manage Organizations](/en/products/midaz/console/managing-organizations)**
>
> Edit your Organization settings and create additional Organizations.

> **[Manage Ledgers](/en/products/midaz/console/managing-ledgers-via-console)**
>
> Configure your Ledger and create new ones.

> **[Create Assets](/en/products/midaz/console/creating-an-asset)**
>
> Define the currencies and tokens for your Ledger.

> **[Create Accounts](/en/products/midaz/console/creating-an-account)**
>
> Set up accounts to start managing balances.


# Setup path
Source: https://docs.lerian.studio/en/products/midaz/console/midaz-console-setup-path

Follow the recommended setup order for the Midaz Module so each Console screen has the Organization, Ledger, Assets, and Accounts it depends on.

The Midaz Module is easier to configure when you follow the dependency order the product expects. Most user confusion comes from trying to create Accounts, Routes, or Transactions before the structural pieces already exist.

## Recommended order

***

**1. Create your Organization**

Start with the legal and operational owner of the environment.

Use [Midaz Module onboarding](/en/products/midaz/console/midaz-console-onboarding) if this is your first setup. If the organization already exists and you want to add another, go directly to [Creating an Organization](/en/products/midaz/console/creating-an-organization).

**2. Create your first Ledger**

The Ledger is the workspace that scopes balances, Accounts, and Transactions.

Go to [Creating a new Ledger](/en/products/midaz/console/creating-a-new-ledger).

**3. Review Ledger settings**

Decide whether to enable Accounting Route validation before users start creating Transactions. This setting is optional and defaults to `false`.

You can configure these settings while creating the Ledger in [Creating a new Ledger](/en/products/midaz/console/creating-a-new-ledger#ledger-settings), or update them later from [Managing Ledgers](/en/products/midaz/console/managing-ledgers-via-console#ledger-settings).

**4. Create Assets**

Assets define a unit of value for the Ledger, such as `BRL`, `USD`, or a custom token. Accounts reference an Asset when you create them.

Go to [Creating an Asset](/en/products/midaz/console/creating-an-asset).

**5. Create Account Types**

Define Account Types when your configured Account or Route rules need those classifications.

Go to [Creating an Account Type](/en/products/midaz/console/creating-an-account-type).

**6. Create Accounts**

Accounts hold balances and are the source or destination of transactions.

Go to [Creating an Account](/en/products/midaz/console/creating-an-account).

**7. Add Portfolios, Segments, Holders, and Aliases when needed**

These are persisted support structures. Configure them when your workflow needs ownership context, grouping, fee resolution, or scoped rules.

Use:

* [Creating a Portfolio](/en/products/midaz/console/creating-a-portfolio)
* [Creating a Segment](/en/products/midaz/console/creating-a-segment)
* [Creating a Holder](/en/products/midaz/console/crm-creating-a-holder)
* [Creating an Alias Account](/en/products/midaz/console/crm-creating-alias-account)

**8. Create Accounting Routes**

Accounting Routes define optional participant and posting rules. Midaz applies them when route validation is on.

Go to [Creating an Accounting Route](/en/products/midaz/console/creating-an-accounting-route).

**9. Create Transactions**

Create Transactions after the Ledger has an Asset and the required Accounts. You need a matching Accounting Route only when route validation is on.

Go to [Creating a Transaction](/en/products/midaz/console/creating-a-transaction).

**10. Configure Fees Engine after core setup is stable**

Fees Engine is part of Midaz, but it is optional. Enable it under **Settings > Plugins**, then configure its fee packages after the base ledger model is already clear.

Go to [Midaz module settings](/en/platform/console/plugin-settings).

## Fast path by goal

***

> **[I need my first working ledger](/en/products/midaz/console/midaz-console-onboarding)**
>
> Use onboarding, then create at least one Asset and one Account.

> **[I need to model account structure](/en/products/midaz/console/creating-an-account-type)**
>
> Start with Ledger settings, Account Types, Accounts, and Segments.

> **[I need to control how money moves](/en/products/midaz/console/creating-an-accounting-route)**
>
> Create the accounts first, then define Accounting Routes and test with a transaction.

> **[I need to estimate fees](/en/products/midaz/fees/console/managing-fee-calculations)**
>
> Enable Fees Engine under **Settings > Plugins**, then configure it after the core ledger structure is already in place.

## Common sequencing mistakes

***

> **Creating an Account before creating an Asset**
>
> You must link every Account to an Asset. If the Asset does not exist yet, account creation stalls immediately.

> **Enabling Account Type validation before defining Account Types**
>
> The Type field then lists only registered Account Types, so the list is empty. Create the Account Types first or disable validation until they are ready.

> **Designing Accounting Routes before knowing the real accounts**
>
> Users often try to model routes too early. Route rules are easier to define after the treasury, customer, fee, and settlement accounts already exist.

> **Trying to create Transactions before aliases or accounts are ready**
>
> Transaction creation depends on accounts being searchable and structurally valid. If operators cannot identify the source and destination accounts quickly, stop and fix the account model first.

> [!NOTE]
>
> When you document the setup or train a client team, teach this order first. The CRUD pages become much easier once the dependency chain is explicit.


# Troubleshooting
Source: https://docs.lerian.studio/en/products/midaz/console/midaz-console-troubleshooting

Fix common Midaz Module issues in Lerian Console: missing menus, empty dropdowns, blocked transactions, and Ledger validation setting mismatches.

Use this page when the Console does not show an option you expected, or when you cannot complete a form. Also use it when a transaction does not behave as you expect. Most issues come from missing prerequisites, or from Ledger settings you enabled before the supporting configuration existed.

## First checks

***

Before you troubleshoot a specific screen, confirm these basics:

* You selected the correct **Organization** and **Ledger**.
* The Ledger already has the required **Assets**.
* The Ledger settings match the workflow you want to use.
* The required **Account Types**, **Accounts**, and **Accounting Routes** exist before you create transactions.
* You use each account alias exactly as registered, including any `@` prefix.

> **[Setup path](/en/products/midaz/console/midaz-console-setup-path)**
>
> Review the recommended setup order before you change individual screens.

## Common issues

***

> **I cannot see the Account Types menu**
>
> The **Account Types** menu appears when you enable **Validate Account Type** in the current Ledger settings.
>
> To fix it:
>
> 1. Open **Foundation > Ledgers**.
>
> 2. Select **Edit** for the target Ledger.
>
> 3. Go to the **Settings** tab.
>
> 4. Enable **Validate Account Type**.
>
> 5. Return to the sidebar and open **Foundation > Account Types**.
>
> > [!WARNING]
> >
> > After you enable this setting, new Accounts must use a valid Account Type. Create the required types before you ask operators to create accounts.

> **I cannot create an Account because the Asset field is empty**
>
> Each Account must link to an existing Asset. If no Asset exists in the selected Ledger, you cannot complete the Account form.
>
> Create the Asset first in [Creating an Asset](/en/products/midaz/console/creating-an-asset), then return to [Creating an Account](/en/products/midaz/console/creating-an-account).

> **The Account Type dropdown is empty**
>
> This usually means you enabled **Validate Account Type** but created no Account Types for the selected Ledger.
>
> Create at least one Account Type in [Creating an Account Type](/en/products/midaz/console/creating-an-account-type). If your workflow does not need type validation, disable **Validate Account Type** in Ledger settings.

> **I cannot find an Account when creating a Transaction**
>
> Transaction creation searches accounts by alias. Confirm that:
>
> * The account exists in the selected Ledger.
> * The alias matches the registered alias, including any `@` prefix.
> * The account allows the expected direction: source accounts can send, destination accounts can receive.
> * The account Asset matches the Asset you selected for the Transaction.
>
> If the alias is wrong or does not exist, open the account details from [Managing Accounts](/en/products/midaz/console/managing-accounts).

> **My Transaction fails route validation**
>
> The **Validate Routes** setting controls route validation. When you enable it, transactions must match an existing Accounting Route.
>
> Check that:
>
> * The Accounting Route exists in the selected Ledger.
> * The route has at least one valid source and one valid destination operation route, or one bidirectional route.
> * Account Type or alias validation matches the accounts used in the transaction.
> * The transaction type matches the accounting scenario configured in the route.
>
> Start with [Managing Accounting Routes](/en/products/midaz/console/managing-accounting-routes) and then review [Creating an Accounting Route](/en/products/midaz/console/creating-an-accounting-route).

> **My Transaction amounts do not balance**
>
> For complex transactions, the total you debit from source accounts must equal the total you credit to destination accounts.
>
> Review every operation before you send the transaction. To model fees, include the fee account as an additional destination so the total credits match the total debits.

> **I cannot delete an entity**
>
> You cannot delete some entities after downstream records use them. For example, treat an Asset that Accounts use, or an Account that Transactions use, as part of the ledger history.
>
> Instead, edit optional metadata, disable future use where the Console supports it, or create a replacement entity for new operations.

> **Balances do not look right after a Transaction**
>
> Start from the transaction details page and check:
>
> * The source and destination accounts.
> * The Asset used in the transaction.
> * Each debit and credit operation.
> * The transaction status: `APPROVED`, `PENDING`, `CANCELED`, or `NOTED` (an annotation with no balance change). A reversal is a separate transaction. The original stays `APPROVED`.
>
> Then open the account balance and operation history for the accounts involved.

## API references

***

When a Console issue needs deeper inspection, use the corresponding API references:

> **[List Accounts](/en/reference/products/midaz/v2/list-accounts)**
>
> Confirm whether the account exists in the selected Ledger.

> **[Retrieve an Account](/en/reference/products/midaz/v2/get-account-by-id)**
>
> Inspect account details such as type, asset, and metadata.

> **[List Transactions](/en/reference/products/midaz/v2/get-all-transactions)**
>
> Review transaction history for a Ledger.

> **[Retrieve a Transaction](/en/reference/products/midaz/v2/get-transaction)**
>
> Inspect transaction status and operation details.


# About Midaz module
Source: https://docs.lerian.studio/en/products/midaz/console/midaz-module

Use the Midaz Module in Lerian Console to manage Organizations, Ledgers, Accounts, Assets, and Transactions from a single visual interface.

**Midaz** is a module inside the [Lerian Console](/en/platform/console/about-lerian-console) that provides a visual interface for managing ledger infrastructure.

From a single screen, you create organizations and ledgers, register assets (such as BRL or USD), and open accounts. You define the rules that govern how money moves, and record transactions, all without writing API calls.

Use the Midaz Module for day-to-day operations: open an account, run a transaction, or check balances. You can also configure how the ledger validates and posts transactions.

> [!NOTE]
>
> Midaz Console is now part of Lerian Console as the **Midaz Module**. All existing functionality remains available, along with new integrations and platform features.

## Start here first

***

Start with these pages if you are new to Midaz. They show what to create and in which order. They also show how the main components work together.

> **[Setup path](/en/products/midaz/console/midaz-console-setup-path)**
>
> Follow the recommended setup order for Organizations, Ledgers, Assets, Accounts, Routes, and Transactions.

> **[Midaz Console concepts map](/en/products/midaz/console/midaz-console-concepts-map)**
>
> Learn how Midaz components connect and how they support financial operations.

> **[Midaz Console troubleshooting](/en/products/midaz/console/midaz-console-troubleshooting)**
>
> Resolve common issues related to configuration, routes, permissions, and transactions.

## What you can do

***

From the Midaz Module, you can:

* **Manage organizations and ledgers**: Create the operational structure used by your financial environment
* **Configure assets**: Define currencies, tokens, and other asset types used across ledgers
* **Set up accounts**: Create accounts with account types, portfolios, and segments
* **Configure accounting routes**: Define how operations and transactions move assets between accounts
* **Monitor transactions**: Track financial movements across organizations and ledgers
* **Manage Holders and Alias Accounts**: Use the integrated CRM to register account owners and link them to ledger accounts
* **Configure Fees Engine**: Fees Engine is integrated into Midaz, but it is optional. Enable it from the [Settings > Plugins](/en/platform/console/plugin-settings) page before you configure it

## Recommended setup order

***

For a new environment, we recommend configuring Midaz in the following order:

**1. Create an Organization**

Define the top-level structure that groups your ledgers and operations.

**2. Create a Ledger**

Create the ledger that will store balances, accounts, and transactions.

**3. Configure Ledger settings**

Adjust operational and accounting settings for the ledger.

**4. Create Assets**

Define the currencies or asset types that will circulate in the ledger.

**5. Configure Account Types**

Define how accounts behave within the financial structure.

**6. Create Accounts**

Create the accounts that will hold balances and participate in transactions.

**7. Configure Portfolios and Segments**

Organize accounts based on business or operational needs.

**8. Create Accounting Routes**

Define how transactions move assets between accounts.

**9. Create Transactions**

Start recording and monitoring financial operations.

**10. Configure Fees Engine**

Fees Engine is integrated into Midaz, but it is optional. Enable it under **Settings > Plugins**, then configure its fee packages after the core ledger structure is in place.

For a more detailed explanation of each step, see [Setup path](/en/products/midaz/console/midaz-console-setup-path).

## Accessing Midaz

***

To open Midaz, select the **Midaz Module** from the Lerian Console product launcher (*Figure 1*).

![The Midaz Module card in the Lerian Console product launcher, used to open Midaz](https://mintcdn.com/lerian-49cb71fc/yneNeAhnXdrrmE3_/images/en/console/midaz_button.png?fit=max\&auto=format\&n=yneNeAhnXdrrmE3_\&q=85\&s=237682e7534e9c4fe11cefe3379e2437)

Figure 1. The card used to access the Midaz Module.

## Ledger activity

***

The Midaz home page shows a **Ledger activity** section for the current Ledger. Select the period at the top of the section: **Last 7 days**, **Last 30 days**, or **Last 90 days**. The default is the last 30 days.

The section has three cards and a chart:

* **Transactions in period**: the number of transactions in the period, split by status.
* **Settled volume**: the settled amount of each asset, with its number of transactions. When an asset has reversals, a line shows their amount.
* **Current position**: the available amount of each asset, the number of accounts that hold it, and the amount on hold. The period does not change this card.
* **Transactions per Day**: a chart of the number of transactions on each day of the period.

With Access Manager, this section needs the read permission on the Midaz dashboard resource.

## Available features

***

The sidebar follows the order in which most teams build their environment. You start with **Foundation**, then move to **Accounting**, **Accounts**, **Transactions**, and finally **Plugins**.

> **[Foundation](/en/products/midaz/console/mc-foundation)**
>
> Configure Organizations, Ledgers, Assets, and Account Types that support your financial structure.

> **[Accounting](/en/products/midaz/console/mc-accounting)**
>
> Configure Accounting Routes that control how assets move through the system.

> **[Accounts](/en/products/midaz/console/mc-accounts)**
>
> Manage Accounts, Holders, Aliases, Segments, and Portfolios.

> **[Transactions](/en/products/midaz/console/mc-transactions)**
>
> Create and monitor transactions that transfer assets between accounts.

> **[Plugins](/en/platform/console/mc-console-plugins)**
>
> Manage optional platform plugins available from Lerian Console.

## Migrating from Midaz Console

***

If you're currently using the standalone **Midaz Console**, here's what changes when moving to Lerian Console.

> [!WARNING]
>
> Midaz v3.5.0 and later releases do not include the standalone Midaz Console.
>
> We recommend migrating to Lerian Console to access the latest platform capabilities and integrations.

### Why migrate to Lerian Console?

* **Unified platform**: Access Midaz and other Lerian products from a single interface
* **New platform features**: Lerian releases new improvements and capabilities only in Lerian Console
* **Integrated workflows**: Connect Midaz with plugins and other platform modules
* **Simplified navigation**: Work with a consistent operational experience across products

### What stays the same?

* All core Midaz capabilities remain available
* Existing data and configurations continue to work
* Operational workflows remain familiar for current users


# Instruments
Source: https://docs.lerian.studio/en/products/midaz/crm/alias-accounts

Associate Holders with Ledger Accounts and store banking, regulatory, metadata, and related-party information.

An **Instrument** is the CRM record that associates a [Holder](/en/products/midaz/crm/holders) with a Ledger Account in Midaz. It stores the `ledgerId` and `accountId` for that association, together with banking details, regulatory fields, metadata, and related parties.

Instruments keep CRM context separate from the transactional Ledger. The Ledger remains the balance and movement record. The Instrument holds the context associated with a Holder and its Ledger Account.

## Create an Instrument

Create an Instrument in the scope of a Holder. The creation input requires `ledgerId` and `accountId` for the associated Ledger Account. The ledger and the account must exist in the organization.

The `bankingDetails` object can contain `branch`, `account`, `type`, `openingDate`, `closingDate`, `iban`, `countryCode`, and `bankId`. Its individual fields are optional. Midaz rejects banking details whose `bankId`, `branch`, and `account` another Instrument in the organization already holds.

An Instrument response includes its `id`, `holderId`, `ledgerId`, `accountId`, `document`, `type`, timestamps, and any configured banking, regulatory, metadata, or related-party data.

To open the Ledger Account and its Instrument in one call, use `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/holders/{id}/accounts`. The Holder in the path owns the new Account. The body takes the Account fields and, optionally, `bankingDetails`, `regulatoryFields`, and `relatedParties`. When the body has none of these three, Midaz creates only the Account.

A `201` response carries `account` and `instrument`. When Midaz creates the Account but cannot write the Instrument, `instrument` is `null` and `instrumentError` carries `status` and `reason`. The Account stays, and you can create its Instrument separately.

## Regulatory fields and related parties

Use `regulatoryFields.participantDocument` to store the participant document when it applies. `regulatoryFields.accountType` accepts `DEPOSIT`, `SAVINGS`, `INVESTMENT`, `OTHER_FINANCIAL_INVESTMENTS`, `NON_RESIDENT`, or `PAYMENT`.

An Instrument can include related parties. Each related party requires `document`, `name`, `role`, and `startDate`. The `role` is `PRIMARY_HOLDER`, `LEGAL_REPRESENTATIVE`, or `RESPONSIBLE_PARTY`. The `id` and `endDate` fields are optional, and `endDate` must not be before `startDate`.

## Manage Instruments

The Midaz API lets you:

* List Instruments for an organization.
* Create an Instrument for a Holder.
* Retrieve, update, or delete an Instrument in the scope of its Holder.
* Delete a related party from an Instrument.

Use the [Midaz API reference](/en/reference/products/midaz/v2/list-instruments) for the current request and response schema.

## Next steps

> **[Holders](/en/products/midaz/crm/holders)**
>
> Learn about the Holder associated with an Instrument.

> **[Accounts](/en/products/midaz/accounts)**
>
> Learn how Midaz Ledger Accounts hold balances and movements.


# Best practices
Source: https://docs.lerian.studio/en/products/midaz/crm/crm-best-practices

Follow CRM production best practices covering integration flow, encryption key management, metadata safeguards, and safe operational workflows.

CRM manages sensitive, identity-related data. These practices help you integrate CRM correctly, protect that data, and run it safely in production.

These recommendations complement the [CRM data security](/en/products/midaz/crm/crm-data-security) guide, which covers encryption, hashing, and key management in detail.

## 1. Follow the correct integration flow

***

CRM relies on a specific order to create entities. If you skip steps or create entities out of order, you can break integrations and lose data downstream.

The expected flow is:

1. **Create the holder**: the individual or the organization.
2. **Link the holder to a Midaz ledger account**: associate the holder with an account that already exists in the ledger.
3. **Make sure both exist** before you start any downstream flow.

> [!WARNING]
>
> Make sure your identifiers are correct before you create or link records. CRM checks that the `ledgerId` and `accountId` of an Instrument exist in the organization.

## 2. Protect your encryption keys

***

CRM encrypts and hashes sensitive fields before it stores them. The security of this data depends entirely on how you manage your keys.

* **Generate unique keys** for `LCRYPTO_HASH_SECRET_KEY` and `LCRYPTO_ENCRYPT_SECRET_KEY` with `openssl rand -hex 32`.
* **Store keys in a secret manager** (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault, or equivalent). Never hardcode them in configuration files, source code, or version control.
* **Pass the keys to the deployment from your secret vault.** To configure them on a Midaz deployment, see the [Midaz chart README](https://github.com/LerianStudio/helm/tree/main/charts/midaz).

For the full list of protected fields and encryption strategies, see [CRM data security](/en/products/midaz/crm/crm-data-security).

## 3. Never store sensitive data in metadata

***

The `metadata` object in CRM entities is **not encrypted**. CRM stores it in plain text for non-sensitive, auxiliary information only.

Do not use metadata for:

* Personal identification numbers (CPF, SSN, passport)
* Financial account details
* Contact information (email, phone)
* Any data subject to LGPD, GDPR, or similar regulations

If you need to store a sensitive attribute that is not in the [protected fields list](/en/products/midaz/crm/crm-data-security#protected-fields), contact your Lerian representative to discuss options.

## 4. Do not expose CRM directly on edge layers

***

CRM runs inside the Midaz ledger and exposes an internal API. If you expose it directly through API gateways, load balancers, or frontend applications, you increase your attack surface.

Instead:

* Route CRM traffic through your **backend services** or an internal API layer.
* Use [Access Manager](/en/platform/access-manager) to enforce authentication and authorization if you need fine-grained control.
* Restrict network access to the ledger pods with Kubernetes NetworkPolicies or your cloud provider's security groups.

## 5. Use soft delete as the default

***

CRM supports both **soft delete** and **hard delete**:

* **Soft delete** (default): CRM marks the record with a `deletedAt` timestamp. The record drops out of standard queries but stays in the database for audit and recovery.
* **Hard delete** (`hard_delete=true`): CRM removes the record from its database.

For most cases, soft delete is the safer choice. It preserves audit trails. Reserve hard delete for cases where regulations demand complete removal (for example, GDPR right-to-erasure requests).

> [!NOTE]
>
> Confirm your retention and legal-hold policy before you run a hard delete. The GDPR right to erasure (Article 17) is not absolute. Where legal, regulatory, audit, or record-keeping obligations require data retention, they can take precedence and restrict erasure.

## 6. Validate data before sending it to CRM

***

CRM is a **neutral, persistent data layer**. It does not validate document formats or check KYC compliance. Data integrity is your responsibility.

Before you create or update a record:

* Validate document formats (CPF, CNPJ, passport numbers) on your application layer.
* Sanitize inputs so you do not store malformed or inconsistent data.

## 7. Keep CRM and Midaz versions aligned

***

CRM ships inside the Midaz ledger binary, so it shares the Midaz version. Before you upgrade:

* Check the [version compatibility table](/en/products/midaz/midaz-version-compatibility) to confirm your target version.
* Test the upgrade in a staging environment before you apply it to production.
* Back up your MongoDB data and your deployment configuration before any major upgrade.

For upgrade procedures, see the [Helm upgrade guide](https://github.com/LerianStudio/helm/tree/main/charts/midaz).

## 8. Monitor database health and performance

***

CRM uses MongoDB for data storage. In production:

* **Monitor connection pool usage.** The Helm chart sets `MONGO_CRM_MAX_POOL_SIZE` to 1000 by default. Adjust it for your traffic patterns and replica count.
* **Set up alerts** for MongoDB disk usage, replication lag, and connection saturation.
* **Enable backups.** Whether you use the bundled Bitnami MongoDB or an external instance, run automated backups and test them regularly.
* **Enable OpenTelemetry** (`ENABLE_TELEMETRY: true`) to collect traces and metrics from CRM. Integrate with your observability stack for end-to-end visibility.

## 9. Review the security recommendations

***

CRM handles personal and sensitive data. Beyond CRM-specific practices, make sure your deployment follows the platform-wide [Security recommendations](/en/products/midaz/security-recommendations), which cover:

* Network segmentation and Zero Trust Architecture
* TLS 1.2+ enforcement for all communications
* IAM and RBAC configuration
* Incident response planning
* Patch management and vulnerability scanning


# Core Concepts
Source: https://docs.lerian.studio/en/products/midaz/crm/crm-core-concepts-overview

Meet the two CRM entities that connect customer identity to Midaz Ledger accounts: Holders that carry identity and Instruments that link them to accounts.

The CRM core concepts define the entities that connect real-world identities to your Midaz ledger accounts. They provide the business context that the ledger's transactional layer doesn't manage.

## Content

***

Here, you'll find:

* [**Holders**](/en/products/midaz/crm/holders): The core entity for an individual (`NATURAL_PERSON`) or an organization (`LEGAL_PERSON`) behind a ledger account. A Holder stores identity attributes such as name, document number, contact details, and addresses.
* [**Instruments**](/en/products/midaz/crm/alias-accounts): The link between a Holder and a specific ledger account. Instruments let one Holder associate accounts in different ledgers. Each one keeps banking details and metadata in one place.


# CRM data security
Source: https://docs.lerian.studio/en/products/midaz/crm/crm-data-security

Secure CRM personal data with HTTPS/TLS in transit, field-level encryption and hashing at rest, and controls aligned with GDPR and LGPD requirements.

### Personal data under GDPR and LGPD

Every regulation, from GDPR to LGPD, shares one principle: you use personal data only for the purpose the user agreed to. The **CRM** is part of the Midaz ledger. It handles transactional and non-transactional flows, so it must protect the sensitive data these flows carry.

Although Lerian doesn't offer cybersecurity services, we follow strict information security practices in all software we ship.

## Security responsibilities

***

Lerian does not oversee or enforce our clients' cybersecurity policies. We respect the trust-based relationship each institution has with its end users. We assume that each client follows the LGPD and any other data protection regulation that applies to its region or industry. The split of security work between Lerian and you depends on your deployment model. See the [shared responsibility model](/en/products/midaz/security).

Still, Lerian delivers technology that follows strong, market-aligned security practices. These practices protect sensitive CRM data as follows:

### In transit

The Midaz ledger serves plain HTTP. Terminate TLS in front of it, at your ingress or service mesh, to protect the data you exchange with the CRM. The CRM encrypts sensitive fields *before* it writes them to the database. This applies to every request that creates or updates a holder or an instrument.

### At rest

In BYOC, disk and volume encryption is your responsibility. We strongly recommend it. It adds another layer of protection.

## How we protect data

***

The CRM uses different protection methods. The method depends on the type of data and its intended use.

* **Encryption** protects values that the system might need to read again, such as names or contact information.
* **Hashing** creates a search token for some encrypted fields, such as the Holder `document`, so the CRM can find a record by that value. The field itself stays encrypted.

> [!WARNING]
>
> The CRM writes the protected fields to the database only in encrypted form.

### Encryption and hashing strategies

The CRM combines several cryptographic techniques. These techniques protect sensitive data and still support the application.

#### Encryption

The system must read or show some fields again, such as personal names or emails. The CRM encrypts each of these values with strong, symmetric encryption. Even if someone reads the database directly, the original values stay unreadable without the encryption key.

Encryption also adds a random component, so identical values never produce the same encrypted output.

#### Hashing

The CRM hashes certain fields to allow secure filtering without exposure of the original value. It stores these hashes in a separate internal structure for fast, secure lookups.

### Key management

The CRM uses encryption keys and hashing keys, in one of two modes that `KMS_VENDOR` selects. When `KMS_VENDOR` is unset or `none`, the CRM reads its keys from `LCRYPTO_ENCRYPT_SECRET_KEY` and `LCRYPTO_HASH_SECRET_KEY`. When `KMS_VENDOR` is `hashicorp-vault`, the CRM generates keys for each organization and wraps them with a HashiCorp Vault Transit key that you operate. Never hardcode a key or expose it in source code or version control.

With `hashicorp-vault`, the CRM uses the Vault Transit engine mounted at `transit-st`. Each Organization has its own Transit key, named `org-<organization_id>`. Midaz signs in to Vault with AppRole: set `KMS_VAULT_AUTH_METHOD` to `approle`, and set `KMS_VAULT_ROLE_ID` and `KMS_VAULT_SECRET_ID`. Give that AppRole permission to encrypt and decrypt with the Organization keys on `transit-st`.

Midaz provisions the CRM keys of an Organization when the Organization first needs them. To provision them in advance, call `POST /v2/organizations/{organization_id}/encryption/provision`. To check them, call `GET /v2/organizations/{organization_id}/encryption/status`.

> [!CAUTION]
>
> Protect your keys with a dedicated secret manager or secure storage.

### Protected fields

The CRM protects the fields listed below. You do not need to know how this protection works. Do not enter sensitive data in any field that this list does not include.

> [!CAUTION]
>
> Never store sensitive information in the `metadata` object.

#### Holder

* `name`
* `document`
* `contact.primaryEmail`
* `contact.secondaryEmail`
* `contact.mobilePhone`
* `contact.otherPhone`
* `naturalPerson.motherName`
* `naturalPerson.fatherName`
* `naturalPerson.monthlyGrossIncome.value`
* `legalPerson.representative.name`
* `legalPerson.representative.document`
* `legalPerson.representative.email`

#### Instrument

* `document`
* `bankingDetails.account`
* `bankingDetails.iban`
* `regulatoryFields.participantDocument`
* `relatedParties.document`

## Best practices & recommendations

***

Data encryption in the CRM adds a strong security layer. Even if an attacker compromises the database, the protected fields stay unreadable in their original form.

The CRM decrypts data only with a valid key, or through authenticated and authorized service calls. Key security is therefore critical. If a key leaks, the application cannot protect your data on its own.

To keep your environment safe, we strongly recommend:

* **Do not expose the Midaz API** directly on edge layers such as gateways or frontend apps.
* **Never store sensitive data in metadata fields.** The CRM does not encrypt them.
* **Enforce governance** over access to the production environment and related tools.
* **Use secure key managers** with strict access controls to safeguard your secrets.
* **Encrypt disks or volumes** to protect data at rest.

> [!WARNING]
>
> Data security is a shared responsibility. The CRM gives you the building blocks. Make sure your deployment uses them well.


# Getting started with CRM
Source: https://docs.lerian.studio/en/products/midaz/crm/crm-getting-started

Follow this guide to register Holders in CRM and link them to ledger accounts with Instruments through the Midaz REST API.

This guide shows how to create and manage **Holders**, the customers or companies behind your accounts.

It also links each holder to a ledger account with an **Instrument**. By the end, you have a holder registered in CRM and linked to a ledger account.

## Prerequisites

***

Before you begin, make sure you meet the following requirements:

* You completed the [Midaz setup](/en/products/midaz/midaz-setup) guide and all services run.
* At least one **Organization**, **Ledger**, and **Account** already exist, as created in the [Midaz Getting Started](/en/products/midaz/midaz-getting-started) guide.
* The Midaz ledger serves the holder and instrument endpoints. In Midaz v4, CRM is part of the ledger binary, so it needs no separate service or port.

> [!NOTE]
>
> Replace the placeholder IDs in the examples below with the real IDs from your environment.

## CRM components

***

The CRM (Customer Relationship Management) component lets you register the people and companies behind your ledger accounts.

It manages two core entities:

* **Holders**: Individuals (`NATURAL_PERSON`) or companies (`LEGAL_PERSON`) that own accounts.
* **Instruments**: The link between a holder and a specific ledger account, with optional banking details.

This model lets one holder own many accounts across different ledgers. It keeps identity and contact information in one place.

## Step 1: Create a holder

***

A **Holder** represents a person or company in your system. Create holders for individuals (`NATURAL_PERSON`) or companies (`LEGAL_PERSON`).

Send a `POST` request with the holder's type, name, document, contact, and address. For the full request and response schema, see [Create a holder](/en/reference/products/midaz/v2/create-holder).

> **Individual holder example**
>
> ```bash theme={null}
> curl -X POST http://localhost:3002/v2/organizations/{organization_id}/holders \
>   -H "Content-Type: application/json" \
>   -d '{
>     "type": "NATURAL_PERSON",
>     "name": "Jane Smith",
>     "document": "12345678900",
>     "contact": {
>       "primaryEmail": "jane.smith@example.com",
>       "mobilePhone": "+15551234567"
>     },
>     "addresses": {
>       "primary": {
>         "line1": "123 Main Street",
>         "line2": "Apt 4B",
>         "city": "New York",
>         "state": "NY",
>         "zipCode": "10001",
>         "country": "US",
>         "description": "Home address"
>       }
>     },
>     "naturalPerson": {
>       "favoriteName": "Jane",
>       "birthDate": "1990-05-15",
>       "nationality": "American"
>     },
>     "metadata": {
>       "segment": "premium",
>       "source": "onboarding"
>     }
>   }'
> ```

> **Company holder example**
>
> To register a company instead of an individual, set the type to `LEGAL_PERSON`:
>
> ```bash theme={null}
> curl -X POST http://localhost:3002/v2/organizations/{organization_id}/holders \
>   -H "Content-Type: application/json" \
>   -d '{
>     "type": "LEGAL_PERSON",
>     "name": "Acme Corp Ltd",
>     "document": "12345678000199",
>     "contact": {
>       "primaryEmail": "finance@acmecorp.com",
>       "mobilePhone": "+15559876543"
>     },
>     "legalPerson": {
>       "tradeName": "Acme Corp",
>       "activity": "Financial services",
>       "type": "Limited Liability",
>       "foundingDate": "2015-03-20",
>       "size": "Medium",
>       "status": "Active",
>       "representative": {
>         "name": "Bob Johnson",
>         "document": "98765432100",
>         "email": "bob@acmecorp.com",
>         "role": "CFO"
>       }
>     }
>   }'
> ```

> [!TIP]
>
> Save the `id` from the response. You use it when you create instruments.

## Step 2: Link a holder to an account

***

Once the holder exists, link it to a ledger account with an **Instrument**. An instrument connects a holder to one account inside a ledger, with optional banking details.

For the full request and response schema, see [Create an instrument](/en/reference/products/midaz/v2/create-instrument).

> **Example request**
>
> ```bash theme={null}
> curl -X POST http://localhost:3002/v2/organizations/{organization_id}/holders/{holder_id}/instruments \
>   -H "Content-Type: application/json" \
>   -d '{
>     "ledgerId": "{ledger_id}",
>     "accountId": "{account_id}",
>     "bankingDetails": {
>       "branch": "0001",
>       "account": "123450",
>       "type": "CACC",
>       "openingDate": "2025-01-15",
>       "countryCode": "US",
>       "bankId": "12345"
>     },
>     "metadata": {
>       "isPrimary": "true"
>     }
>   }'
> ```

## Step 3: Query and update your data

***

Once holders and instruments exist, you can retrieve, list, and update them.

| Operation | Endpoint | API reference |
| - | - | - |
| Retrieve a holder | `GET /v2/organizations/{organization_id}/holders/{holder_id}` | [Retrieve a holder](/en/reference/products/midaz/v2/get-holder-by-id) |
| List all holders | `GET /v2/organizations/{organization_id}/holders?limit=10&page=1` | [List holders](/en/reference/products/midaz/v2/list-holders) |
| List instruments for a holder | `GET /v2/organizations/{organization_id}/instruments?holder_id={holder_id}` | [List instruments](/en/reference/products/midaz/v2/list-instruments) |
| Retrieve a specific instrument | `GET /v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}` | [Retrieve an instrument](/en/reference/products/midaz/v2/get-instrument-by-id) |
| Update a holder | `PATCH /v2/organizations/{organization_id}/holders/{holder_id}` | [Update a holder](/en/reference/products/midaz/v2/update-holder) |

> **Update holder example**
>
> ```bash theme={null}
> curl -X PATCH http://localhost:3002/v2/organizations/{organization_id}/holders/{holder_id} \
>   -H "Content-Type: application/json" \
>   -d '{
>     "contact": {
>       "primaryEmail": "jane.new-email@example.com",
>       "mobilePhone": "+15559999999"
>     },
>     "metadata": {
>       "segment": "vip",
>       "source": "onboarding"
>     }
>   }'
> ```

## Step 4: Clean up

***

To remove resources, delete instruments first, then holders. Midaz refuses to delete a holder that still has instruments or accounts that carry its ID.

| Operation | Endpoint | API reference |
| - | - | - |
| Delete an instrument | `DELETE /v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}` | [Delete an instrument](/en/reference/products/midaz/v2/delete-instrument) |
| Delete a holder | `DELETE /v2/organizations/{organization_id}/holders/{holder_id}` | [Delete a holder](/en/reference/products/midaz/v2/delete-holder) |

> **Example requests**
>
> Delete an instrument:
>
> ```bash theme={null}
> curl -X DELETE http://localhost:3002/v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}
> ```
>
> Delete a holder:
>
> ```bash theme={null}
> curl -X DELETE http://localhost:3002/v2/organizations/{organization_id}/holders/{holder_id}
> ```

## Next steps

***

> **[CRM API reference](/en/reference/products/midaz/v2/create-holder)**
>
> Explore advanced filtering, metadata queries, and all available endpoints.

> **[Using CRM with Midaz Console](/en/products/midaz/crm/using-crm-with-midaz-console)**
>
> Manage holders through a graphical interface.


# CRM migration history
Source: https://docs.lerian.studio/en/products/midaz/crm/crm-migration-guide

Historical context for moving standalone CRM data to the Midaz v4 Ledger.

> [!WARNING]
>
> This page documents a legacy topology. Do not use it as a deployment guide for Midaz v4.

Earlier installations could run CRM separately. Midaz v4 embeds CRM in the Ledger: use Holder and Instrument endpoints only through `/v2/organizations/{organization_id}/...`. The Ledger is the current deployment unit. CRM is not a plugin, standalone service, or separate v4 release.

## What a v4 installation does not use

Do not use the standalone CRM service, port `4003`, the `X-Organization-Id` header, or the legacy CRM v1 alias endpoints in a v4 installation. Fees in Midaz v4 runs in the Ledger and is available only on `/v2`.

If you retire an older standalone CRM deployment, retain its MongoDB backup and release values. Then reconcile Holder and Instrument records through the Ledger `/v2` API before you decommission the old workload. Preserve that release record.

See [CRM getting started](/en/products/midaz/crm/crm-getting-started) and the [Midaz chart README](https://github.com/LerianStudio/helm/tree/main/charts/midaz).


# What is CRM?
Source: https://docs.lerian.studio/en/products/midaz/crm/crm-overview

The optional CRM layer adds customer identity, contact details, and business context to Midaz Ledger accounts, outside the ledger.

CRM is not part of the ledger's transactional domain. It adds business attributes to ledger accounts.

CRM is where user metadata lives. It does not hold balances, transfers, or fees. It records who is behind an account and what you need to run your business.

## Current API

***

CRM is served by the Ledger only on `/v2`, under `/v2/organizations/{organization_id}/...`. `/v1` does not expose CRM. Use the `midaz` authorization namespace with the `holders` and `instruments` resources.

> [!TIP]
>
> **Test CRM locally**
>
> You can run CRM locally, without Kubernetes, with the Midaz stack from [Getting started](/en/products/midaz/midaz-getting-started).

## Why use the CRM?

***

Midaz ledger accounts are generic by design. They are transaction-first and domain-agnostic. CRM adds meaning to those accounts and links each one to a user profile and a business context.

You do not have to use CRM. You can adopt it later, only when your use case needs customer or business metadata beyond the ledger.

### Example use cases

* **Banking (individuals and businesses)**: CRM stores identifiers like CPF or CNPJ, an address, contact details, or account numbers. Midaz runs the same transaction logic for both customer types.
* **Supply chains (supplier, factory, retailer)**: CRM tracks metadata like supplier IDs, warehouse locations, or contract details. This data does not belong in the transaction, but it drives business decisions.

> [!TIP]
>
> CRM ships inside the Midaz ledger, so there is no separate service to deploy. Use it only if your product or regulatory context needs customer or business metadata.

## Entities

***

CRM has two core entities:

* **[Holder](/en/products/midaz/crm/holders)** – The main entity in CRM. It represents the persona for a Midaz ledger account. It stores identity attributes and individual traits.
* **[Instrument](/en/products/midaz/crm/alias-accounts)** – The business context for a [Ledger Account](/en/products/midaz/accounts) in **Midaz Ledger**. It holds financial details such as bank account information.

*Figure 1* shows how the CRM entities connect to Midaz.

![How CRM entities, the Holder and the Instrument, connect to accounts in the Midaz ledger](https://mintcdn.com/lerian-49cb71fc/svQbQMf9Iz90q0Cc/images/en/d2/entities-new.svg?fit=max\&auto=format\&n=svQbQMf9Iz90q0Cc\&q=85\&s=87a301718533b124568d374140b17cea)

Figure 1. How CRM entities connect to Midaz

## Design principles

***

CRM focuses on:

* **Separation of concerns**: It keeps user profile data out of transaction logic.

* **Simpler deployment**: CRM ships inside the ledger binary, with no separate service to run.

* **Clear domain boundaries**: It evolves with Midaz without coupling to ledger internals.

> [!CAUTION]
>
> CRM does not validate compliance processes such as KYC. It is a neutral, persistent data layer.

## API behavior

***

CRM runs inside the Midaz ledger binary. It exposes a registry API for non-transactional data linked to Midaz accounts.

* It does not enforce validations such as user status, risk profile, or document verification.
* It is agnostic to the asset or grouping logic used in Midaz accounts.
* It gives consistent access to holder metadata without loading the transaction layer.

## Security & compliance

***

In BYOC, you run Midaz and its components in your own infrastructure. You keep control of your infrastructure, compliance policies, and user-data lifecycle.

CRM ships with Midaz and follows the same security standards as the rest of the platform:

* **Data in transit**: Midaz serves plain HTTP, so terminate TLS at your ingress or service mesh.
* **Data at rest**: Midaz encrypts the protected CRM fields before it stores them.

> [!CAUTION]
>
> You own encryption key management. Use a secret-management service to store and control access to keys.

You define and enforce your own policies for LGPD, GDPR, and other regional data-protection rules. CRM provides the structure.

Review the [Security recommendations](/en/products/midaz/security-recommendations) before you deploy any component into your environment.

Apply security best practices to every component: **Access Manager**, **Fees Engine**, **Pix**, and **CRM**. Secure network boundaries, manage secrets, apply patches, and enforce strict access control.

## Data deletion strategies

***

CRM gives you full control over how it removes data. It offers two options:

* **Soft delete** (default): CRM flags the record as deleted but keeps it in the database. Use it to keep an audit trail or to recover data later.
* **Hard delete**: Where your policy permits removal, CRM removes the record from its database.

Your policies define the behavior.

## Access control

***

To restrict who can access your CRM data, enable our [Access Manager](/en/platform/access-manager).

### Enabling Access Manager

First, install **Access Manager**. Then open the Midaz ledger `.env` file and set these environment variables:

```text Text theme={null}
## AUTH

PLUGIN_AUTH_HOST=http://plugin-auth:4000
PLUGIN_AUTH_ENABLED=true
```

After you enable it, CRM enforces access permissions from your authentication setup.

> [!TIP]
>
> Access Manager is available under the Enterprise model.
> To evaluate it, [contact our team](https://lerian.studio/contact).

> [!TIP]
>
> See [Getting started with CRM](/en/products/midaz/crm/crm-getting-started) for a step-by-step guide.

## Next steps

***

> **[Core concepts](/en/products/midaz/crm/crm-core-concepts-overview)**
>
> Understand the key entities managed by CRM: Holders and Instruments.

> **[Explore the CRM API](/en/reference/products/midaz/v2/create-holder)**
>
> Browse endpoints for holders, instruments, and related parties.

> **[Using CRM](/en/products/midaz/crm/crm-using-overview)**
>
> Learn how to register holders and link them to ledger accounts.


# Using CRM
Source: https://docs.lerian.studio/en/products/midaz/crm/crm-using-overview

Manage Holders and Instruments in CRM day to day through the REST API or the visual Midaz Console interface.

This section covers CRM configuration and day-to-day operations through the REST API or the Midaz Console.

## Content

***

Here, you'll find:

* [**Using CRM**](/en/products/midaz/crm/crm-getting-started): Manage Holders and Instruments through the REST API.
* [**Using CRM with Midaz Console**](/en/products/midaz/crm/using-crm-with-midaz-console): Manage Holders and Instruments through the Midaz Console graphical interface.


# Holders
Source: https://docs.lerian.studio/en/products/midaz/crm/holders

Model the individuals or organizations behind Midaz accounts as Holders, storing names, documents, contacts, and compliance details as Natural or Legal Person.

A **Holder** is the core entity in CRM. It represents a real-world individual or organization behind a Midaz ledger account. A Holder stores identity attributes such as the name, document number, contact details, and addresses.

[CRM](/en/products/midaz/crm/crm-overview) manages Holders. Holders do not belong to the ledger's transactional domain. They enrich ledger accounts with business data.

Each Holder is one of two types: **Natural Person** (individual) or **Legal Person** (company/organization).

> [!TIP]
>
> To create and manage holders step by step, see [Getting started with CRM](/en/products/midaz/crm/crm-getting-started).

## Holder types

***

You choose the type at creation. You cannot change it later.

### Natural Person

The Natural Person type represents an individual customer. It supports personal attributes such as the name, gender, birth date, civil status, nationality, and family information.

Use this type for:

* Individual bank account holders
* Personal wallet owners
* Freelancers or sole proprietors

### Legal Person

The Legal Person type represents a company or organization. It supports business attributes such as the trade name, activity type, founding date, company size, and legal representative details.

Use this type for:

* Corporate treasury accounts
* Business partners and suppliers
* Institutional clients

> [!TIP]
>
> Choose the holder type carefully at creation. You cannot change it later. To use a different type, create a new Holder.

## Holder fields

***

### Core fields

| Field | Type | Required | Description |
| :- | :- | :- | :- |
| **id** | `uuid` | System-generated | Unique identifier of the Holder. |
| **type** | `enum` | Yes | `NATURAL_PERSON` or `LEGAL_PERSON`. |
| **name** | `string` | Yes | Full name of the individual or legal name of the company. |
| **document** | `string` | Yes | Identification document number (e.g., CPF, CNPJ, passport). |
| **externalId** | `string` | No | Optional identifier to map the Holder to an external system. |
| **metadata** | `object` | No | Key-value pairs for custom, non-sensitive data. Keys are limited to 100 characters and values to 2000 characters. |
| **createdAt** | `datetime` | System-generated | Timestamp of creation (RFC 3339). |
| **updatedAt** | `datetime` | System-generated | Timestamp of last update (RFC 3339). |
| **deletedAt** | `datetime` | System-generated | Timestamp of soft deletion, if applicable (RFC 3339). |

### Address fields

The `addresses` object supports up to three addresses: `primary`, `additional1`, and `additional2`. Each address contains:

| Field | Type | Required | Description |
| :- | :- | :- | :- |
| **line1** | `string` | No | Primary address line (street, number). Max 256 characters. |
| **line2** | `string` | No | Secondary address line (apartment, suite). Max 256 characters. |
| **zipCode** | `string` | No | Postal or ZIP code. Max 20 characters. |
| **city** | `string` | No | City name. Max 100 characters. |
| **state** | `string` | No | State or province code. Max 100 characters. |
| **country** | `string` | No | ISO 3166-1 alpha-2 country code (e.g., `US`, `BR`). |
| **description** | `string` | No | A descriptive label for the address (for example, Home, Office, or Billing). Max 100 characters. |

### Contact fields

| Field | Type | Required | Description |
| :- | :- | :- | :- |
| **primaryEmail** | `string` | No | Primary email address. |
| **secondaryEmail** | `string` | No | Secondary email address. |
| **mobilePhone** | `string` | No | Mobile phone number with country code (e.g., `+5511999999999`). |
| **otherPhone** | `string` | No | Alternative phone number. |

### Natural Person fields

| Field | Type | Required | Description |
| :- | :- | :- | :- |
| **favoriteName** | `string` | No | Preferred name or nickname. |
| **socialName** | `string` | No | Social name (name the person identifies with). |
| **gender** | `string` | No | Gender identity. |
| **birthDate** | `string` | No | Date of birth in `YYYY-MM-DD` format. |
| **civilStatus** | `string` | No | Marital status (e.g., Single, Married, Divorced). |
| **nationality** | `string` | No | Nationality (e.g., Brazilian, American). |
| **motherName** | `string` | No | Mother's full name. |
| **fatherName** | `string` | No | Father's full name. |
| **monthlyGrossIncome** | `object` | No | Monthly gross income, with `value`, `currency`, and `referenceDate`. All three are required inside the object. |
| **status** | `string` | No | Lifecycle status (e.g., `Active`, `Inactive`, `Suspended`, `Closed`). |

### Legal Person fields

| Field | Type | Required | Description |
| :- | :- | :- | :- |
| **tradeName** | `string` | No | Trade or doing-business-as name. |
| **activity** | `string` | No | Primary business activity. |
| **type** | `string` | No | Legal structure (e.g., LLC, Corporation). |
| **foundingDate** | `string` | No | Date the company was founded in `YYYY-MM-DD` format. |
| **size** | `string` | No | Company size classification (e.g., Small, Medium, Large). |
| **annualGrossRevenue** | `object` | No | Annual gross revenue, with `value`, `currency`, and `referenceDate`. All three are required inside the object. |
| **totalAssets** | `object` | No | Total assets, with `value`, `currency`, and `referenceDate`. All three are required inside the object. |
| **status** | `string` | No | Lifecycle status (e.g., `Active`, `Inactive`, `Suspended`, `Closed`). |

#### Representative

The `representative` object within `legalPerson` stores the details of the company's legal representative:

| Field | Type | Required | Description |
| :- | :- | :- | :- |
| **name** | `string` | No | Full name of the legal representative. |
| **document** | `string` | No | Document number of the representative. |
| **email** | `string` | No | Email address of the representative. |
| **role** | `string` | No | Role within the company (e.g., CEO, CFO). |

## Data security

***

Midaz encrypts several Holder fields at rest, including the `name`, the `document`, and the contact fields. This protects the data even if someone gains access to the storage.

> [!WARNING]
>
> Never store sensitive information in the `metadata` object. Midaz does not encrypt metadata and stores it in plain text.

For the full list of protected fields and encryption strategies, see [CRM data security](/en/products/midaz/crm/crm-data-security).

## Managing Holders

***

### Via API

Use the CRM API to manage Holders programmatically:

* [Create a Holder](/en/reference/products/midaz/v2/create-holder): Register a new Holder in the system.
* [List Holders](/en/reference/products/midaz/v2/list-holders): View all Holders with pagination and filters.
* [Retrieve a Holder](/en/reference/products/midaz/v2/get-holder-by-id): Get the details of a specific Holder.
* [Update a Holder](/en/reference/products/midaz/v2/update-holder): Edit an existing Holder's data.
* [Delete a Holder](/en/reference/products/midaz/v2/delete-holder): Soft-delete or permanently remove a Holder. Midaz refuses while the Holder still has Instruments or accounts that carry its ID.

> [!NOTE]
>
> Every CRM API request includes the organization ID in the URL path, for example `/organizations/{organization_id}/holders`. If you enable [Access Manager](/en/platform/access-manager), add an `Authorization` header with a Bearer token.

### Via Lerian Console

You can manage Holders through the **Holders** page in the Midaz Module of [Lerian Console](/en/platform/console/about-lerian-console). The console lets you create, view, edit, and delete Holders without code.

[**Learn more in the Managing Holders guide.**](/en/products/midaz/console/managing-crm-holders)

## Next steps

***

> **[Instruments](/en/products/midaz/crm/alias-accounts)**
>
> Learn how Instruments link Holders to Midaz ledger accounts.

> **[Using CRM](/en/products/midaz/crm/crm-using-overview)**
>
> Follow the step-by-step guide to register Holders and create Instruments.


# CRM in Lerian Console
Source: https://docs.lerian.studio/en/products/midaz/crm/using-crm-with-midaz-console

Manage CRM Holders and Alias Accounts visually inside the Midaz Module of Lerian Console, without writing API calls.

The **CRM** interface is part of the **Midaz Module** in [Lerian Console](/en/platform/console/about-lerian-console). Use it to manage core entities such as Holders and Alias Accounts.

## Accessing CRM features

***

CRM features are in the **Midaz Module** of Lerian Console. To open them:

1. Open **Lerian Console** and go to the **Midaz Module**
2. In the left-side menu, find the CRM entities in the **Accounts** section:
   * **Holders** - Manage individuals and companies
   * **Alias** - Link holders to ledger accounts on the **Alias Accounts** page

### Available actions

From the Midaz Module, you can:

> **[Manage Holders](/en/products/midaz/console/managing-crm-holders)**
>
> Create and manage individuals or companies associated with your accounts

> **[Manage Alias Accounts](/en/products/midaz/console/managing-crm-alias-accounts)**
>
> Link holders to Midaz ledger accounts with business context


# Database migrations
Source: https://docs.lerian.studio/en/products/midaz/database-migrations

Run Midaz Ledger and Tracer PostgreSQL schema migrations with dedicated runner images so applications boot against an already-migrated database.

Midaz applies PostgreSQL schema migrations through dedicated migration-runner images (one for the Ledger, one for Tracer), decoupled from the application binaries. The apps do not migrate at startup. They boot against a schema that the runner has already migrated.

> [!NOTE]
>
> This model is what runs under `make up` in local development and under the Helm chart in Kubernetes. If you use `make up`, you need no manual step. The compose stack gates the app on the migration runner.

## Why a dedicated runner

***

The dedicated runner has these properties:

* Migrations run once, as a separate step.
* The app image does not bundle migration SQL and does not change the schema.
* The runner image runs under a hardened security context (see [Security posture](#security-posture)).

## Runner images

***

Each release ships two images:

| Image | Applies | Databases |
| - | - | - |
| `midaz-ledger-migrations` | Ledger onboarding + transaction migrations | Two: `onboarding`, `transaction` |
| `midaz-tracer-migrations` | Tracer schema | One |

Both images share the same shape:

* Base: [`migrate/migrate`](https://github.com/golang-migrate/migrate), at a pinned version.
* Runs as `USER 65532:65532` (non-root, UID-agnostic).
* POSIX shell entrypoint that assembles a DSN from environment variables, runs `migrate ... up`, and exits.
* Writes nothing to disk. Postgres tracks migration progress in the `schema_migrations` table, so `readOnlyRootFilesystem: true` is safe.

The Ledger runner applies onboarding first, then transaction, in a single invocation. The Tracer runner applies its single database in one pass.

## Environment contract

***

Each entrypoint accepts either a prebuilt URL override or the individual `DB_*` variables. The URL override takes precedence when set.

### Ledger runner

| Database | URL override | Assembled from |
| - | - | - |
| onboarding | `ONBOARDING_DATABASE_URL` | `DB_ONBOARDING_HOST`, `DB_ONBOARDING_PORT` (default `5432`), `DB_ONBOARDING_USER`, `DB_ONBOARDING_PASSWORD`, `DB_ONBOARDING_NAME`, `DB_ONBOARDING_SSLMODE` (default `disable`) |
| transaction | `TRANSACTION_DATABASE_URL` | `DB_TRANSACTION_*` (same shape) |

### Tracer runner

| URL override | Assembled from |
| - | - |
| `DATABASE_URL` | `DB_HOST`, `DB_PORT` (default `5432`), `DB_USER`, `DB_PASSWORD`, `DB_NAME`, `DB_SSL_MODE` (default `disable`) |

### DSN shape

When the entrypoint assembles the DSN from `DB_*` variables, it produces:

```text theme={null}
postgres://<user>:<encoded-password>@<host>:<port>/<name>?sslmode=<sslmode>
```

The password is percent-encoded so URI-reserved characters (`% @ : / ? # & + space [ ]`) do not break the DSN. `%` is encoded first so already-inserted escapes are not double-encoded.

The entrypoint prints phase markers (`applying onboarding migrations`, `applying transaction migrations`, `applying tracer migrations`, `migrations complete`).

## Local development

***

### `make up`

From the repository root, `make up`:

1. Starts infra and waits until Postgres, MongoDB, Valkey, and RabbitMQ are ready.
2. Starts the one-shot `ledger-migrate` and `tracer-migrate` compose services.
3. Starts each app service, which `depends_on` its migrate service with `condition: service_completed_successfully`.

The app never starts against an un-migrated database.

### Host `make` targets

Each component exposes host-side Make targets that run migrations directly against a local database, for example when you develop a new migration. The targets install the pinned `golang-migrate` CLI when `migrate` is absent, and read connection settings from `.env`.

Ledger (`components/ledger`):

| Target | Effect |
| - | - |
| `make migrate` | Applies onboarding then transaction (aggregate) |
| `make migrate-onboarding` | Applies onboarding only |
| `make migrate-transaction` | Applies transaction only |
| `make migrate-down` | Rolls back the last migration on both databases |

Tracer (`components/tracer`):

| Target | Effect |
| - | - |
| `make migrate` | Applies the tracer schema |
| `make migrate-down` | Rolls back the last tracer migration |

### Example: run the Ledger runner manually

You rarely need to invoke the runner image by hand, because the compose gate does it for you. When you do, point the runner at your databases via `DB_*` (or `*_DATABASE_URL`) and run it once:

```bash theme={null}
docker run --rm \
  --network=infra-network \
  -e DB_ONBOARDING_HOST=midaz-postgres-primary \
  -e DB_ONBOARDING_PORT=5701 \
  -e DB_ONBOARDING_USER=midaz \
  -e DB_ONBOARDING_PASSWORD=lerian \
  -e DB_ONBOARDING_NAME=onboarding \
  -e DB_ONBOARDING_SSLMODE=disable \
  -e DB_TRANSACTION_HOST=midaz-postgres-primary \
  -e DB_TRANSACTION_PORT=5701 \
  -e DB_TRANSACTION_USER=midaz \
  -e DB_TRANSACTION_PASSWORD=lerian \
  -e DB_TRANSACTION_NAME=transaction \
  -e DB_TRANSACTION_SSLMODE=disable \
  lerianstudio/midaz-ledger-migrations:<tag>
```

The runner exits `0` on success (including the idempotent no-op case) and non-zero on failure.

## Kubernetes deployment

***

In production, run each migration runner as a Kubernetes Job (typically an Argo CD PreSync Job or a Helm hook) that completes before the app rollout. The Helm chart wires this up for you. The sections below cover the properties that matter if you author your own manifests.

> [!NOTE]
>
> The runner migrates the databases pointed at by its environment, once.

### Security posture

The runner works under a hardened pod security context:

* **Non-root**: the image sets `USER 65532:65532`.
* **UID-agnostic**: migration files are root-owned and world-readable, so any UID can read them.
* **`readOnlyRootFilesystem`-safe**: `migrate` writes no filesystem state.

The same image runs cleanly under `runAsNonRoot: true`, `readOnlyRootFilesystem: true`, and `capabilities: drop [ALL]`.

### TLS

The entrypoints honor `sslmode` from the environment (`DB_ONBOARDING_SSLMODE`, `DB_TRANSACTION_SSLMODE`, or `DB_SSL_MODE`), defaulting to `disable`. Production deployments should set `require` (or stricter). The shell runner does not reproduce the in-code TLS enforcement, error classification, or telemetry that the apps use for their own connections. You control TLS for migrations through `sslmode` alone, in exchange for a minimal, dependency-free runner.

## Conventions and idempotency

***

* **Paired up/down**: every migration has a `.up.sql` and a `.down.sql` file.
* **Idempotent**: running `migrate up` when the schema is already at the latest version is a no-op. Re-running the runner after a partial or complete apply is safe.
* **Pinned CLI**: the runner images use a pinned `golang-migrate` version. The host `make` targets install the same version when `migrate` is absent.

## Upgrading from earlier versions

***

To adopt the new model:

1. Pull the release that ships the runner images.
2. In Kubernetes, add the `midaz-ledger-migrations` and `midaz-tracer-migrations` Jobs to your deploy pipeline so they run before the app rollout. If you use the official Helm chart, this is done for you.
3. In local development, `make up` gates the apps on the one-shot migrate services.

## Related pages

***

* [Installing Midaz](/en/products/midaz/midaz-setup): full local setup with `make up`.
* [Updating Midaz](/en/products/midaz/updating-midaz): upgrade flows for local and Helm.
* [Deployment strategies](/en/products/midaz/deployment): BYOC deployment overview.
* [Tracer environment variables](/en/products/tracer/tracer-environment-variables): full Tracer configuration reference.


# Deployment strategies
Source: https://docs.lerian.studio/en/products/midaz/deployment

Choose the right deployment strategy for Midaz under BYOC: Kubernetes with Helm, Terraform foundations, and infrastructure prerequisites.

This section covers deployment strategies for running Midaz in your own infrastructure under the **BYOC (Bring Your Own Cloud)** model. If you're using the **SaaS** model, Lerian manages deployment for you. Skip ahead to [Getting started](/en/start-here/getting-started) to begin configuring your platform.

> [!NOTE]
>
> Not sure which model fits? See [Deployment models](/en/start-here/evaluate-and-deploy/deployment-models) for a full comparison of SaaS and BYOC.

Set up your environment, meet the prerequisites, and follow our best practices.

> [!TIP]
>
> Before you deploy, check out the [Midaz Architecture Overview](/en/products/midaz/architecture).

### Content

* [Midaz Terraform Foundation](/en/products/midaz/midaz-terraform-foundation): Ready-made Terraform examples for provisioning the cloud infrastructure Midaz runs on (AWS, GCP, or Azure).

To install, configure, and upgrade Midaz with its chart, see the [Midaz chart README](https://github.com/LerianStudio/helm/tree/main/charts/midaz).

## Deployment strategies

***

You manage the infrastructure in both Midaz editions, Community and Enterprise. We strongly recommend using Kubernetes with our Helm Charts. This approach simplifies deployment and scaling.

You can choose the deployment strategy that fits your needs.

### Deploying with Kubernetes

We recommend our official Helm Charts. They install Midaz in a Kubernetes environment.

You can either plug Midaz into your existing databases and services or use the default components provided in the Helm chart. This setup adapts to different infrastructure needs.

For the step-by-step installation, see the [Midaz chart README](https://github.com/LerianStudio/helm/tree/main/charts/midaz).

### Self-managed deployment

If you prefer full control, you can deploy Midaz manually. Midaz includes a Docker configuration, which makes local or small-scale setups straightforward.

You can also adapt it to your own infrastructure, with a different orchestrator or directly on virtual machines or bare metal.

For instructions, check the [Installing Midaz](/en/products/midaz/midaz-setup) page.

## Platform requirements

***

The default Helm configuration meets these minimums, except for RabbitMQ. The bundled RabbitMQ server runs below the 4.x target. If you bring your own infrastructure components, make sure you meet the minimum supported versions:

| Service | Minimum Supported Version | Notes |
| :- | :- | :- |
| Kubernetes | 1.23+ | 1.30+ recommended |
| Helm CLI | 3.8+ | Required for OCI registry |
| PostgreSQL | 17 | Primary database |
| MongoDB | 8.x | Document storage |
| RabbitMQ | 4.x | Message broker |
| Valkey | 8.x | Live balances (Redis fork) |

Midaz needs these minimum versions for a stable, performant platform.

## Best practices

***

### Access to the infrastructure

* Use least privilege policies when connecting to databases.
* Block direct access to databases by default. Only allow it in exceptional cases with approval.
* Store secrets securely using tools like HashiCorp Vault.
* Use dedicated tools for safe access to production data.

### Redundancy and high availability

* Enable replication and backups for both Midaz and your databases.
* Use load balancers to route traffic across services evenly.

### Network security

* Run your services inside VPCs to isolate critical components.
* Use NAT gateways or proxies for outbound connections.
* Apply security groups or firewall rules to restrict access to required ports and IPs.

### Data persistence and storage

* Use replicated databases to support high availability and recovery.
* Choose scalable storage solutions that match your data growth.
* Use Valkey (Redis fork), which holds the live balances.

### Observability

* Integrate tools that monitor logs, traces, and metrics.
* Midaz supports observability through OpenTelemetry.

## Shared responsibilities

***

Under the BYOC model, Lerian and your team share responsibility for running Midaz. For a detailed breakdown of who secures what (including how responsibilities differ between BYOC and SaaS), see the [Security](/en/products/midaz/security) page.

> [!TIP]
>
> For guidance on securing your environment before deployment, check the [Security Recommendations](/en/products/midaz/security-recommendations) documentation.


# Fees Engine billing package examples
Source: https://docs.lerian.studio/en/products/midaz/fees/billing-package-examples

Walk through end-to-end billing package examples for boleto tiered pricing, volume discounts, and account maintenance charges with full JSON configuration.

> [!TIP]
>
> This page is business-oriented. It focuses on *what* each billing model solves and *how* to configure it. For field-level details, see the [Billing Packages overview](/en/products/midaz/fees/fees-engine-overview#billing-packages) and the [API reference](/en/reference/products/midaz/v2/create-billing-package).

## Volume billing: boleto issuance with tiered pricing

***

### The business need

A fintech offers boleto issuance to its business clients. Pricing is volume-based: the more boletos a client issues each month, the lower the unit cost. The first 50 boletos each month are free. Clients that issue 1,000 or more boletos receive an extra 5% discount. At 3,000 boletos or more, the discount increases to 10%.

### Pricing structure

| Range | Unit price |
| - | - |
| 1–500 | R\$ 1.20 |
| 501–2,000 | R\$ 0.80 |
| 2,001+ | R\$ 0.45 |

### Package configuration

```json theme={null}
POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages
Body:
{
  "label": "Boleto Issuance — Tiered",
  "description": "Monthly volume billing for boleto issuance with progressive tiers",
  "type": "volume",
  "enable": true,
  "eventFilter": {
    "transactionRoute": "boleto-issuance",
    "status": "APPROVED"
  },
  "pricingModel": "tiered",
  "tiers": [
    { "minQuantity": 1, "maxQuantity": 500, "unitPrice": "1.20" },
    { "minQuantity": 501, "maxQuantity": 2000, "unitPrice": "0.80" },
    { "minQuantity": 2001, "maxQuantity": null, "unitPrice": "0.45" }
  ],
  "freeQuota": 50,
  "discountTiers": [
    { "minQuantity": 1000, "discountPercentage": "5.00" },
    { "minQuantity": 3000, "discountPercentage": "10.00" }
  ],
  "countMode": "perRoute",
  "assetCode": "BRL",
  "debitAccountAlias": "client-operating",
  "creditAccountAlias": "fees-boleto-revenue"
}
```

### How the calculation works

At month-end, the orchestrator calls `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate` with the billing period. The engine counts approved boleto transactions on the route, subtracts the free quota, applies tiered pricing, and applies the matching discount.

Tiered pricing is **volume pricing**: the engine picks the single tier the billable count lands in and charges every billable unit at that tier's price. It does not bill each tier's slice separately.

**Example result** for a client that issued 1,800 boletos in March:

| Step | Detail | Amount |
| - | - | - |
| Total issued | 1,800 boletos | — |
| Free quota | 50 exempt | — |
| Billable | 1,750 boletos | — |
| Matching tier | 501–2,000 → R\$ 0.80 | — |
| Gross | 1,750 × R\$ 0.80 | R\$ 1,400.00 |
| Discount | 5% (total count ≥ 1,000) | −R\$ 70.00 |
| **Net total** | — | **R\$ 1,330.00** |

The engine returns a transaction payload that debits `client-operating` by R\$ 1,330.00 and credits `fees-boleto-revenue`.

## Maintenance billing: monthly account fee (*PF*)

***

### The business need

A digital bank charges a fixed monthly maintenance fee for active personal (PF) accounts. The fee is R\$ 9.90 per account. The engine keeps only accounts whose status code is `active` and excludes every other status. You do not filter them by hand.

Midaz organizes accounts by segment. A PF segment groups all personal accounts.

### Package configuration

```json theme={null}
POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages
Body:
{
  "label": "PF Account Maintenance",
  "description": "Monthly maintenance fee for active personal accounts",
  "type": "maintenance",
  "enable": true,
  "feeAmount": "9.90",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "fees-maintenance-pf",
  "accountTarget": {
    "segmentId": "0198e5f4-7b2a-7c3d-9e1f-2a3b4c5d6e7f"
  }
}
```

### How the calculation works

The engine resolves all accounts in the PF segment and filters for active status. It generates one N:1 transaction: it debits R\$ 9.90 from each active account and sends the full total to `fees-maintenance-pf`.

**Example result** for 12,000 active PF accounts:

| Detail | Value |
| :- | :- |
| Active accounts | 12,000 |
| Fee per account | R\$ 9.90 |
| Transaction entries (source) | 12,000 debit entries |
| Transaction entries (destination) | 1 credit entry |
| **Total revenue** | **R\$ 118,800.00** |

## Volume billing: fixed-price Pix

***

### The business need

A fintech charges R\$ 0.10 per Pix sent (flat rate, no tiers).

### Package configuration

```json theme={null}
POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages
Body:
{
  "label": "Pix Send — Standard",
  "description": "Flat-rate billing per Pix sent",
  "type": "volume",
  "enable": true,
  "eventFilter": {
    "transactionRoute": "pix-send",
    "status": "APPROVED"
  },
  "pricingModel": "fixed",
  "tiers": [
    { "minQuantity": 1, "maxQuantity": null, "unitPrice": "0.10" }
  ],
  "freeQuota": 0,
  "discountTiers": [],
  "countMode": "perRoute",
  "assetCode": "BRL",
  "debitAccountAlias": "client-wallet",
  "creditAccountAlias": "fees-pix-revenue"
}
```

### How the calculation works

**Example result** for 5,000 Pix transactions:

| Detail | Value |
| :- | :- |
| Total Pix sent | 5,000 |
| Unit price | R\$ 0.10 |
| **Total** | **R\$ 500.00** |

## Maintenance billing: PJ portfolios with different rates

***

### The business need

A financial institution manages multiple business (PJ) account portfolios: PME (small and medium enterprises) and Corporate. Each portfolio has a different monthly maintenance fee. The institution wants to calculate both in a single billing run.

### Package configuration

**PME portfolio (R\$ 29.90/month):**

```json theme={null}
POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages
Body:
{
  "label": "PJ Maintenance — PME",
  "description": "Monthly maintenance for PME business accounts",
  "type": "maintenance",
  "enable": true,
  "feeAmount": "29.90",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "fees-maintenance-pj",
  "accountTarget": {
    "portfolioId": "0198e5f4-8c1d-7a2b-9f3e-4d5c6b7a8e9f"
  }
}
```

**Corporate portfolio (R\$ 89.90/month):**

```json theme={null}
POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages
Body:
{
  "label": "PJ Maintenance — Corporate",
  "description": "Monthly maintenance for Corporate business accounts",
  "type": "maintenance",
  "enable": true,
  "feeAmount": "89.90",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "fees-maintenance-pj",
  "accountTarget": {
    "portfolioId": "0198e5f4-9d2e-7b3c-8a4f-5e6d7c8b9a0e"
  }
}
```

### How the calculation works

A single call to `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate` with `"type": "maintenance"` processes both packages. The response includes one result per package and a consolidated summary.

**Example result** for 500 PME accounts + 50 Corporate accounts:

| Portfolio | Active accounts | Fee | Total |
| - | - | - | - |
| PME | 500 | R\$ 29.90 | R\$ 14,950.00 |
| Corporate | 50 | R\$ 89.90 | R\$ 4,495.00 |
| **Consolidated** | **550** | — | **R\$ 19,445.00** |

Both results credit the same `fees-maintenance-pj` account, so revenue stays consolidated. The orchestrator sends each transaction payload to Midaz independently.

## Next steps

***

> **[Create a billing package](/en/reference/products/midaz/v2/create-billing-package)**
>
> API reference for creating volume and maintenance billing packages.

> **[Calculate billing](/en/reference/products/midaz/v2/calculate-billing)**
>
> Trigger billing calculations for a period and retrieve transaction payloads.

> **[Billing calculations](/en/products/midaz/fees/fee-engine-calculation#billing-calculations)**
>
> Detailed mechanics of tiered pricing, free quotas, and maintenance billing.

> **[Best practices](/en/products/midaz/fees/fees-engine-best-practices)**
>
> Operational guidance for billing packages in production.


# Connect the Fees Engine to Midaz
Source: https://docs.lerian.studio/en/products/midaz/fees/connecting-fees-to-midaz

Configure the embedded Fees Engine with the Midaz ledger.

Fees runs inside the unified Midaz ledger process. Configure it in the ledger deployment. It is neither a separate service nor a plugin.

## Configuration

***

Configure its MongoDB storage with `MONGO_FEES_*` settings in the Midaz deployment. Each fee request must provide `send.asset`. Midaz rejects an empty value instead of using a fallback currency. See [Midaz environment variables](/en/products/midaz/midaz-environment-variables) for ledger configuration.

## See it in Lerian

***

* The full integration journey across the pieces: [Building a complete core banking](/en/products/building-a-complete-core-banking)
* What the Fees Engine does: [What is Fees Engine?](/en/products/midaz/fees/fees-engine-overview)
* Deploy the stack: [Helm charts](https://github.com/LerianStudio/helm)


# Creating a Fee Package
Source: https://docs.lerian.studio/en/products/midaz/fees/console/fe-creating-a-package

Build a new Fee Package in the Midaz Module by configuring basic info, amount ranges, flat or percentage fee rules, waivers, and priorities from the Console UI.

A Fee Package groups fee rules and defines when they apply to Transactions.

## Before you start

***

* Enable the **Fees Engine** in [Midaz module settings](/en/platform/console/plugin-settings).
* You need an existing Ledger and at least one Account that can receive fee amounts.
* If the package should apply only to a specific route or segment, create those records first.

## Create the Fee Package

***

**Step 1**

Go to the **Fee Packages** page and click the **New Package** button.

**Step 2**

The **New Fee Package** form will open with multiple sections to configure.

> [!TIP]
>
> Check the field guide for more information about the fields in the form.

**Step 1**

Fill in the **Basic Information** section

**Step 2**

Set **Minimum Amount** and **Maximum Amount** in the same section.

> [!NOTE]
>
> Transactions outside this range will not have fees applied from this package.

**Step 3**

Click the **Next** button.

**Step 4**

Select one of the options in the **Add Fee** section:

* **Flat Fee** - Fixed amount regardless of transaction value.
* **Percentage Fee** - Percentage of the transaction amount.
* **Max between types** - Higher value between flat and percentage.

**Step 5**

Add Fee information.

**Step 6**

(Optional) You can add another fee rule if needed. To do so, select a new fee type and fill the information.

**Step 7**

Click the **Next** button.

**Step 8**

(Optional) Configure **Account Waivers** section:

* Add account aliases that should be exempt from fees in this package
* Click **Add** to add each waived account

**Step 9**

Click the **Next** button.

**Step 10**

Review the information and confirm that everything is correct.

**Step 11**

Click the **Create Package** button.

If successful, the Console shows a confirmation message and opens the Fee Packages list.

## Field guide

***

### Basic Information

| Field | Description | Example |
| - | - | - |
| Fee Package Name | Required package name. Use a name that describes the charge model. | `Standard Transfer Fee` |
| Description | An explanation of when and why the package applies. | `Fixed fee for standard transfers` |
| Transaction Route | Optional route filter for the package. | `Pix Transfer Route` |
| Segment | Optional segment filter for targeted fees. | `Retail Customers` |
| Minimum Amount | Lowest transaction amount eligible for the package. | `10.00` |
| Maximum Amount | Highest transaction amount eligible for the package. | `500.00` |

### Fee Rules

Every fee inside a package has a **Priority** (1 = applied first). The fee with priority `1` must use **Original Amount** as Reference Amount.

#### Flat Fee

A fixed amount applied to the Transaction regardless of its value.

| Field | Description | Example |
| - | - | - |
| Amount | The fixed amount charged for this fee. Must be a positive number. | `5.00` |
| Fee Name | Unique identifier for this fee, used as the JSON object key. **Must start with a letter or underscore** and contain only letters, numbers, or `_`. | `taxaAdm` |
| Reference Amount | Base used by the calculation: **Original Amount** (transaction value as sent) or **After Fees Amount** (value after previous fees in the package). | `Original Amount` |
| Credit Account ID | Alias of the account that receives the fee amount. | `@fees_transfers` |
| Route From | Optional. Name or UUID of the source route for this fee operation. | `payments_in` |
| Route To | Optional. Name or UUID of the destination route for this fee operation. | `fees_revenue` |
| Deductible from transaction? | When enabled, the fee is deducted from the transaction amount (recipient pays); when disabled, the fee is added on top (sender pays). | Off |

> [!NOTE]
>
> When you enable **Deductible from transaction?**, the form forces **Reference Amount** to **Original Amount** and disables the **After Fees Amount** option.

#### Percentage Fee

A percentage of the Transaction amount.

| Field | Description | Example |
| - | - | - |
| Percentage | Percentage rate applied to the reference amount. Must be greater than `0` and less than or equal to `100`. | `2.5` |
| Fee Name | Unique identifier for this fee, used as the JSON object key. Must start with a letter or underscore and contain only letters, numbers, or `_`. | `processingFee` |
| Reference Amount | **Original Amount** to charge on the transaction value as sent, or **After Fees Amount** to charge on the value after previous fees in the package. | `Original Amount` |
| Credit Account ID | Alias of the account that receives the fee amount. | `@fees_revenue` |
| Route From | Optional. Name or UUID of the source route for this fee operation. | `payments_in` |
| Route To | Optional. Name or UUID of the destination route for this fee operation. | `fees_revenue` |
| Deductible from transaction? | Enable so the fee is deducted from the transaction amount; disable to add the fee on top of the transaction. | `Disabled` |

#### Max Between Types

Calculates a flat amount **and** a percentage, then applies the highest result. The form requires both calculations.

| Field | Description | Example |
| - | - | - |
| Flat Fee (Calculations) | First calculation row. Fixed amount candidate. Must be a positive number. | `1.00` |
| Percentage Fee (Calculations) | Second calculation row. Percentage candidate; must be greater than `0` and less than or equal to `100`. | `2.0` |
| Fee Name | Unique identifier for this fee, used as the JSON object key. Must start with a letter or underscore and contain only letters, numbers, or `_`. | `guaranteeFee` |
| Reference Amount | Base used to calculate the percentage candidate before the comparison. | `Original Amount` |
| Credit Account | Alias of the account that receives the resulting (highest) fee amount. | `@fees_guarantee` |
| Route From | Optional. Name or UUID of the source route for this fee operation. | `payments_in` |
| Route To | Optional. Name or UUID of the destination route for this fee operation. | `fees_revenue` |
| Deductible from transaction? | When enabled, the higher of the two results is deducted from the transaction amount; when disabled, it is added on top. | `Disabled` |

### Account Waivers

| Field | Description | Example |
| - | - | - |
| Account Alias | The alias of the account that will be waived. | `@customer_john_checking` |

## Priority, ranges and waived accounts

***

### Fee priority ordering

When a package contains multiple fees, Midaz applies them in priority order (lowest number first). With **After Fees Amount** as the reference, earlier fees affect the calculation base for later fees.

**Example**:

* Fee A (Priority 1): 1% on original amount, not deductible
* Fee B (Priority 2): 0.5% on after fees amount

On a \$100 transaction:

* Fee A = \$1.00 (1% of \$100)
* Fee B = \$0.505 (0.5% of \$101)

### Amount range considerations

* Midaz rejects a package whose range overlaps another package with the same transaction route and segment
* Use `0.01` as minimum for packages that should apply to all transactions
* Use a high maximum (e.g., `999999999.99`) for no upper limit
* The range includes Transactions exactly at the min or max values

### Waived accounts behavior

* Waived accounts bypass all fees in the package, not just specific fees
* Use account aliases (not IDs) when adding waived accounts
* When every source account is waived, the package charges no fee. Otherwise, the fee is split among the accounts that are not waived: sources for a fee added on top, destinations for a deductible fee.

## What to do next

***

After creating the Fee Package, run a test calculation in [Running a Fee Estimation](/en/products/midaz/fees/console/fe-fee-simulation) before using it with live Transactions.

> **API equivalent**
>
> [Create Package endpoint](/en/reference/products/midaz/v2/create-package)


# Deleting a Fee Package
Source: https://docs.lerian.studio/en/products/midaz/fees/console/fe-deleting-a-package

Delete a Fee Package from the Midaz Module when it is no longer needed, keeping in mind data retention, audit, and compliance rules for regulated deployments.

> [!CAUTION]
>
> If you only need to stop a package temporarily, disable it instead of deleting it. A deleted Fee Package no longer appears in active listings. Your deployment's data retention and compliance policies still apply to the record. In regulated environments, your deployment can keep the record for audit, regulatory, or reporting purposes.

## Delete a package

**Step 1**

On the **Fee Packages** page, click the three dots () in the **Actions** column for the package you want to delete.

**Step 2**

Select **Delete**.

**Step 3**

Review the confirmation dialog.

**Step 4**

Click **Delete Package** to finalize the deletion.


# Editing a Fee Package
Source: https://docs.lerian.studio/en/products/midaz/fees/console/fe-editing-a-package

Edit a saved Fee Package in the Midaz Console to adjust its name, amount range, fee rules, or waived accounts without recalculating fees already applied to past Transactions.

Edit a Fee Package to change its name, amount range, fee rules, or waived accounts. Your changes apply to new fee calculations. Midaz does not recalculate fees already applied to past Transactions.

## Edit a package

**Step 1**

On the **Fee Packages** page, find the package you want to edit.

**Step 2**

Click the three dots () in the **Actions** column and select **Edit**.

**Step 3**

The creation wizard opens with the current values.

**Step 4**

Make your changes and click **Save**.

**Step 5**

A confirmation toast appears and the updated package returns to the list.


# Running a Fee Estimation
Source: https://docs.lerian.studio/en/products/midaz/fees/console/fe-fee-simulation

Run a fee estimation with the Console Fee Calculator to preview charges on sample amounts, accounts, and assets before creating any real Ledger Transaction.

Use the **Fee Calculator** in the Midaz Module to estimate fees before you process a real Transaction. The Fee Calculator is read-only. It does not create a Transaction or change any Ledger balance.

## Before you start

***

* Enable the **Fees Engine** in [Midaz module settings](/en/platform/console/plugin-settings).
* You need at least one [Fee Package](/en/products/midaz/fees/console/fe-creating-a-package) saved.
* You need the source and destination Account aliases you want to test against.

## Running an estimation

***

**Step 1**

In the Midaz Module sidebar, expand **Fees Engine** and click **Calculator**.

**Step 2**

Fill in the estimated transaction. See the [Field guide](#field-guide) below for each input.

**Step 3**

Click **Calculate Fees** to run the estimation.

**Step 4**

Review the results displayed below the form.

## Field guide

***

| Field | What to enter | Example |
| - | - | - |
| Transaction Amount | Total value to estimate fees against. | `100.00` |
| Asset | One of the assets of the current ledger. Select it in the list. | `BRL` |
| Fee Package | Fee Package to test. | `Standard Transfer Fee` |
| From Account | Account alias that would be debited. | `@customer_123` |
| To Account | Account alias that would be credited. | `@merchant_456` |
| Description | Optional description for the estimation. | `Pix transfer test` |

> [!NOTE]
>
> The Fee Calculator is a read-only tool. It does not affect the ledger or create any transactions. You can run as many estimations as needed safely.

## Understanding the results

***

After you run an estimation, the Fee Calculator shows a detailed breakdown of the calculation:

### Totals

* **Payer paid** - The amount the source sends, including fees added on top
* **Total fees** - The sum of all fees for the transaction
* **Recipient received** - **Payer paid** minus **Total fees**

### Fee breakdown

For each fee rule applied, you'll see:

| Field | Description |
| - | - |
| **Fee Label** | Name identifying the fee |
| **Source Pays** or **Destination Pays** | Who pays the fee. The source pays a fee added on top. The destination pays a deductible fee. |
| **Calculation Type** | **Flat**, **Percentage**, or **Max Between** |
| **Calculated Amount** | The actual fee value |

## Estimation examples

***

> **Simple flat fee estimation**
>
> **Scenario**: Test a \$2.00 flat fee on a \$100 transfer
>
> **Input**:
>
> * Fee Package: `Standard Transfer Fee`
> * Asset: `USD`
> * Amount: `100.00`
> * Source: `@customer/checking`
> * Destination: `@merchant/revenue`
>
> **Expected Result**:
>
> * Total fees: \$2.00
> * Recipient received: \$98.00 if the fee is deductible. If it is not deductible, Payer paid is \$102.00 and Recipient received is \$100.00.

> **Percentage fee estimation**
>
> **Scenario**: Test a 1.5% fee on a \$500 transfer
>
> **Input**:
>
> * Fee Package: `Percentage Transaction Fee`
> * Asset: `USD`
> * Amount: `500.00`
> * Source: `@customer/savings`
> * Destination: `@vendor/payments`
>
> **Expected Result**:
>
> * Total fees: \$7.50 (1.5% of \$500)
> * Calculation: 500 × 0.015 = 7.50

> **Combined fee estimation**
>
> **Scenario**: Test max(flat, percentage) fee on different amounts
>
> **Test 1** - Small transaction (\$30):
>
> * Flat: \$1.00
> * Percentage: 2% = \$0.60
> * Result: \$1.00 (flat is higher)
>
> **Test 2** - Large transaction (\$200):
>
> * Flat: \$1.00
> * Percentage: 2% = \$4.00
> * Result: \$4.00 (percentage is higher)

> **Multiple fees estimation**
>
> **Scenario**: Package with two fees applied in priority order
>
> **Fee A** (Priority 1): 1% on original amount, not deductible
> **Fee B** (Priority 2): 0.5% on after fees amount
>
> **Input**: \$1000 transaction
>
> **Expected Result**:
>
> * Fee A: \$10.00 (1% of \$1000)
> * Fee B: \$5.05 (0.5% of \$1010)
> * Total fees: \$15.05

## Use cases for fee estimation

***

### Validate new fee packages

Before you enable a new fee package, run estimations at various transaction amounts. Make sure the fees are correct across the full amount range.

### Test edge cases

Estimate transactions at minimum and maximum amount boundaries to verify fee behavior at the limits of your configured ranges.

### Compare fee structures

Run the same transaction through different fee packages to compare outcomes and choose the best structure for your use case.

### Document expected fees

Use estimation results to create documentation for your finance team or customers about expected fee amounts.

### Debug fee issues

If a transaction shows unexpected fees, use the Fee Calculator to reproduce the scenario and understand the calculation breakdown.

## Best practices

***

* **Test full amount ranges** - Do not test only one amount. Estimate transactions at the minimum, the maximum, and several points in between.
* **Verify priority ordering** - When packages have multiple fees, confirm they apply in the expected order.
* **Check waived accounts** - Test with accounts that the fee package waives. Confirm the results exclude them from fees.
* **Document your tests** - Keep a record of estimation results for audit and compliance purposes.
* **Share with stakeholders** - Use estimation breakdowns to align with finance teams on expected fee outcomes before going live.

## What to do next

***

After validating the fee result, adjust the Fee Package if needed in [Editing a Fee Package](/en/products/midaz/fees/console/fe-editing-a-package), or create a real Transaction in [Creating a Transaction](/en/products/midaz/console/creating-a-transaction).

> **API equivalent**
>
> [Estimate Fees endpoint](/en/reference/products/midaz/v2/estimate-fee-calculation)


# Fees Engine in Lerian Console
Source: https://docs.lerian.studio/en/products/midaz/fees/console/fees-engine-overview

Explore the Fees Engine in the Midaz Module: enable it, manage Fee Packages, and estimate charges from the Console using Ledgers, segments, and routes.

The **Fees Engine** is an optional capability of the Midaz Module that lets operators model transaction fees from the Console. Once enabled, it adds four pages to the Midaz Module sidebar:

* **Fee Packages**: create and edit packages and their rules.
* **Calculator**: estimate what a package would charge before you apply it to a real Transaction.
* [**Billing Packages**](/en/products/midaz/fees/console/managing-billing-packages): create and edit volume and maintenance billing packages.
* **Billing Runs**: preview the billing for a period.

The Fees Engine builds on the same Ledgers, Segments, Transaction Routes, and Accounts already defined in Midaz Core.

Packages use that existing structure to set their scope. Midaz applies a package automatically to each Transaction that matches its conditions.

## Key concepts

***

* **Fee Package**: Container that groups one or more fee rules and the conditions under which they apply (transaction route, segment, ledger, amount range).
* **Fee Rule**: An individual fee inside a package, with its own calculation method.
* **Application Rule**: How Midaz calculates a single fee, either **flat**, **percentage**, or **maximum between both**.
* **Reference Amount**: Whether a percentage fee applies to the original Transaction amount or to the amount after other fees.
* **Priority**: The order in which Midaz applies multiple fees inside the same package.
* **Waiver**: A source account exempted from a given package.

## Enabling the Fees Engine

***

The Fees Engine appears in the sidebar only after you enable it in [Plugin settings](/en/platform/console/plugin-settings).

**1. Open Plugin settings**

From the Midaz Module sidebar, go to **Settings** > **Plugins**.

**2. Enable Fees Engine**

Toggle **Fees Engine** on. The **Fees Engine** menu item appears in the sidebar with **Fee Packages**, **Calculator**, **Billing Packages**, and **Billing Runs** sub-items.

> [!NOTE]
>
> If you disable the Fees Engine later, the Console hides its menu. Midaz keeps your packages and still applies them to matching Transactions.

## Where to go next

***

> **[Manage Fee Packages](/en/products/midaz/fees/console/managing-fee-packages)**
>
> Create, edit, and delete packages. Define rules, scope by ledger or segment, and set waivers.

> **[Fee Calculator](/en/products/midaz/fees/console/managing-fee-calculations)**
>
> Estimate what a package would charge for a sample Transaction without running a real one.

> **[Manage Billing Packages](/en/products/midaz/fees/console/managing-billing-packages)**
>
> Create volume and maintenance packages, and turn them on or off.

> **[Billing Runs](/en/products/midaz/fees/console/billing-runs)**
>
> Preview the fees for a period before you apply them.


# Managing Billing Packages
Source: https://docs.lerian.studio/en/products/midaz/fees/console/managing-billing-packages

Create, edit, activate, and delete volume and maintenance Billing Packages from the Midaz Console to set the periodic charges that Billing Runs calculate.

A **Billing Package** sets a periodic charge in the [Fees Engine](/en/products/midaz/fees/console/fees-engine-overview). A package has one of two types:

* **Volume**: charges per number of events in the period. It supports price tiers, a free quota, and discounts.
* **Maintenance**: charges a fixed amount from each target account every period.

> [!NOTE]
>
> Enable the Fees Engine in [Midaz module settings](/en/platform/console/plugin-settings) before you use this page.

## Accessing the Billing Packages page

***

In the Midaz Module sidebar, expand **Fees Engine**. Select **Billing Packages**. The page lists the packages of the Ledger that you select in the organization switcher.

The list shows the **Name**, **Type**, **Asset**, and **Status** of each package. Use the **Type** filter to show Volume or Maintenance packages.

From the list, you can:

* Turn the **Status** switch on or off to activate or deactivate a package.
* Select **Details** in the row menu to see the package configuration.
* Select **Edit** in the row menu to change the package.
* Select **Delete** in the row menu to delete the package. The Console asks you to confirm.

## Creating a Billing Package

***

**1. Choose the type**

Click **New Package**. In **Choose the billing type**, select **Volume Package (Tiered)** or **Maintenance Package (Flat Fee)**.

**2. Fill in the basic information**

In **Type & Information**, enter the **Package Name** and an optional **Description**. Select the **Asset Code**. The package uses the Ledger that you select in the organization switcher.

**3. Configure the package**

In **Configuration**, set the fields for the package type. The next two sections describe these fields.

**4. Review and save**

In **Review**, check the summary. To change a section, use its edit button to go back to that step. Then select **Save**.

A new package is active when you create it. The next billing run includes it.

You can change the type until you save the package. If you change it after you fill in **Configuration**, the Console discards the **Configuration** data.

## Volume package fields

***

| Section | What you set |
| - | - |
| **Event Filter** | The **Transaction Route** that defines which transactions the package counts, and the **Transaction Status** to count: **Approved** or **Pending**. |
| **Pricing Model** | **Tiered**: events fill the tiers in order, and each tier has its own unit price. **Flat Tier**: one unit price applies to every event. |
| **Price Tiers** | For **Tiered**, each row has **From (min)**, **To (max)**, and **Unit Price**. Each tier starts at the quantity after the maximum of the previous tier. The last tier has no maximum. For **Flat Tier**, you set one unit price. |
| **Free Quota** | For **Tiered**. The package does not charge the first N events in the period, where N is the quota. |
| **Progressive Discounts (optional)** | For **Tiered**. Each discount sets a percentage that applies from a starting quantity. Enter the discounts in ascending order. |
| **Debit and Credit Accounts** | The **Debit Account (alias)** and the **Credit Account (alias)**. Both are required. |
| **Calculation Preview** | The charge for sample event counts, from the tiers, the free quota, and the discounts. |

## Maintenance package fields

***

* **Fee Amount**: the amount that the package charges from each target account every period.
* **Target Accounts**: the accounts to charge.
  * **By Segment**: the accounts in the selected segment.
  * **By Portfolio**: the accounts in the selected portfolio.
  * **Account List**: account aliases that you type, or that you upload in a UTF-8 CSV file with an `accountAlias` column.
* **Credit Account (alias)**: the account that receives the charged amounts.

An account list can have at most 100 aliases. When you create the package, Midaz checks that each alias exists in the Ledger. If an alias does not exist, Midaz refuses the package.

## Editing a Billing Package

***

Select **Edit** in the row menu. You can change the **Package Name** and the **Description**. The type, the asset, and the **Configuration** fields do not change after creation.

To stop a package from charging, turn its **Status** switch off. Billing runs use active packages only.

## Where to go next

***

> **[Billing Runs](/en/products/midaz/fees/console/billing-runs)**
>
> Preview the fees for a period before you apply them.

> **[Fees Engine overview](/en/products/midaz/fees/console/fees-engine-overview)**
>
> Understand how the Fees Engine, packages, and rules fit together.


# Fee Calculator
Source: https://docs.lerian.studio/en/products/midaz/fees/console/managing-fee-calculations

Preview how Fee Packages apply to a sample Transaction using the Console Fee Calculator, with a detailed breakdown of flat, percentage, and deductible fees.

The **Fee Calculator** previews how fees apply before you run a real Transaction. It uses an existing [Fee Package](/en/products/midaz/fees/console/managing-fee-packages) to estimate the total fees. It also shows a detailed breakdown of each rule: flat fees, percentages, and deductibles.

Use it to test changes and validate logic with business teams.

## Accessing the Fee Calculator

***

**Step 1**

In the Midaz Module sidebar, expand **Fees Engine**.

**Step 2**

Click **Calculator** to open the Fee Calculator page.

> [!WARNING]
>
> You need at least one [Fee Package](/en/products/midaz/fees/console/fe-creating-a-package) before using the Calculator. The estimator must run against a saved package.

## Why use the Fee Calculator

***

The Fee Calculator is a read-only tool that does not affect the ledger or create any transactions. Use it to:

* **Validate new fee packages** before enabling them in production
* **Test edge cases** at minimum and maximum amount boundaries
* **Compare fee structures** by running the same transaction through different packages
* **Document expected fees** for finance teams or customers
* **Debug fee issues** by reproducing scenarios and analyzing calculation breakdowns


# Managing Fee Packages
Source: https://docs.lerian.studio/en/products/midaz/fees/console/managing-fee-packages

Browse, create, edit, and delete Fee Packages from the Midaz Console to control how flat, percentage, and combined charges apply to matching Transactions.

**Fee Packages** are the base unit of the [Fees Engine](/en/products/midaz/fees/console/fees-engine-overview). Each package defines a set of fee rules and the conditions under which they apply to Transactions.

> [!NOTE]
>
> Enable the Fees Engine in [Midaz module settings](/en/platform/console/plugin-settings) before you use this page.

## What a Fee Package contains

***

A Fee Package lets you:

* **Define fee calculation rules**: flat fees, percentage-based fees, or combined calculations.
* **Set amount ranges**: apply fees only to transactions within a min/max range.
* **Link to transaction routes**: target specific transaction flows.
* **Waive fees for specific accounts**: exempt selected source accounts.
* **Prioritize fee application**: control the order in which Fees Engine applies multiple fees.

Fee Packages combine with [Accounting Routes](/en/products/midaz/console/managing-accounting-routes) and [Segments](/en/products/midaz/console/managing-segments) for granular control.

## Accessing the Fee Packages page

***

In the Midaz Module sidebar, expand **Fees Engine**. Select **Fee Packages**. The page lists every configured package.

> [!NOTE]
>
> If you have no Fee Packages, the list is empty and shows a prompt to create your first package.

### Available actions

From the Fee Packages page, you can:

> **[Create a Fee Package](/en/products/midaz/fees/console/fe-creating-a-package)**
>
> Define new fee calculation rules for transactions

> **[Edit a Fee Package](/en/products/midaz/fees/console/fe-editing-a-package)**
>
> Update fee configurations and rules

> **[Delete a Fee Package](/en/products/midaz/fees/console/fe-deleting-a-package)**
>
> Delete a fee package from your configuration

> [!NOTE]
>
> Select a package from the list to open its **details view**. There you can review the package's configuration (scope, amount range, and fee rules) before you edit it. To preview the fees a period generates across packages, use [Billing Runs](/en/products/midaz/fees/console/billing-runs).

## Understanding Fee Package structure

***

When you create or edit a fee package in Midaz Module, you work with these fields:

### Basic information

* **Fee Package Name** (required) - A descriptive name for the fee package
* **Description** (optional) - Explanation of the package purpose and when it applies
* **Transaction Route** (optional) - Link to a specific transaction route
* **Segment** (optional) - Associate with a specific segment
* **Ledger** (required) - The ledger this package applies to

### Amount range

* **Minimum Amount** (required) - Lowest transaction amount for fee application
* **Maximum Amount** (required) - Highest transaction amount for fee application
* **Waived Accounts** (optional) - List of account aliases exempt from these fees

### Fee rules

Each fee package can contain multiple fee rules with:

* The fee name field (placeholder **Display Name**) - Name that identifies this fee
* The fee type card - How Fees Engine calculates the fee:
  * **Flat Fee** - Fixed amount regardless of transaction value
  * **Percentage Fee** - Percentage of the transaction amount
  * **Max between types** - Higher value between flat and percentage calculations
* **Calculation Type** - `flat` or `percentage`
* **Calculation Value** - The fee amount or percentage
* **Reference Amount** - Base for percentage calculation:
  * `originalAmount` - Calculate on the original transaction value
  * `afterFeesAmount` - Calculate after Fees Engine applies other fees
* **Priority** - Order of fee application (lower numbers apply first)
* **Deductible from transaction?** - Whether Fees Engine deducts this fee from the transaction
* **Credit Account ID** - Account that receives the fee amount

## Common use cases

***

> **Simple flat fee per transaction**
>
> Apply a fixed fee to all transactions within an amount range:
>
> * Fee type: **Flat Fee**
> * **Calculation**: `flat` with value `2.50`
> * **Example**: $2.50 fee on every transaction between $10 and \$1000

> **Percentage-based fee**
>
> Charge a percentage of the transaction amount:
>
> * Fee type: **Percentage Fee**
> * **Calculation**: `percentage` with value `1.5`
> * **Example**: 1.5% fee on transfers, where $100 transfer = $1.50 fee

> **Tiered fee structure**
>
> Create multiple packages with different amount ranges:
>
> * Package 1: $0-$100 → 2% fee
> * Package 2: $100.01-$1000 → 1.5% fee
> * Package 3: \$1000.01+ → 1% fee
> * Lower fees for higher-value transactions

> **Combined flat + percentage (maximum)**
>
> Apply whichever is higher between flat and percentage:
>
> * Fee type: **Max between types**
> * **Calculations**: `flat: 1.00` and `percentage: 2.0`
> * **Example**: On $30 transaction: max($1.00, $0.60) = $1.00 fee
> * **Example**: On $100 transaction: max($1.00, $2.00) = $2.00 fee

> **Fee waiver for premium accounts**
>
> Exempt specific accounts from fees:
>
> * Create package with standard fee rules
> * Add premium account aliases to **Waived Accounts** list
> * These accounts transact without the configured fees

## Best practices

***

**1. Plan your fee structure**

Design your fee packages before implementation. Consider transaction types, amount ranges, and customer segments that require different fee treatments.

**2. Use descriptive labels**

Choose clear fee group labels and descriptions that explain when and why fees apply. This helps with auditing and customer communication.

**3. Set appropriate amount ranges**

Define minimum and maximum amounts carefully to avoid gaps or overlaps in your fee structure.

**4. Test fee calculations**

Use the [Fee Estimation](/en/products/midaz/fees/console/fe-fee-simulation) feature to preview fee calculations before you enable packages in production.

**5. Manage priority carefully**

When you use multiple fees in a package, set priorities so the fees apply in the correct order.

**6. Document waived accounts**

Record why you waive fees for certain accounts. This supports audit and compliance.

## Fee calculation flow

***

When Fees Engine processes a transaction, it:

1. Finds the enabled packages that match the transaction route, segment, and amount range
2. Keeps the most specific match, so one package applies at most
3. Skips the waived accounts
4. Applies fee rules in priority order
5. Calculates each fee based on application rule and reference amount
6. Credits fee amounts to designated accounts

> [!NOTE]
>
> Enable a fee package so it applies to transactions. To pause a package, disable it. A disabled package stays in your configuration.


# Fee debt
Source: https://docs.lerian.studio/en/products/midaz/fees/fee-debt

Keep an unpaid fee as a debt that the payer's next credits can settle, oldest first, instead of refusing the transaction.

By default, Midaz refuses a transaction when the payer cannot fund its fees. A **deferrable** fee changes this. The payer pays the part of the fee that its available amount covers. The rest becomes a **fee debt**, and the transaction goes through. Later credits to the payer can settle the debt.

Fee debt is off by default. It applies only to fees that you mark as deferrable.

## Make a fee deferrable

***

Set `deferrable: true` on a fee when you [create](/en/reference/products/midaz/v2/create-package) or [update](/en/reference/products/midaz/v2/update-package) its fee package.

* Only a fee with `isDeductibleFrom: false` can be deferrable. Midaz refuses a deductible fee that is also deferrable with error `0530`.
* A deferrable fee opens a debt only in a `/v2` direct transaction. In a `/v2` hold, Midaz refuses an unfunded fee with error `0018`.
* When a balance already has 256 open fee debts, Midaz refuses a new unfunded deferrable fee on it with error `0018`.

**Example.** A payer holds 105 and sends 100 with a deferrable fee of 10. The transaction moves 105: the payment of 100 and 5 of the fee. The other 5 becomes a fee debt. The transaction metadata key `feeDebtOpenings` records the debt.

## How a debt is settled

***

A credit to the payer's balance through the `/v2` API can settle its open fee debts, oldest first. This includes direct transactions, commits, and reversals. A credit that is smaller than a debt settles part of it. A payer's balance that cannot send funds settles nothing, and settlement stops at the first debt whose fee account cannot receive funds.

Each settlement moves the value from the payer's balance to the fee account of the debt. Midaz records these movements as operations of type `FEE_SETTLEMENT`, and the transaction metadata key `feeDebtSettlements` records the settled debts.

To settle debts without a credit, use [Collect open fee debts](/en/reference/products/midaz/v2/collect-a-balance-s-open-fee-debts). Send the `accountAlias` of the payer, and optionally a `balanceKey` and a `maxAmount`.

* Midaz pays the open debts of that balance from its available amount, oldest first, and charges no fee on the collection.
* The response gives the `collected` amount and the `transactionId` of the collection.
* When nothing is collected, the response gives `collected: "0"` and Midaz creates no transaction.
* You cannot revert a collection. Midaz refuses it with error `0089`.

## Reversals and fee debt

***

When you [revert](/en/reference/products/midaz/v2/revert-transaction) the transaction that opened a debt, the payer gets the whole fee back:

* The reversal returns the part of the fee that the payer paid in the original transaction.
* Midaz cancels the part of the debt that is still open.
* Midaz refunds the part that later credits settled. The fee account pays the refund, and Midaz records it as operations of type `FEE_REFUND`. On `/v2`, the refund can then settle the payer's other open debts, oldest first.

A revert of a credit that settled a debt can reopen that debt for the settled amount.

When the fee-debt record of a transaction is not complete yet, Midaz refuses the revert with error `0529` (HTTP 409) and moves nothing. Try again later.

## Read fee debts

***

* [List fee debts](/en/reference/products/midaz/v2/list-the-fee-debts-of-a-ledger-oldest-first) gives the debts of a ledger, oldest first. Filter by `account_alias`, `balance_key`, and `status` (`open` or `settled`). With `account_alias`, the response also gives `openTotal`, the total that the balance owes.
* [Retrieve a fee debt](/en/reference/products/midaz/v2/get-a-fee-debt) gives one debt with its `remaining` amount and its history of changes.

Listing and reading fee debts needs the `midaz/fee-debts` permission with `get`. Collecting fee debt needs `post`.

Each change has one of these kinds:

| Kind | What happened |
| - | - |
| `opened` | The payer could not fund the fee, and the debt opened. |
| `settled` | A credit or a collection paid part or all of the debt. |
| `canceled` | A revert of the original transaction canceled the open part. |
| `reopened` | A revert took back a settlement, and that amount is owed again. |
| `refunded` | A revert of the original transaction returned a settled part to the payer. |

## Accounts and balances with fee debt

***

Midaz refuses to delete a balance, or to delete or close its account, when:

* The balance owes fee debt (error `0527`). Credit the balance or collect the debt first.
* Other balances owe fee debt to the balance (error `0528`), for example a fee account. Credit the balances that owe the debt first.

## Before you enable fee debt

***

* Run Midaz v4.2.0 or later on every ledger instance before you set `deferrable` on a fee. An earlier version cannot complete a transaction that carries fee debt. After you set it, do not roll the ledger back to an earlier version.
* The ledger keeps open fee debts in Valkey. Valkey must be persistent and keep these keys. See [Configuring dependencies](https://github.com/LerianStudio/helm/blob/main/charts/midaz/README.md#valkey).


# Fees Engine calculations
Source: https://docs.lerian.studio/en/products/midaz/fees/fee-engine-calculation

Learn how the Fees Engine calculates fees, handles decimal precision, splits amounts across accounts, and applies exemptions over daily, weekly, or monthly periods.

## Numeric values (string)

***

Express all financial values in **Fees Engine** as a `string` with the `numeric` type. This gives high-precision decimal handling for assets like BRL or BTC. It also prevents rounding errors during calculations, splits, or exemptions.

**Example:**

```
"value": "12.50"
```

## Billing periods

***

When triggering a billing calculation, you specify the time window through the `period` field. Fees Engine supports three formats:

| Format | Example | Window |
| - | - | - |
| Daily | `2026-03-15` | Start of that day → start of the next day (UTC) |
| Weekly | `2026-W13` | Monday 00:00 UTC of the ISO week → following Monday 00:00 UTC |
| Monthly | `2026-03` | First instant of the month → first instant of the next month (UTC) |

The engine counts qualifying transactions for volume packages within that window. Maintenance packages charge the accounts that are active when you run the calculation, and the period only labels the result.

> [!TIP]
>
> Weekly periods follow [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601#Week_dates). Week numbering ranges from `W01` to `W52` (or `W53` in years that have 53 ISO weeks). The week always starts on Monday.

Choose the granularity that matches your billing cycle. A prepaid card product billed daily would use `2026-03-15`. A SaaS platform billed monthly would use `2026-03`. A marketplace that settles weekly would use `2026-W13`.

## Fee calculation rules

***

Each fee uses an `applicationRule` to define how it's calculated. You can choose from three rule types:

* [maxBetweenTypes](#maxbetweentypes)
* [flatFee](#flatfee)
* [percentual](#percentual)

You can combine different rules in a single package to match your use case.

Other key fields:

* `isDeductibleFrom`: `false` adds the fee on top of what the source sends. `true` deducts it from what the destination receives. The **Result** columns below show that amount.
* `referenceAmount`: either `originalAmount` or `afterFeesAmount`.
* `priority`: defines the order of application. Priority 1 must always use `originalAmount`.
* `deferrable`: `true` keeps the part of the fee that the payer cannot fund as a [fee debt](/en/products/midaz/fees/fee-debt).

### maxBetweenTypes

Applies whichever is greater: a flat or percentage-based fee.

**Example**

* Flat fee value: R\$5.
* Percentual fee: 2%.
* Reference amount: R\$1,000.

```
rate = 1000 * 0.02 = R$ 20.00
```

Since **R\$ 20 > R\$ 5**, the engine applies the percentage-based fee.

### flatFee

Applies a fixed fee amount. Behavior depends on `isDeductibleFrom`.

**Example**

* Flat fee: R\$15.
* Reference amount: R\$115.

| `isDeductibleFrom` | Formula | Result |
| :- | :- | :- |
| `false` | `referenceAmount + fee` | R\$ 130.00 |
| `true` | `referenceAmount - fee` | R\$ 100.00 |

### percentual

Applies a fee as a percentage of the reference amount.

**Example**

* Value: 30%.
* Reference amount: R\$ 389.50.

| `isDeductibleFrom` | Formula | Result |
| :- | :- | :- |
| `false` | `referenceAmount + (referenceAmount * value)` | R\$ 506.35 |
| `true` | `referenceAmount - (referenceAmount * value)` | R\$ 272.65 |

## Fee splitting

***

When a transaction has multiple source accounts, Fees Engine splits fees proportionally.

### Example

* Total amount: R\$4,000.00
* Fixed fee: R\$15.00
* Tax: 4%
* `isDeductibleFrom: false`

### Participation %

> **Formula**: (Account Amount ÷ Total Amount) × 100

| Account | Share | Amount |
| :- | :- | :- |
| @account1 | 25% | R\$ 1,000 |
| @account2 | 25% | R\$ 1,000 |
| @account3 | 40% | R\$ 1,600 |
| @account4 | 10% | R\$ 400 |

### Fixed fee distribution

> **Formula**: `fixed Fee × participation %`

| Account | Fee Share | Total |
| :- | :- | :- |
| @account1 | R\$ 3.75 | R\$ 1,003.75 |
| @account2 | R\$ 3.75 | R\$ 1,003.75 |
| @account3 | R\$ 6.00 | R\$ 1,606.00 |
| @account4 | R\$ 1.50 | R\$ 401.50 |

### Proportional tax

> **Formula**: `account amount × tax %`

| Account | Tax | Total w/ Tax |
| :- | :- | :- |
| @account1 | R\$ 40.00 | R\$ 1,040.00 |
| @account2 | R\$ 40.00 | R\$ 1,040.00 |
| @account3 | R\$ 64.00 | R\$ 1,664.00 |
| @account4 | R\$ 16.00 | R\$ 416.00 |

### Final amount per account

> **Formula**: `principal + fee + tax`

| Account | Fee | Tax | Final Total |
| :- | :- | :- | :- |
| @account1 | R\$ 3.75 | R\$ 40.00 | R\$ 1,043.75 |
| @account2 | R\$ 3.75 | R\$ 40.00 | R\$ 1,043.75 |
| @account3 | R\$ 6.00 | R\$ 64.00 | R\$ 1,670.00 |
| @account4 | R\$ 1.50 | R\$ 16.00 | R\$ 417.50 |

#### Validations

* Total shares = 100%
* Fee split matches flat fee
* Tax split = 4%
* Total sent = R\$ 4,175.00

## Fee exemptions: rules & hierarchy

***

### By transaction amount

Use `minimumAmount` and `maximumAmount` to define when **fees should apply**.

> For example: If the range is R$ 0–300, a transaction of R$ 301 won’t trigger fees.

### By account

The system checks `waivedAccounts`. A waived account pays no share of the fee. When every source account is waived, no fee applies.

> [!TIP]
>
> **Hierarchy:** Value range check > then account exemption

## Mixed example: fee exemptions and proportional fee splitting

***

This package includes accounts with fee exemptions and requires splitting fees proportionally.

### Scenario

We’re processing a transaction of **R\$ 4,000**, which includes:

* A **fixed fee** of **R\$ 16**.
* Only some accounts are subject to the fixed fee
* An **IOF tax** of **6%** to be deducted.

#### Split on the source side

| Source Account | % | Proportional Value |
| :- | - | :- |
| @account1 | 15% | R\$ 600 |
| @account2 | 35% | R\$ 1,400 |
| @account3 | 40% | R\$ 1,600 |
| @account4 | 10% | R\$ 400 |

The engine applies the fixed fee only to `@account3` and `@account4`.

#### Result after Admin Fee (proportional)

| Account | Admin Fee | Total |
| :- | :- | :- |
| @account1 | Exempt | R\$ 600 |
| @account2 | Exempt | R\$ 1,400 |
| @account3 | R\$ 12.80 | R\$ 1,612.80 |
| @account4 | R\$ 3.20 | R\$ 403.20 |

Total send value increases to **R\$4,016**.

#### IOF deduction (recipient)

| Recipient | % | Gross | IOF (6%) | Net |
| :- | - | :- | :- | :- |
| @donation1 | 25% | R\$ 1,000 | R\$ 60 | R\$ 940 |
| @donation2 | 25% | R\$ 1,000 | R\$ 60 | R\$ 940 |
| @donation3 | 25% | R\$ 1,000 | R\$ 60 | R\$ 940 |
| @donation4 | 25% | R\$ 1,000 | R\$ 60 | R\$ 940 |

> [!CAUTION]
>
> The engine credits fees to the accounts defined in each fee’s `creditAccount`.

## Repeating decimals

***

When a fee split produces a repeating decimal (for example, 0.3333...), Fees Engine keeps every fee leg at full precision. It reconciles the small remainder onto the fee for the account with the largest value. This keeps the total exact, avoids rounding drift, and keeps your ledger consistent.

## Billing calculations

***

Billing packages use a different calculation model than fee packages. Instead of evaluating individual transactions, they aggregate data over a billing period and return charge payloads for your orchestrator to execute.

Billing supports three period formats: monthly (`YYYY-MM`), weekly (`YYYY-Www`, e.g., `2026-W13`), and daily (`YYYY-MM-DD`).

### Volume billing calculation

Volume billing counts transactions matching an `eventFilter` (transaction route + status) within the billing period, then applies pricing based on the configured model.

The calculation follows this order:

1. **Count** qualifying transactions in the period.
2. **Subtract** the `freeQuota` from the total count to get the billable count.
3. **Apply pricing** based on the `pricingModel` (`tiered` or `fixed`).
4. **Apply a discount** from `discountTiers`, evaluated against the **total** count (before the free quota was subtracted).

The engine keeps amounts at full decimal precision throughout. The engine applies no asset-scale rounding.

#### Tiered pricing

Tiered pricing is **volume pricing, not graduated pricing**. The engine finds the single tier whose quantity range contains the billable count, then charges **every** billable unit at that tier's unit price. It does not price each unit inside its own range.

A tier's range is inclusive on both ends. If you omit the upper bound, the tier is unbounded. The API rejects overlapping tiers. With two or more tiers, it also rejects gaps and requires the last tier to be unbounded. A package holds at most 50 tiers.

The engine looks up a tier only when the billable count is positive. If the billable count is positive and no tier covers it, the calculation fails for that package. A billable count of zero skips the tier lookup and produces a zero amount, so your tiers do not need to cover zero.

**Example**: A billing package for boleto issuance with three tiers and a free quota of 50:

| Range | Unit price |
| - | - |
| 1–500 | R\$ 1.20 |
| 501–2,000 | R\$ 0.80 |
| 2,001+ | R\$ 0.45 |

For a client that issued 1,800 boletos in the month:

* 50 exempt (free quota) → 1,750 billable
* 1,750 falls in the 501–2,000 tier, so the engine prices **all** 1,750 units at R\$ 0.80: R\$ 1,400.00 gross
* Discount tier applies on the total count of 1,800 (≥ 1,000 → 5%): −R\$ 70.00
* **Net total: R\$ 1,330.00**

#### Fixed pricing

A single unit price applies to all billable transactions regardless of volume. The engine still subtracts the free quota before calculation. Fixed pricing takes its unit price from the **first tier** in the package. The API requires at least one tier on every volume package.

**Example**: R\$ 0.10 per Pix sent, no free quota:

* 5,000 Pix transactions × R\$ 0.10 = R\$ 500.00

#### Discount tiers

At most **one** discount tier applies: the one with the largest `minQuantity` that the total count meets or exceeds. The engine applies its percentage to the gross amount. The engine evaluates discounts against the total transaction count, not the billable count.

#### Count scope

Volume calculation counts transactions **per transaction route across the whole ledger**. The free quota, the tiers, and the discount tiers all apply to that route-level total. To count two flows separately, create one package per transaction route.

### Maintenance billing calculation

Maintenance billing charges a fixed amount per account that is active when you run the calculation. The engine resolves the target accounts, keeps only the active ones, and generates a single transaction payload.

The result is a N:1 transaction:

* Each active account appears as a debit entry (`source.from`) for the configured `feeAmount`.
* The `maintenanceCreditAccount` receives the full total as a single credit entry (`distribute.to`).

The engine keeps only accounts whose status code is `active` and excludes every other status. If no account resolves, the package returns an empty payload (`{}`) instead of a transaction.

**Example**: Monthly maintenance of R\$ 9.90 for a segment with 12,000 active PF accounts:

* 12,000 entries in `source.from`, each debited R\$ 9.90
* 1 entry in `distribute.to` credited R\$ 118,800.00

### Zero-amount results

When a package's net amount comes out zero (for example the free quota covered every transaction), the engine still returns a result for that package, but with an empty transaction payload (`{}`). Treat that as "processed, nothing to submit".

Fully exempt usage reaches this result without a tier lookup. The free quota brings the billable count to zero, the engine skips tier matching, and the amount is zero. A package whose tiers start at 1 is correct for this case.

### All-or-nothing failure policy

If any billing package fails during a `/billing/calculate` call, the entire operation fails. The engine returns no partial results. The response includes which package and resource caused the failure, so you can fix and re-execute.

### Audit metadata

The metadata of a volume transaction payload includes the billing type, package id and label, period, total and billable event counts, free quota used, pricing model, gross and net amounts, and the discount detail (percentage, amount, and `minQuantity`) when one applied. The metadata of a maintenance transaction payload includes the billing type, package id and label, period, total account count, and the per-account fee amount.


# Fees Engine best practices
Source: https://docs.lerian.studio/en/products/midaz/fees/fees-engine-best-practices

Follow Fees Engine best practices for naming packages, setting fee priorities, segmenting customers, and running production setups with full auditability.

Fees Engine controls how you calculate, apply, and track fees.

These recommendations complement the [Fees Engine overview](/en/products/midaz/fees/fees-engine-overview) and the [calculation mechanics](/en/products/midaz/fees/fee-engine-calculation) guide.

## 1. Design fee packages with clear naming and segmentation

***

A well-organized package structure makes it easier to maintain, debug, and audit your fee configuration over time.

* **Use descriptive names** that reflect the business context (e.g., "pix-transfer-standard", "wire-premium-segment").
* **Segment by product and customer group** using `segmentId`. This allows you to apply different fee rules to different customer tiers without creating conflicting packages.
* **Keep packages focused**. A package that tries to cover too many scenarios becomes hard to test and maintain. Prefer multiple focused packages over one that does everything.
* **Document your package structure** internally. As your package count grows, a clear reference of which package applies where prevents misconfiguration.

## 2. Set fee priorities carefully

***

When a package contains multiple fees, the `priority` field determines the order of execution. Getting this wrong can produce incorrect calculations.

* **Priority 1 must always use `referenceAmount: originalAmount`**. The engine enforces this.
* **Fees with `isDeductibleFrom: true` must also use `referenceAmount: originalAmount`**. Deductible fees then always apply to the full transaction value.
* **Priority must be unique within a package**. The engine rejects duplicate priorities.
* **Think about fee dependencies**. If one fee adjusts the transaction value and another fee should be calculated on the adjusted value, use `referenceAmount: afterFeesAmount` with a higher priority number. If the second fee should reference the original value, use `originalAmount`.

> [!TIP]
>
> When in doubt, start with a simple configuration (one or two fees per package) and validate the results using the estimate endpoint before adding complexity.

## 3. Always estimate before applying fees in production

***

Fees Engine provides an [estimate endpoint](/en/reference/products/midaz/v2/estimate-fee-calculation) that lets you preview fee calculations without writing anything to the ledger.

Use estimation to:

* **Validate new packages** before activating them. Confirm that the calculated values match your expected results across different transaction amounts.
* **Test edge cases**: zero-amount transactions, boundary values at `minimumAmount` and `maximumAmount` thresholds, and exempted accounts.
* **Preview fees for users**. If your product shows fees before confirmation, use the estimate endpoint to provide accurate previews.
* **Debug unexpected results**. If a calculated fee doesn't match expectations, estimate the same transaction with a specific `packageId` to isolate the issue.

> [!NOTE]
>
> A v2 transaction selects the matching package automatically. The estimate endpoint requires a specific `packageId`, so you choose which package to test.

## 4. Manage exemptions explicitly

***

Fees Engine supports two types of exemptions: by **transaction amount range** and by **account**.

* **Amount ranges** (`minimumAmount`, `maximumAmount`): Define the transaction value window in which fees apply. Transactions outside this range are exempt. Use this for promotional thresholds or tiered pricing.
* **Waived accounts** (`waivedAccounts`): Specific accounts exempt from fees within a package. Use this for internal accounts, employee accounts, or partnership arrangements.

Best practices for exemptions:

* **Keep waived account lists short and reviewed**. Large lists become hard to audit. Periodically review which accounts are exempted and why.
* **Document the business reason** for each exemption in your internal records.
* **Test exemption boundaries**. If your range is R$ 0–300, make sure transactions at exactly R$ 300 and R\$ 301 behave as expected.

## 5. Use correct numeric values

***

Express all financial values in Fees Engine as **strings** using the `numeric` type. This prevents floating-point precision errors that are common with decimal arithmetic.

```json theme={null}
"value": "12.50"
```

* Always send values as strings, even whole numbers (e.g., `"100"` not `100`).
* Never use floating-point types for monetary calculations in your integration layer.
* The engine automatically adjusts fee splits with repeating decimals (e.g., R\$ 10 divided by 3 accounts) to keep ledger totals exact.

## 6. Use soft delete for auditability

***

When you delete a fee package, Fees Engine marks it with a `deletedAt` timestamp rather than removing it from the database. This preserves the audit trail for historical transactions that referenced that package.

* **Periodically review** deleted packages if your database grows significantly. Archiving strategies can help manage storage without losing audit capability.

## 7. Monitor fee processing in production

***

Fees run inside the Midaz ledger process. Use the ledger's shared OpenTelemetry configuration and health endpoints to observe fee processing. See [Environment variables](/en/products/midaz/midaz-environment-variables) for the supported configuration.

In production:

* **Monitor the ledger health endpoints** and its traces and logs.
* **Set up alerts** for sustained high latency or errors in fee calculations.
* **Monitor the configured MongoDB deployment**: connection-pool usage, disk space, and replication health.
* **Review ledger pod resource usage** against your traffic patterns and autoscaling behavior.

## 8. Keep versions compatible

***

Fees runs inside the Midaz ledger process, so it upgrades with Midaz and has the same version. Before you upgrade Midaz:

* Check the [version compatibility table](/en/products/midaz/midaz-version-compatibility) for the components you run with Midaz.
* Back up your MongoDB data and Helm values before any major upgrade.
* Test the upgrade in a staging environment before applying it to production.

For the chart's per-version upgrade notes, see the [Midaz chart upgrade notes](https://github.com/LerianStudio/helm/tree/main/charts/midaz/docs).

## 9. Review the security recommendations

***

Fees Engine processes financial data and integrates with Midaz ledger operations. Make sure your deployment follows the platform-wide [Security recommendations](/en/products/midaz/security-recommendations), which cover:

* Network segmentation and Zero Trust Architecture
* Secret management and rotation (including database credentials)
* TLS 1.2+ enforcement for all communications
* RBAC configuration via [Access Manager](/en/platform/access-manager)
* Patch management and vulnerability scanning

## 10. Design billing packages with clear scope

***

Each billing package should represent a single, well-defined charge. Avoid packing unrelated pricing into one package.

* **Separate packages per transaction route**. A package for Pix billing and a package for boleto billing are clearer than one package that tries to handle both.
* **Use descriptive labels** that include the billing type and target: "Pix Send Monthly Billing (Standard Tier)" is better than "Billing Package 1".
* **One `accountTarget` type per maintenance package**. You cannot combine `segmentId`, `portfolioId`, and `aliases` in the same package. If you need different targets, create separate packages. A single `/billing/calculate` call evaluates all active packages.

## 11. Write commercial terms against route volume

***

Volume calculation counts transactions per transaction route across the whole ledger. The free quota, the tiers, and the discount tiers all apply to that route-level total.

* **State thresholds as route volume.** "The first 100 transactions on the `pix-send` route are free" maps directly onto a package. Write the contract in the same terms the engine bills in.
* **Split routes to split counts.** One package per transaction route keeps each flow on its own quota, tiers, and discounts.

## 12. Plan free quotas and discount tiers carefully

***

Fees Engine evaluates free quotas and discounts in a specific order:

1. The engine subtracts the free quota from the total count to get the billable count.
2. The engine prices the billable count. For tiered packages it charges every billable unit at the single matching tier's rate (volume pricing, not graduated).
3. The engine applies one discount tier to the gross amount, chosen against the **total** count (before the free quota was subtracted).

Design considerations:

* **Free quotas reset each billing period**. Set the value based on your commercial agreement per period (monthly, weekly, or daily), not lifetime.
* **Tiers are volume brackets, not slices**. A billable count of 1,750 against a 501–2,000 tier prices all 1,750 units at that tier's rate. Crossing a bracket boundary changes the rate for the whole volume, so tier boundaries can move the bill sharply.
* **Cover every positive billable count.** If the billable count is positive and no tier's range contains it, the calculation fails for that package. With two or more tiers, the API rejects gaps and requires an open upper bound on the last tier. Start the first tier at 1 (a billable count of zero produces a zero amount and an empty payload without a tier lookup).
* **Discount tiers are cumulative thresholds**, not ranges, and only one applies: the highest `minQuantity` the total count reaches. If you define discounts at 200 and 400 transactions, a client with 500 transactions gets the 400+ discount, not both.
* **Watch the two different counts.** Pricing uses the billable count (after free quota); the discount uses the total count (before it).

> [!TIP]
>
> Use test calculations with known transaction counts to validate your tier and discount configuration before enabling the package in production.

## 13. Size maintenance account targets appropriately

***

Maintenance packages support three target types:

| Target type | Use case |
| - | - |
| `segmentId` | Standard tiers (PF, PJ, premium) |
| `portfolioId` | Business portfolios (PME, Corporate, Enterprise) |
| `aliases` | Specific named accounts, at most 100 |

For more than 100 accounts, use a segment or a portfolio in Midaz.

## 14. Handle billing failures with re-execution

***

Billing calculation follows an all-or-nothing policy. If any package fails, the engine returns no results.

* **Build retry logic** into your orchestrator. The calculation is stateless, so a retry is safe. A retry reflects the ledger at the time it runs.
* **Check error responses** for the package that failed. The message names its ID and label. A common cause is a volume package whose tiers do not cover the billable count.
* **Separate volume and maintenance calculations** if one type consistently succeeds while the other fails. Call `/billing/calculate` with `"type": "volume"` and `"type": "maintenance"` independently to isolate failures.


# What is Fees Engine?
Source: https://docs.lerian.studio/en/products/midaz/fees/fees-engine-overview

Fees Engine controls how fees and billing are configured, calculated, and tracked across per-transaction and per-period scenarios.

Fees is an embedded component of the unified Midaz ledger process. It provides fee and billing configuration and calculations alongside the ledger. Deploy and configure it with Midaz. It is not a separate service or plugin.

## Why use Fees Engine?

***

The **Fees Engine** helps you manage complex fee logic. It applies flat rates, distributes fees proportionally, and estimates transactions before you run them.

It offers:

* **Flexible fee configuration** via fee packages, tailored to account groups or specific ledgers.
* **Multiple calculation methods**: flat fees, percentual rates, and "max between types" logic.
* **Proportional fee distribution** for marketplace flows and multi-account operations.
* **Support for accounting routes** via `transactionRoute`, `routeFrom`, and `routeTo`.
* **Estimation tools** to preview calculations before executing transactions.
* **Fee exemption logic** by account and transaction value ranges.
* **Priority-based application** to control the order of multiple fees.
* **Accurate deduction mechanics** with `isDeductibleFrom` support.
* **Volume-based billing** via billing packages. Charge based on accumulated transaction counts per period (daily, weekly, or monthly).
* **Maintenance billing** for recurring per-account charges, targeting accounts by segment, portfolio, or explicit list.
* **Free quotas and progressive discounts** to model tiered pricing and volume incentives.
* **Segment-based exemptions** to exempt entire account groups from fee packages without listing individual accounts.
* **Fee debt** for deferrable fees: a fee that the payer cannot fund becomes a debt that later credits settle.

> [!TIP]
>
> Fees Engine is a licensed Midaz capability that runs inside the unified ledger process. Deploy and configure it with Midaz. If you'd like to learn more or evaluate it for your use case, [get in touch with our team](https://lerian.studio/contact).

## What are fees?

***

Fees are monetary values charged in exchange for services, products, or access to resources. Their purpose depends on the industry. Below are a few examples:

### Finance

In the financial sector, fees cover operational costs and support legal compliance.

* **Account maintenance fee**: Keeps accounts operational and covers administrative costs.
* **Transfer fee:** Applies to transactions like TEDs or international transfers.

### Logistics and transportation

In the logistics sector, fees cover transportation and storage services.

* **Handling fee**: Applies during storage and physical movement of goods.
* **Unloading fee**: Covers unloading operations at delivery points.

### Pharmaceutical and healthcare

In the pharmaceutical sector, fees ensure the quality and regulation of services.

* **Medication registration fee**: Related to regulatory approvals and market entry.
* **Laboratory analysis fee**: Covers testing and quality control costs.

### Agricultural

In the agricultural sector, fees cover commercialization and regulatory processes.

* **Sanitary inspection fee**: Ensures health compliance for agricultural exports.
* **Agricultural export fee**: Covers admin and regulatory export costs.

## Scope

***

The unified Midaz service exposes Fees and Billing only on the ledger-scoped v2 surface. The URL is the sole ledger input: a `ledgerId` query parameter is not accepted, and a request body that sends `ledgerId` is rejected as an unknown field. Retrieving, updating, or deleting a package owned by another ledger returns not found.

## Fee Packages

***

A **Fee Package** defines how the engine applies fees to a transaction. It groups one or more fee rules. You customize it by segment, ledger, and accounting routes.

You can create different packages for different products, transaction types, or customer segments. Each package has its own calculation logic, route configuration, and priority rules.

A package includes required fields and can add optional matching or exemption fields:

* **Ledger scope** – The v2 URL identifies the ledger that records the transaction and its fees. Do not send `ledgerId` in the request body.
* **transactionRoute** – The ID of a transaction route. The package matches a transaction that sends the same `routeId`.
* **segmentId** – A segment ID. The package matches when every source account, except `@external` accounts, belongs to this segment.
* **metadataSelector** – Metadata pairs that the transaction must all carry for the package to match. A pair matches only a string metadata value that is equal to it. You set it when you create the package.
* **waivedAccounts** – Accounts to exempt from fees, when you configure exemptions.
* **fees** – A map of individual fee rules, each including:
  * **priority** – Defines execution order.
  * **routeFrom** and **routeTo** – Custom accounting routes for the fee.
  * **isDeductibleFrom** – Whether the engine deducts the fee from what the destination receives, instead of adding it on top.
  * **referenceAmount** – The base amount for calculations.
  * **deferrable** – Whether the part of the fee that the payer cannot fund becomes a [fee debt](/en/products/midaz/fees/fee-debt). The default is `false`.

### Validation rules

Fees Engine enforces the following rules:

* **Fee priority must be unique** within a package.
* Fees with `isDeductibleFrom: true` must use `referenceAmount: originalAmount`.
* Fees with `priority` 1 must also use `referenceAmount: originalAmount`.
* Fees with `deferrable: true` must use `isDeductibleFrom: false`.
* Each fee's `creditAccount` must be an account alias that exists in the ledger. Midaz checks it when you create or update the package.

### Fee application and estimation

Midaz applies fees in-process when it creates a transaction. There is no separate public calculate-fees endpoint. The ledger evaluates the matching package in the transaction flow and applies its rules when one matches.

#### [Estimate transaction fees](/en/reference/products/midaz/v2/estimate-fee-calculation)

* Estimates fees for a specific package by its `packageId`.
* Returns calculated fees only if the amount falls inside the package's amount range. It does not check `transactionRoute` or `segmentId`.
* Useful for testing, debugging, or a preview of fees, without writing to the ledger.

> [!NOTE]
>
> Fee application happens during transaction creation. Use `estimate` when you want to test a specific package without writing to the ledger.

### Segment-based exemptions

Fee packages support exempting individual accounts by listing their aliases in `waivedAccounts`. To exempt a whole group at once, add a segment reference to that same list using the `segment:<segment-uuid>` form, for example `"segment:0198e5f4-7b2a-7c3d-9e1f-2a3b4c5d6e7f"`.

> [!WARNING]
>
> The package's own `segmentId` field is not an exemption. It scopes which package applies to a transaction (segment-level package matching). Exemptions always live in `waivedAccounts`.

Use segment-based exemptions when:

* A customer tier (such as premium accounts) is universally exempt from a fee.
* Internal or partner accounts belong to an existing segment in Midaz.
* Maintaining a list of individual account aliases is impractical at scale.

> [!TIP]
>
> Fees Engine resolves segment-based exemptions at calculation time. When accounts join or leave the segment, the change takes effect on the next calculation. You do not update the package.

## Billing Packages

***

**Billing Packages** calculate charges from accumulated transaction volume over a period (daily, weekly, or monthly). Fee packages charge per individual transaction. Billing packages count the qualifying transactions and return payloads for your orchestrator to execute.

Two types are available:

* **Volume**: charges based on the number of transactions matching an event filter in the period.
* **Maintenance**: charges a fixed fee per account that is active when you run the calculation.

> [!NOTE]
>
> Billing packages are a calculation engine, not a billing platform. The engine calculates the charges and returns the payloads. Your orchestrator (Flowker, a cron job, or any other caller) runs the actual charges against Midaz.

### Volume packages

A volume package counts transactions that match a given `eventFilter` (transaction route + status) within the billing period. It then applies a charge from the configured pricing model.

Key fields:

* **eventFilter**: Specifies which transactions to count, using `transactionRoute` and `status`.
* **pricingModel**: Either `tiered` (unit price varies by quantity range) or `fixed` (single unit price regardless of volume).
* **tiers**: Quantity ranges (`minQuantity`, `maxQuantity`) and `unitPrice` per unit within each range.
* **freeQuota**: Number of transactions exempt per period. The engine subtracts this count before it applies pricing.
* **discountTiers**: Progressive discounts. When total volume meets a threshold, the engine applies the configured discount percentage to the final amount.
* **countMode**: Accepts `perRoute` or `perAccount`. Volume calculation counts all matching transactions on the route as a single total.
* **debitAccountAlias** / **creditAccountAlias**: The accounts the charge debits and credits. Both must exist in the ledger.

### Maintenance packages

A maintenance package applies a fixed fee per account that is active when you run the calculation, regardless of transaction activity.

Key fields:

* **feeAmount**: Fixed charge per active account.
* **assetCode**: Currency for the charge.
* **maintenanceCreditAccount**: Account that receives the fee revenue.
* **accountTarget**: Defines which accounts to charge. Use exactly one per package:
  * `segmentId`: All accounts in the segment.
  * `portfolioId`: All accounts in the portfolio.
  * `aliases`: Explicit list of account aliases (maximum 100 accounts).

> [!WARNING]
>
> Each maintenance package supports only one `accountTarget` type. You cannot combine `segmentId`, `portfolioId`, and `aliases` in the same package.

### Managing billing packages

The following endpoints manage billing packages:

* `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages`: Create a billing package.
* `GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages`: List all billing packages.
* `GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}`: Retrieve a specific billing package.
* `PATCH /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}`: Update a billing package (`label`, `description`, `enable`).
* `DELETE /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}`: Soft-delete a billing package.
* `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate`: Calculate billing for a period.

## Fee Packages vs. Billing Packages

***

| | Fee Packages | Billing Packages |
| - | - | - |
| **Trigger** | Per transaction (synchronous) | Per period (monthly, weekly, or daily) |
| **Pricing model** | Flat, percentual, maxBetweenTypes | Tiered or fixed by volume |
| **Account exemption** | `waivedAccounts` (aliases or `segment:<uuid>`) | No (`accountTarget` selects the accounts to charge) |
| **Volume discounts** | No | Yes (`discountTiers`) |
| **Free quotas** | No | Yes (`freeQuota` per period) |
| **Recurring charges** | No | Yes (maintenance type) |
| **Output** | Transaction with fees applied | Calculation payloads for the caller to execute |

> [!NOTE]
>
> Fee packages and billing packages operate independently.

## Routing fees

***

Every fee can have:

* A `routeFrom`, which represents the accounting route for the debit (or source).
* A `routeTo`, which represents the accounting route for the credit (or destination).
* A `transactionRoute` on its package, which selects the transactions the package applies to.

This allows granular tracking of each fee entry in the ledger.

## Deductible fees

***

If you flag a fee as deductible ( `isDeductibleFrom: true`), the following logic applies:

* The source account sends the full value.
* The engine subtracts the fee from the amount the destination account receives.
* The `referenceAmount` for calculations must be `originalAmount`.

## Soft delete for safe recordkeeping

***

When you delete a resource:

* Fees Engine marks it with a `deletedAt` timestamp.
* Standard queries exclude it, but the database still stores it for audit and history.

## Integrations

***

Use Fees Engine in a Midaz deployment alongside other components in your stack. You can call its capabilities from Lerian plugins or your own implementation to apply fees from your business logic.

Use cases include:

* Exchange engines
* Lending platforms
* Bill payment systems
* Smart contracts
* Pix (Brazil's instant payment platform)

## Security recommendations

***

Before you deploy any component, review our [Security Recommendations](/en/products/midaz/security-recommendations). Implement each product and its plugins in line with security best practices, such as:

* Securing network boundaries
* Managing and rotating secrets
* Applying timely patch management
* Enforcing strict role-based access controls (RBAC)

## Next steps

***

> **[Explore the Fees Engine API](/en/reference/products/midaz/v2/create-package)**
>
> Browse endpoints for fee packages, calculations, and estimations.

> **[Using Fees Engine](/en/products/midaz/fees/using-fee-engine)**
>
> Learn how to create fee packages and apply them to transactions.


# Migrate Bank Transfer fees to Midaz
Source: https://docs.lerian.studio/en/products/midaz/fees/fees-migration-guide

Move fee packages from the standalone plugin-fees to the Midaz Fees Engine, and switch Bank Transfer 3.1.0 or later to Midaz fees without a gap in charging.

Bank Transfer 3.0.x charges fees through the standalone Fees plugin, `plugin-fees`. Bank Transfer 3.1.0 and later can charge them through the [Fees Engine](/en/products/midaz/fees/fees-engine-overview) that runs inside Midaz 4.1.0 and later. This page moves your fee packages from plugin-fees to Midaz. It then switches Bank Transfer over in an order that keeps every transfer charged.

Follow this page when all of these are true:

* You run Bank Transfer 3.0.x.
* Your fee packages live in plugin-fees.
* You upgrade to Bank Transfer 3.1.0 or later and to Midaz 4.1.0 or later.

Bank Transfer uses only the fee packages of plugin-fees. If you also keep billing packages in plugin-fees, recreate them as Midaz [billing packages](/en/products/midaz/fees/using-fee-engine) before you retire plugin-fees. This page does not map them.

> [!NOTE]
>
> The Lerian Console manages Midaz fee packages only. It does not show the packages that live in plugin-fees. See [Console](#console).

## How Bank Transfer chooses who charges the fee

***

From 3.1.0, the Bank Transfer variable `MIDAZ_FEE_MODE` decides who calculates and charges the fee of each transfer.

| Value | Who charges the fee | Midaz API that Bank Transfer posts on |
| - | - | - |
| `legacy` | plugin-fees, as in Bank Transfer 3.0.x | `/v1` |
| `native` | The Midaz Fees Engine, from the fee packages of the ledger | `/v2` |
| `auto` (default) | Bank Transfer reads the Midaz version. It uses `native` on Midaz 4.1.0 or later, and `legacy` on an earlier version. | `/v2` or `/v1` |

* Bank Transfer does not start with any other value.
* Under `auto`, Bank Transfer reads the Midaz version again every `MIDAZ_FEE_MODE_REFRESH` (default `5m`). When it cannot read the version, it keeps the mode it has, or uses `legacy` if it has none.
* Bank Transfer fixes the mode of a P2P transfer or TED OUT at `/initiate`, and of a TED IN when it receives it. Every later step of that transfer uses the same mode: retries, confirmation, cancellation and reconciliation. A change of mode applies to new transfers only.
* In `legacy` mode, `BTF_FEE_ENABLED` turns the plugin-fees integration on. With `false`, the default, Bank Transfer does not call plugin-fees, and every transfer runs with fee 0.
* Set `native` only on Midaz 4.1.0 or later. Midaz 4.0.x charges fees without marking the fee entries, so Bank Transfer cannot read the fee that it charged.

> [!WARNING]
>
> Do not rely on `auto` during the migration. Under `auto`, Bank Transfer 3.1.0 moves to `native` by itself as soon as it reads Midaz 4.1.0 or later. New transfers then use the Midaz packages. If your packages are still only in plugin-fees, Midaz finds no package, and those transfers carry no fee.
>
> In Bank Transfer 3.1.0, `BTF_FEE_ENABLED` does not stop Midaz from charging fees in `native` mode. To stop a fee, disable its Midaz package with `enable: false`, or delete the package. Midaz then also charges no fee on a native transfer that it has not posted yet.

## Before you start

***

You need:

* Midaz 4.1.0 or later, or a plan to upgrade to it. See [Updating Midaz](/en/products/midaz/updating-midaz).
* Bank Transfer 3.1.0 or later, or a plan to upgrade to it.
* Access to the plugin-fees API, to read and estimate your packages.
* Access to the Midaz fee package API, or to the Console [Fee Packages](/en/products/midaz/fees/console/managing-fee-packages) page.
* For each ledger and transfer type, the Midaz transaction route that Bank Transfer posts with. The tenant policy `routing.ledger_bindings` names it. See [Ledger routing](/en/interfaces/ted-jd/ted-configuration#ledger-routing).
* Three Midaz permissions for the Midaz credentials of Bank Transfer: the resource `packages` with action `get`, the resource `estimates` with action `post`, and the resource `organizations` with action `get`. In single-tenant mode, these are the credentials of `MIDAZ_CLIENT_ID`. In multi-tenant mode, Bank Transfer uses the Midaz credentials of each tenant, so grant all three permissions to the application of each tenant.

`legacy` mode does not use these permissions. Both modes also use the Midaz `settings` `post` permission described in [Bank Transfer environment variables](/en/interfaces/ted-jd/ted-environment-variables).

In `native` mode, without `packages`, every P2P and TED OUT initiation answers `503 BTF-2000`. Without `estimates`, every initiation that matches a package answers `503 BTF-2000`. `organizations` is needed because this page sets `MIDAZ_FEE_MODE=native` explicitly: Bank Transfer then makes one read of the Midaz organization list, to check the `/v2` API, before it first uses a set of credentials. Under `auto`, it does not make this read. Without `organizations`, Bank Transfer in single-tenant mode does not start, and in multi-tenant mode every P2P and TED OUT initiation of that tenant answers `503 BTF-2000`.

The examples below use these shell variables. Every UUID is a placeholder. Use the values from your own environment.

Bank Transfer reaches the Midaz ledger at `MIDAZ_TRANSACTION_URL`, or at `MIDAZ_BASE_URL` when that is unset. It strips a trailing `/v1` or `/v2` from that address. Strip it in `MIDAZ_LEDGER_URL` too, because the paths below carry the version.

```bash theme={null}
# Addresses, as Bank Transfer has them.
FEES_BASE_URL="https://plugin-fees.example.com"    # FEES_BASE_URL
MIDAZ_LEDGER_URL="https://midaz.example.com"

# Two different bearers. They are not interchangeable.
FEES_BEARER_TOKEN="..."                            # for plugin-fees
MIDAZ_BEARER_TOKEN="..."                           # for the ledger

MIDAZ_ORGANIZATION_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6"
MIDAZ_LEDGER_ID="9c858901-8a57-4791-81fe-4a34d4dd8ab5"
```

## Map a plugin-fees package to a Midaz package

***

The fee rules keep their field names and their JSON shape. Three things change: where the organization goes, where the ledger goes, and what `transactionRoute` holds.

| plugin-fees | Midaz | What to do |
| - | - | - |
| `X-Organization-Id` header | `{organization_id}` in the URL | Send the organization in the path. |
| `ledgerId` in the body | `{ledger_id}` in the URL | Send the ledger in the path. |
| `transactionRoute` | `transactionRoute` | Replace the value. See [Transaction route](#transaction-route). |
| `feeGroupLabel`, `description` | Same fields | Copy. |
| `segmentId` | `segmentId` | Copy it or leave it out, as [Package scope](#package-scope) says. Leave it out of every TED IN package. |
| `minimumAmount`, `maximumAmount` | Same fields | Copy. |
| `waivedAccounts` | `waivedAccounts` | Copy. Both accept account aliases and the `segment:<segment-uuid>` form. |
| `enable` | `enable` | Migrate only packages with `true`. Create each one with `false`. You enable it when you switch to `native`. |
| `feeLabel`, `calculationModel`, `referenceAmount`, `priority`, `isDeductibleFrom` of each fee | Same fields | Copy. |
| `creditAccount` of each fee | `creditAccount` | Copy. The account must exist in the ledger. Midaz checks it when you create the package. |
| `routeFrom`, `routeTo` of each fee | Same fields | Midaz writes the value as the operation route of the fee entry. Use the ID of a Midaz operation route, or leave the field out. In `legacy` mode, Bank Transfer dropped a value that was not a route ID. |
| `id`, `createdAt`, `updatedAt`, `deletedAt` | New values | Leave them out. Midaz assigns a new ID. Keep a record of the plugin-fees package that each Midaz package replaces. |
| No equivalent | `metadataSelector` (Midaz 4.2.0 or later) | Leave it out. |

Midaz rejects a field that it does not know. Send none of `ledgerId`, `id`, `createdAt`, `updatedAt` and `deletedAt`.

A TED OUT charges its fee on top of the amount. In both modes, Bank Transfer 3.1.0 or later refuses a TED OUT with `422 BTF-3002` when the package that matches it has a fee with `isDeductibleFrom: true`.

### Transaction route

plugin-fees compares `transactionRoute` with a name that Bank Transfer sends: `ted_out`, `ted_in` or `p2p`. Midaz compares it with the `routeId` of the transaction, which is the ID of a Midaz transaction route. Midaz accepts a UUID in this field.

For each package, use the transaction route that `routing.ledger_bindings` names for the ledger and the transfer type of the package.

> [!WARNING]
>
> A ledger whose binding uses `mode: omit` has no safe package: the only one that can match its transfers has no route, so it charges every `/v2` transaction of the ledger. Give that binding the Midaz transaction route of each transfer type on the Console [Accounting Routes](/en/interfaces/ted-jd/console/bt-accounting-routes) page, and check **Cutover readiness** there. This changes the accounting of every Bank Transfer posting on that ledger. Do it after step 2, once Midaz runs 4.1.0 or later, and before you switch.

### Package scope

plugin-fees and Midaz select the package of a transfer in different ways, so an exact copy can charge a different fee. Apply these rules to the enabled packages of each ledger:

* **The ledger has one enabled package.** plugin-fees applies it to every transfer in its amount range, P2P, TED OUT and TED IN alike. It ignores the `transactionRoute` and the `segmentId` of that package. In Midaz, create one copy for each transfer type that it charged, each with the transaction route of that type, and without `segmentId`.
* **A route has one package.** When the ledger has more than one enabled package, plugin-fees applies the only package of a route to every transfer on that route, inside its amount range. It ignores the `segmentId` of that package. Create the Midaz package without `segmentId`.
* **A route has several packages.** plugin-fees then picks by the segment of the sender. A sender with a segment gets only a package with that segment. A sender with no segment gets only a package with no segment. Keep each `segmentId`. Midaz also applies a package with no segment to a sender who has a segment, when no package of that segment covers the amount. If the route has a package with no segment, decide which behavior you want.
  * When every fee of that package is charged on top of the amount (`isDeductibleFrom: false`), you can keep the plugin-fees behavior. Add `segment:<segment-uuid>` to the `waivedAccounts` of that package for every segment of the ledger, and for every segment that you create later. Midaz then charges none of its fees to a sender in those segments.
  * On a fee taken out of the amount, the waiver also exempts a recipient in those segments, so do not use it there. For such a package, the engines cannot match. Decide whether a sender whose segment has no package of its own for that amount pays it in Midaz, or whether you leave it out, so that a sender with no segment pays none of its fees.
* **TED IN.** For a TED IN, Bank Transfer sent plugin-fees the segment of the recipient account. Midaz reads the segment from the source accounts, and it skips the external account, which is the only source of a TED IN. So a Midaz package with a `segmentId` never matches a TED IN. Create every TED IN package without `segmentId`.
  * If the ledger has more than one TED IN package in plugin-fees, plugin-fees charged a recipient with a segment only a package with that segment, and a recipient with no segment only a package with no segment. Midaz cannot see the segment of the recipient, and it applies the packages with no segment to every recipient. Decide the TED IN price that applies to every recipient.
* **A package with no route.** When the ledger has more than one enabled package, plugin-fees never applied a package with no route to a Bank Transfer transfer, because Bank Transfer always sends a route. Leave it out.
* **Two packages that match.** Midaz selects the package that matches the most constraints. When two packages match equally, Midaz refuses the transaction with error `0198`. At initiation, Bank Transfer answers `422 BTF-2005`.

## Migrate step by step

***

**1. Pin the legacy mode**

Set `MIDAZ_FEE_MODE=legacy` in the Bank Transfer environment. Bank Transfer 3.0.x ignores the variable, so you can set it ahead of the upgrade. If you deploy with the Helm chart, follow its [upgrade note](https://github.com/LerianStudio/helm/blob/main/charts/plugin-br-bank-transfer/docs/UPGRADE-2.3.md) to set the value and check it before the rollout.

Keep `BTF_FEE_ENABLED=true` and the `FEES_*` variables as they are.

**2. Upgrade Bank Transfer, then Midaz**

Before you upgrade, make sure that no plugin-fees package that a TED OUT can match has a fee with `isDeductibleFrom: true`. [Package scope](#package-scope) says which packages a TED OUT can match. From 3.1.0, Bank Transfer refuses such a TED OUT with `422 BTF-3002` in `legacy` mode too.

Upgrade Bank Transfer to 3.1.0 or later. Wait until every Bank Transfer pod runs 3.1.0 or later. An earlier version cannot settle a transfer that Bank Transfer created in `native` mode.

Check the log of every pod for `midaz: fee mode resolved` with `feeMode=legacy` and `source=config`. In single-tenant mode, a pod logs it at boot. In multi-tenant mode, it logs it for each tenant at the first transfer of that tenant. `source=config` proves that the pin works. Check it while Midaz still runs a version earlier than 4.1.0. There, `auto` also resolves to `legacy`, so a transfer that pays its plugin-fees fee does not prove the pin.

Upgrade Midaz to 4.1.0 or later.

Make a small transfer. Check that plugin-fees still charges its fee.

**3. Recreate each enabled package in Midaz**

List the enabled packages of each ledger in plugin-fees. Each answer holds one page, and its `total` counts the items of that page only. Read the next page until a page returns fewer items than `limit`. The list leaves out deleted packages.

```bash theme={null}
curl -s "$FEES_BASE_URL/v1/packages?ledgerId=$MIDAZ_LEDGER_ID&enable=true&limit=100&page=1" \
  -H "Authorization: Bearer $FEES_BEARER_TOKEN" \
  -H "X-Organization-Id: $MIDAZ_ORGANIZATION_ID"
```

Create each package in Midaz with the mapping and the scope rules above. Set `enable` to `false`. Keep a list of the packages that you create: you enable exactly these when you switch. This example recreates a flat TED OUT fee. Its `transactionRoute` is the TED OUT transaction route of the ledger binding.

```bash theme={null}
curl -s -X POST "$MIDAZ_LEDGER_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/packages" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "feeGroupLabel": "TED OUT fee",
    "description": "Fee on outgoing TEDs",
    "transactionRoute": "0199a5c1-3e2f-7b4d-9a8e-5f6d7c8b9a0e",
    "minimumAmount": "0.01",
    "maximumAmount": "1000000.00",
    "fees": {
      "tedOutFee": {
        "feeLabel": "TED OUT fee",
        "calculationModel": {
          "applicationRule": "flatFee",
          "calculations": [{ "type": "flat", "value": "5.00" }]
        },
        "referenceAmount": "originalAmount",
        "priority": 1,
        "isDeductibleFrom": false,
        "creditAccount": "fees-revenue"
      }
    },
    "enable": false
  }'
# -> {"id": "..."}  this is the Midaz package ID
```

You can also create the packages on the Console [Fee Packages](/en/products/midaz/fees/console/managing-fee-packages) page.

**4. Compare the fees of both engines**

For each package, estimate the same transaction in plugin-fees and in Midaz. Compare the fee amounts. They must be equal. Use amounts at both ends of the range of the package, and one amount in the middle. For a package that carries the segment waivers from [Package scope](#package-scope), use a sender outside those segments. Midaz exempts a sender in them by design, and plugin-fees does not.

```bash theme={null}
TRANSACTION='{
  "send": {
    "asset": "BRL",
    "value": "1500.00",
    "source": { "from": [{ "accountAlias": "@sender", "amount": { "asset": "BRL", "value": "1500.00" } }] },
    "distribute": { "to": [{ "accountAlias": "@external/BRL", "amount": { "asset": "BRL", "value": "1500.00" } }] }
  }
}'

# plugin-fees: the plugin-fees package ID, and the ledger in the body
curl -s -X POST "$FEES_BASE_URL/v1/estimates" \
  -H "Authorization: Bearer $FEES_BEARER_TOKEN" \
  -H "X-Organization-Id: $MIDAZ_ORGANIZATION_ID" \
  -H 'Content-Type: application/json' \
  -d '{ "packageId": "0198f1a2-6c3d-7e4f-8a9b-1c2d3e4f5a6b", "ledgerId": "'"$MIDAZ_LEDGER_ID"'", "transaction": '"$TRANSACTION"' }'

# Midaz: the Midaz package ID, and the ledger in the URL
curl -s -X POST "$MIDAZ_LEDGER_URL/v2/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/estimates" \
  -H "Authorization: Bearer $MIDAZ_BEARER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "packageId": "0199b7d2-4f5e-7a6b-8c9d-2e3f4a5b6c7d", "transaction": '"$TRANSACTION"' }'
```

In the Midaz answer, each fee entry has `"feeLeg": "true"` in its `metadata`. You can also use the Console [Fee Calculator](/en/products/midaz/fees/console/managing-fee-calculations).

An estimate calculates the one package that you name. It does not check `transactionRoute` or `segmentId`, so it does not show which package a transfer gets. The next step tests that.

**5. Rehearse the selection in homologation**

Run steps 1 to 4 in homologation first, with the same packages. Then test which package each transfer gets, before you switch production:

1. Under `legacy`, call `POST /v1/transfers/initiate` for each case: P2P and TED OUT, from a sender in each segment of the ledger and from a sender with no segment, with amounts at both ends of the range of each package. Record `feeAmount` and `packageAppliedId` from each answer. Do not process these initiations. An initiation posts nothing to Midaz. It writes a `payment_initiations` row that expires at `expiresAt`, keeps a duplicate fingerprint for 300 seconds by default, and sends a `payment_initiation.created` event to your webhook and event consumers. A TED OUT initiation outside the operating window answers `422 BTF-0010`.
2. Switch homologation to `native`, as in the next step.
3. Repeat the same initiations. Compare each `feeAmount`. `packageAppliedId` now names the Midaz package. Check that it is the package that replaces the plugin-fees one. An identical initiation inside that duplicate window answers `409 BTF-0012`, so wait for it to pass.
4. TED IN has no initiation. Under each mode, receive one small TED IN for a recipient in each segment and for a recipient with no segment. Compare the fees.

Expect a difference only where [Package scope](#package-scope) says the engines cannot match, and only the one you chose there. Fix every other difference in the Midaz packages, and repeat the cases.

**6. Switch Bank Transfer to native**

Before the switch, run the P2P and TED OUT initiation cases of step 5 in production, under `legacy`. Use test accounts of your own, one in each segment and one with no segment. Record each `feeAmount`. Step 5 says what an initiation writes.

1. Give the Midaz credentials of Bank Transfer the `packages` (`get`), `estimates` (`post`) and `organizations` (`get`) permissions.
2. Enable each Midaz package that you created in step 3. Send `"enable": true` with [Update a Package](/en/reference/products/midaz/v2/update-package). No initiation tests a TED IN, so first compare the `transactionRoute` of each TED IN package with the **Transaction route** of the `TED_IN` binding of its ledger, on the Console [Accounting Routes](/en/interfaces/ted-jd/console/bt-accounting-routes) page.
3. Set `MIDAZ_FEE_MODE=native`.
4. Restart every Bank Transfer pod.

Right after the restart, run the same cases again, with the same accounts. Compare each `feeAmount`, and check each `packageAppliedId`. Expect a difference only where [Package scope](#package-scope) says the engines cannot match, and only the one you chose there. An identical initiation inside the duplicate window answers `409 BTF-0012`, so wait for the window to pass between the two runs. An initiation posts nothing to Midaz, so these cases show a wrong route or segment ID without moving money.

If another difference shows, [roll back](#roll-back). Correct the fees or the amount range of a package with Update a Package. Update a Package cannot change `transactionRoute` or `segmentId`, so for a wrong route or segment, create a corrected package with `enable: false`, and delete the wrong one only after the native transfers that used it have finished. This query lists the transfers created in `native` mode since the restart began. Check the fee of each one by hand.

```sql theme={null}
SELECT id, type, status, created_at FROM transfers
 WHERE ledger_fee_mode = 'native'
   AND created_at >= '2026-10-09 14:00:00-03';  -- just before the restart began
```

New transfers now use Midaz fees. A P2P transfer or TED OUT initiated before the restart, and a TED IN received before it, keep the `legacy` mode until they finish.

**7. Check real transfers**

Make a small P2P transfer or TED OUT. Check the fee that Bank Transfer shows at initiation. Check the fee that it records on the transfer. Both must match the fee that plugin-fees charged before, except for a difference that you chose in [Package scope](#package-scope).

Check the first TED IN that arrives after the switch the same way.

In Midaz, the metadata of a transaction that a package charged or exempted has `packageAppliedID`. It is the ID of that Midaz package.

**8. Retire plugin-fees**

Keep plugin-fees running while this query returns rows. In multi-tenant mode, run it on the Bank Transfer database of each tenant.

```sql theme={null}
SELECT id, status FROM transfers
 WHERE type = 'TED_IN' AND ledger_fee_mode = 'legacy'
   AND status NOT IN ('COMPLETED', 'REJECTED', 'FAILED', 'CANCELLED');
```

These are TED INs received before the switch. When Bank Transfer resumes one, it asks plugin-fees for its fee. If plugin-fees is stopped, Bank Transfer credits the recipient with no fee. When `fees.fail_closed_default` is `true`, it returns the TED to the sender instead, unless Bank Transfer cannot read that policy.

Then back up the plugin-fees MongoDB database, and stop plugin-fees. After that, you cannot [roll back](#roll-back).

Keep `MIDAZ_FEE_MODE=native`. Under `auto`, a pod that cannot read the Midaz version starts in `legacy` mode, and `legacy` needs plugin-fees.

## Roll back

***

You can return to plugin-fees while plugin-fees still runs with its packages unchanged:

1. Set `MIDAZ_FEE_MODE=legacy`.
2. Restart every Bank Transfer pod.

New transfers then use plugin-fees again. This needs `BTF_FEE_ENABLED=true` and the `FEES_*` variables still in place.

Transfers created in `native` mode keep that mode. Bank Transfer finishes them on the Midaz `/v2` API, and Midaz charges their fees when it posts them. Keep the Midaz packages enabled until every native transfer has finished.

Keep Bank Transfer on 3.1.0 or later while any transfer created in `native` mode is still open. An earlier version settles that transfer on `/v1`, so its fee is not charged or not recorded.

## Console

***

The Fees Engine pages of the Console, [Fee Packages](/en/products/midaz/fees/console/managing-fee-packages) and [Fee Calculator](/en/products/midaz/fees/console/managing-fee-calculations), work on Midaz fee packages only. They do not read plugin-fees.

## See also

***

* [What is Fees Engine?](/en/products/midaz/fees/fees-engine-overview)
* [Using Fees Engine](/en/products/midaz/fees/using-fee-engine)
* [Estimate transaction fees](/en/reference/products/midaz/v2/estimate-fee-calculation)
* [Bank Transfer configuration](/en/interfaces/ted-jd/ted-configuration)
* [Bank Transfer environment variables](/en/interfaces/ted-jd/ted-environment-variables)


# Using Fees Engine
Source: https://docs.lerian.studio/en/products/midaz/fees/using-fee-engine

Use the Fees Engine to apply per-transaction fee packages and per-period billing packages that match your ledgers, segments, and transaction routes.

Fees Engine applies per-transaction fees and calculates periodic billing charges. This guide covers both workflows: fee packages (per-transaction) and billing packages (per-period).

> [!TIP]
>
> Fee packages apply charges at transaction time. Billing packages calculate charges over a period (daily, weekly, or monthly) for your orchestrator to execute. You can use both simultaneously.

## Fee packages: per-transaction workflow

***

Fee packages apply charges synchronously when you create a v2 transaction. This section shows the process, from fee setup to results.

### Step 1 - Create your fee packages

First, set up **fee packages** that define how the engine applies fees. Use the [Create a Package](/en/reference/products/midaz/v2/create-package) endpoint. Each package contains a set of fee rules and matching criteria.

You can tailor packages to different ledgers, segments, and transaction routes with these fields:

* **transactionRoute** - The ID of a transaction route, when you need route-level matching.
* **segmentId** - The ID of the segment the source accounts belong to, when you need segment-level matching.
* **metadataSelector** - Metadata pairs that the transaction must carry, when you need metadata-level matching.
* **Ledger scope** - The request URL identifies which ledger records the transaction; do not send `ledgerId` in the package body.
* **Minimum** and **maximum** amount - Thresholds for fee application.
* **routeFrom** / **routeTo** - Define how each fee moves across accounting flows.

These fields let you apply distinct fees per scenario, from account-based setups to value-based.

**Managing Packages**

The following endpoints are also available for you to manage the packages:

* [List Packages](/en/reference/products/midaz/v2/get-all-packages) - List all packages created.
* [Retrieve a Package](/en/reference/products/midaz/v2/get-package-by-id) - Retrieve information of a specific package.
* [Update a Package](/en/reference/products/midaz/v2/update-package) - Update the information of a specific package.
* [Delete a Package](/en/reference/products/midaz/v2/delete-package) - Soft-delete a package.

### (optional) Step 2 - Run an estimation

To preview how a fee package behaves before you commit a real transaction, use the [Estimate Transaction Fees](/en/reference/products/midaz/v2/estimate-fee-calculation) endpoint.

This estimation helps validate:

* Which fee rules apply.
* How the package will behave with the given values.
* Whether any exemptions apply.

### Step 3 - Create a transaction

Once you set the packages, create the transaction through the v2 transaction API, for example with the [Create a Transaction using the v2 direct model](/en/reference/products/midaz/v2/create-transaction-direct) endpoint. Only v2 transactions apply fees, including the direct and hold items of a v2 batch. To match a route-scoped package, send the transaction route ID in `routeId`. Midaz reads the segment from the source accounts.

### Step 4 - Fees Engine evaluates the packages

Fees Engine runs in-process when Midaz creates the transaction. It evaluates whether a package applies, based on:

* **transactionRoute**, when configured
* **segmentId**, when configured
* **metadataSelector**, when configured
* **Ledger scope from the request URL**
* **Minimum** and **maximum** amount
* **waivedAccounts**, when configured for fee exemptions

> [!NOTE]
>
> Fees Engine selects at most one package per transaction: the most specific match. Each `metadataSelector` pair makes a package more specific. When two packages match equally, Midaz refuses the transaction with error `0198`.

### Step 5 - Check for exemptions

The system checks:

* If the transaction amount is outside the allowed range.
* If every source account is waived.

If either condition is true, Fees Engine applies no fees and the transaction proceeds normally.

The External Account (`@external/<asset>`) that Midaz adds to a cross-ledger transaction never pays a fee.

### Step 6 - Fee calculation and application

If a package applies, Fees Engine:

* Calculates fee values based on the selected `applicationRule`.
* Applies fees proportionally across accounts if needed.
* Uses `isDeductibleFrom` to set whether it adds or deducts the fee.
* Routes fees to the correct `creditAccount` with the configured `routeFrom` and `routeTo`.
* Returns the full transaction result along with the `packageAppliedID` in the metadata.

### Step 7 - Ledger updates

Once Fees Engine calculates the fees, the **Transactions** component takes over. It processes:

* Debits from source accounts
* Credits to fee destinations
* Fee breakdown per route and account

The ledger stores every movement for full traceability and auditability.

### Step 8 - Review and confirm

After execution, you can:

* Inspect the final transaction and amounts per account.
* Confirm which fee package applied.
* Verify all fee movements via metadata and ledger records.

## Why estimate a transaction?

***

Estimations let you preview how a specific fee package behaves, without running a real transaction or writing to the ledger.

Use estimations when:

* You want to test a specific package.
* You debug fee rules or thresholds.
* You want to validate exemptions, value ranges, or proportional splits.
* You need a preview before you create a real transaction.
* You build an interface and want to show estimated fees.

Fees Engine provides the [Estimate Transaction Fees](/en/reference/products/midaz/v2/estimate-fee-calculation) endpoint for this purpose. You pass a `packageId`, and the endpoint returns what would happen if it applied that exact package.

### What do you get with an estimation?

* A full estimation of the fee rules.
* Which accounts the engine would charge.
* How the engine would split the fee.
* No impact on the ledger.

> [!TIP]
>
> Use estimations when you're not ready to commit the transaction, or want to give your users a clear fee preview.

## Common errors

***

Fees Engine validates every request for consistency and correct fee logic. Below are the most frequent issues you might see when you create packages or process transactions.

| Code | Title | Message |
| :- | :- | :- |
| 0009 | Missing Fields in Request | Your request is missing one or more required fields: `<fields>`. Please refer to the documentation to ensure all necessary fields are included in your request. |
| 0007 | Entity Not Found | No entity was found for the given ID. Please make sure to use the correct ID for the entity you are trying to manage. |
| 0180 | Invalid fee priority | The priority field in fees is invalid. Field can not be repeated. |
| 0182 | minimumAmount greater than maximumAmount | minimumAmount value is greater than maximumAmount. |
| 0186 | Failed to calculate fee | Failed to calculate the fee for the transaction. Please check the fee configuration and try again. |
| 0188 | originalAmount is required when priority is one | For Priority equals to one, referenceAmount must be 'originalAmount' for fee `<fee>`. |
| 0189 | Failed to apply rule: flatFee or percentual | applicationRule flatFee or percentual must have exactly 1 calculation for Fee `<fee>`. |
| 0198 | Package filtering error | More than one fee package matches this transaction at the same specificity, so none of them can be applied. Re-scope one of these packages: `<package IDs>`. |
| 0199 | Package amount range overlap | The maximumAmount and minimumAmount of the new package overlap with the amount range of an existing package. |
| 0530 | Deductible fee cannot be deferrable | Fee `<fee>` is deducted from the payment (isDeductibleFrom true), so it cannot be deferrable. Set deferrable to false or isDeductibleFrom to false. |

## Billing packages: per-period workflow

***

Billing packages calculate charges based on accumulated transaction volume or per-account maintenance over a billing period. Unlike fee packages, your orchestrator triggers billing. It decides when to calculate and executes the resulting charges.

### Step 1: Create billing packages

Set up billing packages that define your periodic charge rules. Each package is either **volume** or **maintenance** type.

**Volume package example**, a charge per Pix sent with tiered pricing:

```json theme={null}
POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages
Body:
{
  "label": "Pix Send Monthly Billing",
  "description": "Monthly volume billing for Pix transactions",
  "type": "volume",
  "enable": true,
  "eventFilter": {
    "transactionRoute": "pix-send",
    "status": "APPROVED"
  },
  "pricingModel": "tiered",
  "tiers": [
    { "minQuantity": 1, "maxQuantity": 100, "unitPrice": "0.50" },
    { "minQuantity": 101, "maxQuantity": 500, "unitPrice": "0.35" },
    { "minQuantity": 501, "maxQuantity": null, "unitPrice": "0.20" }
  ],
  "freeQuota": 10,
  "discountTiers": [
    { "minQuantity": 200, "discountPercentage": "5.00" },
    { "minQuantity": 400, "discountPercentage": "10.00" }
  ],
  "countMode": "perRoute",
  "assetCode": "BRL",
  "debitAccountAlias": "client-wallet",
  "creditAccountAlias": "fees-revenue"
}
```

**Maintenance package example**, a monthly fee per active PF account:

```json theme={null}
POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages
Body:
{
  "label": "PF Account Maintenance",
  "description": "Monthly maintenance fee for active PF accounts",
  "type": "maintenance",
  "enable": true,
  "feeAmount": "9.90",
  "assetCode": "BRL",
  "maintenanceCreditAccount": "fees-maintenance-pf",
  "accountTarget": {
    "segmentId": "0198e5f4-7b2a-7c3d-9e1f-2a3b4c5d6e7f"
  }
}
```

### Step 2: Trigger billing calculation

Call `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate` with the billing period. The URL identifies the ledger. The engine evaluates every enabled billing package in the ledger, limited to the `type` you send.

```json theme={null}
POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate

Body:
{
  "period": "2026-03",
  "type": "volume"
}
```

The `period` field supports three formats: `YYYY-MM` (monthly), `YYYY-Www` (weekly, e.g., `2026-W13`), and `YYYY-MM-DD` (daily).

The `type` field is optional. Use `"volume"` or `"maintenance"` to restrict the calculation to one type. Omit it to calculate both types in a single call.

### Step 3: Receive calculation results

Each result includes:

* The billing package that generated it.
* The calculated amounts.

### Step 4: Execute charges

Submit only nonempty `transactionPayload` results. An empty object means there is no charge to execute.

> [!NOTE]
>
> The billing engine calculates and returns results. It does not create transactions in Midaz. Your orchestrator controls when and how it executes charges.

### Step 5: Review and reconcile

After executing the charges:

* Verify the created transactions in Midaz match the billing calculation results.
* Use the audit metadata from nonempty transaction payloads for reconciliation.
* The billing calculation is stateless. A re-run for the same period reflects the ledger at the time of the re-run.

### Managing billing packages

Use these endpoints to manage existing billing packages:

* `GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages`: List all billing packages.
* `GET /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}`: Retrieve a specific billing package.
* `PATCH /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}`: Update a billing package (`label`, `description`, `enable` only).
* `DELETE /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}`: Soft-delete a billing package.

> [!WARNING]
>
> If any package fails during calculation, the entire operation fails and returns no partial results. Billing calculation follows an all-or-nothing policy. Fix the failing package and re-execute.


# Fees Engine in Lerian Console
Source: https://docs.lerian.studio/en/products/midaz/fees/using-fee-engine-with-midaz-console

Define, test, and apply fees visually with the Fees Engine in the Midaz Module, with no code required for fee packages and estimations.

The **Fees Engine** is available through the Midaz Module in [Lerian Console](/en/platform/console/about-lerian-console). The visual interface lets you define, test, and update how fees apply to transactions without writing code.

## What you can do

***

Through the Lerian Console, you can:

* **Create and manage Fee Packages**: Define fee rules with different calculation types (flat fee, percentage, or maximum between both)
* **Run fee estimations**: Test how the engine calculates fees for specific amounts before you apply them to real transactions
* **Associate fees with your data**: Link fee packages to specific ledgers, segments, or transaction routes
* **Configure billing**: Create volume and maintenance billing packages, and preview the billing for a period

## Accessing the Fees Engine

***

To access the Fees Engine in Lerian Console:

1. From the home page, select **Midaz** to enter the Midaz Module
2. In the left sidebar, go to **Plugins**
3. Select **Fees Engine**

## Learn more

***

For complete documentation on using the Fees Engine through Lerian Console, see:

> **[Fees Engine in Midaz Module](/en/products/midaz/fees/console/fees-engine-overview)**
>
> Complete guide to managing fees through the Lerian Console interface.


# Prerequisites
Source: https://docs.lerian.studio/en/products/midaz/installing-and-deploying-overview

Prerequisites hub for installing and deploying Midaz: security recommendations, setup, updates, deployment strategies, Terraform, and Helm guides.

This section shows you how to install, update, and deploy Midaz. You can run it locally or provision a full cloud-native setup.

## Content

***

* [**Security recommendations**](/en/products/midaz/security-recommendations): Understand shared responsibilities, best practices, and the configurations you need to deploy Midaz and its plugins securely.
* [**Installing Midaz**](/en/products/midaz/midaz-setup): Instructions to install and configure Midaz.
* [**Updating Midaz**](/en/products/midaz/updating-midaz): Instructions to update your instance when you need to.
* [**Deployment strategies**](/en/products/midaz/deployment): Learn about Midaz deployment strategies and platform requirements.
  * [**Midaz Terraform Foundation**](/en/products/midaz/midaz-terraform-foundation): Set up the Midaz cloud foundation with Terraform best practices.
  * [**Midaz chart README**](https://github.com/LerianStudio/helm/blob/main/charts/midaz/README.md): install and configure Midaz with its chart. Per-version upgrade notes are in the chart's [upgrade notes](https://github.com/LerianStudio/helm/tree/main/charts/midaz/docs).
* [**Version compatibility**](/en/products/midaz/midaz-version-compatibility): Check which plugin versions work with each Midaz release.

> [!CAUTION]
>
> By default, Midaz does not require authentication, so you can call the Midaz APIs directly. To require authentication, use the [Access Manager](/en/platform/access-manager) plugin. When `ENV_NAME=production`, the ledger requires authentication and does not start without it. For details, [contact us](https://lerian.studio/contact).


# Lerian Support Portal
Source: https://docs.lerian.studio/en/products/midaz/lerian-support-portal

Open tickets, report incidents, and request services through the official Lerian Support Portal, for Enterprise clients with SLA-backed response times.

The [Lerian Support Portal](https://lerian.atlassian.net/servicedesk) is the official support channel for **Enterprise clients**. Use it to get support, report issues, and manage your service requests.

> [!NOTE]
>
> If you use the community version of Midaz, see the [Community support](/en/products/midaz/community-support) page. It explains how to ask questions, report bugs, and get help from the community.

### How it works

Use the portal to open tickets, track progress, submit service requests, and report incidents.

The portal routes each request to the right team based on its type and context.

## Incident types

***

When you raise an incident, choose one of two categories:

### Non Transactional Incident

Use this option for issues with platform and operational products such as:

* Accounts
* CRM
* Reporter
* Lifecycle Management
* Flowker
* Other non-transactional services

### Transactional Incident

Use this option for issues with financial and payment operations such as:

* Transactions
* Fees
* Bank transfers
* Payments
* Pix

> [!TIP]
>
> If you are unsure which category fits, check whether the issue involves money movement or payments. If yes, choose **Transactional Incident**. If not, choose **Non Transactional Incident**.

## Request form fields

***

Both incident types use the same form. When you register a request, provide complete and accurate information.

| Field | Description |
| :- | :- |
| **Summary** | A short, clear description of the issue or request. |
| **What are the details of your request?** | A detailed explanation of what happened, the expected behavior, and any relevant technical context. This is the most important field in the form. |
| **Products** | Select the specific product related to your issue. The available options depend on the incident type you chose (Transactional or Non Transactional). |
| **Environment** | Select the environment where the issue occurred (e.g., production, staging). |
| **Business Function Impact** | Select how the issue impacts your business operations. |
| **Current State Affected Service** | Select the severity level based on the current state of the affected service. See the priority table below for guidance. |
| **Current Workaround** | Select whether a workaround is currently available. |
| **Data Integrity Security** | Select if there are any data integrity or security concerns related to the issue. |
| **Expects to be Resolved** | Select your expected resolution timeframe. |
| **Users Affected** | Select the scope of users impacted by this issue. |
| **Attachment** | Attach logs, screenshots, payloads (excluding sensitive data), or request IDs to help us investigate. |

> [!TIP]
>
> The more context you provide, the fewer follow-up questions we need to resolve your issue.

## Priority levels and SLA

***

When you fill out the **Current State Affected Service** field, select the option that describes your service now. Each option maps to a priority level and an SLA:

| Current State Affected Service | Priority | SLA (Response Time) |
| :- | :- | :- |
| **Complete outage – service is unreachable** | P1 – Critical | Response within **15 minutes** |
| **Severe degradation – service is very slow or partially broken** | P2 – High | Response within **30 minutes** |
| **Minor degradation – some features are impaired** | P3 – Medium | Analyzed during regular prioritization |
| **Cosmetic issue or minor inconvenience** | P4 – Low | Analyzed during regular prioritization |

> [!CAUTION]
>
> For P1 or P2 incidents, provide as much detail as possible in the description field.

## How to open an incident

***

To open an incident, follow these steps:

**Step 1**

Go to the [Lerian Support Portal](https://lerian.atlassian.net/servicedesk).

**Step 2**

Log in with your email and password.

**Step 3**

Select **Incidents**.

**Step 4**

Choose the incident type: **Non Transactional Incident** or **Transactional Incident**.

**Step 5**

Fill in all required fields, especially the description and product selection.

**Step 6**

Click **Submit**.

## Still need help?

***

If you are still unsure where your issue fits, email us at [**suporte@lerian.studio**](mailto:suporte@lerian.studio). We route your message to the right team.


# Environment variables
Source: https://docs.lerian.studio/en/products/midaz/midaz-environment-variables

Reference for Midaz ledger service environment variables: ports, TLS, deployment mode, and CRM or Fees settings for onboarding and transaction APIs.

This reference lists the environment variables that configure the **Midaz ledger service**. Midaz is the double-entry engine. It serves the onboarding and transaction APIs on a single port. You set these variables at deploy time, through Helm values, Docker Compose, or your orchestrator's environment. A required variable that you do not set makes the server fail on startup.

Every Lerian product shares a set of configuration blocks: TLS posture, OpenTelemetry, Access Manager authentication, service discovery, and event streaming. The [BYOC configuration reference](/en/reference/byoc-configuration) documents these blocks. This page focuses on what is distinctive to the ledger.

> [!NOTE]
>
> You deploy the **ledger** service. It serves the onboarding and transaction routes, and **CRM** and **Fees** run in the same process. The ledger reads the CRM and Fees variables below. Tracer ships as its own optional service. The Helm chart also carries a legacy standalone `crm` deployment, disabled by default.

## Ports and health endpoints

The ledger runs one HTTP process. See the [health and readiness reference](/en/reference/health-and-readiness) for the probe contract.

| Surface | Port variable | Default | Endpoints |
| - | - | - | - |
| Ledger HTTP (onboarding + transaction) | `SERVER_PORT` / `SERVER_ADDRESS` | `3002` | `/health`, `/readyz`, `/version` |

The ledger uses OTLP push for telemetry and does not expose a `/metrics` scrape endpoint.

## Deployment and TLS

| Variable | Description | Default | Required |
| - | - | - | - |
| `DEPLOYMENT_MODE` | Deployment flavor: `local`, `byoc`, or `saas`. In `saas`, TLS is mandatory for every dependency connection and the server refuses to start without it. In `byoc`, TLS is recommended and warned-on rather than enforced. Also tags the `/readyz` response. | `local` | No |
| `ALLOW_INSECURE_TLS` | Bypass per-connection TLS enforcement on infrastructure DSNs. Leave unset or `false` in production; set `true` only for local plaintext infrastructure. | `false` | No |

## Application

| Variable | Description | Default | Required |
| - | - | - | - |
| `ENV_NAME` | Environment label (for example `development`, `staging`, `production`) | `development` | No |
| `LOG_LEVEL` | Log verbosity: `debug`, `info`, `warn`, or `error` | `debug` | No |
| `MAX_PAGINATION_LIMIT` | Maximum page size accepted by list endpoints | `100` | No |
| `MAX_PAGINATION_MONTH_DATE_RANGE` | Default date-range window in months for transaction and operation lists when neither start nor end date is supplied. The bundled example configuration ships `3`. | `1` | No |
| `TRANSACTION_BATCH_MAX_SIZE` | Maximum number of transactions in one atomic batch request. Accepts `1` to `50`. Any other value stops the server on startup. | `10` | No |
| `OPENAPI_DOCS_ENABLED` | Serve the OpenAPI 3.1 spec at `/openapi.json` and `/openapi.yaml`, and the interactive docs at `/docs` | `false` | No |

## Database (PostgreSQL)

The ledger keeps two logical databases (`onboarding` and `transaction`), each with a primary and a replica connection block. The variables share one shape. Replace `{MODULE}` with `ONBOARDING` or `TRANSACTION`. Replica variables carry a `_REPLICA_` infix (for example `DB_ONBOARDING_REPLICA_HOST`).

| Variable | Description | Default | Required |
| - | - | - | - |
| `DB_{MODULE}_HOST` | Primary PostgreSQL host | — | Yes |
| `DB_{MODULE}_PORT` | PostgreSQL port | — | Yes |
| `DB_{MODULE}_USER` | Database user | — | Yes |
| `DB_{MODULE}_PASSWORD` | Database password. Sensitive. Do not commit it. Supply it through your secret store. | — | Yes |
| `DB_{MODULE}_NAME` | Database name | `onboarding` / `transaction` | Yes |
| `DB_{MODULE}_SSLMODE` | libpq SSL mode: `disable`, `require`, `verify-ca`, or `verify-full`. Use `require` or stronger in production. | `disable` | No |
| `DB_{MODULE}_MAX_OPEN_CONNS` | Maximum open connections in the pool | `3000` | No |
| `DB_{MODULE}_MAX_IDLE_CONNS` | Maximum idle connections in the pool | `3000` | No |
| `DB_TRANSACTION_ROUTE_TX_READS_TO_PRIMARY` | Send the reads of the transaction flow to the primary, not the replica. A false value, such as `false` or `0`, turns it off. | `true` | No |

## Document store (MongoDB)

The MongoDB variables use one namespace per module: `MONGO_ONBOARDING_*`, `MONGO_TRANSACTION_*`, and, on the consolidated binary, `MONGO_CRM_*` and `MONGO_FEES_*`. All share one shape. Replace `{NS}` with the namespace. They may point at one MongoDB deployment (separate logical databases) or dedicated hosts.

| Variable | Description | Default | Required |
| - | - | - | - |
| `MONGO_{NS}_HOST` | MongoDB host | — | Yes |
| `MONGO_{NS}_PORT` | MongoDB port | — | Yes |
| `MONGO_{NS}_USER` | Database user | — | Yes |
| `MONGO_{NS}_PASSWORD` | Database password. Sensitive. | — | Yes |
| `MONGO_{NS}_NAME` | Database name | namespace name | Yes |
| `MONGO_{NS}_URI` | Connection scheme: `mongodb` or `mongodb+srv` | `mongodb` | No |
| `MONGO_{NS}_MAX_POOL_SIZE` | Maximum connection pool size | `100` | No |
| `MONGO_{NS}_TLS_CA_CERT` | Base64-encoded PEM CA certificate for TLS (for example AWS DocumentDB) | — | No |
| `MONGO_{NS}_PARAMETERS` | Extra connection-string parameters | — | No |

## Cache (Redis / Valkey)

| Variable | Description | Default | Required |
| - | - | - | - |
| `REDIS_HOST` | Redis/Valkey host and port | — | Yes |
| `REDIS_PASSWORD` | Authentication password. Sensitive. | — | No |
| `REDIS_TLS` | Enable TLS for the connection | `false` | No |
| `REDIS_CA_CERT` | Base64-encoded PEM CA certificate for TLS | — | No |
| `REDIS_DB` | Logical database index | `0` | No |
| `REDIS_PROTOCOL` | RESP protocol version | `3` | No |
| `REDIS_POOL_SIZE` | Connection pool size | `10` | No |
| `REDIS_MASTER_NAME` | Sentinel master name (Sentinel deployments) | — | No |
| `REDIS_USE_GCP_IAM` | Authenticate to GCP Memorystore with IAM instead of a password | `false` | No |
| `REDIS_SERVICE_ACCOUNT` | GCP service account for IAM auth | — | No |
| `GOOGLE_APPLICATION_CREDENTIALS` | Base64-encoded GCP service account credentials for IAM auth | — | When `REDIS_USE_GCP_IAM=true` |

## Message broker (RabbitMQ)

The internal asynchronous balance-operation pipeline uses RabbitMQ when `RABBITMQ_TRANSACTION_ASYNC=true`. RabbitMQ also carries selected legacy outbound exchanges.

| Variable | Description | Default | Required |
| - | - | - | - |
| `RABBITMQ_HOST` | Broker host | — | Yes |
| `RABBITMQ_PORT_HOST` | **AMQP port** used to dial the broker. Despite the name, this is the port the connection string uses (`3003` in the bundled infrastructure). | — | Yes |
| `RABBITMQ_PORT_AMQP` | **Management/HTTP port** reported on the health-check connection (`3004` in the bundled infrastructure). Despite the name, it is not used to dial AMQP. | — | No |
| `RABBITMQ_URI` | Connection scheme: `amqp` or `amqps`. Use `amqps` in production. | `amqp` | No |
| `RABBITMQ_DEFAULT_USER` | Publisher user | — | Yes |
| `RABBITMQ_DEFAULT_PASS` | Publisher password. Sensitive. | — | Yes |
| `RABBITMQ_CONSUMER_USER` | Consumer user | — | Yes |
| `RABBITMQ_CONSUMER_PASS` | Consumer password. Sensitive. | — | Yes |
| `RABBITMQ_VHOST` | Virtual host | `/` | No |
| `RABBITMQ_NUMBERS_OF_WORKERS` | Consumer concurrency | `5` | No |
| `RABBITMQ_NUMBERS_OF_PREFETCH` | Consumer prefetch count | `10` | No |
| `RABBITMQ_TRANSACTION_ASYNC` | Record transactions asynchronously through the broker | `false` | No |
| `RABBITMQ_OVERDRAFT_EVENTS_ENABLED` | Publish overdraft events. Any value other than `false`, including unset, enables publishing. Set `false` explicitly to disable. The bundled example configuration ships `false`. | enabled | No |
| `AUDIT_LOG_ENABLED` | Append transactions to an audit log exchange. Any value other than `false`, including unset, enables it. Set `false` explicitly to disable. The bundled example configuration ships `false`. | enabled | No |

## Throughput

| Variable | Description | Default | Required |
| - | - | - | - |
| `BULK_RECORDER_ENABLED` | Batch transaction writes for high-throughput ingestion. Takes effect only when `RABBITMQ_TRANSACTION_ASYNC=true`. | `true` | No |
| `BULK_RECORDER_SIZE` | Batch size trigger. When unset, Midaz derives it from `RABBITMQ_NUMBERS_OF_WORKERS` × `RABBITMQ_NUMBERS_OF_PREFETCH` (50 with the default worker and prefetch values). | workers × prefetch | No |
| `BULK_RECORDER_FLUSH_TIMEOUT_MS` | Flush interval for the batch recorder (milliseconds) | `100` | No |
| `BULK_RECORDER_MAX_ROWS_PER_INSERT` | Maximum rows per batch insert | `1000` | No |

## Tracer integration

The optional seam lets the ledger check a transaction with Tracer before it commits the transaction. Leave `TRACER_BASE_URL` unset to disable it.

| Variable | Description | Default | Required |
| - | - | - | - |
| `TRACER_BASE_URL` | Address of the Tracer gRPC seam, `host:4021` (the `TRACER_GRPC_PORT` of Tracer). Setting it enables the reservation client. | — | No |
| `TRACER_TIMEOUT_MS` | Reservation call deadline (milliseconds) | `250` | No |
| `TRACER_TLS_MODE` | Seam security: `mesh` (default, TLS terminated by the service mesh), `mtls`, or `server` | `mesh` | No |
| `TRACER_TLS_CERT_FILE` | Client certificate PEM path (when `mtls`) | — | If `mtls` |
| `TRACER_TLS_KEY_FILE` | Client private-key PEM path (when `mtls`). Sensitive. | — | If `mtls` |
| `TRACER_TLS_CA_FILE` | CA certificate PEM path (when `mtls` or `server`) | — | If `mtls` or `server` |
| `TRACER_M2M_CLIENT_ID` | Read with `PLUGIN_AUTH_ENABLED=true`. | — | Required when `TRACER_BASE_URL` is set and `PLUGIN_AUTH_ENABLED=true`. |
| `TRACER_M2M_CLIENT_SECRET` | Read with `PLUGIN_AUTH_ENABLED=true`. Sensitive. | — | Required when `TRACER_BASE_URL` is set and `PLUGIN_AUTH_ENABLED=true`. |
| `TRACER_M2M_WAIT_TIMEOUT_MS` | Read only with `PLUGIN_AUTH_ENABLED=true`. Accepts `1` to `5000` (milliseconds). | `3000` | No |
| `TRACER_API_KEY` | Read with `PLUGIN_AUTH_ENABLED=false`. When `TRACER_BASE_URL` is set, the ledger does not start if you also set `PLUGIN_AUTH_ENABLED=true`. Tracer accepts it only with `API_KEY_ENABLED=true` and `PLUGIN_AUTH_ENABLED=false`. Sensitive. | — | No |

## CRM and Fees

The ledger process reads these variables, because CRM and Fees are compiled into the ledger binary. They protect account-holder PII and configure the field-encryption backend.

| Variable | Description | Default | Required |
| - | - | - | - |
| `LCRYPTO_HASH_SECRET_KEY` | 64-hex hashing key for holder PII. Sensitive. Generate a unique value per environment. | — | Yes (CRM) |
| `LCRYPTO_ENCRYPT_SECRET_KEY` | 64-hex encryption key for holder PII. Sensitive. | — | Yes (CRM) |
| `KMS_VENDOR` | Field-encryption backend: `none` or `hashicorp-vault` | `none` | No |
| `KMS_VAULT_ADDR` | Vault address (when `hashicorp-vault`) | — | No |
| `KMS_VAULT_AUTH_METHOD` | Vault auth method: `token` or `approle`. Use `token` only in `local`; use `approle` in `byoc`/`saas`. | — | When `KMS_VENDOR=hashicorp-vault` |
| `KMS_VAULT_ROLE_ID` | Vault AppRole role ID (when `approle`) | — | No |
| `KMS_VAULT_SECRET_ID` | Vault AppRole secret ID (when `approle`). Sensitive. | — | No |

## Configuration shared across Lerian products

The following blocks are identical across Lerian products. The [BYOC configuration reference](/en/reference/byoc-configuration) documents them in full. They default off. A BYOC deployment can ignore all the optional ones.

* **Access Manager authentication**: `PLUGIN_AUTH_ENABLED`, `PLUGIN_AUTH_HOST`. Enable in production.
* **Service discovery**: `SD_*` (Consul). Off by default.
* **Event streaming**: `STREAMING_*`. Off by default on the ledger.
* **OpenTelemetry**: `ENABLE_TELEMETRY`, `OTEL_*`. Telemetry is OTLP push.


# Installing Midaz
Source: https://docs.lerian.studio/en/products/midaz/midaz-setup

Install Midaz locally with Docker Compose in a few commands: the full environment, ready for local development.

You run and test Midaz locally. Install it with **Docker Compose**, which sets up the full environment.

## System requirements

***

| Requirement | Minimum |
| - | - |
| **Operating System** | - **Windows**: Windows 10 **via WSL** version 2004 or later (Build 19041+)  - **macOS**: Current or previous two versions  - **Linux**: Ubuntu or Debian recommended |
| **RAM** | 8 GB |
| **Disk Space** | 20 GB |
| **Internet** | Stable connection |
| **Browser** | Chrome, Firefox, or equivalent |

## Tools you’ll need

***

* [Docker Desktop](https://docs.docker.com/get-docker/)
* [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
* Package Manager:
  * macOS: [Homebrew](https://brew.sh/)
  * Linux: Use your system’s package manager (e.g., `apt`, `dnf`)

## On Windows? Install WSL

***

On Windows, you must install WSL (Windows Subsystem for Linux) to run Midaz.

**Step 1**

Open PowerShell as an administrator.

**Step 2**

Run:

```bash Text theme={null}
wsl --install
```

**Step 3**

Restart your machine if needed.

**Step 4**

Once installed, open the Ubuntu app from the Start Menu to continue the setup.

## Install Midaz

***

### Step 1 – Open your terminal

* **macOS/Linux:** Use your Terminal app.
* **Windows:** Open Ubuntu via WSL.

> [!CAUTION]
>
> On Windows, **run all commands inside Ubuntu (WSL)**. New to terminals? See [this beginner guide](https://www.codecademy.com/learn/learn-the-command-line).

### Step 2 – Install `make`

* **Linux:**

  ```bash Text theme={null}
  sudo apt install make
  ```
* **macOS:**

  ```bash Text theme={null}
  brew install make
  ```

### Step 3 – Download the Midaz repo

**1. Choose your working directory**

```bash Text theme={null}
cd ~/Desktop
```

**2. Clone the repo**

```bash Text theme={null}
git clone https://github.com/LerianStudio/midaz.git
```

**3. Enter the folder**

```bash Bash theme={null}
cd midaz
```

### Step 4 – Set up environment variables

Start Docker before this step. `make set-env` copies the `.env` files and generates the `LCRYPTO_*` CRM keys through a Docker one-shot container. The command fails if Docker is unavailable.

```bash Bash theme={null}
make set-env
```

### Step 5 – Start the services

Make sure Docker is up, then:

```bash Bash theme={null}
make up
```

All bundled services start.

### Step 6 – Access your environment

* Ledger API: [http://localhost:3002](http://localhost:3002/)
* Tracer API: [http://localhost:4020](http://localhost:4020/)

> [!CAUTION]
>
> Make sure Docker is up and all `.env` files are set before you access the API.

## Try the API

***

> [!TIP]
>
> Start with our [Quick Start Guide](/en/reference/products/midaz/quick-start-guide).

## Authentication

***

By default, Midaz does not require authentication. This makes local testing easier.

If you need authentication, use the [Access Manager](/en/platform/access-manager) plugin, available for enterprise institutions.

> [!CAUTION]
>
> Run Midaz without authentication only in a secured, private environment.

## Community and contribution

***

* Join us on [Discord](https://discord.com/invite/DnhqKwkGv3).
* Report issues on [GitHub](https://github.com/LerianStudio/midaz).
* Follow [@LerianStudio](https://twitter.com/LerianStudio) on Twitter.

To contribute, start with our [Contributing Guide](https://github.com/LerianStudio/midaz/blob/main/CONTRIBUTING.md).

> [!TIP]
>
> [Talk to our team](https://lerian.studio/contact) for hands-on support.

## License

***

Midaz is proprietary to Lerian Studio Ltd. Versions released under the Elastic License 2.0 keep that license.


# Midaz Terraform Foundation
Source: https://docs.lerian.studio/en/products/midaz/midaz-terraform-foundation

Provision the base infrastructure for Midaz on AWS, GCP, or Azure with Terraform templates: network, Kubernetes cluster, and datastores.

The [Lerian Terraform Foundation](https://github.com/LerianStudio/lerian-terraform-foundation) repository holds Terraform templates for the infrastructure that Midaz runs on: the network, the Kubernetes cluster, and the datastores. It supports AWS, GCP, and Azure. The repository uses the [Apache License 2.0](https://github.com/LerianStudio/lerian-terraform-foundation/blob/main/LICENSE).

## What the templates create

***

| Cloud | Network and cluster | Datastores for Midaz |
| - | - | - |
| AWS | VPC with public and private subnets, Amazon EKS | PostgreSQL (Amazon RDS), Amazon DocumentDB, Valkey (Amazon ElastiCache), RabbitMQ (Amazon MQ) |
| GCP | VPC, Cloud DNS, GKE | PostgreSQL (Cloud SQL), Valkey (Memorystore) |
| Azure | Virtual network, DNS, AKS | PostgreSQL (Azure Database for PostgreSQL flexible server), Azure Cache for Redis, Cosmos DB with the MongoDB API |

> [!CAUTION]
>
> On GCP, the templates create no MongoDB-compatible database and no RabbitMQ broker. On Azure, they create no RabbitMQ broker. Provision these services yourself on those clouds.

Treat the instance classes in the example files as a starting point, not as a capacity plan. Before a production deployment, review the instance classes, storage, and connection limits against your transaction volume. Then read the important information section of the repository README.

## AWS

***

On AWS, a command-line tool runs the templates. It runs each stack in order and makes sure that the live credentials match the AWS account of the environment. To install the tool and run it, follow the AWS section of the [repository README](https://github.com/LerianStudio/lerian-terraform-foundation#aws).

You need Terraform 1.10.0 or later, the `aws` CLI, and `git`.

The deployment of one environment runs these stacks in this order:

1. `bootstrap`: the state bucket and the lock table. Run it once per environment.
2. `infra-base`: the VPC, then the EKS cluster.
3. `midaz`: the Midaz datastores.

After the `midaz` stack, a separate run of the tool with `--action helm-values` writes a Helm values file from the stack outputs. The file contains no passwords. It references the secrets that the templates store in AWS Secrets Manager.

> [!NOTE]
>
> Amazon MQ accepts AMQPS connections only. If you write the values yourself, set `RABBITMQ_URI` to `amqps`.

## GCP and Azure

***

On GCP and Azure, an interactive script runs the templates. Each component directory has its own `backend.tf` and `midaz.tfvars` files. You need Terraform and the CLI of your cloud provider: `gcloud` for GCP or `az` for Azure.

**1. Create the state bucket**

GCP:

```
gsutil mb -p PROJECT_ID -l REGION gs://BUCKET_NAME
gsutil versioning set on gs://BUCKET_NAME
```

Azure:

```
az group create --name RESOURCE_GROUP --location LOCATION
az storage account create --name STORAGE_ACCOUNT --resource-group RESOURCE_GROUP \
  --location LOCATION --sku Standard_LRS
az storage container create --name CONTAINER --account-name STORAGE_ACCOUNT
```

**2. Configure each component**

```
cd examples/<provider>/<component>
cp midaz.tfvars-example midaz.tfvars
```

Replace the placeholders in `backend.tf` with your state bucket details. Then replace the placeholders in `midaz.tfvars` with your values.

**3. Run the script**

From the repository root, run:

```
./deploy-legacy.sh
```

Select the cloud provider and the action: deploy or destroy.

The script stops before it runs Terraform if a `backend.tf` file still contains a placeholder. It deploys every component in a fixed order and stops at the first failure. A destroy runs in the reverse order.

| Order | Component | GCP directory | Azure directory |
| - | - | - | - |
| 1 | Network | `vpc` | `network` |
| 2 | DNS | `cloud-dns` | `dns` |
| 3 | PostgreSQL | `cloud-sql` | `database` |
| 4 | Valkey or Redis | `valkey` | `redis` |
| 5 | MongoDB | — | `cosmosdb` |
| 6 | Kubernetes | `gke` | `aks` |

## Authenticate to your cloud provider

***

Use the authentication tools of your cloud provider CLI instead of raw credentials:

```
aws sso login --profile your-profile
gcloud auth application-default login
az login
```

Follow the guidance of your cloud provider:

* **AWS**: [Managing AWS access keys](https://docs.aws.amazon.com/general/latest/gr/aws-access-keys-best-practices.html).
* **GCP**: [Managing service account keys](https://cloud.google.com/iam/docs/best-practices-for-managing-service-account-keys).
* **Azure**: [Identity management best practices](https://learn.microsoft.com/en-us/azure/security/fundamentals/identity-management-best-practices).

Do not commit credentials to version control.

## Install Midaz

***

After the infrastructure is ready, install Midaz on the cluster with Helm. On AWS, use the values file that the tool writes. On GCP and Azure, read the endpoints with `terraform output` and set them in your values file. For the chart and its values, see [Deploying using Helm](https://github.com/LerianStudio/helm/tree/main/charts/midaz).

## Security tips

***

To keep your Midaz infrastructure secure, follow these recommendations:

* Use **private Kubernetes clusters** to limit public exposure. The templates do not create a VPN.
* Set up and **enforce RBAC** (Role-Based Access Control) to manage user permissions.
* Store all secrets in the cloud provider’s **secret management service**.
* Give service accounts only the **permissions they need**.

## Need help?

***

* Read the README inside the directory that you deploy.
* Search the existing [issues](https://github.com/LerianStudio/lerian-terraform-foundation/issues), or open a new issue.


# Midaz and plugin compatibility
Source: https://docs.lerian.studio/en/products/midaz/midaz-version-compatibility

Which capabilities the unified Ledger serves as modules, and which ones run as separate plugins.

## Midaz application v4

***

| Capability | Runs as | API surface |
| :- | :- | :- |
| CRM | Unified Ledger module | `/v2` only |
| Fees | Unified Ledger module | `/v2` only |
| Pix and Bank Transfer | Separate plugins | See each plugin's API guide |

In Midaz application v4, the unified Ledger contains CRM and Fees as modules. Use their `/v2` API through the Ledger. They are not separate services, ports, or plugins. The `/v1` compatibility surface does not run Fees or Tracer.

Before Midaz v4, Fees ran as its own service. Its earlier releases do not define Midaz v4 compatibility.

## Upgrade order

***

Upgrade Midaz before you upgrade its plugins. Plugins call the Midaz APIs, so a plugin that is newer than Midaz can call an API that Midaz does not serve yet.

To install or upgrade Midaz, see the [Midaz chart README](https://github.com/LerianStudio/helm/tree/main/charts/midaz).


# Observability
Source: https://docs.lerian.studio/en/products/midaz/observability-in-midaz

Monitor Midaz metrics, logs, and traces with OpenTelemetry, Client Collectors, and Lerian's managed Prometheus, Loki, Tempo, and Grafana observability stack.

Observability in Midaz lets you monitor metrics, logs, and traces across your deployed environments.

Midaz collects telemetry with the OpenTelemetry framework. A **Client Collector** in your infrastructure processes it. The collector then routes it securely to Lerian's managed stack: Prometheus, Loki, Tempo, and Grafana.

## How it works

***

Midaz uses a **dual observability model**:

* **Client side**: for local development, the collector configuration lives in `components/infra/grafana/otelcol-config.yaml`, mounted read-only into the bundled all-in-one Grafana/OTel container. It sets the collector's receivers, processors, and exporters. The local configuration ships with `ENABLE_TELEMETRY=false`. Set it to `true` to send telemetry to the collector. For production and BYOC, install the Alloy Lerian collection agent instead; see the [Alloy Lerian chart README](https://github.com/LerianStudio/helm/tree/main/charts/alloy-lerian).
* **Lerian side**: Lerian operates the managed collector and storage stack.

> [!NOTE]
>
> The bundled collector config masks known sensitive keys (credentials, tokens, `legalDocument`, `accountAlias`) in log bodies and in the `app.request.payload` span attribute. Masking happens in the collector, so it applies after telemetry leaves the application process. The bundled local-development exporters run with TLS disabled (`insecure: true`). Enable TLS on the collector exporters for any non-local deployment.

## Grafana, OpenTelemetry, and tenant isolation

***

* Unified view of metrics, logs, and traces in Grafana
* Built on OpenTelemetry standards
* Grafana preconfigured and operated by Lerian
* Secure routing and tenant isolation

> [!TIP]
>
> See [**Infra Tools → Observability**](/en/platform/observability) for advanced setup, collector configuration, and processor customization.


# Security
Source: https://docs.lerian.studio/en/products/midaz/security

See how Midaz protects financial operations with security by design, STRIDE threat modeling, OWASP-aligned controls, and a clear shared responsibility model.

Midaz builds in protections for data integrity, access control, and tenant isolation. It uses strong identity management, fine-grained permissions, and industry-standard practices.

This page describes the security architecture Midaz provides by default. It also shows how you run secure and compliant operations.

## Architecture

***

Midaz applied security by design and threat modeling from the start. It still applies both to every new feature.

* **Security by design**: Midaz embeds security controls across the lifecycle, from design to deployment. It follows OWASP guidelines such as the OWASP Top 10 and the OWASP Application Security Verification Standard (ASVS).
* **Threat Modeling**: A structured process identifies, assesses, and reduces security risks before an attacker exploits them. Midaz uses the STRIDE methodology. STRIDE groups threats into six types:
  * **S**poofing (e.g., fake authentication in a banking API).
  * **T**ampering (e.g., altering transaction data mid-request).
  * **R**epudiation (e.g., lack of audit logs for transactions).
  * **I**nformation Disclosure (e.g., leaking sensitive data via API responses).
  * **D**enial of Service (e.g., overwhelming the API with fake requests).
  * **E**levation of Privilege (e.g., exploiting a bug to gain admin access).

## Shared responsibility model

***

Security is a shared responsibility between Lerian and the customer. The exact split depends on your [deployment model](/en/start-here/evaluate-and-deploy/deployment-models).

| Lerian | Customer |
| - | - |
| Application Development | Infrastructure |
| Application Security Updates | Network |
| | Database |
| | Identity & Access Management |
| | Encryption |
| | User Data |
| | Monitoring |
| | Additional Security Layers |

### In the BYOC model

In BYOC (Bring Your Own Cloud), you deploy Lerian in your own infrastructure. Lerian secures the application layer. You secure the environment.

**What Lerian secures:**

* Secure-by-design services.
* Proactive vulnerability fixes.
* Security updates: dependency upgrades, security patches, and improvements.

**What the customer secures:**

* **Infrastructure**: Harden the OS and container images, manage patches, and apply secure configurations on the hosting platform.
* **Network**: Implement segmentation, firewalls, and IDS/IPS systems. Adopt Zero Trust principles to protect internal and external communication.
* **Database**: Set up backups and audit logging. Follow security best practices for data storage.
* **Identity & Access Management**: Control access to the environment. Use Access Manager to enforce least-privilege policies within the platform.
* **Encryption**: Encrypt sensitive data at rest and in transit. Consider tokenization or anonymization where appropriate.
* **User Data**: All user data that Midaz stores or processes stays under your control and responsibility.
* **Monitoring**: Establish monitoring tools that detect unusual access patterns or suspicious behavior.
* **Additional Security Layers**: Reinforce defenses with Web Application Firewalls (WAF), anti-DDoS mechanisms, and bot mitigation tools.

### In the SaaS model

In SaaS, Lerian manages the full infrastructure. Lerian takes on more of the security responsibility.

**What Lerian secures:**

* Everything in the BYOC application layer, plus:
* Cloud infrastructure, networking, and compute environment.
* Database provisioning, encryption at rest, and automated backups.
* OS and container patching.
* Monitoring, alerting, and incident response.
* High availability and disaster recovery.

**What the customer secures:**

* **Business-level access control**: Manage users, roles, and permissions within the platform.
* **API integration security**: Secure the communication between your systems and the Lerian APIs.
* **User Data governance**: Define and enforce data-handling policies that meet your regulatory obligations.
* **Compliance**: Make sure your use of the platform aligns with your institution's regulatory requirements.

> [!TIP]
>
> For step-by-step guidance, see [Security Recommendations](/en/products/midaz/security-recommendations).

## Identity and Access Management

***

With authentication on, Midaz forwards each request's bearer token, together with the product, resource and action, to the configured authorization service. Midaz serves the request only when that service answers that the caller is authorized. Access Manager provides this service.

Authentication is on when you set `PLUGIN_AUTH_ENABLED=true`, and Midaz refuses to start without it when you set `ENV_NAME=production`. Midaz takes the authorization service address from `PLUGIN_AUTH_HOST` or from service discovery, and protected requests fail when no authorization service is reachable.

### Option 1: External IAM

An authorization service of your own must answer the same authorization request that Access Manager answers.

### Option 2: Access Manager Plugin

The [Access Manager Plugin](/en/platform/access-manager) manages authentication and authorization for Midaz. It provides:

* User lifecycle management
* Session token handling
* Refresh token rotation
* Application registration and management

## Tenant isolation on Lerian Cloud

***

On Lerian Cloud, Midaz isolates all resources by tenant at the application layer. This covers organizations, ledgers, accounts, and transactions.

Your JWT access token carries the tenant context. On every request, the platform middleware resolves the tenant from the `tenantId` claim in the token. Your API calls never see data from other tenants. Other tenants never see your data.

This isolation works independently of the organization hierarchy. Two tenants can create similar organization structures, and their data stays completely separate.

### Credential isolation

Each tenant has its own credentials. Midaz never shares them between tenants. One tenant can never authenticate into another tenant's data.

Lerian generates and manages these credentials. They never sit in configuration files or environment variables.

### Per-tenant resource limits

Lerian Cloud enforces resource limits so that no single tenant degrades others. This is the **noisy neighbor** problem:

* **Kubernetes resource limits**: CPU and memory limits on each workload cap how much compute it can consume. This bounds the impact of a spike or a runaway workload.
* **PostgreSQL statement timeout**: Midaz does not set one itself. Configure `statement_timeout` on your PostgreSQL roles or databases so no single query can hold resources indefinitely.
* **Connection pool per service**: each service keeps its own connection pool, with one pool per active tenant. This bounds connection capacity per tenant. One tenant cannot exhaust the database connections that others need.

> [!NOTE]
>
> These limits complement the data isolation above. Data isolation protects each tenant's *data* from other tenants. Resource limits protect each tenant's *performance and availability* from other tenants' load.

## Data protection

***

Midaz enforces double-entry principles by design. Every transaction must have balanced debits and credits. Midaz rejects any entry that fails this validation. This protects ledger integrity. It also protects the system against posting discrepancies.

### Built-in safeguards

Midaz applies strict validation across all transaction flows to keep data consistent and prevent logic errors:

* Midaz refuses a transaction that would take an internal account's available balance below zero. When overdraft is enabled on the balance, Midaz records the shortfall as overdraft usage, within the overdraft limit when one is set. External accounts have no floor.
* Midaz verifies account status before any operation.
* Midaz requires a registered, valid asset before it posts an entry.

### Compliance with LGPD and GDPR

Midaz encrypts the personal data fields of CRM holders and instruments before it stores them. Other data, such as metadata and descriptions, is stored as sent.

Midaz handles transaction validation. You protect personally identifiable information (PII). To stay compliant with LGPD, GDPR, and similar data protection laws, we recommend that you:

* Apply encryption to sensitive data, at rest and in transit.
* Use tokenization or anonymization when appropriate.
* Store and manage customer data under clearly defined security policies.

## Responsible disclosure policy

***

If you find a security vulnerability in Midaz, report it directly to our team before you make it public. We support responsible disclosure. We investigate and resolve issues quickly and thoroughly.

> [!CAUTION]
>
> Do not disclose any findings publicly until we review and address them.

The steps to report a vulnerability:

**1. Report**

Open a GitHub Security Advisory on the [Midaz repository](https://github.com/LerianStudio/midaz/security), or email us at [security@lerian.studio](mailto:security@lerian.studio).

**2. Acknowledgment**

We respond within 24 hours.

**3. Verification**

Our team validates the report.

**4. Impact Assessment**

We determine the severity and impact.

**5. Resolution**

We fix the issue and notify the reporter.

**6. Public Disclosure**

We coordinate disclosure with the researcher.


# Security recommendations
Source: https://docs.lerian.studio/en/products/midaz/security-recommendations

Apply Lerian's shared responsibility security model: infrastructure hardening, network segmentation, TLS, and Zero Trust patterns.

Read this guide before you install and deploy Midaz.

At Lerian, we work under a **Security Shared Responsibility Model**. We secure the application layer: Midaz and all Lerian plugins. In BYOC, you secure the infrastructure where they run. This guide helps your team build and keep a strong security posture across the Lerian ecosystem, from Midaz to every integrated plugin.

These recommendations are not exhaustive. They complement your existing security practices, whether you run in the cloud or on-prem.

## Infrastructure & network security

***

Midaz and all Lerian plugins are cloud-native. They run in containerized, distributed environments. To strengthen your infrastructure and network security:

* Establish a patch management process that updates the OS and services with security patches on a regular schedule.
* Apply hardening procedures to your operating system images before deployment.
* Use the Midaz and plugin Docker images, which follow the least privilege principle. Reinforce this at the cluster level with the right controls.
* For Kubernetes, enforce security baselines with policy-as-code tools such as Kyverno or OPA Gatekeeper.
* Run routine vulnerability scans across all layers of your infrastructure, including the layers that host plugins.
* Use network segmentation to restrict access to Midaz components and plugins to only the systems that need it.
* Configure firewalls to manage traffic flow and prevent unauthorized access.
* Where possible, implement Intrusion Detection Systems (IDS) and Intrusion Prevention Systems (IPS) to analyze network behavior and block anomalies.
* Adopt a Zero Trust Architecture for sensitive systems and data flows.
* Enforce TLS 1.2 or higher for all communication across Midaz and plugin services.

## General security configurations

***

You must protect secrets, storage, and data across all Lerian components, including Midaz and its plugins. Follow these practices:

* Use trusted solutions such as AWS Secrets Manager, Azure Key Vault, Google Secret Manager, or HashiCorp Vault to store secrets and configuration data securely.
* Rotate credentials and secrets on a regular schedule. Follow the principle of least privilege when you grant access.
* Enable audit logging. Configure automated backups for all databases that Midaz and plugins use.
* Apply encryption at rest to all persistent data, including the data that plugins such as Access Manager process.
* Enforce access restrictions on sensitive data. Use tokenization, encryption, or anonymization where appropriate.
* Update Midaz and all Lerian plugins to the latest releases, including patches and security improvements.

## Identity & Access Management (IAM)

***

Apply a unified IAM approach across two layers: the environment where you deploy Midaz and plugins, and the services themselves. Follow these practices:

* Implement a centralized IAM process to manage access to the infrastructure that hosts Lerian products.
* Enforce multi-factor authentication (MFA) across all user and admin accounts.
* Monitor and audit access to service accounts on a regular schedule, especially the accounts that plugins use.
* Define access control models that follow the least privilege principle with RBAC, ABAC, or custom strategies.
* Use temporary credentials and time-limited access for high-sensitivity operations.
* Review all access privileges on a regular schedule, including access to Midaz, Access Manager, Reporter, and other products.

## Monitoring & incident response

***

To build observability and incident readiness into how you deploy Midaz and plugins:

* Deploy security monitoring tools to track behavior across all Lerian services, including plugin activity.
* Enable logs and traces across your infrastructure and each component of Midaz and its plugins.
* Integrate logs from Midaz and plugin services with fraud detection or anomaly monitoring tools.
* Centralize logs in a SIEM platform for more efficient threat detection.
* Maintain an updated incident response plan, with specific playbooks for services such as Access Manager.

## Additional protection layers

***

For production-critical or high-compliance environments, add these protective layers:

* Apply OS and service hardening procedures across your entire stack.
* Maintain regular patch cycles for all runtime environments, including third-party services and dependencies.
* Conduct manual penetration tests to validate your defenses, including the defenses around plugins and integrations.
* Deploy Web Application Firewalls (WAFs) to protect plugin APIs and Midaz endpoints from Layer 7 attacks.
* Use Anti-DDoS services and bot mitigation tools to block automated or mass-scale attacks on exposed components.

> [!TIP]
>
> Combine infrastructure-level protections with the built-in security validations of Midaz and its plugins.

## Midaz security configurations

***

Review and adjust all credentials and certificates before you go live, whether you run Midaz locally or deploy it in a managed cluster.

### Credentials and secrets

Midaz runs as a consolidated ledger service. For local development, its environment template is `components/ledger/.env.example`. In a deployment, provide the production configuration through your orchestrator, and keep the secrets in your secret vault.

> [!CAUTION]
>
> Never deploy Midaz with default credentials. Update all secret values in your environment before you launch.

Keep database credentials, encryption keys, and API tokens out of the repository. Keep them in your secret vault and inject them at deployment time.

Store secrets such as database credentials, encryption keys, and API tokens securely. Rotate them on a regular schedule, except `LCRYPTO_HASH_SECRET_KEY` and `LCRYPTO_ENCRYPT_SECRET_KEY`. Midaz cannot read the holder and instrument data it encrypted with the previous values.

### TLS Certificate configuration

When you expose Midaz services through ingress controllers, use valid TLS certificates. A certificate configured on ingress protects external-client traffic only as far as the ingress TLS termination point. It does not encrypt a plaintext ingress-to-service hop. Configure upstream TLS or mTLS when you must also protect that internal hop.

Use a certificate from a trusted provider, and keep the full certificate chain in your secret vault. To set the certificate on a Midaz deployment, see the [Midaz chart README](https://github.com/LerianStudio/helm/tree/main/charts/midaz).

> [!TIP]
>
> Always enforce TLS 1.2 or higher. For internal clusters, issue short-lived certificates automatically with a service mesh or cert manager.


# Updating Midaz
Source: https://docs.lerian.studio/en/products/midaz/updating-midaz

Update your local Midaz environment, and find the upgrade procedure for a deployed environment.

Keeping Midaz up to date means you work with the latest features, security patches, and improvements. Regular updates also keep Midaz compatible with other components and help prevent issues caused by outdated dependencies.

Below are the steps to update Midaz in your local environment. For a deployed environment, see [Updating a deployment](#updating-a-deployment).

> [!NOTE]
>
> Dedicated migration-runner images (`midaz-ledger-migrations`, `midaz-tracer-migrations`) apply the schema migrations. The apps do not migrate at startup. Local `make up` and the official Helm chart run these images for you. See [Database migrations](/en/products/midaz/database-migrations) for details.

## Updating Midaz locally

***

If you're running Midaz locally for development or testing, follow these steps to update your environment:

### 1. Stop the running containers

Shut down all running services before making updates. This ensures a clean restart with the latest updates.

To stop the containers via the terminal, follow these steps:

**Step 1**

Open your terminal and navigate to the `midaz` directory.

**Step 2**

Run the stop command:

```Shell Shell theme={null}
make down
```

### 2. (Optional) Clean up unused Docker resources

Cleaning up unused resources frees disk space, removes stale Docker cache layers, and prevents conflicts from outdated images, containers, and volumes.

To remove unused images and containers of every project on your machine:

```Shell Shell theme={null}
docker system prune --all
```

To remove unused Docker volumes of every project on your machine:

```Shell Shell theme={null}
docker volume prune
```

### 3. Update your local codebase

Fetch the latest changes from the repository to ensure you're working with the most recent version:

```Shell Shell theme={null}
git pull origin main
```

### 4. Rebuild and restart Midaz

Rebuild necessary Docker images and relaunch the application locally with the latest updates:

```Shell Shell theme={null}
make rebuild-up
```

## Updating a deployment

***

To install, upgrade, or uninstall a Midaz deployment, see the [Midaz chart README](https://github.com/LerianStudio/helm/tree/main/charts/midaz). It carries the procedure and the upgrade notes of each chart version.

Before you upgrade, check these product rules:

* In production, the Ledger does not start without authentication. See [Security](/en/products/midaz/security).
* Keep `LCRYPTO_HASH_SECRET_KEY` and `LCRYPTO_ENCRYPT_SECRET_KEY` unchanged. Midaz cannot read the holder and instrument data that it encrypted with previous values.
* Upgrade Midaz before its plugins. See [Midaz and plugin compatibility](/en/products/midaz/midaz-version-compatibility).
* To upgrade to v4.2.0 or later, upgrade Tracer before the Ledger. While a Ledger on v4.2.0 or later runs, do not roll Tracer back to a version earlier than v4.2.0.
* From v4.2.0, the Ledger reaches Tracer over gRPC only. When `TRACER_BASE_URL` is set, the Ledger does not start with `TRACER_TRANSPORT=rest`. If you set `TRACER_TRANSPORT=rest`, remove `TRACER_TRANSPORT` before you upgrade. Then set `TRACER_BASE_URL` to the Tracer gRPC address (`TRACER_GRPC_PORT`, `:4021` by default). See [Midaz environment variables](/en/products/midaz/midaz-environment-variables).
* Run v4.2.0 or later on every Ledger instance before you set `deferrable` on a fee. After you set it, do not roll the Ledger back to an earlier version. See [Fee debt](/en/products/midaz/fees/fee-debt).


# Midaz in Lerian Console
Source: https://docs.lerian.studio/en/products/midaz/using-midaz-in-lerian-console

Manage Midaz visually inside the Lerian Console: Organizations, Ledgers, Accounts, Transactions, and plugins from a single web interface.

Midaz is a product module in the [Lerian Console](/en/platform/console/about-lerian-console), the web interface for all Lerian products.

Through the Console, you manage your full ledger infrastructure, from organizations and assets to transactions and plugins.

> **[Midaz in Lerian Console](/en/products/midaz/console/midaz-module)**
>
> Access the full documentation for using Midaz in the Lerian Console.

## Available actions

***

From the Lerian Console, you can:

* **Foundation**: Manage [organizations](/en/products/midaz/console/managing-organizations), [ledgers](/en/products/midaz/console/managing-ledgers-via-console), [assets](/en/products/midaz/console/managing-assets), and [account types](/en/products/midaz/console/managing-account-types)
* **Accounting**: Configure [routes](/en/products/midaz/console/managing-accounting-routes)
* **Accounts**: Manage [accounts](/en/products/midaz/console/managing-accounts), [holders](/en/products/midaz/console/managing-crm-holders), [aliases](/en/products/midaz/console/managing-crm-alias-accounts), [segments](/en/products/midaz/console/managing-segments), and [portfolios](/en/products/midaz/console/managing-portfolios)
* **Transactions**: [View and create transactions](/en/products/midaz/console/managing-transactions)
* **Fees**: Manage [fee packages](/en/products/midaz/fees/using-fee-engine-with-midaz-console)


# Contexts and sources
Source: https://docs.lerian.studio/en/products/matcher/configuration/matcher-contexts-and-sources

Set up a reconciliation context and its sources in Matcher. Pick 1:1, 1:N, or N:M cardinality, add bank and ledger feeds, and trigger match runs.

Contexts and sources are how you tell Matcher what to reconcile and where the numbers come from. You set up these two building blocks before any matching happens.

* A **context** is a single reconciliation you care about. For example, *"our main bank account vs. our books."* It sets the scope: which systems to compare and which rules apply.
* A **source** is one of the systems feeding numbers into that comparison: a bank statement, an ERP export, a payment processor's settlement file, or a ledger.

Every context compares exactly two sides against each other, so each one needs at least two sources. Matching, exceptions, and reporting all depend on these two.

## What is a reconciliation context?

***

A reconciliation context defines the operational boundaries of a reconciliation process.
It specifies:

* Which data sources to compare
* Which matching rules apply
* How to handle exceptions

**Common examples:**

* *Bank Account 1234 vs General Ledger* (daily bank reconciliation)
* *Payment Gateway vs Revenue System* (payment reconciliation)
* *Intercompany Entity A vs Entity B* (intercompany reconciliation)

## Context types

***

Matcher lets you use different reconciliation cardinalities based on transaction structure.

### One-to-one (1:1)

Matcher reconciles each transaction against a single counterpart.

**Typical use cases:**

* Bank statements
* Direct payment matching

### One-to-many (1:N)

Matcher reconciles one transaction against multiple counterparts.

**Typical use cases:**

* Split payments
* Batch deposits
* Consolidated invoices

### Many-to-many (N:M)

Matcher reconciles multiple transactions across multiple counterparts.

**Typical use cases:**

* Netting arrangements
* Complex payment allocation
* Multi-leg financial flows

## Creating a reconciliation context

***

Once you know what you're reconciling, create the context. At this stage you're mainly declaring the cardinality (`type`), a required execution label (`interval`), and any fee tolerance the comparison should allow. The `interval` value does not schedule runs. Automatic execution requires a separate [reconciliation schedule](/en/products/matcher/configuration/matcher-schedules).

#### Request

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Daily Bank Reconciliation",
   "interval": "daily",
   "type": "1:1",
   "feeToleranceAbs": "0",
   "feeTolerancePct": "0",
   "feeNormalization": "NET",
   "autoMatchOnUpload": false
 }'
```

#### Context fields

**name** `string`

Descriptive name for the context

**type** `string`

Matching cardinality: `1:1`, `1:N`, or `N:M`

**interval** `string`

Required execution label (e.g. `daily`, `weekly`). It does not schedule runs.

**feeToleranceAbs** `string` (default: 0)

Absolute tolerance when Matcher compares an actual fee with the expected fee, as a decimal string (e.g. `"0.01"`)

**feeTolerancePct** `string` (default: 0)

Relative tolerance for the same fee comparison, as a fraction in a decimal string (`"0.02"` tolerates 2%)

**feeNormalization** `string`

Optional fee normalization mode: `NET` or `GROSS`. Omit it to leave fee normalization disabled.

**autoMatchOnUpload** `boolean` (default: false)

Automatically trigger a match run after a file upload

**signConvention** `string` (default: SAME)

How the context's data carries sign: `SAME` or `OPPOSITE`. With `SAME`, a payment carries the same sign as what it settles, and a negative amount is a reversal. With `OPPOSITE`, a payment carries the opposite sign of the invoice it settles. After the context carries a partial balance, Matcher refuses a change with `409`. It also refuses a change while a match run is in progress.

**agedBreakThresholdDays** `integer`

Optional aging limit for open items, in days (1 or more). In a `COMMIT` run, an open-item balance older than this limit raises an `AGED_BREAK` exception. Omit it to disable aging. On update, `0` disables it.

**agedBreakCalendar** `string`

Optional business-day calendar for `agedBreakThresholdDays`: `US_FED` or `BR_ANBIMA`. Omit it to count calendar days.

#### Response

```json theme={null}
{
  "id":"019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f",
  "tenantId":"11111111-1111-1111-1111-111111111111",
  "name":"Daily Bank Reconciliation",
  "type":"1:1",
  "interval":"daily",
  "status":"DRAFT",
  "feeToleranceAbs":"0",
  "feeTolerancePct":"0",
  "feeNormalization":"NET",
  "autoMatchOnUpload":false,
  "signConvention":"SAME",
  "createdAt":"2026-02-02T16:31:22Z",
  "updatedAt":"2026-02-02T16:31:22Z"
}
```

> [!TIP]
>
> API Reference: [Create context](/en/reference/products/matcher/create-context)

## Running reconciliation

***

A context does not reconcile on its own. You trigger a **match run**. A run applies the context's rules to the transactions in its sources, then produces matches and exceptions. You can trigger runs by hand, or let a [schedule](/en/products/matcher/configuration/matcher-schedules) fire them automatically.

Every run works in one of two modes:

| Mode | What it does |
| - | - |
| `DRY_RUN` | Does not persist matching results, transaction mutations, fee artifacts, or exceptions, but does persist a completed `MatchRun` and its statistics |
| `COMMIT` | Executes matching and persists the results |

Trigger a run for a context:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mode": "COMMIT"
 }'
```

By default a run is **synchronous**: it executes in-request and the response carries the final status. For large volumes, set `"async": true` to submit the run and poll its progress instead. When asynchronous submission is unavailable, Matcher rejects `"async": true` with HTTP 503.

> [!NOTE]
>
> Both modes return **HTTP 202 Accepted** on success, so read the response `status` to tell them apart.
>
> A synchronous run returns `COMPLETED`. When it fails, the request returns a problem response instead. An async run returns `QUEUED`, and you poll `GET /v1/matching/runs/{runId}`.
>
> While in flight, a run moves through `PROCESSING` and `FINALIZING` (treat both as not-yet-done) before reaching `COMPLETED` or `FAILED`.

To review past runs, list a context's run history with `GET /v1/matching/contexts/{contextId}/runs`.

> [!TIP]
>
> API Reference:
>
> * [Run match](/en/reference/products/matcher/run-match)
> * [List match runs](/en/reference/products/matcher/list-match-runs)

## What is a source?

***

A source represents a system or data feed that supplies transactions to a reconciliation context.
Each context requires at least two sources.

**Typical sources include:**

* Bank statement feeds
* ERP general ledger exports
* Payment processor transaction streams
* Internal accounting systems

## Adding sources to a context

***

A context needs at least two sources, one for each side of the comparison. The `side` field (`LEFT` or `RIGHT`) declares which side a source feeds. Matcher reconciles the `LEFT` side against the `RIGHT` side. Assign one side to each source and keep the assignment consistent.

Create a source with a `name`, `type`, `side`, and a `config` object. Leave `config` empty (`{}`) when the source needs no connection-specific settings, as with a bank feed on the `LEFT` side. The `config` object also holds import settings, such as [duplicate detection](/en/products/matcher/daily-reconciliation/matcher-uploading-files):

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Chase Bank - Account 1234",
   "type": "BANK",
   "side": "LEFT",
   "config": {}
 }'
```

Point the other side at a second source, for example a payment gateway on the `RIGHT` side:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Payment Gateway",
   "type": "GATEWAY",
   "side": "RIGHT"
 }'
```

> [!NOTE]
>
> `name`, `type`, and `side` are required (`name` is 1–50 characters). `config` is optional and defaults to an empty object when omitted.

> [!TIP]
>
> API Reference: [Create source](/en/reference/products/matcher/create-source)

### Source types

| Type | Description | Typical use |
| - | - | - |
| `LEDGER` | Internal ledger | Internal accounting systems (including Midaz) |
| `BANK` | Bank statement feed | External bank feeds |
| `GATEWAY` | Payment gateway | Payment processors (Stripe, Adyen, PayPal) |
| `CUSTOM` | Bespoke feed | Any other data source |
| `FETCHER` | Discovery-engine source | Rows the extraction engine pulls from a Discovery connection |

### Discovery sources

`FETCHER` identifies a source type. Its `config` must carry `connection_id`, the id of a [Discovery](/en/products/matcher/integrations/matcher-discovery) connection, and each connection backs one `FETCHER` source. Rows that the extraction engine pulls from that connection land in this source. To pull on a schedule, add a [source binding](#source-bindings) on the query rail with the same `connectionId`.

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Open Banking Aggregator",
   "type": "FETCHER",
   "side": "LEFT",
   "config": {
     "connection_id": "8f14e45f-ceea-4f6a-9d1b-2b6f3c7a9e10"
   }
 }'
```

## Managing sources

***

Sources support a full CRUD lifecycle under `/v1/contexts/{contextId}/sources`. You can rename or reconfigure a source at any time, and archiving is soft and reversible. An archived source is excluded from context readiness, matching, and the default source listing, but keeps its full history until you restore it. Archiving does not disable its bindings. Disable or delete them separately to stop scheduler dispatch.

| Action | Method & path | Notes |
| - | - | - |
| Create source | `POST /v1/contexts/{contextId}/sources` | Body: `name`, `type`, `side`, `config` (see above). |
| List sources | `GET /v1/contexts/{contextId}/sources` | Lists sources in the context. Add `includeArchived=true` to include archived sources. |
| Get source | `GET /v1/contexts/{contextId}/sources/{sourceId}` | Retrieves a single source by id. |
| Update source | `PATCH /v1/contexts/{contextId}/sources/{sourceId}` | Updates mutable source fields (e.g. `name`, `config`). |
| Archive source | `POST /v1/contexts/{contextId}/sources/{sourceId}/archive` | Excludes the source from readiness, matching, and the default listing; bindings remain enabled until changed separately. |
| Restore source | `POST /v1/contexts/{contextId}/sources/{sourceId}/restore` | Reactivates a previously archived source. |

> [!TIP]
>
> API Reference:
>
> * [Create source](/en/reference/products/matcher/create-source)
> * [Get source](/en/reference/products/matcher/retrieve-source)
> * [Update source](/en/reference/products/matcher/update-source)
> * [Archive source](/en/reference/products/matcher/archive-source)
> * [Restore source](/en/reference/products/matcher/restore-source)

## Source bindings

***

Bindings define how the binding scheduler can pull source data without a manual file upload. A **source binding** ties a source to the rail that supplies its transactions, plus a duration that determines when it is due. Exactly one rail applies to each binding `kind`:

* `file`: fetches files via a transport (populates `transportConfig`).
* `query`: pulls rows through a discovery-engine connection (populates `connectionId`). The rows land in the `FETCHER` source whose `config.connection_id` matches, whatever source and `format` the binding names. See [Discovery](/en/products/matcher/integrations/matcher-discovery).

Bindings live under `/v1/contexts/{contextId}/sources/{sourceId}/bindings`.

> [!NOTE]
>
> Scheduled pulls run when Lerian enables the binding scheduler. A binding is dispatched only when it is enabled and due. Creating or enabling a binding does not run it immediately.

| Action | Method & path |
| - | - |
| Create binding | `POST /v1/contexts/{contextId}/sources/{sourceId}/bindings` |
| List bindings | `GET /v1/contexts/{contextId}/sources/{sourceId}/bindings` |
| Get binding | `GET /v1/contexts/{contextId}/sources/{sourceId}/bindings/{bindingId}` |
| Update binding | `PATCH /v1/contexts/{contextId}/sources/{sourceId}/bindings/{bindingId}` |
| Delete binding | `DELETE /v1/contexts/{contextId}/sources/{sourceId}/bindings/{bindingId}` |

List returns every binding, enabled and disabled, so a disabled binding stays visible instead of silently vanishing.

### Create a query-rail binding

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{sourceId}/bindings" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "kind": "query",
   "connectionId": "550e8400-e29b-41d4-a716-446655440000",
   "format": "br/cnab400/febraban-base",
   "scheduleSpec": "1h",
   "enabled": true
 }'
```

#### Fields

**kind** `string` *required*

Rail the scheduler pulls the source on: `file` or `query` (required).

**connectionId** `string (UUID)`

Query-rail discovery-engine connection. Required for `query`, rejected for `file`.

**format** `string` *required*

Declared format the binding produces (region/family-namespaced descriptor key, e.g. `br/cnab400/febraban-base`).

**scheduleSpec** `string` *required*

Go duration string the binding scheduler reads, such as `1h` or `30m`. Cron and `@every` syntax are invalid.

**enabled** `boolean`

Whether the scheduler can dispatch the binding when it is due. Defaults to `true`. Enabling it does not run it immediately.

> [!TIP]
>
> API Reference:
>
> * [Create source binding](/en/reference/products/matcher/create-source-binding)
> * [List source bindings](/en/reference/products/matcher/list-source-bindings)
> * [Get source binding](/en/reference/products/matcher/get-source-binding)
> * [Update source binding](/en/reference/products/matcher/update-source-binding)
> * [Delete source binding](/en/reference/products/matcher/delete-source-binding)

## Managing contexts

***

You can adjust a context's settings, pause it, retire it, or copy it. These lifecycle operations preserve history so you never lose an audit trail.

### Update a context

```bash cURL theme={null}
curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Daily Bank Reconciliation - Updated",
   "interval": "weekly",
   "status": "PAUSED"
 }'
```

> [!TIP]
>
> API Reference: [Update context](/en/reference/products/matcher/update-context)

### Pause a context

To temporarily keep a context out of reconciliation runs, update its status to `PAUSED`:

```bash cURL theme={null}
curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "status": "PAUSED"
 }'
```

Pausing a context:

* Prevents new match runs
* Preserves historical data
* Allows future reactivation by setting status back to `ACTIVE`

### Archive a context

Archiving is a reversible soft-delete. Instead of permanently removing a context, it moves the context to the `ARCHIVED` status, preserving its full history (sources, rules, match runs, and audit records) while excluding it from the default context listing.

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/archive" \
 -H "Authorization: Bearer $TOKEN"
```

Archiving a context:

* Sets the context status to `ARCHIVED`
* Preserves the complete history and audit trail
* Excludes the context from the default listing
* Is reversible at any time with the [restore](#restore-a-context) endpoint

> [!TIP]
>
> API Reference: [Archive context](/en/reference/products/matcher/archive-context)

### Restore a context

Restoring reverses an archive. It moves the context from `ARCHIVED` back to `DRAFT`, so you can review and reconfigure the context before you reactivate it.

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/restore" \
 -H "Authorization: Bearer $TOKEN"
```

Restoring a context:

* Sets the context status from `ARCHIVED` back to `DRAFT`
* Does **not** resume matching automatically. Review and reactivate the context to run reconciliation again
* Returns `409 Conflict` if called on a context that is not archived

> [!TIP]
>
> API Reference: [Restore context](/en/reference/products/matcher/restore-context)

### Clone a context

To duplicate an existing context with its sources, rules, fee rules, and field maps, use the clone endpoint. Use it to create templates. Cloned fee rules keep referencing the same fee schedules as the source context. Matcher does not copy the fee schedules themselves.

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/clone" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Q1 2025 Reconciliation (Copy)",
   "includeSources": true,
   "includeRules": true
 }'
```

The response reports how many sources, rules, fee rules, and field maps Matcher copied. A successful clone returns in `ACTIVE` status.

> [!TIP]
>
> API Reference: [Clone context](/en/reference/products/matcher/clone-context)

## Context lifecycle

***

A reconciliation context follows a lifecycle that controls when matching can run and how data is preserved.

* A context starts in **Draft**, where you configure sources and settings.
* A context remains **Draft** until an explicit update sets it to `ACTIVE`. Activation validates the required sources on both `LEFT` and `RIGHT` sides, field mappings or CAMT options, match rules, and fee rules when you enable fee normalization.
* An active context can be temporarily **Paused** to stop execution without affecting configuration or historical data.
* When you no longer need a context, move it to **Archived** with the [archive](#archive-a-context) endpoint. Archiving is a reversible soft-delete: it moves the context to `ARCHIVED`, preserves the full history and audit records, and excludes it from the default listing. An archived context can be brought back to **Draft** at any time with the [restore](#restore-a-context) endpoint.

![Matcher Context Lifecycle](https://mintcdn.com/lerian-49cb71fc/a5129LsdHp16c4y9/images/en/d2/matcher-context-lifecycle.svg?fit=max\&auto=format\&n=a5129LsdHp16c4y9\&q=85\&s=9af73ee89f85f0096b92e9e4d9529a69)

Lifecycle of a Matcher context

## Best practices

***

> **Use descriptive names**
>
> Use explicit names that reflect accounts, systems, and purpose.

> **Start with conservative thresholds**
>
> Favor accuracy over automation initially. Adjust thresholds based on observed results.

> **Separate concerns**
>
> Use multiple contexts instead of a single broad reconciliation.

## Next steps

***

> **[Field mapping](/en/products/matcher/configuration/matcher-field-mapping)**
>
> Define how source fields map to Matcher's schema.

> **[Match rules](/en/products/matcher/configuration/matcher-match-rules)**
>
> Configure the rules that drive reconciliation.


# Exception routing
Source: https://docs.lerian.studio/en/products/matcher/configuration/matcher-exception-routing

Understand automatic severity classification and use explicit assignment, bulk actions, caller-directed dispatch, and callbacks.

Matcher automatically classifies unmatched transactions by severity. Assignment, bulk operations, and dispatch are explicit API actions. Matcher does not automatically route exceptions.

## Severity classification

***

Matcher classifies exceptions automatically from amount and age to support review prioritization. The amount is the absolute value of the transaction's base amount, or of its amount when it has no base amount. For an aged open item, it is the absolute value of the open balance.

### Default severity rules

| Severity | Default amount or age criteria |
| - | - |
| **Critical** | Amount ≥ 100,000 OR age ≥ 120 hours |
| **High** | Amount ≥ 10,000 OR age ≥ 72 hours |
| **Medium** | Amount ≥ 1,000 OR age ≥ 24 hours |
| **Low** | All other cases |

Matcher caps exceptions with reason `FEE_DATA_MISSING` at `MEDIUM`, even when amount or age thresholds would otherwise classify them as `HIGH` or `CRITICAL`.

## Assignment

***

Assignment is explicit. For an `OPEN` exception, the assignment API accepts one opaque `assignee` string and changes the exception to `ASSIGNED`.

> [!NOTE]
>
> Matcher has no user-group model and does not implement automatic assignment, round-robin routing, or least-loaded routing. If you use a user or group identifier, encode it in the `assignee` string and resolve its meaning in your own identity system.

## SLA behavior

***

Matcher stores an SLA due date only when an inbound callback supplies `dueAt`. It does not derive a deadline from severity, emit automatic SLA warnings, escalate exceptions through an SLA workflow, or route them automatically. Dashboard aggregates can report compliance for those externally supplied due dates. Define and enforce the SLA policy in the external system that sends the callback.

## Additional exception endpoints

***

Matcher provides endpoints for advanced exception workflows:

| Endpoint | Method | Description |
| - | - | - |
| [Dispatch exception](/en/reference/products/matcher/dispatch-exception) | `POST` | Attempt caller-selected dispatch without changing exception status |
| [Process callback](/en/reference/products/matcher/process-exception-callback) | `POST` | Apply a token-authenticated, idempotent external update |
| [Bulk assign](/en/reference/products/matcher/bulk-assign-exceptions) | `POST` | Assign exceptions to one `assignee` string |
| [Bulk resolve](/en/reference/products/matcher/bulk-resolve-exceptions) | `POST` | Resolve multiple exceptions independently |
| [Bulk dispatch](/en/reference/products/matcher/bulk-dispatch-exceptions) | `POST` | Dispatch multiple exceptions independently |
| [List comments](/en/reference/products/matcher/list-exception-comments) | `GET` | Retrieve all comments on an exception |
| [Add comment](/en/reference/products/matcher/add-exception-comment) | `POST` | Add a comment to an exception for audit and collaboration |
| [Delete comment](/en/reference/products/matcher/delete-exception-comment) | `DELETE` | Remove a comment from an exception |
| [List disputes](/en/reference/products/matcher/list-disputes) | `GET` | Retrieve all disputes with filtering |
| [Get dispute](/en/reference/products/matcher/retrieve-dispute) | `GET` | Retrieve details of a specific dispute |
| [Open dispute](/en/reference/products/matcher/open-dispute) | `POST` | Flag an exception as disputed for escalated review |
| [Close dispute](/en/reference/products/matcher/close-dispute) | `POST` | Close a dispute with a resolution |
| [Submit evidence ](/en/reference/products/matcher/submit-evidence) | `POST` | Add evidence to support a dispute case |

Bulk assign, resolve, and dispatch accept 1–100 exception IDs. Matcher processes each ID independently, so expect partial success. Bulk assignment accepts a single `assignee` string, not a user or group object.

## Dispatch and callbacks

***

Dispatch is caller-directed: each request names the target. Dispatch records an audit event but does not change the exception status.

### Dispatch targets

When dispatching an exception, set the `targetSystem` field to the following value:

| Target | Description |
| - | - |
| `MANUAL` | Acknowledges the dispatch locally without sending to an external system. |

Inbound callbacks are a separate token-authenticated, idempotent flow. A callback can set an exception to `ASSIGNED` when it includes an assignee, or to `RESOLVED`. Dispatch does not perform bidirectional synchronization.

### Filtering by external system

When listing exceptions, the `external_system` query parameter returns the exceptions whose external system equals the value exactly. Only inbound callbacks set that value. Dispatch does not.

## Queue summaries and observability

***

The exception list exposes queue-scoped summary counts. Dashboard aggregates expose SLA compliance counts for externally supplied due dates. Matcher does not expose routing-rule distribution or integration success and failure analytics. Use your external observability stack for those operational signals.

## Best practices

***

> **Review automatic severity**
>
> Use the classified severity to prioritize review, and account for the `FEE_DATA_MISSING` cap at `MEDIUM`.

> **Use stable assignee values**
>
> Pass a stable identifier in the opaque `assignee` string and resolve ownership in your identity system.

> **Track SLAs externally**
>
> Define deadlines, warnings, and escalation in your workflow system because Matcher does not enforce them.

> **Inspect every bulk result**
>
> Treat bulk operations as independent per ID and handle partial success explicitly.

> **Secure callbacks**
>
> Protect callback tokens and use stable idempotency keys when external systems update exception status.

## Next steps

***

> **[Resolving exceptions](/en/products/matcher/daily-reconciliation/matcher-resolving-exceptions)**
>
> Resolve exceptions through the API or external systems.

> **[Webhooks & callbacks](/en/products/matcher/integrations/matcher-webhooks-callbacks)**
>
> Advanced event delivery and callback handling.


# Fee rules
Source: https://docs.lerian.studio/en/products/matcher/configuration/matcher-fee-rules

Configure fee schedules and predicate rules. Matcher checks matched transactions against the expected fee and, with NET or GROSS normalization, adjusts comparison amounts.

Fee handling in Matcher is split across two entities:

* A **fee schedule** defines *how much* fee to compute: the currency, rounding, and one or more fee items (flat, percentage, tiered, or expression-based).
* A **fee rule** decides *when* a fee schedule applies. It belongs to a reconciliation context, targets a matching side, and carries predicates that a transaction's metadata must satisfy. When the predicates match, the rule selects its fee schedule.

Modeling expected fees this way lets Matcher check matched transactions against the expected fee. With fee normalization enabled, Matcher also accounts for the fee before comparing transactions, when the transaction and schedule currencies match.

## What fee handling solves

***

Reconciliation fails when one side of a transaction includes fees or charges that the other side doesn't record. A payment gateway deducts a processing fee before settling. A bank charges a wire transfer fee. An acquirer nets fees against payouts.

Without modeled fees, Matcher treats these differences as amount mismatches and generates exceptions, even when you expect and document the difference. Fee schedules describe the charge, and fee rules select when to use it.

## How rules and schedules fit together

***

A fee rule does not contain the fee amount or calculation itself. It references a fee schedule by ID and applies it to the transactions its predicates select.

1. You create a **fee schedule** once at the tenant level. Many rules across many contexts can reuse it.
2. You create a **fee rule** inside a context. It sets a `side`, a `feeScheduleId`, a `priority`, and a list of `predicates`.
3. When Matcher processes a context, it evaluates the relevant side's fee rules in `priority` order (lowest first). The first matching rule selects the referenced schedule.

This separation means you change *when* the fee applies by editing the rule, without touching the schedule. Editing a schedule changes only its name, application order, rounding scale, and rounding mode. To change its items or currency, create a new schedule and point the rule's `feeScheduleId` at it.

> [!NOTE]
>
> A fee rule alone does not change comparison amounts. It changes them only when the context sets `feeNormalization` to `NET` or `GROSS`, the relevant side has rules, and the transaction and schedule currencies match. Once a context has fee rules, every `COMMIT` run also checks matched transactions against the expected fee and raises `FEE_VARIANCE`, `FEE_DATA_MISSING`, or `FEE_CURRENCY_MISMATCH` exceptions.

## Fee rule structure

***

A fee rule belongs to a context and has the following fields.

| Field | Type | Description |
| - | - | - |
| `side` | Enum | Which matching side the rule applies to: `LEFT`, `RIGHT`, or `ANY`. `ANY` matches transactions on either side. |
| `feeScheduleId` | UUID | The fee schedule this rule applies when its predicates match. |
| `name` | String | Human-readable name of the fee rule. |
| `priority` | Integer | Evaluation priority; lower numbers are evaluated first. Must be unique within the context. `LEFT`, `RIGHT`, and `ANY` rules share the same priority space. |
| `predicates` | Array | Predicates (ANDed together) that a transaction's metadata must satisfy for this rule to apply. |

### Predicates

Each predicate tests one transaction metadata field with an operator.

| Field | Description |
| - | - |
| `field` | The transaction metadata field the predicate tests (e.g. `institution`). |
| `operator` | The comparison operator (see below). |
| `value` | Single comparison value, used by `EQUALS`, `NEQ`, and the numeric comparators. |
| `values` | List of candidate values, used by `IN` and `BETWEEN`. |

**Available operators:**

| Operator | Meaning |
| - | - |
| `EQUALS` | Case-insensitive string equality with a single `value`. |
| `NEQ` | For a present field, numeric inequality when both values coerce to decimals; otherwise case-insensitive string inequality. |
| `IN` | Matches any entry in `values`. |
| `EXISTS` | Asserts the field is present (no value needed). |
| `GT` / `GTE` / `LT` / `LTE` | Numeric comparison of the field against a single decimal `value`. |
| `BETWEEN` | Inclusive numeric membership in `values` = `[lo, hi]` (with `lo <= hi`). |

Missing fields evaluate to `false` for every operator except `EXISTS`.

## Fee schedule structure

***

A fee schedule is a tenant-level entity that computes a fee from a gross amount.

| Field | Type | Description |
| - | - | - |
| `name` | String | Human-readable name of the schedule. |
| `currency` | String | ISO 4217 currency the schedule's amounts are denominated in. |
| `applicationOrder` | Enum | How items combine: `PARALLEL` applies every item to the same gross base; `CASCADING` applies each item to the net remaining after prior items. |
| `roundingScale` | Integer | Number of decimal places fee amounts are rounded to. |
| `roundingMode` | Enum | Rounding strategy: `HALF_UP`, `BANKERS`, `FLOOR`, `CEIL`, or `TRUNCATE`. |
| `items` | Array | One or more fee items that make up the schedule (at least one required). |

### Fee items

Each item declares a `name`, a `priority` (application order, relevant for `CASCADING`), a `structureType`, and a type-specific `structure`.

| `structureType` | `structure` shape | Notes |
| - | - | - |
| `FLAT` | `{ "amount": "1.50" }` | Fixed amount. |
| `PERCENTAGE` | `{ "rate": "0.029" }` | `rate` is a `0..1` fraction of the base (`0.029` = 2.9%), **not** a percent value. |
| `TIERED` | `{ "tiers": [ { "rate": "0.01", "upTo": "1000" }, ... ] }` | Same `0..1` fraction semantics per tier rate. |
| `EXPRESSION` | `{ "expression": "gross - desconto + multa" }` | Formula over identifiers (`+ - * /`, parentheses, and the functions `days_late`, `days_between`, `max`, `min`, `abs`, `clamp`). `gross` is the engine-provided base amount and overrides any metadata key named `gross`; other identifiers resolve from metadata. |

## Managing fee schedules

***

Fee schedules are tenant-scoped and managed independently of any context.

| Operation | Endpoint |
| - | - |
| Create a fee schedule | `POST /v1/fee-schedules` |
| List fee schedules | `GET /v1/fee-schedules` |
| Retrieve a fee schedule | `GET /v1/fee-schedules/{scheduleId}` |
| Update a fee schedule | `PATCH /v1/fee-schedules/{scheduleId}` |
| Delete a fee schedule | `DELETE /v1/fee-schedules/{scheduleId}` |
| Simulate a fee calculation | `POST /v1/fee-schedules/{scheduleId}/simulate` |

### Create a fee schedule

This schedule computes a 2.9% processing fee on the gross amount, denominated in BRL.

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/fee-schedules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Gateway Processing - 2.9%",
   "currency": "BRL",
   "applicationOrder": "PARALLEL",
   "roundingScale": 2,
   "roundingMode": "HALF_UP",
   "items": [
     {
       "name": "processing",
       "priority": 1,
       "structureType": "PERCENTAGE",
       "structure": { "rate": "0.029" }
     }
   ]
 }'
```

> [!TIP]
>
> API Reference:
>
> * [Create fee schedule](/en/reference/products/matcher/create-fee-schedule)
> * [List fee schedules](/en/reference/products/matcher/list-fee-schedules)
> * [Retrieve fee schedule](/en/reference/products/matcher/retrieve-fee-schedule)
> * [Update fee schedule](/en/reference/products/matcher/update-fee-schedule)
> * [Delete fee schedule](/en/reference/products/matcher/delete-fee-schedule)

### Simulate a fee schedule

Before wiring a schedule into a rule, simulate it against a gross amount to confirm the computed fee.

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/fee-schedules/{scheduleId}/simulate" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "grossAmount": "100.00",
   "currency": "BRL"
 }'
```

The response returns the `netAmount`, `totalFee`, and a per-item breakdown.

> [!TIP]
>
> API Reference: [Simulate fee calculation](/en/reference/products/matcher/simulate-fee-schedule)

> [!NOTE]
>
> A fee schedule cannot be deleted while a fee rule or fee-variance history references it. The delete request returns `409 Conflict` with code `MTCH-0108`. When fee rules block the deletion, the response lists their contexts in the `errors[]` entry whose `location` is `fee-schedule.delete.blocking-contexts`. Remove or repoint current rule references first. Historical variance references continue to block deletion.

## Managing fee rules

***

Fee rules are created inside a context and reference a fee schedule.

| Operation | Endpoint |
| - | - |
| Create a fee rule | `POST /v1/contexts/{contextId}/fee-rules` |
| List fee rules for a context | `GET /v1/contexts/{contextId}/fee-rules` |
| Retrieve a fee rule | `GET /v1/fee-rules/{feeRuleId}` |
| Update a fee rule | `PATCH /v1/fee-rules/{feeRuleId}` |
| Delete a fee rule | `DELETE /v1/fee-rules/{feeRuleId}` |

### Create a fee rule

This rule applies the fee schedule created above to right-side transactions whose `institution` metadata equals `Banco do Brasil`.

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/fee-rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "side": "RIGHT",
   "feeScheduleId": "550e8400-e29b-41d4-a716-446655440000",
   "name": "BB Right-Side Processing Fee",
   "priority": 0,
   "predicates": [
     {
       "field": "institution",
       "operator": "EQUALS",
       "value": "Banco do Brasil"
     }
   ]
 }'
```

> [!TIP]
>
> API Reference:
>
> * [Create fee rule](/en/reference/products/matcher/create-fee-rule)
> * [List fee rules](/en/reference/products/matcher/list-fee-rules)
> * [Retrieve fee rule](/en/reference/products/matcher/retrieve-fee-rule)
> * [Update fee rule](/en/reference/products/matcher/update-fee-rule)
> * [Delete fee rule](/en/reference/products/matcher/delete-fee-rule)

## End-to-end flow

***

Expected-fee handling follows three steps:

**1. Create the fee schedule**

Define how the fee is computed once at the tenant level with `POST /v1/fee-schedules`. Optionally validate it with the simulate endpoint. Note the returned `id`.

**2. Create the fee rule in the context**

Inside the reconciliation context, create a fee rule with `POST /v1/contexts/{contextId}/fee-rules`. Set `feeScheduleId` to the schedule's `id`, choose the `side`, set a unique `priority`, and add the `predicates` that select the transactions the fee applies to.

**3. Apply during matching**

Set the context's `feeNormalization` to `NET` or `GROSS`. The context then needs at least one fee rule to activate. Until it has one, activation readiness reports `context.activation.requirement.fee-rule`. During matching, Matcher evaluates rules for each relevant side in `priority` order. A matching rule changes the comparison amount only when its schedule and the transaction use the same currency.

## Best practices

***

> **Reuse schedules across contexts**
>
> A fee schedule is tenant-scoped and can be referenced by many rules. Define a schedule once (e.g. "Card Processing - Visa") and point rules in different contexts at it. Editing the schedule updates every rule that uses it.

> **Keep priorities unique and intentional**
>
> Priorities are unique within a context and shared across `LEFT`, `RIGHT`, and `ANY` rules. Order them from most specific to most general so a narrow rule wins before a broad fallback.

> **Scope rules with precise predicates**
>
> Predicates are ANDed together and tested against transaction metadata. Combine operators (`EQUALS`, `IN`, `BETWEEN`, `EXISTS`) to target exactly the transactions a fee applies to and avoid unintended fee attribution.

> **Simulate before wiring a schedule into a rule**
>
> Use `POST /v1/fee-schedules/{scheduleId}/simulate` to confirm a schedule produces the expected fee for representative amounts before referencing it from a rule.

> **Repoint rules before deleting a schedule**
>
> A schedule referenced by a rule or fee-variance history cannot be deleted (`409 MTCH-0108`). When fee rules block it, the response lists their contexts in `errors[]`. Update or remove current rule references first; historical variance references continue to block deletion.

## Next steps

***

> **[Match rules](/en/products/matcher/configuration/matcher-match-rules)**
>
> Configure how Matcher compares transactions once it accounts for expected fees.

> **[Exception routing](/en/products/matcher/configuration/matcher-exception-routing)**
>
> Review explicit assignment, dispatch, and callback behavior for exceptions that fee handling doesn't cover.

> **[Fee schedules API](/en/reference/products/matcher/create-fee-schedule)**
>
> Full API reference for fee schedule endpoints.

> **[Fee rules API](/en/reference/products/matcher/create-fee-rule)**
>
> Full API reference for fee rule endpoints.


# Field mapping
Source: https://docs.lerian.studio/en/products/matcher/configuration/matcher-field-mapping

Map each source's raw columns to Matcher's canonical fields: external_id, amount, currency, date, plus optional fields per source.

A field map tells Matcher which raw column in a source carries each canonical transaction field. Every source names its columns differently: bank statements, ledger exports, gateway reports. The field map normalizes those column names into one fixed vocabulary before matching runs.

## What a field map is

***

A field map belongs to a single **source** inside a **context**. A context reconciles two sides (a `LEFT` source and a `RIGHT` source), and each source has its own field map. Matcher compares the canonical fields produced by both maps. Both sides must resolve to the same vocabulary, even when their raw files look nothing alike.

The mapping is a JSON object in the form:

```JSON theme={null}
  { 
    "<canonicalKey>": "<sourceColumnName>"
  }
```

* The **key** is a canonical field. Keys come from a **closed, case-sensitive vocabulary**. Matcher rejects any key outside it.
* The **value** is the name of the column in the raw source that carries that field.

## Canonical vocabulary

***

Matcher uses a closed key space. These are the only keys Matcher accepts.

### Required keys

Every field map must declare all four:

| Key | Description |
| - | - |
| `external_id` | Identifier of the record within the source |
| `amount` | Transaction amount |
| `currency` | ISO 4217 currency code |
| `date` | Transaction date |

### Optional keys

Declare these only when the source carries them:

| Key | Description |
| - | - |
| `description` | Free-text label copied into the transaction's description column |
| `fee_amount` | Column carrying a fee amount for the record |
| `fee_currency` | Column carrying the currency of that fee |
| `direction` | Object that names a debit or credit column (see below) |

> [!NOTE]
>
> `fee_amount` and `fee_currency` are the optional **fee slot**. When present, the mapped column's value is copied into the transaction metadata that fee verification reads. A column with any name, for example `mdr_fee`, can therefore carry fees end to end without hand-built metadata. Omit them and behavior is identical to a map without a fee slot.

> [!NOTE]
>
> `direction` is for a file that marks each row as a debit or a credit in a column of its own. Its value is an object with three non-empty strings, for example `{"column": "DC", "debit": "D", "credit": "C"}`. `column` names that column, and `debit` and `credit` are the two values it holds. Matcher compares these values ignoring case, and they must differ. A debit row imports with a negative amount and a credit row with a positive amount. The amount column must then hold unsigned amounts. Matcher rejects a row with a signed amount, or with a direction cell that is empty or holds neither value. `direction` applies to CSV, JSON, and XML uploads only.

## Creating a field map

***

You create one field map **per source**. A second field map for the same source is refused with `409`. Update the existing one instead. Send the mapping object to the source's field-map endpoint:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{sourceId}/field-maps" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mapping": {
     "external_id": "Transaction ID",
     "amount": "Amount",
     "currency": "Currency",
     "date": "Post Date",
     "description": "Memo"
   }
 }'
```

**Response**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "sourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "mapping": {
    "external_id": "Transaction ID",
    "amount": "Amount",
    "currency": "Currency",
    "date": "Post Date",
    "description": "Memo"
  },
  "version": 1,
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T10:00:00Z"
}
```

> [!TIP]
>
> API Reference: [Create field map](/en/reference/products/matcher/create-field-map)

## Updating a field map

***

To change a mapping, `PATCH` the field map by its own ID (not the source ID). Send the full mapping. It replaces the previous one and increments `version`.

```bash cURL theme={null}
curl -X PATCH "https://api.matcher.example.com/v1/field-maps/{fieldMapId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mapping": {
     "external_id": "Transaction ID",
     "amount": "Amount",
     "currency": "Currency",
     "date": "Value Date",
     "description": "Memo",
     "fee_amount": "Fee",
     "fee_currency": "Fee Currency"
   }
 }'
```

> [!TIP]
>
> API Reference: [Update field map](/en/reference/products/matcher/update-field-map)

Other operations:

| Operation | Endpoint |
| - | - |
| Get a source's field map | `GET /v1/contexts/{contextId}/sources/{sourceId}/field-maps` |
| List every field map in a context | `GET /v1/contexts/{contextId}/field-maps` |
| Delete a field map | `DELETE /v1/field-maps/{fieldMapId}` |

## Example: both sides of a context

***

A context reconciles a bank feed against an internal ledger export. The two files use different column names, so each source declares its own map, but both resolve to the same canonical keys.

### LEFT source: bank statement (CSV)

Raw columns:

```csv theme={null}
BankRef,BookingDate,Amount,Ccy,Narrative
BANK-001,2025-01-15,-500.00,USD,Wire to Acme Corp
```

Field map:

```json theme={null}
{
  "mapping": {
    "external_id": "BankRef",
    "amount": "Amount",
    "currency": "Ccy",
    "date": "BookingDate",
    "description": "Narrative"
  }
}
```

### RIGHT source: ledger export (CSV)

Raw columns:

```csv theme={null}
entry_id,posted_at,value,asset,memo,mdr_fee,fee_ccy
LDG-9931,2025-01-15,-500.00,USD,Payment Acme Corp,2.50,USD
```

Field map:

```json theme={null}
{
  "mapping": {
    "external_id": "entry_id",
    "amount": "value",
    "currency": "asset",
    "date": "posted_at",
    "description": "memo",
    "fee_amount": "mdr_fee",
    "fee_currency": "fee_ccy"
  }
}
```

Both sources now expose `external_id`, `amount`, `currency`, and `date` in the canonical vocabulary. Match rules can compare them directly, even though one file called the amount `Amount` and the other called it `value`.

## Common mistakes

***

> **Reversing the direction**
>
> The key is the canonical field and the value is your column: `{"external_id": "BankRef"}`, not `{"BankRef": "external_id"}`. Writing it backwards puts an unknown key (`BankRef`) on the left, and Matcher rejects the map.

> **Using keys outside the vocabulary**
>
> Matcher rejects keys outside the vocabulary, such as `transaction_id`, `reference`, `counterparty`, or `type`, as unknown keys. The error names each offender.

> **Wrong case**
>
> Keys are case-sensitive lowercase tokens. Matcher treats `External_Id`, `Amount`, or `CURRENCY` as unknown keys.

> **Missing a required key**
>
> All of `external_id`, `amount`, `currency`, and `date` must be present. A map missing any of them fails validation with a "missing required keys" message.

> **Empty or non-string column names**
>
> A column name must be a non-empty string. Matcher rejects `null`, numbers, objects, or `""` in its place.

> **Dropping a duplicate-key field**
>
> A source `config` can declare `duplicate_key`, the ordered list of fields that identify a duplicate row. The default key is `external_id` alone. The field map must map every field that `duplicate_key` names. Matcher rejects a field map that leaves one of them out.

> **Expecting transformations**
>
> Field maps do not parse dates, divide amounts, or concatenate columns. Deliver values already in the expected shape from the source file, or normalize upstream before upload.

## Next steps

***

> **[Match rules](/en/products/matcher/configuration/matcher-match-rules)**
>
> Define how Matcher compares and groups the canonical fields.

> **[Uploading files](/en/products/matcher/daily-reconciliation/matcher-uploading-files)**
>
> Import transactions using your field maps.


# Match rules
Source: https://docs.lerian.studio/en/products/matcher/configuration/matcher-match-rules

Author exact, tolerance, date-lag, and fuzzy rules in Matcher. Set priorities, tolerances, and reference matching to control how transactions pair up.

Match rules are where you set your reconciliation policy. The policy sets how strict or forgiving Matcher is when it decides two transactions are the same. Tight rules mean more manual review but fewer false matches. Looser rules automate more but need careful oversight. You can enforce exact matches, allow controlled variance, tolerate timing differences, or compare external IDs by similarity.

## How rules work

***

When a matching run starts, Matcher evaluates rules in priority order.

* Rules are evaluated from the lowest priority number to the highest.
* Each rule creates all matches it can from transactions not already used by higher-priority rules.

This approach stops any rule from reusing a higher-priority match. Progressively looser rules process the transactions that remain.

## Rule types

***

### Exact

Requires a strict match on configured fields.

* **Best for**: Deterministic matches where values should align 1:1.

### Tolerance

Allows controlled variance in amount matching.

* **Best for**: Known variance patterns such as fees, rounding, or FX differences.

### Date lag

Allows date differences between transactions. DATE\_LAG always proposes a match for review and never auto-confirms, whatever its score.

* **Best for**: Posting delays between systems.

### Fuzzy

Replaces exact reference equality with normalized string-similarity scoring. Amount, currency, and date gates require exact equality by default, but `matchAmount`, `matchCurrency`, and `matchDate` independently control whether each gate applies. FUZZY always proposes a match for review and never auto-confirms.

* **Best for**: Truncated or reformatted external IDs, where the ID varies but the enabled financial gates still align.

## Creating match rules

***

### Exact rule

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "EXACT",
   "priority": 1,
   "config": {
     "matchAmount": true,
     "matchCurrency": true,
     "matchDate": true,
     "matchReference": true,
     "datePrecision": "DAY",
     "caseInsensitive": true,
     "referenceMustSet": false,
     "matchBaseAmount": false,
     "matchBaseCurrency": false,
     "matchScore": 100,
     "matchBaseScore": 90
   }
 }'
```

#### Config reference

**matchAmount** `Boolean` (default: true)

Require exact amount match

**matchCurrency** `Boolean` (default: true)

Require exact currency match

**matchDate** `Boolean` (default: true)

Require exact date match

**matchReference** `Boolean` (default: true)

Require exact reference match

**datePrecision** `String` (default: DAY)

Date comparison precision: `DAY` or `TIMESTAMP`

**caseInsensitive** `Boolean` (default: true)

Case-insensitive reference comparison

**referenceMustSet** `Boolean` (default: false)

Require reference to be present on both sides

**matchBaseAmount** `Boolean` (default: false)

Require equal base (converted) amounts, in addition to the `matchAmount` check

**matchBaseCurrency** `Boolean` (default: false)

Require the same base currency, in addition to the `matchCurrency` check

**matchScore** `Integer` (default: 100)

Accepted and validated, but **inert**. It does not change the calculated confidence score (see note below)

**matchBaseScore** `Integer` (default: 90)

Accepted and validated, but **inert**. It does not change the calculated confidence score (see note below)

> [!NOTE]
>
> **`matchScore` and `matchBaseScore` are inert.** They are accepted and validated in the rule config, but the scoring engine ignores them: confidence is always computed from the fixed internal component weights (amount 40, currency 30, date 20, reference 10). Setting them does **not** alter the confidence score or auto-confirm behavior. See [Confidence scoring](/en/products/matcher/reference/matcher-confidence-scoring).

The response echoes the persisted rule with its assigned `id` and timestamps.

> [!TIP]
>
> API Reference: [Create match rule](/en/reference/products/matcher/create-match-rule)

### Tolerance rule

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "TOLERANCE",
   "priority": 2,
   "config": {
     "percentTolerance": 0.005,
     "absTolerance": 0.50,
     "dateWindowDays": 3,
     "roundingScale": 2,
     "roundingMode": "HALF_UP",
     "percentageBase": "MAX",
     "matchCurrency": true,
     "matchReference": true,
     "caseInsensitive": true,
     "referenceMustSet": false,
     "matchBaseAmount": false,
     "matchBaseCurrency": false,
     "matchScore": 85,
     "matchBaseScore": 80
   }
 }'
```

#### Config reference

**percentTolerance** `Decimal`

Percentage threshold applied to `percentageBase` (0.005 = 0.5%). Defaults to `0`. Matcher compares this threshold with `absTolerance` and uses the larger one

**absTolerance** `Decimal`

Absolute amount threshold. Defaults to `0`. Matcher compares it with the percentage threshold and uses the larger one

Both thresholds default to zero, so you must configure any permitted amount variance explicitly.

**dateWindowDays** `Integer`

Number of days allowed between transaction dates

**roundingScale** `Integer`

Decimal places for rounding

**roundingMode** `String`

Rounding strategy: `HALF_UP`, `BANKERS`, `FLOOR`, `CEIL`, or `TRUNCATE`

**percentageBase** `String` (default: MAX)

Base for percentage calculation: `MAX`, `MIN`, `AVERAGE`, `LEFT`, or `RIGHT`

**matchCurrency** `Boolean` (default: true)

Require currency match

**matchReference** `Boolean` (default: true)

Require reference match

**caseInsensitive** `Boolean` (default: true)

Case-insensitive reference comparison

**referenceMustSet** `Boolean` (default: false)

Require reference to be present on both sides

**matchBaseAmount** `Boolean` (default: false)

Match on base (converted) amount

**matchBaseCurrency** `Boolean` (default: false)

Match on base currency

**matchScore** `Integer` (default: 85)

Accepted and validated, but **inert**. It does not change the calculated confidence score

**matchBaseScore** `Integer` (default: 80)

Accepted and validated, but **inert**. It does not change the calculated confidence score

**Example:**

* Transaction A: \$1,000.00
* Transaction B: \$1,005.00
* Amount difference: \$5.00
* Percentage threshold: $1,005.00 × 0.5% = $5.025 (`percentageBase: MAX`)
* Absolute threshold: \$0.50
* Effective threshold: `MAX($5.025, $0.50)` = \$5.025 → **Matches**

### Fuzzy rule

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "FUZZY",
   "priority": 4,
   "config": {
     "minSimilarity": 0.85,
     "matchAmount": true,
     "matchCurrency": true,
     "matchDate": true,
     "datePrecision": "DAY",
     "referenceMustSet": true,
     "matchScore": 70
   }
 }'
```

#### Config reference

**minSimilarity** `Decimal` (default: 0.80)

Minimum normalized reference similarity (0–1) required to gate as a match

**matchAmount** `Boolean` (default: true)

When `true`, require an exact amount match

**matchCurrency** `Boolean` (default: true)

When `true`, require an exact currency match

**matchDate** `Boolean` (default: true)

When `true`, require an exact date match

**datePrecision** `String` (default: DAY)

Date comparison precision: `DAY` or `TIMESTAMP`

**referenceMustSet** `Boolean` (default: true)

Require a non-empty reference on both sides

**matchScore** `Integer` (default: 70)

Accepted and defaulted to `70`, but **inert**. It does not cap or change calculated confidence or auto-confirm behavior

> [!NOTE]
>
> FUZZY replaces reference equality with similarity. By default, it also requires exact amount, currency, and date matches. Disable each gate independently with `matchAmount`, `matchCurrency`, or `matchDate`. FUZZY always proposes matches for human review and never auto-confirms them.

### Date lag rule

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "DATE_LAG",
   "priority": 3,
   "config": {
     "maxDays": 3,
     "minDays": 0,
     "inclusive": true,
     "direction": "ABS",
     "feeTolerance": 0,
     "matchScore": 80,
     "matchCurrency": true
   }
 }'
```

#### Config reference

**maxDays** `Integer`

Maximum number of days difference allowed

**minDays** `Integer` (default: 0)

Minimum number of days difference required

**inclusive** `Boolean` (default: true)

Whether the boundary days are inclusive

**direction** `String` (default: ABS)

How to measure the lag: `ABS` (absolute), `LEFT_BEFORE_RIGHT`, or `RIGHT_BEFORE_LEFT`

**feeTolerance** `Decimal` (default: 0)

Allowed amount difference to account for fees

**matchScore** `Integer` (default: 80)

Accepted and validated, but **inert**. It does not change the calculated confidence score. DATE\_LAG rules always score the reference component as 0, which caps the maximum score at 90

**matchCurrency** `Boolean` (default: true)

Require currency match

### Allocation settings (all rule types)

All rule types accept additional allocation settings for split and aggregate matching:

| Field | Type | Description |
| - | - | - |
| `allowPartial` | Boolean | Allow partial allocation of transaction amounts |
| `allocationToleranceMode` | String | How tolerance is measured: `ABS` (absolute) or `PERCENT` |
| `allocationToleranceValue` | Decimal | Tolerance threshold for allocation |
| `allocationUseBaseAmount` | Boolean | Use base (converted) amount for allocation |

## Rule priority

***

Rules are evaluated by priority. Lower numbers run first. Each priority is an integer from 1 to 1000 and is unique within the context. Matcher refuses a priority that another rule already uses with `409` (`MTCH-0102`).

### Priority strategy

| Priority | Rule type | Use case |
| - | - | - |
| 1–10 | EXACT | Deterministic matches |
| 11–50 | TOLERANCE | Small, expected variance |
| 51–100 | DATE\_LAG | Date differences between systems |

### Reorder rules

You can reorder rules by providing the rule IDs in the desired order:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules/reorder" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "ruleIds": [
     "550e8400-e29b-41d4-a716-446655440001",
     "550e8400-e29b-41d4-a716-446655440002",
     "550e8400-e29b-41d4-a716-446655440000"
   ]
 }'
```

Matcher then renumbers every rule in the context from 1, in the new order. Rules that you leave out of the list follow the listed rules, in their previous order.

> [!TIP]
>
> API Reference: [Reorder match rules](/en/reference/products/matcher/reorder-match-rules)

## Testing rules

***

Test rules in dry-run mode before committing matches.

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mode": "DRY_RUN"
 }'
```

Dry run mode evaluates all rules and returns only the `runId` and `status`. It does not create exceptions, but Matcher completes and persists the `MatchRun` with statistics and emits its completion event. Read the statistics with `GET /v1/matching/runs/{runId}`.

## Managing rules

***

### List rules

```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN"
```

#### Response

Each item is the full rule, in the same shape as the create response, including `config`.

```json theme={null}
{
  "items": [
    {
      "id": "019c96a0-2b20-7123-9a1b-2c3d4e5f6a7b",
      "contextId": "019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f",
      "type": "EXACT",
      "priority": 1,
      "config": {
        "matchAmount": true,
        "matchCurrency": true,
        "matchDate": true,
        "matchReference": true,
        "datePrecision": "DAY",
        "matchScore": 100,
        "matchBaseScore": 90
      },
      "createdAt": "2026-02-02T16:40:00Z",
      "updatedAt": "2026-02-02T16:40:00Z"
    }
  ],
  "limit": 20,
  "hasMore": false
}
```

> [!TIP]
>
> API Reference: [List match rules](/en/reference/products/matcher/list-match-rules)

### Update a rule

```bash cURL theme={null}
curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}/rules/{ruleId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "priority": 5,
   "type": "TOLERANCE",
   "config": {
     "percentTolerance": 0.02,
     "absTolerance": 10.0
   }
 }'
```

`config` replaces the whole stored configuration. Matcher does not merge it with the previous one, so a key that you omit returns to its default.

> [!TIP]
>
> API Reference: [Update match rule](/en/reference/products/matcher/update-match-rule)

### Delete a rule

```bash cURL theme={null}
curl -X DELETE "https://api.matcher.example.com/v1/contexts/{contextId}/rules/{ruleId}" \
 -H "Authorization: Bearer $TOKEN"
```

Matcher refuses the delete with `409` (`MTCH-0118`) while a confirmed match group that this rule created still has an exception attached.

> [!TIP]
>
> API Reference: [Delete match rule](/en/reference/products/matcher/delete-match-rule)

## Best practices

***

> **Start strict, then loosen**
>
> Lead with exact rules. Add tolerance rules only for the variance you can justify and explain.

> **Dry-run every change**
>
> Treat rule updates as production changes. Validate match rates and exception volume before committing.

> **Review rule output over time**
>
> If a rule never matches, it may be unnecessary. If it matches too often, it may be too broad.

> **Keep loose rules at low priority**
>
> High tolerance increases false positives. Use it as a fallback and review results carefully.

## Next steps

***

> **[Exception routing](/en/products/matcher/configuration/matcher-exception-routing)**
>
> Configure classification, assignment, and escalation for unmatched transactions.

> **[Confidence scoring](/en/products/matcher/reference/matcher-confidence-scoring)**
>
> Understand how scores are calculated and how thresholds impact automation.


# Schedules
Source: https://docs.lerian.studio/en/products/matcher/configuration/matcher-schedules

Automate reconciliation runs with cron-based schedules per context, and manage them through a full create, list, retrieve, update, and delete lifecycle.

Schedules let you run reconciliation automatically on a recurring cadence instead of triggering match runs by hand. Each schedule belongs to a reconciliation context and fires on a cron expression, with a minimum interval of five minutes between firings.

## What is a schedule?

***

A schedule is a cron-based trigger attached to a context. When it fires, Matcher starts a `COMMIT` match run for that context with its rules and sources. The run reconciles only when the context is `ACTIVE`.

| Field | Type | Description |
| - | - | - |
| `id` | UUID | Unique identifier for the schedule |
| `contextId` | UUID | Context this schedule belongs to |
| `cronExpression` | String | Cron expression defining the frequency (e.g. `0 0 * * *` for daily at midnight) |
| `enabled` | Boolean | Whether the schedule is active |
| `lastRunAt` | Timestamp | Time Matcher last dispatched the asynchronous match-run trigger; it does not indicate completion or success (RFC 3339) |
| `nextRunAt` | Timestamp | Next scheduled run time (RFC 3339) |
| `createdAt` / `updatedAt` | Timestamp | Creation and last-update timestamps (RFC 3339) |

## Schedule lifecycle

***

Schedules support a full CRUD lifecycle under `/v1/contexts/{contextId}/schedules`.

| Action | Method & path |
| - | - |
| Create schedule | `POST /v1/contexts/{contextId}/schedules` |
| List schedules | `GET /v1/contexts/{contextId}/schedules` |
| Retrieve schedule | `GET /v1/contexts/{contextId}/schedules/{scheduleId}` |
| Update schedule | `PATCH /v1/contexts/{contextId}/schedules/{scheduleId}` |
| Delete schedule | `DELETE /v1/contexts/{contextId}/schedules/{scheduleId}` |

> [!TIP]
>
> API Reference:
>
> * [Create schedule](/en/reference/products/matcher/create-schedule)
> * [List schedules](/en/reference/products/matcher/list-schedules)
> * [Get schedule](/en/reference/products/matcher/retrieve-schedule)
> * [Update schedule](/en/reference/products/matcher/update-schedule)
> * [Delete schedule](/en/reference/products/matcher/delete-schedule)

## Creating a schedule

***

Provide a `cronExpression`. The `enabled` field defaults to active when omitted.

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/schedules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "cronExpression": "0 0 * * *",
   "enabled": true
 }'
```

**cronExpression** `String` *required*

Cron expression defining the run frequency (1–100 chars), with at least five minutes between firings. Use five fields: minute, hour, day of month, month, and day of week. Matcher rejects a seconds field, macros such as `@daily`, and per-minute and sub-minute schedules

**enabled** `Boolean`

Whether the schedule is active immediately

The response returns the created schedule, including its `id`, `nextRunAt`, and timestamps. Listing schedules (`GET`) returns every schedule for the context, enabled and disabled alike.

## Pausing vs. deleting a schedule

***

When you need to stop a recurring reconciliation, you have two options.

**Disable** the schedule to pause automatic runs while keeping its configuration and history. Re-enabling later is a single call, with no need to recreate it. Update the cron expression, toggle `enabled`, or both (omitted fields stay unchanged):

```bash cURL theme={null}
curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}/schedules/{scheduleId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "cronExpression": "0 6 * * *",
   "enabled": false
 }'
```

**Delete** the schedule (`DELETE .../schedules/{scheduleId}`) only when the cadence is gone for good. Deletion is permanent. To take a break, disable instead.

## Best practices

***

> **Align cadence with source availability**
>
> Schedule runs to fire after all sources for the context have delivered their data for the period. Running before ingestion completes produces avoidable exceptions.

> **Prefer disabling over deleting**
>
> To pause a reconciliation cadence, disable the schedule. It keeps history and configuration, and re-enabling is a single call.

> **Use explicit cron expressions**
>
> Keep cron expressions readable and documented (e.g. `0 0 * * *` = daily at 00:00). Matcher evaluates them in UTC.

## Next steps

***

> **[Contexts and Sources](/en/products/matcher/configuration/matcher-contexts-and-sources)**
>
> Configure the contexts and sources a schedule reconciles.

> **[Generating Reports](/en/products/matcher/daily-reconciliation/matcher-generating-reports)**
>
> Review the results produced by scheduled runs.


# Generating reports
Source: https://docs.lerian.studio/en/products/matcher/daily-reconciliation/matcher-generating-reports

Generate reconciliation summaries, match details, exception views, and variance reports to monitor outcomes and support compliance.

Reports turn a reconciliation run into something you can act on: how much matched, what's still open, and how much money is exposed. Operations teams use them to work the day's queue. Finance and compliance use them to close the books and document outcomes.

## Available reports

***

Each report answers a different question:

* **Reconciliation summary**: Matched and unmatched counts and amounts for the date range.
* **Match detail report**: A list of matched transactions with their match group, source, amount, currency, and date.
* **Unmatched report**: A list of transactions that remain unmatched for follow-up.
* **Exception report**: A list of exceptions created in the date range, with severity, status, reason, and due date.
* **Variance report**: Expected and actual fee totals per source, fee schedule, and currency, with the net variance and its percentage.

Each variance row also carries `adjustmentsApplied`, the signed sum of the adjustments recorded against it, and `outstandingVariance`, the variance that remains after them. Each variance page carries `unattributedAdjustments`: per-currency totals of the adjustments that no single row includes.

Use the reporting dashboard endpoints to access reconciliation metrics and export data.

> [!TIP]
>
> API Reference:
>
> * [Dashboard aggregates](/en/reference/products/matcher/get-dashboard-aggregates)
> * [Export matched report](/en/reference/products/matcher/export-matched-report)
> * [Export unmatched report](/en/reference/products/matcher/export-unmatched-report)

## Dashboard analytics

***

The reporting dashboard provides reconciliation metrics for a context and date range. Reporting endpoints default to the 30-day window ending tomorrow (UTC) and normally limit the window to 90 days. Only the unmatched list and count endpoints accept `unbounded=true` to query without date bounds.

### Dashboard aggregates

Use the combined dashboard aggregates endpoint for a single call that returns volume, match-rate, and SLA statistics for a context:

```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/reports/contexts/{contextId}/dashboard?date_from=2025-01-01&date_to=2025-01-31" \
 -H "Authorization: Bearer $TOKEN"
```

`GET /v1/reports/contexts/{contextId}/dashboard` accepts `date_from`, `date_to`, and an optional `source_id` filter, and returns a `DashboardAggregatesResponse`:

| Field | Description |
| - | - |
| `volume` | Transaction volume statistics for the range |
| `matchRate` | Match-rate statistics (matched vs. total) |
| `sla` | SLA statistics for exception handling |
| `unmatchedByCurrency` | Unmatched amounts split by currency |
| `updatedAt` | When the aggregates were last computed (RFC 3339) |

More granular dashboard slices are available under `/v1/reports/contexts/{contextId}/dashboard/*` (for example `metrics`, `match-rate`, `sla`, `volume`, `source-breakdown`, and `cash-impact`).

> [!NOTE]
>
> There is no bare `GET /v1/reports/contexts/{contextId}` endpoint. The typed sub-paths under `/v1/reports/contexts/{contextId}/...` carry report data, for example `dashboard`, `summary`, `matched`, `unmatched`, and `variance` (all except `dashboard` have an `/export` variant, as does `exceptions`).

> [!TIP]
>
> API Reference: [Get dashboard aggregates](/en/reference/products/matcher/get-dashboard-aggregates)

### Source breakdown

View reconciliation performance by source, including match rates, transaction counts, and unmatched amounts:

```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/reports/contexts/{contextId}/dashboard/source-breakdown?date_from=2025-01-01&date_to=2025-01-31" \
 -H "Authorization: Bearer $TOKEN"
```

> [!TIP]
>
> API Reference: [Get source breakdown](/en/reference/products/matcher/get-source-breakdown)

### Cash impact

Assess the total financial exposure from unmatched transactions, broken down by currency and age:

```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/reports/contexts/{contextId}/dashboard/cash-impact?date_from=2025-01-01&date_to=2025-01-31" \
 -H "Authorization: Bearer $TOKEN"
```

The response includes `byCurrency` and `byAge` breakdowns to help prioritize resolution efforts.

> [!TIP]
>
> API Reference: [Get cash impact](/en/reference/products/matcher/get-cash-impact)

## Pagination

***

The matched, unmatched, and variance report endpoints use cursor-based pagination. Pass the `cursor` value from a previous response to retrieve the next page of results.

If you provide an invalid cursor value, the API returns a `400 Bad Request` error with a message indicating the pagination parameters are invalid.

## Exports

***

The `summary`, `matched`, `unmatched`, `variance`, and `exceptions` reports each have a synchronous `/export` operation that returns the file in the response. Choose the format with `format=csv` (the default) or `format=pdf`. A CSV export holds at most 100,000 records, and a PDF export holds at most 25,000.

```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/reports/contexts/{contextId}/matched/export?date_from=2025-01-01&date_to=2025-01-31&format=csv" \
 -H "Authorization: Bearer $TOKEN" \
 -o matched_report.csv
```

The matched, unmatched, variance, and exceptions reports also run as asynchronous export jobs, with a window of up to 365 days and CSV, JSON, or XML files. See [Exports & disputes](/en/products/matcher/reference/matcher-export-disputes).

## Quick counts

***

Use count endpoints for lightweight status checks without fetching full result sets:

| Endpoint | Description |
| - | - |
| [Count matches](/en/reference/products/matcher/count-matches) | Total matched items in a date range |
| [Count transactions](/en/reference/products/matcher/count-transactions) | Total transactions in a date range |
| [Count exceptions](/en/reference/products/matcher/count-exceptions) | Total exceptions in a date range |
| [Count unmatched](/en/reference/products/matcher/count-unmatched) | Total unmatched items in a date range |

```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/reports/contexts/{contextId}/matches/count?date_from=2025-01-01&date_to=2025-01-31" \
 -H "Authorization: Bearer $TOKEN"
```

Each count endpoint returns a single `count` value, ideal for lightweight dashboards or health checks that don't need the full result set.

## Best practices

***

> **Schedule daily summaries**
>
> Automate a daily summary report delivered each morning to keep stakeholders aligned.

> **Archive exports for compliance**
>
> Store reports in secure, durable storage. Financial artifacts often require multi-year retention.

> **Use filters to stay actionable**
>
> Generate targeted reports by date and source. Avoid exporting everything by default.

> **Monitor report jobs**
>
> Large reports can fail or stall. Export jobs use `QUEUED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `EXPIRED`, and `CANCELED`. Alert on `FAILED` or prolonged `RUNNING`.

## Next steps

***

> **[Contexts and Sources](/en/products/matcher/configuration/matcher-contexts-and-sources)**
>
> Set up reconciliation contexts and data sources.

> **[Security](/en/products/matcher/reference/matcher-security)**
>
> Learn how access control and data protection work in Matcher.


# Resolving exceptions
Source: https://docs.lerian.studio/en/products/matcher/daily-reconciliation/matcher-resolving-exceptions

Review, prioritize, and resolve transactions Matcher couldn't reconcile automatically using severity, lifecycle, and audit-friendly actions.

This guide shows how to review exceptions, prioritize work based on severity, and resolve items with the right level of documentation.

## What is an exception?

***

An exception marks a transaction that needs your review. Common causes include:

* **No candidate found**: No transaction in the other source meets the active rule criteria.
* **Duplicate rejection**: A previous match was rejected and no alternative candidate remains.
* **Source imbalance**: One source contains transactions that are not in the other.

## Exception lifecycle

***

Exceptions move through a simple workflow:

* When Matcher can't reconcile a transaction, it creates an exception in `OPEN` status.
* Assigning the exception moves it from `OPEN` to `ASSIGNED`. The API does not expose an unassign operation. You must send a non-empty `assignee`.
* Force match and adjust entry set `PENDING_RESOLUTION` while the operation is in progress. Success moves the exception to `RESOLVED`.
* Direct resolution moves an `OPEN` or `ASSIGNED` exception to `RESOLVED`.
* Dispatch writes a `DISPATCH` audit event and emits `exception.dispatched`. It does not change the exception status.

![Matcher Exception Lifecycle](https://mintcdn.com/lerian-49cb71fc/eJbUTctk-eLsW0J5/images/en/d2/matcher-exception-lifecycle.svg?fit=max\&auto=format\&n=eJbUTctk-eLsW0J5\&q=85\&s=69503da0352eca4a5625e9edeb50c176)

The lifecycle of an exception in Matcher

### Status definitions

| Status | Description | Who Can Transition |
| - | - | - |
| `OPEN` | New exception waiting for assignment | System |
| `ASSIGNED` | Assigned to an analyst for investigation | System, Analyst |
| `PENDING_RESOLUTION` | Force match or adjust entry is in progress | System |
| `RESOLVED` | Closed with an auditable resolution | Analyst, System |

### State-machine endpoints

The following single-exception endpoints change the lifecycle or record related actions. Each is addressed by the exception's `exceptionId` in the path.

| Endpoint | Method & path | Purpose |
| - | - | - |
| Assign exception | `POST /v1/exceptions/{exceptionId}/assign` | Assigns the exception to an analyst. Body: `assignee` (required). Returns the updated exception. (`OPEN` → `ASSIGNED`) |
| Dispatch exception | `POST /v1/exceptions/{exceptionId}/dispatch` | Records a dispatch to a target system. Body: `targetSystem` (required; `MANUAL` is the target value that records a dispatch), `queue` (optional). Writes a `DISPATCH` audit event and emits `exception.dispatched` without changing status. |
| Resolve exception | `POST /v1/exceptions/{exceptionId}/resolve` | Resolves a single exception. Body: `resolution` (required), `reason` (optional). Mirrors bulk-resolve validation for one exception. (`OPEN` or `ASSIGNED` → `RESOLVED`) |
| Force match | `POST /v1/exceptions/{exceptionId}/force-match` | Marks the exception's transaction as matched and resolves the exception. Body: `overrideReason` (`POLICY_EXCEPTION`, `OPS_APPROVAL`, `CUSTOMER_DISPUTE`, or `DATA_CORRECTION`) and `notes`. Uses `PENDING_RESOLUTION` while the operation is in progress. |
| Adjust entry | `POST /v1/exceptions/{exceptionId}/adjust-entry` | Resolves an exception by creating an accounting adjustment entry. Body: `amount`, `currency`, `effectiveAt`, `notes`, `reasonCode` (all required). Uses `PENDING_RESOLUTION` while the operation is in progress. |
| Exception history | `GET /v1/exceptions/{exceptionId}/history` | Returns the ordered history of state transitions and actions for the exception (`HistoryResponse`). Supports `cursor`/`limit` pagination. *(read-only)* |
| Select exception IDs | `GET /v1/exceptions/ids` | Returns up to 10,000 IDs of the exceptions that match the current filters (`contextId`, `status`, `severity`, `reason`, …). `total` gives the full count, and `truncated` is `true` when the list stops at the cap. Use it to drive a bulk selection before calling the bulk endpoints. *(read-only)* |

> [!NOTE]
>
> `MANUAL` dispatch acknowledges the hand-off locally without calling an external system.

> [!TIP]
>
> API Reference:
>
> * [Assign exception](/en/reference/products/matcher/assign-exception)
> * [Dispatch exception](/en/reference/products/matcher/dispatch-exception)
> * [Resolve exception](/en/reference/products/matcher/resolve-exception)
> * [Force match](/en/reference/products/matcher/force-match-exception)
> * [Adjust entry](/en/reference/products/matcher/adjust-entry-exception)
> * [Get exception history](/en/reference/products/matcher/retrieve-exception-history)
> * [Select exception IDs](/en/reference/products/matcher/select-exception-ids)

#### Assign example

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/assign" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{ "assignee": "john.doe@company.com" }'
```

#### Resolve example

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/resolve" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{ "resolution": "ACCEPTED", "reason": "Variance within tolerance" }'
```

#### Adjust entry example

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/adjust-entry" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "amount": "150.50",
   "currency": "BRL",
   "effectiveAt": "2026-02-02T16:40:00Z",
   "reasonCode": "AMOUNT_CORRECTION",
   "notes": "Correcting processing fee discrepancy"
 }'
```

#### Bulk selection with `selectExceptionIDs`

```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/exceptions/ids?contextId={contextId}&status=OPEN&severity=CRITICAL" \
 -H "Authorization: Bearer $TOKEN"
```

Feed the returned IDs into the [bulk operations](#bulk-operations) below.

## Exception severity

***

Matcher classifies exceptions by severity so you can work the queue in the right order. The amount is the absolute value of the transaction's base amount, or of its amount when it has no base amount. For an aged open item, it is the absolute value of the open balance.

| Severity | Criteria |
| - | - |
| **Critical** | Amount >= 100,000 OR age >= 120 hours |
| **High** | Amount >= 10,000 OR age >= 72 hours |
| **Medium** | Amount >= 1,000 OR age >= 24 hours |
| **Low** | All others |

Matcher caps an exception with reason `FEE_DATA_MISSING` at **Medium**, whatever its amount or age.

These thresholds reprioritize the exception. They do not create an SLA deadline. An inbound callback can supply `dueAt`, and dashboard aggregates measure compliance for those externally supplied deadlines. Define the response-time policy in the external system that sends the callback.

### Severity escalation

Each time a `COMMIT` matching run finds a transaction still unmatched, Matcher recalculates the severity of the transaction's unresolved exception, unless it is a duplicate-transaction exception. Age counts from the transaction date or, for an aged open item, from its obligation business date or first-seen time. The classification uses OR logic. Either the amount or the age threshold is enough to trigger a higher severity. A recalculated exception escalates as follows:

* An exception under 1,000 starts as **Low**, but escalates to **Medium** after 24 hours.

## Resolution methods

***

Matcher exposes three exception-resolution actions.

### 1. Resolve directly

Close an exception with a required `resolution` and an optional `reason` when no force match or adjustment is needed.

### 2. Force match

Mark the exception's transaction as matched and resolve the exception. Force match adds the transaction to no match group and pairs it with no counterpart. To pair two transactions, create a manual match with `POST /v1/matching/manual`.

**Use Force Match when:**

* You can clearly explain and document the rationale.
* The variance is expected (fees, timing, rounding).

Force Match bypasses scoring and rule logic. Use it only when you can justify the decision in writing.

### 3. Create adjustment

Create an adjusting entry to account for a variance or to balance an unmatched item.

**Adjustment reason codes:**

| Reason code | Use case |
| - | - |
| `AMOUNT_CORRECTION` | Correct the transaction amount |
| `CURRENCY_CORRECTION` | Correct the transaction currency |
| `DATE_CORRECTION` | Correct the effective date |
| `OTHER` | Record another documented correction |

**Validation rules:**

* Adjustment amounts must be positive. A request with a zero or negative amount returns a `400 Bad Request` error.
* `POST /v1/exceptions/{exceptionId}/adjust-entry` requires a valid ISO 4217 currency code.
* `reasonCode` must use `AMOUNT_CORRECTION`, `CURRENCY_CORRECTION`, `DATE_CORRECTION`, or `OTHER`.

## Resolution records

***

Matcher records supported resolution actions in the exception history and audit stream.

| Resolution | Request fields |
| - | - |
| Direct resolution | `resolution` (required), `reason` (optional) |
| Force match | `overrideReason`, `notes` |
| Adjust entry | `reasonCode`, `amount`, `currency`, `effectiveAt`, `notes` |

Matcher does not expose exception split or independent write-off resolution contracts, and it does not enforce amount-based approval thresholds for these actions. Apply any additional approval requirements through your organization's controls.

## Bulk operations

***

When dealing with large volumes of exceptions, bulk endpoints let you process up to 100 exceptions in a single request.

### Bulk assign

Assign multiple exceptions to a team member at once:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/bulk/assign" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "exceptionIds": ["019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f", "019c96a0-2b20-7123-9a1b-2c3d4e5f6a7b"],
   "assignee": "john.doe@company.com"
 }'
```

> [!TIP]
>
> API Reference:
>
> * [Bulk assign](/en/reference/products/matcher/bulk-assign-exceptions)
> * [Bulk resolve](/en/reference/products/matcher/bulk-resolve-exceptions)
> * [Bulk dispatch](/en/reference/products/matcher/bulk-dispatch-exceptions)

### Bulk resolve

Resolve multiple exceptions with a shared resolution:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/bulk/resolve" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "exceptionIds": ["019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f", "019c96a0-2b20-7123-9a1b-2c3d4e5f6a7b"],
   "resolution": "ACCEPTED",
   "reason": "Verified as valid bank fees"
 }'
```

The response includes `succeeded` and `failed` arrays, so you can handle partial failures gracefully.

### Bulk dispatch

Dispatch multiple exceptions:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/bulk/dispatch" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "exceptionIds": ["019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f"],
   "targetSystem": "MANUAL",
   "queue": "RECON-TEAM"
 }'
```

## Exception comments

***

Comments give each exception an audit trail of investigation notes and team discussion. Add a comment as an analyst works an item:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/comments" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "content": "Contacted bank to verify wire transfer fee. Awaiting confirmation."
 }'
```

Listing (`GET`) returns the full thread ordered oldest-first. You cannot add comments after an exception is resolved. Only the comment author can delete it, and the comment must belong to the exception identified in the URL.

| Action | Method & path | Key fields |
| - | - | - |
| Add comment | `POST /v1/exceptions/{exceptionId}/comments` | `content` (comment body) |
| List comments | `GET /v1/exceptions/{exceptionId}/comments` | None (returns the full thread, oldest first) |
| Delete comment | `DELETE /v1/exceptions/{exceptionId}/comments/{commentId}` | `commentId` in path |

> [!TIP]
>
> API Reference:
>
> * [List comments](/en/reference/products/matcher/list-exception-comments)
> * [Add comment](/en/reference/products/matcher/add-exception-comment)
> * [Delete comment](/en/reference/products/matcher/delete-exception-comment)

## Disputes

***

When an exception needs formal investigation or involves an external party (a chargeback, a bank query), escalate it to a **dispute**. Disputes track evidence, state changes, and the final outcome. List disputes with `GET /v1/disputes` (filter by `state`, e.g. `OPEN`) or retrieve one by its `disputeId`.

> [!TIP]
>
> API Reference:
>
> * [List disputes](/en/reference/products/matcher/list-disputes)
> * [Get dispute](/en/reference/products/matcher/retrieve-dispute)
> * [Open dispute](/en/reference/products/matcher/open-dispute)
> * [Close dispute](/en/reference/products/matcher/close-dispute)

### Dispute states and transitions

A new dispute is `OPEN`. Closing it sets `WON` or `LOST`, and both outcomes are terminal.

## Exception resolution workflow

***

Use this flow to keep reviews consistent and audit-friendly.

**1. Triage**

Review the queue by severity and SLA. Start with Critical and High.

**2. Investigate**

Use the exception payload to understand what failed and what candidates exist.

* Read `reason` to see why matching failed.
* Call `GET /v1/matching/candidates` with the reconciliation context's `contextId` and the exception's `transactionId` to review near matches below threshold.
* Look for patterns (same counterparty, recurring reference formats).

**3. Resolve**

Pick the resolution that best reflects reality and policy.

* **Resolve directly**: You can close the exception without a force match or adjustment.
* **Force Match**: You accept the transaction as matched without a counterpart.
* **Adjust**: You need an adjusting entry for variance.

**4. Document**

Capture enough detail for someone else to replay your decision later:

* What you checked
* What you concluded
* Links or IDs for supporting evidence

**5. Dispatch if needed**

If the exception requires external handling, dispatch it. Dispatch records the action but does not change the exception status.

## Best practices

***

> **Work by severity and SLA**
>
> Start with Critical and High items. They carry the highest risk and the tightest deadlines.

> **Make decisions auditable**
>
> Notes aren't optional. Treat them as part of the resolution:
>
> * What you checked
> * Why this resolution is correct
> * Any ticket IDs, statements, or confirmations

> **Fix patterns at the source**
>
> Repeating exceptions usually point to configuration issues:
>
> * Same counterparty → Normalize names or mapping
> * Same date window → Validate ingestion completeness
> * Same source → Review field mapping and sign conventions

> **Treat force matches as exceptions to the rule**
>
> If you force-match regularly, your rules or tolerances need attention.

> **Assign work explicitly**
>
> Assign exceptions through the assignment endpoints. Matcher does not apply assignment rules automatically.

## Next steps

***

> **[Generating Reports](/en/products/matcher/daily-reconciliation/matcher-generating-reports)**
>
> Create reconciliation reports, export results, and support audits.

> **[Exception Routing](/en/products/matcher/configuration/matcher-exception-routing)**
>
> Review severity, SLA, and routing concepts for exceptions.


# Reviewing matches
Source: https://docs.lerian.studio/en/products/matcher/daily-reconciliation/matcher-reviewing-matches

Review matches after a run. Understand the 0–100 confidence score, its four weighted components, variance causes, and how to reject or revoke a match group.

After running a matching job, review the results. This guide explains how to interpret match results, understand confidence scores, and reject proposed or revoke confirmed match groups.

## Match status lifecycle

***

Matches progress through a defined lifecycle:

* When the matching engine finds a pair of transactions that belong together, it creates a match in `PROPOSED` status.
* Engine-created matches that score 90 or above from EXACT and TOLERANCE rules are auto-confirmed immediately. Manual matches, created with `POST /v1/matching/manual`, start in `CONFIRMED` status. FUZZY and DATE\_LAG matches remain `PROPOSED` and are never auto-confirmed.
* Matches that are not auto-confirmed remain in `PROPOSED`. The public match-group API does not expose manual confirmation, but you can reject a proposed group with the unmatch operation and a required reason.
* Rejecting a `PROPOSED` group or revoking a `CONFIRMED` group returns its transactions to the unmatched pool. The status change and the transaction return happen atomically.
* When Matcher changes the status of a match's transactions, it changes all of them or none. A manual match that loses a race on a transaction gets `409`, and Matcher applies nothing.

> [!NOTE]
>
> **FUZZY and DATE\_LAG matches are never auto-confirmed.** Auto-confirmation at score ≥ 90 applies to engine-created EXACT and TOLERANCE matches. A manual match starts in `CONFIRMED` status. A match produced by a FUZZY or DATE\_LAG rule stays in `PROPOSED`, regardless of its score, even when it scores 90+. You can reject it through the unmatch operation. There is no public manual-confirm operation. See [Confidence scoring](/en/products/matcher/reference/matcher-confidence-scoring#rule-types-that-never-auto-confirm).

![Match Status Lifecycle](https://mintcdn.com/lerian-49cb71fc/eJbUTctk-eLsW0J5/images/en/d2/matcher-match-status.svg?fit=max\&auto=format\&n=eJbUTctk-eLsW0J5\&q=85\&s=dc72053489e1132a8cd2dcde512d064d)

Status lifecycle of a match.

### Status definitions

| Status | Description | Next Actions |
| - | - | - |
| `PROPOSED` | Match identified by the system but not confirmed | Review or reject through the unmatch operation |
| `CONFIRMED` | Match was auto-confirmed or created as a manual match | Revoke through the unmatch operation if incorrect |
| `REJECTED` | Match was declined | Transactions return to unmatched pool |
| `REVOKED` | A previously confirmed match was revoked | Transactions return to unmatched pool |

## Confidence tiers

***

Matcher assigns a confidence score (0-100) to each proposed match. The score determines what happens to the match.

### Confidence levels

| Tier | Score range | Behavior |
| - | - | - |
| Auto-confirm eligible | 90-100 | Engine-created EXACT and TOLERANCE matches are automatically confirmed without manual review. Manual matches are created `CONFIRMED`. FUZZY and DATE\_LAG matches remain `PROPOSED`. |
| Needs Review | 60-89 | Medium confidence matches remain `PROPOSED`. You can review and reject them, but the public API does not expose manual confirmation. |

### Understanding the score

Matcher calculates the confidence score from weighted components:

| Component | Weight | What it Measures |
| - | - | - |
| Amount match | 40% | How closely transaction amounts align |
| Currency match | 30% | Whether currencies are the same |
| Date tolerance | 20% | How close the transaction dates are |
| Reference match | 10% | Whether transaction references match |

**Example Score Breakdown:**

```
Match: BANK-001 ↔ LED-001

Amount: $1,000.00 vs $1,000.00 → 100% × 40% = 40 points
Currency: USD vs USD → 100% × 30% = 30 points
Date: 2024-01-15 vs 2024-01-15 → 100% × 20% = 20 points
Reference: PAY-001 vs PAY-001 → match → 10 points
 ─────────────────────────
Total Confidence: 100 points
```

## Understanding variances

***

When matches have differences, review the variance details:

### Amount variance

Common causes of amount variance:

* Bank fees
* Currency conversion differences
* Rounding differences
* Partial payments

### Date variance

Common causes of date variance:

* Settlement timing
* Time zone differences
* Posting vs. transaction date
* Weekend/holiday processing

## Match candidates, open items, and adjustments

***

Matcher gives you three surfaces for working a review queue: match candidates, open items, and adjustments.

### List match candidates

```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/matching/candidates?contextId={contextId}&transactionId={transactionId}&limit=20" \
 -H "Authorization: Bearer $TOKEN"
```

`GET /v1/matching/candidates` accepts `contextId`, `transactionId`, and `limit` query parameters and returns a `CandidateProposalsResponse`. The `limit` defaults to 50 and accepts values from 1 to 200.

The candidate picker scans at most 5,000 unmatched transactions in the context and returns only 1:1 candidates from the opposite side. It applies the shared scorer to raw transaction data, without the run-time fee normalization or FX variance-band matching used by a matching run.

### List open items

Open items are residual balances that remain when a transaction nets only in part. Track them to surface amounts that still need clearing or that have aged past their threshold.

```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/matching/contexts/{contextId}/open-items?status=OPEN&limit=50" \
 -H "Authorization: Bearer $TOKEN"
```

`GET /v1/matching/contexts/{contextId}/open-items` supports a `status` filter, plus `limit`/`cursor` pagination.

#### Open item statuses

| Status | When it occurs |
| - | - |
| `OPEN` | Fresh residual. The item has a remaining balance and no leg has netted against it yet. |
| `PARTIALLY_CLEARED` | At least one leg has netted against the balance, but a residual still remains. |
| `CLEARED` | The residual has been fully netted within tolerance. |
| `AGED` | The item remained open beyond its aging threshold, measured from the obligation business date or the legacy first-seen time. |
| `WITHDRAWN` | An un-match took back the confirmed match that created the obligation. |

The normal lifecycle flows `OPEN` → `PARTIALLY_CLEARED` → `CLEARED`, with any still-open item able to become `AGED` once it passes the aging threshold. `WITHDRAWN` is terminal.

### Create an adjustment

Post an accounting adjustment to account for a variance (bank fee, FX difference, rounding, write-off, and so on) against a match group or transaction.

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/matching/adjustments?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "amount": "10.50",
   "currency": "BRL",
   "direction": "DEBIT",
   "type": "BANK_FEE",
   "reason": "Variance due to bank processing fee",
   "description": "Bank wire fee adjustment",
   "matchGroupId": "019c96a0-0b74-768c-8d25-2bf065dca2f8"
 }'
```

`POST /v1/matching/adjustments` requires the `contextId` query parameter. Body fields:

**amount** `String` *required*

Adjustment amount

**currency** `String` *required*

Three-character currency code.

**direction** `String` *required*

`DEBIT` or `CREDIT`

**type** `String` *required*

`BANK_FEE`, `FX_DIFFERENCE`, `ROUNDING`, `WRITE_OFF`, or `MISCELLANEOUS`

**reason** `String` *required*

Business reason for the adjustment

**description** `String` *required*

Human-readable description

**matchGroupId** `UUID`

Match group the adjustment applies to

**transactionId** `UUID`

Transaction the adjustment applies to

Send at least one of `matchGroupId` or `transactionId`.

To read the adjustments recorded against a context, use `GET /v1/matching/contexts/{contextId}/adjustments`. It accepts an optional `matchGroupId` filter, and pages with `cursor`.

> [!TIP]
>
> API Reference:
>
> * [List match candidates](/en/reference/products/matcher/list-match-candidates)
> * [List open items](/en/reference/products/matcher/list-open-items)
> * [Create adjustment](/en/reference/products/matcher/create-adjustment)

## Rejecting or revoking match groups

***

Use the **unmatch** operation to reject a `PROPOSED` group or revoke a `CONFIRMED` group. After a successful operation, Matcher returns the group's transactions to `UNMATCHED`. The next run can match them again.

Use `DELETE /v1/matching/groups/{matchGroupId}` with the required `contextId` query parameter and a `reason` in the request body (operationId `unmatch`):

```bash cURL theme={null}
curl -X DELETE "https://api.matcher.example.com/v1/matching/groups/{matchGroupId}?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "reason": "incorrect match - amounts do not match"
 }'
```

A successful unmatch returns **204 No Content**. The `reason` field is mandatory and must not be empty.

### When to reject or revoke

Common scenarios for rejecting or revoking a group:

* **Incorrect match confirmed**: the transactions in a confirmed group belong to different records
* **New information**: Additional data shows the match is wrong
* **Source correction**: The source system issued a correction or reversal
* **Duplicate transaction**: one of the transactions is a duplicate that you should remove

### What happens after unmatch

When you unmatch a match group:

1. **Match status changes**: A `CONFIRMED` group becomes `REVOKED`. A still-`PROPOSED` group becomes `REJECTED`.
2. **Transactions returned**: All associated transactions revert to `UNMATCHED` status atomically with the status change.
3. **Confirmed effects withdrawn**: For a `CONFIRMED` group, Matcher also withdraws its open-item residuals, voids its fee variances, and withdraws the exceptions it raised. These changes and the status change happen in one transaction.
4. **Reason recorded**: The group stores the supplied rejection or revocation reason.
5. **Streaming event emitted**: A `match_group.unmatched` event is emitted only when the group was previously `CONFIRMED`.
6. **Re-matching possible**: after a successful unmatch, the next run can match the transactions again.

## Best practices

***

> **Start with lowest confidence matches**
>
> Review matches with the lowest confidence scores first. These matches are the most likely to be wrong. Give them the most attention.

> **Understand fixed confidence thresholds**
>
> The confidence thresholds do not change. Engine-created EXACT and TOLERANCE matches with scores of 90 or above are auto-confirmed. Manual matches start `CONFIRMED`. Scores between 60 and 89 remain `PROPOSED`. These values are not configurable per context.
>
> **FUZZY and DATE\_LAG matches are the exception. They are never auto-confirmed and remain `PROPOSED`, regardless of score.**
>
> Use rule tuning (priority, tolerance values) to influence how many matches land in each tier.

> **Give a clear reason**
>
> Provide a specific reason when rejecting a proposed group or revoking a confirmed group. The unmatch operation requires it and stores it with the group.

> **Reject only after checking the source data**
>
> Review the group and its source transactions before using the unmatch operation. Matcher exposes this operation per group. It does not expose bulk confirmation.

> **Review high-value matches carefully**
>
> Regardless of confidence score, give extra attention to high-value matches. The impact of an incorrect match is proportional to the amount.

## Next steps

***

> **[Resolving exceptions](/en/products/matcher/daily-reconciliation/matcher-resolving-exceptions)**
>
> Handle transactions with no automatic match.

> **[Confidence scoring](/en/products/matcher/reference/matcher-confidence-scoring)**
>
> Learn in detail how Matcher calculates confidence scores.


# Uploading files
Source: https://docs.lerian.studio/en/products/matcher/daily-reconciliation/matcher-uploading-files

Import transaction data into Matcher from CSV, JSON, XML, or banking formats like camt.053. Preview column detection, then upload files to a source.

This guide covers how to import transaction data from external sources into Matcher for reconciliation.

## Supported formats

***

Matcher accepts transaction files in three general-purpose formats:

* **CSV**: Comma-separated values with headers. Most common for bank exports.
* **JSON**: Array of transaction objects. Best for API integrations.
* **XML**: Structured elements. Common for enterprise systems.

Beyond these, the upload endpoint also accepts specialized banking formats such as `camt053` and the namespaced descriptor keys from the format catalog (CNAB, acquirer layouts). See [Import formats](/en/products/matcher/imports/matcher-import-formats) for the full catalog.

## File structure requirements

***

Each file must contain transaction records with fields you can map to Matcher's internal schema.

### Required fields

Every transaction must have these fields (or mappable equivalents):

| Field | Type | Description |
| - | - | - |
| `external_id` | String | Unique identifier within the source |
| `amount` | Decimal | Transaction amount (positive or negative) |
| `currency` | String | ISO 4217 currency code |
| `date` | Date/DateTime | Transaction date |

### Optional fields

| Field | Type | Description |
| - | - | - |
| `description` | String | Free-text description |
| `fee_amount` | Decimal | Fee charged on the transaction |
| `fee_currency` | String | Currency of the fee |
| `direction` | Object | Column that marks each row as debit or credit. See [Debit and credit column](#debit-and-credit-column). |

Matcher keeps unmapped columns as transaction metadata.

### Debit and credit column

Some files mark each row as debit or credit in a separate column. To read the sign from that column, map the optional `direction` key to an object `{column, debit, credit}`:

```json theme={null}
"direction": { "column": "type", "debit": "debit", "credit": "credit" }
```

A debit row imports with a negative amount, and a credit row imports with a positive amount. With `direction` mapped, the amount column must be unsigned. A signed amount, an empty direction cell, or an unknown direction value rejects the row. Matcher reads `direction` in CSV, JSON, and XML files only.

## Format examples

***

### CSV

**CSV Requirements:**

* First row must be column headers
* UTF-8 encoding and comma delimiter by default (configurable)
* Quote fields containing commas or newlines

**Code example**

```csv theme={null}
 transaction_id,amount,currency,date,reference,type
 BANK-2024-001,1500.00,USD,2024-01-15,Invoice #1234,credit
 BANK-2024-002,250.00,USD,2024-01-15,Service fee,debit
 BANK-2024-003,3200.50,USD,2024-01-16,Customer payment,credit
 BANK-2024-004,89.99,USD,2024-01-16,Subscription,debit
```

### JSON

**JSON Requirements:**

* An array of objects, or a single object
* Consistent field names across objects
* UTF-8 encoding by default (configurable)

**Code example**

```json theme={null}
[
  {
    "transaction_id": "BANK-2024-001",
    "amount": 1500.0,
    "currency": "USD",
    "date": "2024-01-15",
    "reference": "Invoice #1234",
    "type": "credit"
  },
  {
    "transaction_id": "BANK-2024-002",
    "amount": 250.0,
    "currency": "USD",
    "date": "2024-01-15",
    "reference": "Service fee",
    "type": "debit"
  }
]
```

### XML

**XML Requirements:**

* Well-formed XML
* Record elements named `transaction`, `row`, `record`, `item`, or `entry`
* UTF-8 encoding by default (configurable)

**Code example**

```xml theme={null}
  <?xml version="1.0" encoding="UTF-8"?>
  <transactions>
    <transaction>
      <transaction_id>BANK-2024-001</transaction_id>
      <amount>1500.00</amount>
      <currency>USD</currency>
      <date>2024-01-15</date>
     <reference>Invoice #1234</reference>
      <type>credit</type>
    </transaction>
    <transaction>
      <transaction_id>BANK-2024-002</transaction_id>
      <amount>250.00</amount>
      <currency>USD</currency>
      <date>2024-01-15</date>
      <reference>Service fee</reference>
      <type>debit</type>
      </transaction>
  </transactions>
```

## Upload via API

***

Use the import endpoint to upload transaction files.

### Preview before uploading

Before committing a file for ingestion, you can preview it to verify column detection and sample data. This helps catch field mapping issues early.

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{sourceId}/preview" \
 -H "Authorization: Bearer $TOKEN" \
 -F "file=@bank_statement_january.csv" \
 -F "max_rows=5"
```

#### Response

```json theme={null}
{
  "columns": ["transaction_id", "amount", "currency", "date", "reference"],
  "sampleRows": [
    ["BANK-2024-001", "1500.00", "USD", "2024-01-15", "Invoice #1234"],
    ["BANK-2024-002", "-250.00", "USD", "2024-01-15", "Service fee"]
  ],
  "rowCount": 2,
  "format": "csv"
}
```

> [!TIP]
>
> API Reference: [Preview file](/en/reference/products/matcher/preview-upload)

### Single file upload

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{sourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "format=csv" \
 -F "file=@bank_statement_january.csv"
```

> [!NOTE]
>
> Send the `format` field **before** the `file` part. If `file` arrives first, Matcher infers the format from the filename extension for `.csv` and `.json` only. Matcher never infers `.xml`, because it is a format family that covers plain XML and camt.053. Send the explicit `format` field for XML. Matcher rejects the upload without it.

Matcher parses and stores the whole file inside the upload request. Upload returns **202 Accepted** with the finished job. When the import fails, Matcher answers with an error instead of the job.

Matcher reads an idempotency key only from the `X-Idempotency` header, and only when you send one. A request that carries a key only in `X-Idempotency-Key` or `Idempotency-Key` is refused with `400` (`MTCH-0015`), and nothing is processed. A replayed answer carries the `X-Idempotency-Replayed` header.

> [!NOTE]
>
> The upload limit is **1 GiB**. It counts the whole request body of the upload, including every part, part header, and boundary, not only the file.

Matcher refuses an upload larger than the upload limit with `413` (`MTCH-0010`). It refuses an upload that stops sending data for too long with `408` (`MTCH-0311`).

> [!TIP]
>
> API Reference: [Upload file](/en/reference/products/matcher/upload-transaction-file)

#### Response

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "sourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "COMPLETED",
  "fileName": "bank_statement_january.csv",
  "totalRows": 1250,
  "persistedRows": 1250,
  "droppedDuplicateRows": 0,
  "flaggedDuplicateRows": 0,
  "reviewRows": 0,
  "failureRatePercent": 0,
  "completedWithErrors": false,
  "startedAt": "2024-01-20T10:30:00Z",
  "completedAt": "2024-01-20T10:30:45Z",
  "createdAt": "2024-01-20T10:30:00Z"
}
```

### Check import status

```bash cURL theme={null}
curl -X GET https://api.matcher.example.com/v1/imports/contexts/{contextId}/jobs/{jobId} \
 -H "Authorization: Bearer $TOKEN"
```

> [!TIP]
>
> API Reference: [Get import status](/en/reference/products/matcher/retrieve-ingestion-job)

#### Response (Processing)

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "sourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "PROCESSING",
  "fileName": "bank_statement_january.csv",
  "startedAt": "2024-01-20T10:30:05Z"
}
```

#### Response (Completed)

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "sourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "COMPLETED",
  "completedWithErrors": true,
  "fileName": "bank_statement_january.csv",
  "totalRows": 1250,
  "persistedRows": 1233,
  "droppedDuplicateRows": 12,
  "failedRows": 5,
  "failureRatePercent": 1,
  "reviewRows": 0,
  "diagnosis": "",
  "startedAt": "2024-01-20T10:30:05Z",
  "completedAt": "2024-01-20T10:30:45Z"
}
```

> [!NOTE]
>
> Per-row parse/normalization errors are **not** embedded in the job. When `completedWithErrors` is `true` (or the job `FAILED`), fetch the details from `GET /v1/imports/contexts/{contextId}/jobs/{jobId}/errors` (capped at 100 stored rows, with `totalErrors`/`truncated` accounting). For a wholesale `FAILED` job, `diagnosis` carries a safe one-line reason.

`reviewRows` counts rows with a blank `external_id` that Matcher imports with status `PENDING_REVIEW`. This happens when the source sets `blank_external_id` to `NEEDS_REVIEW` in its `config`. With the default, `REJECT`, a blank `external_id` fails the row.

### Import job status values

| Status | Description |
| - | - |
| `PROCESSING` | File is being parsed and normalized |
| `COMPLETED` | Import finished (check `completedWithErrors` for partial failures) |
| `FAILED` | Import aborted wholesale (see `diagnosis`) |

## Validation and error handling

***

Matcher validates uploaded files at multiple stages.

### Validation stages

**1. Format Validation**

Verifies the file is valid CSV, JSON, or XML with correct structure.

**2. Schema Validation**

Checks that required fields are present and match the configured field map.

**3. Data Type Validation**

Validates amounts are valid decimals, dates are parseable, currencies are valid ISO codes.

### Common validation errors

Each row error carries the row number, the field when one applies, and a message. Common messages:

| Message | Cause | Solution |
| - | - | - |
| `missing required field` | A required field is blank in the row | Fill the field in the source file |
| `invalid decimal amount` | Amount not a valid number | Check for currency symbols or thousands separators |
| `invalid date format` | Date cannot be parsed | Use ISO 8601 format (YYYY-MM-DD) |
| `invalid ISO 4217 currency code` | Currency code not recognized | Use ISO 4217 codes (USD, EUR, BRL) |

### Handling errors

By default, Matcher imports valid rows even if some rows have errors. To fail the job when failed rows exceed a percentage, set `fail_on_error_rate_percent` (1 to 99) in the source `config`.

## Duplicate detection

***

Matcher automatically detects and handles duplicate transactions to prevent double-counting.

### How duplicates are detected

By default, a row is a duplicate when it repeats the `external_id` of a row from the same source, within the same upload or against already-persisted data. To detect duplicates on other fields, set `duplicate_key` in the source `config`. Its value is an ordered list of field-map names, such as `["external_id", "amount"]`.

### Duplicate handling options

Set the `duplicate_policy` key in the source `config` to control handling:

| Policy | Behavior |
| - | - |
| `FLAG_AS_EXCEPTION` (default) | Drops the repeat and raises a `DUPLICATE_TRANSACTION` exception on the surviving transaction (subset of `droppedDuplicateRows` reported as `flaggedDuplicateRows`) |
| `KEEP_FIRST` | Keeps the first occurrence and silently drops repeats, counted in `droppedDuplicateRows` |
| `REJECT` | Turns each repeated row into an ingestion row error, counted in `failedRows` |

When `duplicate_policy` is absent, `FLAG_AS_EXCEPTION` applies.

### Viewing duplicate details

The import summary shows the number of duplicates:

```json theme={null}
{
  "totalRows": 1000,
  "persistedRows": 950,
  "droppedDuplicateRows": 50,
  "failedRows": 0,
  "failureRatePercent": 0
}
```

## Batch uploads

***

For large reconciliation jobs, you can upload multiple files in sequence.

### Upload multiple files

```bash theme={null}
# Upload bank statement
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{bankSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "format=csv" \
 -F "file=@bank_january.csv"

# Upload ledger export
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{ledgerSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "format=csv" \
 -F "file=@ledger_january.csv"
```

### Wait for all imports

Before running matching, make sure all imports are complete.

```bash theme={null}
# List imports for context
curl -X GET "https://api.matcher.example.com/v1/imports/contexts/{contextId}/jobs" \
 -H "Authorization: Bearer $TOKEN"
```

## Search uploaded transactions

***

After importing files, you can search across all transactions in a context to verify data quality or investigate specific records.

```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/imports/contexts/{contextId}/transactions/search?q=Invoice&amount_min=1000&status=UNMATCHED" \
 -H "Authorization: Bearer $TOKEN"
```

#### Response

```json theme={null}
{
  "items": [
    {
      "id": "019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f",
      "sourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "amount": "1500.00",
      "currency": "USD",
      "date": "2024-01-15T00:00:00Z",
      "description": "Invoice #1234",
      "status": "UNMATCHED"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}
```

> [!TIP]
>
> API Reference: [Search transactions](/en/reference/products/matcher/search-transactions)

Supported filters include `amount_min`, `amount_max`, `date_from`, `date_to`, `currency`, `source_id`, `status`, exact `external_id` match via the `reference` parameter, and free-text search via the `q` parameter.

## Best practices

***

> **Validate files before upload**
>
> Check file format and encoding locally before uploading. This catches obvious errors faster.
>
> ```bash theme={null}
> # Check CSV is valid
> head -5 transactions.csv
>
> # Check encoding
> file transactions.csv
> ```

> **Use consistent date formats**
>
> Standardize on ISO 8601 format (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SSZ`) across all sources to avoid parsing issues.

> **Include transaction IDs**
>
> Always include unique transaction IDs from the source system. This enables proper duplicate detection and audit trails.

> **Handle negative amounts consistently**
>
> Decide on a convention (negative for debits, positive for credits) and apply it consistently. When a file marks debits and credits in a separate column, map that column with the `direction` key instead.

> **Upload incrementally for large files**
>
> For files larger than 50 MB, consider splitting them into smaller chunks by date range. This is a reliability recommendation, not the upload limit, and allows partial retries.

> **Set up automated uploads**
>
> For recurring reconciliation, automate file uploads using scheduled jobs.
>
> ```bash theme={null}
> # Example: Daily upload via cron
> 0 6 * * * /scripts/upload_bank_statement.sh
> ```

## Next steps

***

> **[Reviewing Matches](/en/products/matcher/daily-reconciliation/matcher-reviewing-matches)**
>
> Learn how to interpret match results and confidence scores.

> **[Field Mapping](/en/products/matcher/configuration/matcher-field-mapping)**
>
> Configure how source fields map to Matcher's schema.


# Prerequisites
Source: https://docs.lerian.studio/en/products/matcher/getting-started/matcher-prerequisites

Check the credentials, network access, and file formats you need before you use Matcher for reconciliation.

Before you use Matcher, confirm that you have what this page describes.

## Optional: reconciling Midaz data

***

Matcher pairs with Midaz Ledger, but there is no live connector between them. Matcher opens no connection to Midaz. Reconciling Midaz data is entirely optional. Matcher works as a stand-alone product that reconciles any data sources.

### When to reconcile Midaz data

Reconcile ledger data from Midaz if:

* You use Midaz as your ledger system
* You want to reconcile Midaz postings against external sources (bank statements, gateway reports)

### When Midaz is not involved

Matcher works independently when:

* Reconciling between external systems (banks, ERPs, payment processors)
* Using a different ledger system
* Importing ledger data via CSV/JSON/XML files

### How it works

Matcher reconciles Midaz data the same way it ingests any source (by import, not a live query):

1. Export the ledger data for the period you want to reconcile.
2. Import that export into a Matcher context as a source of type `LEDGER`.
3. Import the counterparty data (bank statement or gateway report) as the other side.
4. Matcher matches the two sides using your match rules.

> [!NOTE]
>
> See the [Matcher and Midaz](/en/products/matcher/integrations/matcher-midaz-integration) guide for the full flow.

## Authentication

***

Access Manager issues the token and checks the caller's permissions.

### Required permissions

Fine-grained permissions control access to Matcher features:

| Permission | Description |
| - | - |
| `contexts:create` | Create reconciliation contexts |
| `contexts:read` | View context configuration |
| `rules:create` | Create match rules |
| `imports:create` | Upload transaction files |
| `match-runs:run` | Execute matching jobs |
| `exceptions:read` | View exceptions |
| `exceptions:resolve` | Resolve exceptions |
| `reports:read` | Access reports |

## Generic import formats

***

Matcher's generic importers accept CSV, JSON, and XML. Built-in parsers also support CAMT.053, CNAB 240/400, OFX, several acquirer formats, and receivables formats. See the [import format catalog](/en/products/matcher/imports/matcher-import-formats) for the complete inventory.

Each generic format has specific structural requirements for successful ingestion.

### CSV (comma-separated values)

Commonly used for bank statements and exports.

**Requirements:**

* The file must have a header row
* UTF-8 encoding (configurable)
* Comma delimiter (configurable)
* Quoted fields for values containing delimiters

**Example:**

```csv theme={null}
transaction_id,amount,currency,date,reference
TXN-001,1000.00,USD,2024-01-15,Invoice payment
TXN-002,-250.50,USD,2024-01-16,Refund
```

### JSON (javascript object notation)

Recommended for API-based integrations.

**Requirements:**

* UTF-8 encoding (configurable)
* Consistent field names across records

**Example:**

```json theme={null}
[
  {
    "transaction_id": "TXN-001",
    "amount": 1000.0,
    "currency": "USD",
    "date": "2024-01-15",
    "reference": "Invoice payment"
  }
]
```

### XML (extensible markup language)

Common in enterprise and banking integrations.

**Requirements:**

* Single root element
* UTF-8 encoding (configurable)
* Consistent element structure

**Example:**

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<transactions>
 <transaction>
 <transaction_id>TXN-001</transaction_id>
 <amount>1000.00</amount>
 <currency>USD</currency>
 <date>2024-01-15</date>
 <reference>Invoice payment</reference>
 </transaction>
</transactions>
```

### File size limits

| Limit | Default |
| - | - |
| Maximum upload file size | 1 GiB |
| Maximum buffered request body | 100 MiB |

## Network requirements

***

### Access to Matcher

Your systems and users reach the Matcher API and the Matcher module of Lerian Console at the addresses Lerian provides.

### Access to your systems

For these sources, Matcher connects to the system you name, and that system must accept connections from Matcher:

| What you register | What Matcher connects to |
| - | - |
| Discovery connection | The database or API that the connection names. `GET /v1/discovery/connector-types` lists the available types |
| Source binding on the `file` rail | The SFTP server, HTTPS endpoint, S3 bucket, or IMAP mailbox |

Aggregator connections need your account with Pluggy or Belvo.

Event delivery is optional. When Lerian enables it for you, Matcher publishes the events in [Matcher events](/en/reference/events/matcher) as CloudEvents.

## Checklist

***

Before you start, confirm that:

* **Credentials are available**: you have a token from Access Manager
* **Network access works**: the systems you register accept connections from Matcher
* **A web browser is available**: you use it to open the Matcher module of Lerian Console
* **Sample data is ready**: you have transaction files for your first test (see [Quick Start](/en/products/matcher/getting-started/matcher-quick-start))

## Next steps

***

> **[Quick start](/en/products/matcher/getting-started/matcher-quick-start)**
>
> Run your first reconciliation.


# Getting started with Matcher
Source: https://docs.lerian.studio/en/products/matcher/getting-started/matcher-quick-start

Walk the five-stage reconciliation lifecycle in Matcher. Define a context, connect sources, set rules, run matching, and resolve exceptions step by step.

This guide walks through the reconciliation lifecycle in Matcher, from initial setup to reviewing results. It focuses on the concepts and decisions involved at each stage.

For step-by-step API instructions with request and response examples, see the [Matcher API quick start](/en/reference/products/matcher/matcher-developer-quick-start).

## The reconciliation lifecycle

***

Every reconciliation in Matcher follows the same five-stage lifecycle:

**1. Define scope**

Create a context that describes what you reconcile and records its reconciliation interval.

**2. Connect sources**

Register the systems whose transactions you want to compare.

**3. Set rules**

Configure the criteria Matcher uses to pair transactions.

**4. Run matching**

Upload data and let Matcher find pairs, starting with a preview before committing.

**5. Resolve exceptions**

Review unmatched transactions and decide how to handle them.

The sections below explain each stage.

## Define scope with a context

***

A **context** is the top-level container for a reconciliation workflow. It answers three questions:

* **What do you reconcile?** For example, a bank account against your general ledger.
* **What type of pairing?** One-to-one, one-to-many, or many-to-many.
* **What interval label describes the reconciliation period?** For example, `daily`, `weekly`, or `on-demand`.

The required `interval` value is free-text metadata. It does not schedule execution. Automated runs use a separate cron-backed `ReconciliationSchedule`, with a minimum cadence of five minutes.

| Pairing type | When to use | Example |
| - | - | - |
| `1:1` | Each transaction has exactly one counterpart | Bank statement vs. ledger entries |
| `1:N` | One record maps to several on the other side | A single invoice paid in installments |
| `N:M` | Multiple records on both sides relate to each other | Batch payments split across accounts |

Most reconciliations start with `1:1`. You can change the pairing type later as your process evolves.

> [!TIP]
>
> API reference:
>
> * [Create context](/en/reference/products/matcher/create-context)
> * [Update context](/en/reference/products/matcher/update-context)

## Connect data sources

***

Each context needs at least two sources: the systems whose transaction data you want to compare. A source represents a single data feed such as a bank statement, a ledger export, or a payment gateway file.

### Source types

| Type | Typical use |
| - | - |
| `BANK` | Bank statements and account extracts |
| `LEDGER` | General ledger or ERP exports |
| `GATEWAY` | Payment processor data (Stripe, Adyen, etc.) |
| `FETCHER` | Data extracted through Discovery |
| `CUSTOM` | Any other structured data |

### Field mapping

Transaction files from different systems rarely use the same column names. **Field maps** translate your source columns into Matcher's standard schema so transactions can be compared.

For example, a bank file might call the transaction date "Post Date", while your ledger calls it "posting\_date". Field maps normalize both to Matcher's `date` field.

Every transaction must provide at least four fields after mapping:

| Field | Description |
| - | - |
| `external_id` | Unique identifier within the source |
| `amount` | Transaction value |
| `currency` | ISO 4217 currency code (e.g., USD, BRL) |
| `date` | Transaction date |

> [!TIP]
>
> API reference: [Create source](/en/reference/products/matcher/create-source) | [Create field map](/en/reference/products/matcher/create-field-map)

## Set match rules

***

Rules define how Matcher decides whether two transactions are the same. You can stack multiple rules with different priorities. Matcher evaluates them in order: only transactions left unmatched by the first rule pass to the next.

### Rule types

| Rule | What it does | When to use |
| - | - | - |
| **Exact** | Requires identical values on the selected fields | When data is clean and systems are in sync |
| **Tolerance** | Allows small numeric or date differences | When bank fees, rounding, or processing delays cause minor discrepancies |
| **Fuzzy** | Uses normalized string similarity for references. Amount, currency, and date must match by default, but you can configure each gate independently. | When free-text or truncated references vary between sources |
| **Date lag** | Permits a configurable date window | When settlement dates differ between systems |

### Recommended starting configuration

1. **Priority 1: Exact rule** on amount, currency, and date. This catches all perfect matches first.
2. **Priority 10: Tolerance rule** with a small amount tolerance (e.g., 1%) and a 2-day date window. This catches near-matches caused by fees or timing.

As you observe results over time, adjust rules or add new ones to improve your match rate.

> [!TIP]
>
> API reference: [Create match rule](/en/reference/products/matcher/create-match-rule)

## Run matching

***

Once sources are configured and data is uploaded, you can run the matching engine.

### Preview first, commit second

Matcher supports two execution modes:

| Mode | Behavior |
| - | - |
| **Dry run** | Calculates matches and generates a preview without persisting match artifacts or exceptions. It creates and completes a `MatchRun` record. |
| **Commit** | Persists the results: confirmed matches, confidence scores, and exceptions. |

Always start with a dry run. Review the preview to verify match quality before committing.

### Understanding confidence scores

Every match receives a confidence score from 0 to 100:

| Score range | Meaning | Action required |
| - | - | - |
| 90–100 | High confidence | Eligible for auto-confirmation for `EXACT` and `TOLERANCE` groups. `FUZZY` and `DATE_LAG` groups always require review |
| 60–89 | Medium confidence | Flagged for manual review |

Scores derive from the matched components and their fixed weights. Exact and tolerance rules use the same weighting framework. Neither rule type inherently yields higher scores.

> [!TIP]
>
> API reference: [Run match](/en/reference/products/matcher/run-match) | [List match run groups](/en/reference/products/matcher/list-match-run-groups)

## Resolve exceptions

***

### Exception severity

Matcher classifies each exception by severity based on its amount and its age. The amount is the absolute value of the transaction's base amount, or of its amount when it has no base amount. For an aged open item, it is the absolute value of the open balance.

| Severity | Criteria |
| - | - |
| **Critical** | Amount >= 100,000 or age >= 120 hours |
| **High** | Amount >= 10,000 or age >= 72 hours |
| **Medium** | Amount >= 1,000 or age >= 24 hours |
| **Low** | All others |

### Resolution options

* **Force match**: Mark the transaction as matched and resolve the exception. It takes only `overrideReason` and `notes`, and it pairs the transaction with no counterpart. To pair transactions, create a manual match with `POST /v1/matching/manual`.
* **Create adjustment**: Record a correcting entry to account for the difference.
* **Unmatch**: If a confirmed match is incorrect, undo it so both transactions return to the unmatched pool.
* **Dispatch**: Record a manual hand-off of the exception in its audit trail. This caller-directed action does not change its status.

> [!TIP]
>
> API reference:
>
> * [List exceptions](/en/reference/products/matcher/list-exceptions)
> * [Unmatch group](/en/reference/products/matcher/unmatch-group)

## Example scenario

***

A fintech company reconciles its daily bank statement against internal ledger records.

**Setup:**

* Context: "Daily Bank Reconciliation", type `1:1`, interval `daily`
* Two sources: Chase Bank statement (`BANK`) and General Ledger (`LEDGER`)
* Two rules: Exact match (priority 1) and Tolerance match with 1% and 2-day window (priority 10)

**Daily workflow:**

1. Finance uploads the bank statement and ledger export.
2. Matcher runs a dry run. The preview shows 95% of transactions matched with high confidence.
3. The team reviews the preview and commits the results.
4. Five transactions remain as exceptions: two have small fee differences, three have no counterpart.
5. The team resolves the fee exceptions by creating adjustments. The three missing transactions are escalated for investigation.

## Next steps

***

> **[Contexts and sources](/en/products/matcher/configuration/matcher-contexts-and-sources)**
>
> Full guide to setting up reconciliation contexts.

> **[Match rules](/en/products/matcher/configuration/matcher-match-rules)**
>
> Learn about all rule types and configuration options in detail.

> **[Field mapping](/en/products/matcher/configuration/matcher-field-mapping)**
>
> Map different file formats to Matcher's standard schema.

> **[Resolving exceptions](/en/products/matcher/daily-reconciliation/matcher-resolving-exceptions)**
>
> Strategies for handling unmatched transactions.


# Setup progress
Source: https://docs.lerian.studio/en/products/matcher/getting-started/matcher-setup-progress

Read a context's aggregated setup and activation-readiness state in a single request to drive an onboarding checklist or setup wizard.

The setup-progress endpoint returns configured-resource counts, the last-run state, and activation readiness for a context in a single aggregate. A setup wizard or onboarding checklist derives its state from one request instead of many.

## Get setup progress

***

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/contexts/{contextId}/setup-progress" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "contextId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "DRAFT",
  "sources": { "total": 2, "left": 1, "right": 1 },
  "fieldMaps": { "mappedSources": 2 },
  "matchRules": { "total": 3 },
  "schedules": { "total": 1 },
  "lastRun": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "completedAt": "2025-01-15T10:30:00Z"
  },
  "readiness": {
    "ready": true,
    "missing": []
  },
  "next": null
}
```

## What it returns

***

* **`status`**: the context lifecycle status: `DRAFT` (in setup), `ACTIVE` (running), `PAUSED` (suspended), or `ARCHIVED` (retired).
* **`sources`**: source counts split by matching side: `total`, `left`, `right`.
* **`fieldMaps.mappedSources`**: number of mapped sources. This count covers sources with a field map, plus self-mapped CAMT.053 sources. For those, the parser embeds the ISO 20022 mapping and ignores field maps.
* **`matchRules.total`**: match-rule count for the context.
* **`schedules.total`**: schedule count for the context.
* **`lastRun`**: the most recent match run (`id`, `status`, and `completedAt`). It is `null` when the context has never run.
* **`readiness`**: activation-readiness summary (see below).
* **`next`**: the deterministic next setup action to take, or `null` when the context is ready (see below).

## Readiness and the checklist

***

The `readiness` block reports whether the context satisfies every activation requirement:

```json theme={null}
{
  "ready": false,
  "missing": [
    "context.activation.requirement.source-mapping",
    "context.activation.requirement.match-rule"
  ]
}
```

`missing` holds stable requirement IDs you can map to checklist items:

* `context.activation.requirement.left-source`: the context needs at least one LEFT-side source.
* `context.activation.requirement.right-source`: the context needs at least one RIGHT-side source.
* `context.activation.requirement.source-mapping`: the context needs at least one source, and every source needs a mapping. A source is mapped when it has a field map or is a self-mapped CAMT.053 source.
* `context.activation.requirement.match-rule`: the context needs at least one match rule.
* `context.activation.requirement.fee-rule`: the context enables fee normalization but has no fee rule. This requirement is conditional. It appears only when you set `feeNormalization` to `NET` or `GROSS`. It mirrors the run precondition, which requires fee rules, not fee schedules, to be non-empty.

> [!NOTE]
>
> If you move a context to `ACTIVE` before it is ready, the update fails with `409 Conflict` and code `MTCH-0103`. Its `detail` is a fixed sentence. Its `errors` array has one entry for each missing requirement, and the `location` of each entry is the requirement ID. Re-read setup progress to render the remaining setup guidance.

## The next action

***

`next` turns `readiness.missing` into a concrete call. It comes from `missing[0]`, the first unsatisfied requirement in the stable order above. It is `null` when the context is ready:

```json theme={null}
{
  "requirementId": "context.activation.requirement.source-mapping",
  "operationId": "createFieldMap",
  "method": "POST",
  "path": "/v1/contexts/{contextId}/sources/{sourceId}/field-maps",
  "requiredFields": ["mapping"],
  "forSource": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Bank statement"
  }
}
```

* **`requirementId`**: the requirement ID this action satisfies.
* **`operationId`**, **`method`**, **`path`**: the endpoint to call to satisfy the requirement.
* **`requiredFields`**: the names of the fields that the create request requires. They never carry values. You supply those.
* **`forSource`**: present only for the `context.activation.requirement.source-mapping` action, naming the first unmapped source so you can fill `{sourceId}` without a separate lookup.

The full requirement-to-endpoint table:

| `requirementId` | Endpoint | `requiredFields` |
| - | - | - |
| `context.activation.requirement.left-source` | `POST /v1/contexts/{contextId}/sources` | `name`, `type`, `side` |
| `context.activation.requirement.right-source` | `POST /v1/contexts/{contextId}/sources` | `name`, `type`, `side` |
| `context.activation.requirement.source-mapping` | `POST /v1/contexts/{contextId}/sources/{sourceId}/field-maps` | `mapping` |
| `context.activation.requirement.match-rule` | `POST /v1/contexts/{contextId}/rules` | `priority`, `type`, `config` |
| `context.activation.requirement.fee-rule` | `POST /v1/contexts/{contextId}/fee-rules` | `side`, `feeScheduleId`, `name` |

Both source-side requirements resolve to the same `createSource` operation. The `side` field distinguishes them.

The fee-rule action needs the `feeScheduleId` of an existing fee schedule. [Create a fee schedule](/en/reference/products/matcher/create-fee-schedule) first.

## How to use it during setup

***

1. **Render the checklist.** On each step of the wizard, GET setup-progress and use the counts (`sources`, `fieldMaps`, `matchRules`, `schedules`) to tick off completed items.
2. **Drive the primary button from `next`.** Do not reimplement the requirement order client-side. Call the operation that `next` names. Then re-read setup-progress for the next action.
3. **Gate the "Activate" button.** Enable activation only when `readiness.ready` is `true`. Otherwise, list `readiness.missing` as the remaining steps.
4. **Show run health.** Once `lastRun` is present, surface its `status` and `completedAt` so operators can confirm the context produces results.

The whole state comes from one call. You can poll this endpoint to keep the wizard live, with no separate source, rule, and run reads.

## Response codes

***

| Status | Meaning |
| - | - |
| `200` | Setup progress returned |
| `404` | Context not found |


# Extraction reviews
Source: https://docs.lerian.studio/en/products/matcher/imports/matcher-extraction-reviews

Review, approve, or reject AI-extracted transaction candidates before they are ingested, and use mapping proposals and job actions to prepare source data.

Matcher can extract transaction candidates from documents and propose field mappings using AI, but AI output is never authoritative. Nothing reaches reconciliation until a human approves it. This guide covers the human-in-the-loop (HITL) extraction-review queue, AI mapping proposals, and the related job actions.

> [!NOTE]
>
> When Lerian enables document extraction for your environment, you can enqueue documents. When the feature is not available in your environment, the operation answers `503`. That answer comes before any storage or egress of document bytes.

## Enqueue a document for extraction

***

Upload a source document (PDF) to run deterministic + AI extraction. Matcher sends a capped slice of the document's text layer to the language-model provider Lerian configures for your environment. When the PDF has no text layer, Matcher sends the PDF itself. The resulting transaction candidates go into a review queue. Nothing reaches reconciliation yet.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{sourceId}/extract-document" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/pdf" \
  --data-binary @statement.pdf
```

The response (`202 Accepted`) returns the queued review id, the candidate count, and a status that is always `PENDING_REVIEW` on enqueue:

```json theme={null}
{
  "reviewId": "550e8400-e29b-41d4-a716-446655440000",
  "candidateCount": 12,
  "status": "PENDING_REVIEW"
}
```

## The review queue

***

### List reviews

Cursor-paginated list of extraction reviews for a context, optionally filtered by lifecycle status.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/imports/contexts/{contextId}/extraction-reviews?status=PENDING_REVIEW&limit=50" \
  -H "Authorization: Bearer $TOKEN"
```

Query parameters: `status` (`PENDING_REVIEW`, `APPROVED`, `REJECTED`), `limit` (1–200), and `cursor`.

### Get one review

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/imports/contexts/{contextId}/extraction-reviews/{reviewId}" \
  -H "Authorization: Bearer $TOKEN"
```

A review carries its lifecycle, the proposed candidates, provenance, and linkage state:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contextId": "550e8400-e29b-41d4-a716-446655440000",
  "sourceId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PENDING_REVIEW",
  "candidates": [
    {
      "source": "text_layer",
      "fields": [
        { "canonicalKey": "amount", "value": "100.50", "confidence": 0.95, "page": 1 },
        { "canonicalKey": "date", "value": "2025-06-01", "confidence": 0.9, "page": 1 }
      ]
    }
  ],
  "version": 1,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}
```

Each candidate declares the lane that produced it: `text_layer` (PDF text, higher trust) or `vision` (OCR/vision model, lower trust). On the `text_layer` lane, field values are tokens from the document text. On the `vision` lane, the model reads them from the image. Money stays a string, never a parsed amount.

## Approve or reject

***

### Approve

Approving a `PENDING_REVIEW` review runs the single deterministic handoff into the normal ingestion pipeline (dedup + outbox + match-trigger) and links the resulting job to the review. This is the only path from an AI candidate to a reconciled transaction, and it runs only on explicit human approval.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/extraction-reviews/{reviewId}/approve" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "reviewId": "550e8400-e29b-41d4-a716-446655440000",
  "ingestionJobId": "550e8400-e29b-41d4-a716-446655440000",
  "candidateCount": 12
}
```

### Reject

Rejecting closes the review, and nothing enters ingestion. The body is optional. An empty body is a valid "reject with no reason".

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/extraction-reviews/{reviewId}/reject" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "poor scan quality, re-upload" }'
```

The approving/rejecting principal is recorded for audit.

## Mapping proposals

***

Before you declare a field map by hand, ask the advisor to inspect a representative sample and propose a config-only mapping. When Lerian enables the mapping advisor for your environment, Matcher sends a capped slice of the sample to the language-model provider Lerian configures for your environment. It is advisory and side-effect-free. Producing a proposal persists nothing. You confirm the result through the existing field-map declaration path.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{sourceId}/mapping-proposal" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "sample": "id;value;ccy;posted_at\nA1;10,50;BRL;2025-06-01\n",
    "format": "csv",
    "hints": { "locale": "pt-BR", "has_header": "true" }
  }'
```

The response carries the proposed field map, source dialect, and a per-field breakdown with confidence and rationale:

```json theme={null}
{
  "mapping": { "amount": "value", "external_id": "id" },
  "dialect": {
    "encoding": "utf-8",
    "delimiter": "semicolon",
    "decimalStyle": "comma",
    "dateStyle": "iso"
  },
  "fields": [
    { "canonicalKey": "amount", "sourceColumn": "value", "confidence": 0.92, "rationale": "numeric column with comma decimal" }
  ]
}
```

The response never carries parsed values, amounts, or transactions.

## Fetch from an external transport

***

Trigger a manual fetch-and-ingest that lists every object matching the supplied transport coordinates and streams each into the trusted-content ingestion pipeline. `kind` is `sftp` (the default), `https`, `s3`, or `imap`. The body carries the connection coordinates and a required `credentialRef`. An SFTP fetch needs the server's host key in `connectOptions.known_hosts` and reads at most 256 matching objects.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{sourceId}/fetch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "sftp",
    "host": "sftp.bank.example",
    "port": 22,
    "path": "outbound/returns",
    "glob": "*.ret",
    "credentialRef": "<credential-ref>",
    "format": "br/cnab240/febraban-base",
    "connectOptions": { "known_hosts": "sftp.bank.example ssh-ed25519 AAAA..." }
  }'
```

The response (`202 Accepted`) returns a per-file outcome in fetch order. A per-file intake failure does not stop the batch. The response reports each one:

```json theme={null}
{
  "files": [
    { "name": "statement-2025-06.ret", "ingestionJobId": "550e8400-...", "transactionCount": 42 }
  ]
}
```

A transport-level failure (endpoint unreachable or credential rejected) returns `503`.

## Inspect job errors

***

After an import, list the stored per-row parse/normalization errors for a job (capped at 100 per job) to explain failed or partially-failed imports.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/imports/contexts/{contextId}/jobs/{jobId}/errors" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "items": [ ... ],
  "totalErrors": 137,
  "storedErrors": 100,
  "errorCap": 100,
  "truncated": true
}
```

`totalErrors` holds the uncapped failure total. `truncated` is `true` when the total exceeds the stored (capped) set.

## Response codes

***

| Status | Meaning |
| - | - |
| `200` | Review, list, mapping proposal, or job errors returned |
| `202` | Document enqueued / fetch accepted |
| `400` | Invalid input (empty document body, invalid pagination) |
| `403` | Consent for document extraction is not granted for your environment |
| `404` | Review or job not found |
| `409` | Invalid review state transition |
| `422` | No candidates could be extracted, or invalid request (bad status filter, missing mapping sample, structurally invalid body) |
| `503` | Extraction, review, proposal, or fetch not available in your environment, document extractor unavailable, or transport failure |


# Formats and templates
Source: https://docs.lerian.studio/en/products/matcher/imports/matcher-import-formats

Browse the built-in format catalog Matcher can parse and register per-tenant fixed-width layout templates for operator-specific files.

Matcher parses incoming files against a catalog of built-in formats and, when a file does not fit one of them, against per-tenant fixed-width **layout templates** you define. This guide covers browsing the format catalog and managing layout templates.

## The format catalog

***

The catalog gives a read-only inventory of the formats the ingestion engine can parse. It is global-first and static: built-in parsers carry no tenant, so every authenticated caller sees the same response. The catalog uses a `region → family → variant` tree that matches the canonical format descriptor axes.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/imports/formats" \
  -H "Authorization: Bearer $TOKEN"
```

Each variant carries the canonical namespaced registry key, the identity an upload or source declaration pins:

```json theme={null}
{
  "regions": [
    {
      "region": "BR",
      "families": [
        {
          "family": "cnab240",
          "variants": [
            { "variant": "febraban-base", "key": "br/cnab240/febraban-base" }
          ]
        }
      ]
    },
    {
      "region": "XX",
      "families": [
        {
          "family": "camt",
          "variants": [
            { "variant": "camt053", "key": "xx/camt/camt053" }
          ]
        }
      ]
    }
  ]
}
```

Regions use the ISO-3166 alpha-2 code (uppercased), or `XX` for region-neutral formats. Even a single-canonical-layout family (for example `camt`) names its layout as the `variant` (`camt053` above).

The built-in catalog holds these format keys:

| Family | Format keys |
| - | - |
| Generic (region-neutral) | `xx/delimited/generic` (CSV), `xx/json/generic`, `xx/xml/generic`, `xx/ofx/generic`, `xx/camt/camt053` |
| CNAB | `br/cnab240/febraban-base`, `br/cnab240/pagamento`, `br/cnab400/febraban-base` |
| Acquirer EDI | `br/acquirer_edi/cielo-v15`, `br/acquirer_edi/rede`, `br/acquirer_edi/getnet-v10-1`, `br/acquirer_edi/stone-xml`, `br/acquirer_edi/adyen`, `br/acquirer_edi/vero-bknfin1`, `br/acquirer_edi/vero-bknfin2` |
| Acquirer CSV | `br/acquirer_csv/stone-pix`, `br/acquirer_csv/mercadopago` |
| Receivables | `br/receivables/tag` |

> [!NOTE]
>
> The catalog takes no path, query, or body parameters. The tenant has no effect on the built-in catalog.

## Layout templates

***

When a file uses an operator- or brand-specific fixed-width layout that no built-in parser covers, register a layout template. A template namespaces a positional layout under the `{region, family, variant}` axes. The parse path resolves it as an additive layout source for your tenant.

Every submission and edit runs through a well-formedness gate before storage. Overrun, overlap, missing-required fields, a mis-marked money column, or an unknown `kind` reject with `422`. A zero-field record rejects with `400`. Matcher never stores that template. Matcher does not use a template whose key matches a built-in format.

> [!NOTE]
>
> Money third rail: the field named `amount` is the money column, and it must declare `kind: "decimal"`. The submission gate rejects an `amount` field that omits or mis-marks its kind. Matcher reads `amount` as a number with an explicit decimal point and applies no implied decimal places: `000000010050` reads as `10050`.

### Create a template

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/imports/formats/templates" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "region": "BR",
    "family": "cnab400",
    "variant": "acme-cobranca",
    "discriminatorStart": 0,
    "discriminatorLength": 1,
    "records": [
      {
        "recordType": "1",
        "width": 33,
        "fields": [
          { "name": "external_id", "startByte": 1, "length": 10, "kind": "string" },
          { "name": "amount", "startByte": 11, "length": 12, "kind": "decimal" },
          { "name": "date", "startByte": 23, "length": 10, "kind": "date" }
        ]
      }
    ],
    "requiredFields": ["external_id", "amount", "date"]
  }'
```

Field values:

* `region`: ISO alpha-2 region (uppercased) or `XX`.
* `family`: closed-enum format family the template namespaces under.
* `variant`: open operator/brand axis (must be non-blank).
* `discriminatorStart` / `discriminatorLength`: the byte range the parser reads to select a record type.
* `records[]`: each record type with its fixed `width` (bytes) and ordered positional `fields`. Offsets are zero-based.
* `fields[].name`: `external_id`, `amount`, `currency`, `date`, and `description` map to the transaction. Every other name goes into metadata. Without a `currency` field, the currency is `BRL`.
* `fields[].kind`: `string`, `decimal` (money/numeric verbatim token, parsed downstream), or `date`.
* `requiredFields` (optional): field names the variant must declare across its record types.

A successful create returns `201` with the stored template, including its `formatKey` (for example `br/cnab400/acme-cobranca`), the discriminator, the full positional layout, and `recordWidths`.

### List and get templates

```bash theme={null}
# List every active template on the tenant (unpaginated)
curl -X GET "https://api.matcher.example.com/v1/imports/formats/templates" \
  -H "Authorization: Bearer $TOKEN"

# Get one template by id
curl -X GET "https://api.matcher.example.com/v1/imports/formats/templates/{templateId}" \
  -H "Authorization: Bearer $TOKEN"
```

The list has no pagination, because layout templates form a bounded operator config.

### Update and delete a template

`PUT` is a full replace, not a sparse patch. The byte-range invariants are whole-layout properties. The replacement runs through the same well-formedness gate the create path enforces. A failing layout rejects with `422`, and the stored template stays unchanged.

```bash theme={null}
curl -X PUT "https://api.matcher.example.com/v1/imports/formats/templates/{templateId}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "region": "BR", "family": "cnab400", "variant": "acme-cobranca", "discriminatorStart": 0, "discriminatorLength": 1, "records": [ ... ] }'
```

```bash theme={null}
# Soft-delete, freeing the format/variant key for reuse
curl -X DELETE "https://api.matcher.example.com/v1/imports/formats/templates/{templateId}" \
  -H "Authorization: Bearer $TOKEN"
```

Delete responds `204`. A missing template returns `404`.

## Response codes

***

| Status | Meaning |
| - | - |
| `200` | Catalog, template list, get, or update returned |
| `201` | Template created |
| `204` | Template soft-deleted |
| `400` | Structurally malformed field/layout (including a zero-field record) |
| `404` | Template not found |
| `409` | Format/variant key already claimed |
| `422` | Layout failed the well-formedness gate (overrun, overlap, missing-required, mis-marked money), a field has an unknown `kind`, or a required body field is missing |
| `503` | Format catalog or template store not wired on this deployment |


# Aggregator connections
Source: https://docs.lerian.studio/en/products/matcher/integrations/matcher-aggregator-connections

Provision Open-Finance data-aggregator connections (Pluggy, Belvo), test them, browse connector types, and mint webhook tokens for inbound pulls.

Aggregator connections let Matcher pull transaction data from Open-Finance data aggregators (Pluggy, Belvo). You create a connection with a sealed credential, link a reconciliation source to it, and mint a webhook token bound to the connection. The aggregator's webhooks then drive inbound pulls. This guide covers the full lifecycle.

> [!NOTE]
>
> Credentials (`clientId`/`secret`) are inbound-only: Matcher seals them before persistence and never returns them in a response, a log, or an error. The tenant always comes from the JWT, never from the request body.

## Create a connection

***

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/discovery/aggregator-connections" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor": "pluggy",
    "configName": "pluggy-main",
    "baseUrl": "https://api.pluggy.ai",
    "accountRef": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "clientId": "...",
    "secret": "..."
  }'
```

Field values:

* `vendor`: `pluggy` or `belvo`.
* `configName`: unique (tenant-scoped) connection identity. A duplicate is a `409`. The webhook token-mint endpoint binds a token to this name.
* `baseUrl`: vendor API base URL, stored as the connection host.
* `accountRef`: opaque vendor account reference (Pluggy `itemId`, Belvo link id) threaded onto the webhook pull. It is optional. Leave it out to connect the account through [hosted consent](#bind-an-account-through-hosted-consent).
* `clientId` / `secret`: aggregator API credential, sealed and never emitted.

A successful create returns `201` with the secret-free connection descriptor:

```json theme={null}
{
  "vendor": "pluggy",
  "configName": "pluggy-main",
  "baseUrl": "https://api.pluggy.ai",
  "accountRef": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "awaitingConsent": false
}
```

## Link a reconciliation source

***

Matcher ingests the pulled data into the reconciliation source that names the connection. On exactly one source, set `config.connection_config_name` to the `configName` of the connection:

```json theme={null}
{
  "name": "Pluggy Main Account",
  "type": "BANK",
  "side": "RIGHT",
  "config": {
    "connection_config_name": "pluggy-main"
  }
}
```

> [!TIP]
>
> API Reference: [Create source](/en/reference/products/matcher/create-source)

## List, get, update, delete

***

```bash theme={null}
# List (cursor-paginated, secret-free)
curl -X GET "https://api.matcher.example.com/v1/discovery/aggregator-connections?limit=20" \
  -H "Authorization: Bearer $TOKEN"

# Get by opaque id
curl -X GET "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}" \
  -H "Authorization: Bearer $TOKEN"
```

Each list row carries `id`, `vendor`, `configName`, `baseUrl`, `accountRef`, `testable`, and `awaitingConsent`.

### Update

Edit an existing connection by id so a mistyped `baseUrl` is not permanent. The vendor is immutable. The credential is optional: supply both `clientId` and `secret` to rotate the sealed credential, or omit both to leave the stored secret intact. Supplying exactly one is a `400`. The other fields are optional too: a field you leave out keeps its stored value.

```bash theme={null}
curl -X PUT "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "configName": "pluggy-main",
    "baseUrl": "https://api.pluggy.ai",
    "accountRef": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
  }'
```

### Bind an account through hosted consent

A connection created without `accountRef` waits for consent: it shows `"awaitingConsent": true`. `POST /v1/discovery/aggregator-connections/{id}/connect-token` returns a token for the consent widget of the vendor. Send the item or link id that the widget returns as `accountRef` in the update call above. [Discovery](/en/products/matcher/integrations/matcher-discovery#connect-an-account-through-hosted-consent) describes the full flow.

### Delete

```bash theme={null}
curl -X DELETE "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}" \
  -H "Authorization: Bearer $TOKEN"
```

Delete soft-deletes the connection (`204`), freeing its config name for reuse. A non-aggregator connection id returns `404` on any by-id operation. This surface never confirms the existence of a non-aggregator row.

## Test a connection

***

Run a live connectivity check for an existing connection using its already-sealed credential, addressed by `configName`. Matcher reads the vendor from the stored connection. This call takes no credential and returns none.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/discovery/aggregator-connections/test" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "configName": "pluggy-main" }'
```

```json theme={null}
{ "vendor": "pluggy", "configName": "pluggy-main", "healthy": true }
```

> [!NOTE]
>
> A credentials-don't-work outcome is an expected test result surfaced as `"healthy": false` with a `200`, not an error. A missing connection returns `404`. Matcher cannot test Belvo connections, so a Belvo connection returns `422` (`MTCH-0210`). A connection that waits for consent returns `422` (`MTCH-0211`).

## Connector types

***

List the connector types the engine registry has registered for this deployment, each tagged with a backend-derived category (`database` or `rest`). The list reflects the live registry. Only connectors registered at boot appear. It drives the connection form's type-select.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/discovery/connector-types" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "types": [
    { "type": "POSTGRESQL", "category": "database" },
    { "type": "STRIPE", "category": "rest", "requiredFields": ["apiKey"] }
  ]
}
```

Each `rest` entry lists in `requiredFields` the credential fields that a [REST connection](/en/products/matcher/integrations/matcher-discovery#create-a-rest-connection) of that type needs. This list excludes aggregator-vendor types (Pluggy/Belvo). The aggregator-connections surface above provisions them.

## Mint a webhook token

***

Mint a webhook token bound to an existing aggregator connection. The response carries the raw token and its provider-facing webhook URL once. Matcher stores only the token's SHA-256 hash.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/discovery/webhooks/tokens" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor": "pluggy",
    "connection_config_name": "pluggy-main"
  }'
```

```json theme={null}
{
  "token": "<raw-token-shown-once>",
  "webhook_url": "https://api.matcher.example.com/v1/discovery/webhooks/pluggy/<raw-token>",
  "vendor": "pluggy"
}
```

Configure the returned `webhook_url` in the aggregator's dashboard. A missing target connection returns `404`.

Matcher verifies each vendor delivery by an HMAC-SHA256 signature of the raw body in `X-Webhook-Signature`, or by source IP. A delivery that fails verification receives `401`.

## Response codes

***

| Status | Meaning |
| - | - |
| `200` | Get, list, test, or connector-types returned |
| `201` | Connection created, webhook token minted, or consent token minted |
| `204` | Connection soft-deleted |
| `400` | Partial credential pair, malformed credential, or invalid pagination cursor |
| `401` | Tenant could not be resolved |
| `404` | Connection not found (or not an aggregator) |
| `422` | Request fails validation, for example a missing field or a vendor other than `pluggy` or `belvo` |
| `422` (`MTCH-0210`) | Matcher cannot test this vendor (Belvo) |
| `422` (`MTCH-0211`) | The connection waits for consent, so no test ran |
| `422` (`MTCH-0212`) | The vendor did not issue a consent token |
| `422` (`MTCH-0213`) | Matcher has no consent flow for this vendor |
| `409` | Connection with that config name already exists |


# Discovery
Source: https://docs.lerian.studio/en/products/matcher/integrations/matcher-discovery

Use Discovery to detect external data sources, inspect their schemas, and pull transactions into Matcher automatically.

Discovery automates data source detection and extraction through Matcher's embedded extraction engine. Instead of manually uploading files, Discovery connects to external systems, identifies available data, and extracts transactions directly into Matcher.

## What Discovery solves

***

With manual file uploads, teams export files, transfer them, monitor for failures, and re-upload when something goes wrong. This process is time-consuming, error-prone, and breaks when data volume grows.

Discovery replaces the manual pipeline. It connects to external systems through the extraction engine, reads their schemas, and pulls transactions into Matcher on demand.

## How Discovery works

***

Discovery runs inside Matcher. The embedded engine manages connections to external databases and runs extractions locally. Discovery exposes those connections, coordinates the extraction process, and hands results directly to Ingestion.

The workflow has eight steps:

1. **Create a connection**: Register a database with its address and user, or a REST connection to a provider API.
2. **Check status**: See how many connections the tenant has and when they last synced.
3. **Browse connections**: See the tenant's database connections.
4. **Inspect a connection**: Review the schema to understand what fields are available.
5. **Test a connection**: Validate the connection before committing to an extraction.
6. **Create an extraction**: Request that Matcher pull data from a specific source.
7. **Monitor progress**: Track extraction status as data flows in.
8. **Refresh connections**: Re-sync connections from the embedded engine.

## Discovery workflow

***

### Create a connection

Register a database connection for the tenant.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/discovery/connections" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "configName": "prod-ledger-db",
    "databaseType": "POSTGRESQL",
    "host": "db.internal.example.com",
    "port": 5432,
    "databaseName": "ledger",
    "userName": "matcher_ro",
    "password": "..."
  }'
```

`configName`, `databaseType`, `host`, `port`, `databaseName`, and `userName` are required. `schema` and `password` are optional, and Matcher never returns `password`. A successful create returns `201`. Update a connection with `PATCH` and delete it with `DELETE` on `/v1/discovery/connections/{connectionId}`.

### Create a REST connection

Create a REST connection to extract data from a provider API instead of a database.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/discovery/rest-connections" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "configName": "stripe-main",
    "connectorType": "STRIPE",
    "apiKey": "..."
  }'
```

`configName` and `connectorType` are required. `connectorType` is `PAGBANK`, `STRIPE`, or `PIX_BCB`. `baseURL` is optional and sets the provider API address for this connection. Each connector type also requires its own credential fields:

| `connectorType` | Required credential fields |
| - | - |
| `PAGBANK` | `establishmentID`, `ediToken` |
| `STRIPE` | `apiKey` |
| `PIX_BCB` | `clientID`, `clientSecret`, `clientCert`, `clientKey` |

Matcher stores the credentials encrypted. [List connector types](#list-connector-types) returns the same field names as `requiredFields`. A successful create returns `201`, and the connection appears in the connection list like any other connection. On a REST connection, `PATCH` accepts only `configName`. To change anything else, delete the connection and create it again.

### Check Discovery status

Read the tenant's connection count and the time of the last sync.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/discovery/status" \
  -H "Authorization: Bearer $TOKEN"
```

> [!TIP]
>
> API Reference: [Get Discovery status](/en/reference/products/matcher/discovery-status)

### Browse connections

List all data sources available through the embedded extraction engine.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/discovery/connections" \
  -H "Authorization: Bearer $TOKEN"
```

The response lists each database connection with its `configName`, `databaseType`, host, database, `status`, and whether its schema was discovered.

> [!TIP]
>
> API Reference: [List connections](/en/reference/products/matcher/list-discovery-connections)

### Get a connection

Retrieve a single discovered connection by its internal identifier:

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/discovery/connections/{connectionId}" \
  -H "Authorization: Bearer $TOKEN"
```

`GET /v1/discovery/connections/{connectionId}` returns the same fields for one connection. Use it when you already hold a `connectionId`, for example from a source binding's query rail. It gives the current details without a list of every connection.

> [!TIP]
>
> API Reference: [Get discovery connection](/en/reference/products/matcher/retrieve-discovery-connection)

### Inspect a connection

Before you extract, review the schema of a specific connection to understand what data fields are available.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/discovery/connections/{connectionId}/schema" \
  -H "Authorization: Bearer $TOKEN"
```

Use schema inspection to confirm that required fields (transaction IDs, amounts, dates, references) exist before building field mappings.

> [!TIP]
>
> API Reference: [Get connection schema](/en/reference/products/matcher/get-connection-schema)

### Get schema history

Read the earlier generations of a connection's schema, oldest first.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/discovery/connections/{connectionId}/schema/history" \
  -H "Authorization: Bearer $TOKEN"
```

The response carries `connectionId` and a `generations` list. Each generation carries `archivedAt`, the time it stopped being the live schema, and its `tables`. When all tables of a generation share one cause, the generation also carries `retirementCause`:

| `retirementCause` | Meaning |
| - | - |
| `ABSENT_FROM_CATALOG` | The catalog of the source stopped listing the table. |
| `COLUMN_SET_SUPERSEDED` | The catalog still listed the table, but with a different set of columns. |
| `CONNECTION_RETIRED` | Someone retired the connection. |
| `UNKNOWN_LEGACY` | An earlier release archived the generation and recorded no cause. |

An unknown connection returns `404`.

### Test a connection

Validate that Matcher can reach and read from a connection before creating an extraction.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/discovery/connections/{connectionId}/test" \
  -H "Authorization: Bearer $TOKEN"
```

The test connects to the database and pings it. It does not check read access to tables. A failed test returns `200` with `"healthy": false` and an `errorMessage`. Always test before creating an extraction, especially for new or recently modified connections.

> [!TIP]
>
> API Reference: [Test connection](/en/reference/products/matcher/test-discovery-connection)

### Create an extraction

Request that Matcher pull data from a connection. The request names no context. Matcher ingests the result into the `FETCHER` source linked to the connection.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/discovery/connections/{connectionId}/extractions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tables": {
      "public.transactions": {}
    }
  }'
```

Each key in `tables` must be a table name exactly as the connection's schema lists it. The response returns an extraction ID. Use it to monitor progress.

> [!TIP]
>
> API Reference: [Create extraction](/en/reference/products/matcher/create-extraction)

### Monitor extraction progress

Track the status of an active extraction by polling its status with `GET`.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/discovery/extractions/{extractionId}" \
  -H "Authorization: Bearer $TOKEN"
```

Extraction status transitions from `PENDING` → `SUBMITTED` → `EXTRACTING` → `COMPLETE` (or `FAILED`). An extraction fails when its result exceeds 2 GiB. The response carries the extraction `status`, an `errorMessage` when it failed, and the linked `ingestionJobId` once the extraction bridges into ingestion.

> [!TIP]
>
> API Reference: [Get extraction](/en/reference/products/matcher/retrieve-extraction)

### Refresh available connections

Refresh re-syncs the tenant's connections from the embedded engine. A connection that the engine no longer reports becomes `UNREACHABLE`.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/discovery/refresh" \
  -H "Authorization: Bearer $TOKEN"
```

> [!TIP]
>
> API Reference: [Refresh connections](/en/reference/products/matcher/refresh-discovery)

### List connector types

List the connector (datasource) types the engine registry has registered for your environment. Each entry carries a backend-derived `category` (`database` or `rest`). The registry is live. Only connectors registered at boot appear. This list excludes aggregator vendors (Pluggy/Belvo). Provision those through the aggregator-connections surface below.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/discovery/connector-types" \
  -H "Authorization: Bearer $TOKEN"
```

#### Response

```json theme={null}
{
  "types": [
    { "type": "POSTGRESQL", "category": "database" },
    { "type": "MYSQL", "category": "database" }
  ]
}
```

## Aggregator connections (Open Finance)

***

Open-Finance data-aggregator connections (Pluggy or Belvo) let Matcher pull transactions from bank aggregators. Credential material (`clientId`/`secret`) is sealed on write and never returned. Every read is secret-free by construction.

### Create an aggregator connection

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/discovery/aggregator-connections" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor": "pluggy",
    "configName": "pluggy-main",
    "baseUrl": "https://api.pluggy.ai",
    "accountRef": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "clientId": "...",
    "secret": "..."
  }'
```

Send five required fields: `vendor`, `configName`, `baseUrl`, `clientId`, and `secret`. The `accountRef` field (the Pluggy item id or Belvo link id) is optional. Without it, Matcher creates a connection that waits for consent. See [Connect an account through hosted consent](#connect-an-account-through-hosted-consent).

The `vendor` field is one of `pluggy` or `belvo`. The `configName` field is the tenant-scoped name the webhook token-mint endpoint binds to. A successful create returns 201 with a secret-free connection.

#### Response

```json theme={null}
{
  "vendor": "pluggy",
  "configName": "pluggy-main",
  "baseUrl": "https://api.pluggy.ai",
  "accountRef": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "awaitingConsent": false
}
```

### List, get, update, and delete

```bash theme={null}
# List (cursor-paginated, secret-free)
curl -X GET "https://api.matcher.example.com/v1/discovery/aggregator-connections" \
  -H "Authorization: Bearer $TOKEN"

# Get one by id
curl -X GET "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}" \
  -H "Authorization: Bearer $TOKEN"

# Update (PUT). vendor is immutable. Supply clientId+secret together to rotate
# the sealed credential, or omit both to keep the stored secret intact.
curl -X PUT "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "configName": "pluggy-main",
    "baseUrl": "https://api.pluggy.ai",
    "accountRef": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
  }'

# Delete (soft-delete; frees the config name for reuse). Returns 204.
curl -X DELETE "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}" \
  -H "Authorization: Bearer $TOKEN"
```

### Connect an account through hosted consent

Use this flow when you do not have the vendor's item or link id yet. The end customer authorizes access in the vendor's own consent widget.

1. Create the connection without `accountRef`. The response carries `"awaitingConsent": true`.
2. Get the connection `id` from the list response.
3. Request a consent token for the connection. The request has no body.
4. Open the vendor's consent widget with the `token` from the response.
5. Send the item or link id that the widget returns as `accountRef` in `PUT /v1/discovery/aggregator-connections/{id}`. You do not need to send other fields.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}/connect-token" \
  -H "Authorization: Bearer $TOKEN"
```

The `201` response carries `vendor`, `configName`, `token`, `expiresAt`, `reconsent`, and `accountRef`. For a connection that already has an `accountRef`, the token renews consent for that same item or link. Then `reconsent` is `true`, and `accountRef` holds the bound id. Give that `accountRef` to the update mode of the widget.

The answer shows the consent token once, and Matcher does not store it. Use it before `expiresAt`. After that time, the vendor refuses it.

A connection id that is not an aggregator connection returns `404`. If the vendor does not issue a token, the call returns `422` (`MTCH-0212`). If Matcher has no consent flow for the vendor, the call returns `422` (`MTCH-0213`).

### Test an aggregator connection

Run a live connectivity check against an existing connection's already-sealed credential. Send only the `configName`: Matcher reads the vendor from the stored connection. This call takes no credential and returns none.

Invalid stored credentials give an expected test result: `200` with `"healthy": false`, not an error. A missing connection returns `404`. Matcher cannot test Belvo connections, so a Belvo connection returns `422` (`MTCH-0210`). A connection that waits for consent returns `422` (`MTCH-0211`). In these cases, no test runs. Each row of the list response carries `testable`, which tells you if a test can run.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/discovery/aggregator-connections/test" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "configName": "pluggy-main"
  }'
```

#### Response

```json theme={null}
{
  "vendor": "pluggy",
  "configName": "pluggy-main",
  "healthy": true
}
```

## Aggregator webhook tokens

***

Aggregators push data change signals to Matcher via webhooks. Mint an opaque token bound to an aggregator connection, then configure the returned URL in the vendor dashboard.

### Mint a webhook token

Matcher returns the raw token and its provider-facing URL exactly once. Matcher stores only the token's SHA-256 hash.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/discovery/webhooks/tokens" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor": "pluggy",
    "connection_config_name": "pluggy-main"
  }'
```

#### Response

```json theme={null}
{
  "vendor": "pluggy",
  "token": "<raw-token-shown-once>",
  "webhook_url": "https://api.matcher.example.com/v1/discovery/webhooks/pluggy/<raw-token>"
}
```

### Receiving webhooks

The vendor calls `POST /v1/discovery/webhooks/{provider}/{webhookToken}` (no operator JWT). Two layers authenticate it: the opaque path token plus a per-provider source check. When the provider has an HMAC secret, that check is a valid hex HMAC-SHA256 of the raw body in the `X-Webhook-Signature` header. Otherwise it is membership in the provider's source-IP allowlist. Both layers fail closed.

A valid first delivery returns 202 Accepted. Matcher then pulls the signaled data asynchronously into the ingestion pipeline. A redelivery of an event that Matcher already received returns 200 OK.

## Best practices

***

> **Always test connections before extracting**
>
> A failed extraction mid-run is harder to recover from than a failed test. Test every connection before creating an extraction, especially when connecting to a new source or after a credential rotation.

> **Inspect schemas before mapping fields**
>
> Field names vary across systems. A bank might call the transaction date `value_date` while your ledger uses `posting_date`. Check the schema before configuring field mappings to avoid silent mismatches.

> **Monitor extractions actively for large datasets**
>
> Large extractions take time. Don't assume completion. Poll the extraction status, then check the linked ingestion job before starting a match run. Starting a run on incomplete data generates incorrect exceptions.

## Next steps

***

> **[External sources](/en/products/matcher/integrations/matcher-external-sources)**
>
> Configure the external data sources that Discovery connects to.

> **[Field mapping](/en/products/matcher/configuration/matcher-field-mapping)**
>
> Map fields from extracted data to Matcher's transaction model.

> **[Discovery API reference](/en/reference/products/matcher/discovery-status)**
>
> Full API reference for Discovery endpoints.


# External sources
Source: https://docs.lerian.studio/en/products/matcher/integrations/matcher-external-sources

Connect banks, payment gateways like Stripe and Adyen, ERPs such as SAP or Oracle, and card networks to Matcher via LEDGER, BANK, GATEWAY, or CUSTOM types.

External sources provide transaction data from systems outside your organization. This guide covers how to connect banks, payment gateways, and other external systems to Matcher.

## Supported source types

***

Matcher supports five source types. Each represents a category of data origin:

| Type | Description | Typical use |
| - | - | - |
| `LEDGER` | Internal ledger | Internal accounting systems (including Midaz) |
| `BANK` | Bank statement feed | External bank feeds |
| `GATEWAY` | Payment gateway | Payment processors (Stripe, Adyen, PayPal) |
| `CUSTOM` | Bespoke feed | ERPs, card networks, or any other data source |
| `FETCHER` | Discovery-engine pull | Data that [Discovery](/en/products/matcher/integrations/matcher-discovery) extracts from a connection |

## Ingestion methods

***

Transaction data reaches Matcher through several paths:

| Method | Use Case |
| - | - |
| **File upload** | Manual uploads (CSV, JSON, XML, OFX, camt.053, CNAB, acquirer EDIs) |
| **Transport fetch** | Matcher pulls files from a configured transport (for example SFTP) and ingests them |
| **Discovery extraction** | [Discovery](/en/products/matcher/integrations/matcher-discovery) extracts data from discovered connections into ingestion |
| **Aggregator webhooks** | [Open-Finance aggregators](/en/products/matcher/integrations/matcher-aggregator-connections) signal new data, pulled asynchronously |

## File-based ingestion

***

The most common method for bank statements and ERP exports.

### Manual upload

Use the file upload endpoint to import transaction files manually.

> [!TIP]
>
> API Reference: [Upload transaction file](/en/reference/products/matcher/upload-transaction-file)

## Bank connections

***

### Standard Bank format

Most banks provide statements in a format Matcher parses natively (CSV, OFX, camt.053, or the Brazilian CNAB layouts):

```json theme={null}
{
  "name": "Chase Business Account",
  "type": "BANK",
  "side": "RIGHT",
  "config": {
    "bank_name": "Chase",
    "account_number": "****1234",
    "currency": "USD",
    "statement_format": "CSV",
    "timezone": "America/New_York"
  }
}
```

> [!NOTE]
>
> The `config` object is free-form descriptive metadata. Matcher stores it but does not interpret keys like `bank_name` or `statement_format`. Instead, Matcher acts on these reserved keys when you set them: `dialect`, `fail_on_error_rate_percent`, `duplicate_policy`, `duplicate_key`, `blank_external_id`, `camt053`, `connection_id`, and `connection_config_name`.

> [!TIP]
>
> API Reference: [Create source](/en/reference/products/matcher/create-source)

## ERP and custom connections

***

Use the `CUSTOM` source type for ERP systems (SAP, Oracle, NetSuite, etc.) and any other data source that doesn't fit the `BANK`, `LEDGER`, or `GATEWAY` categories.

### Example: ERP source

```json theme={null}
{
  "name": "SAP S/4HANA",
  "type": "CUSTOM",
  "side": "LEFT",
  "config": {
    "erp_type": "SAP",
    "company_codes": ["1000", "2000"]
  }
}
```

Export transaction data from your ERP and upload it through Matcher's file upload endpoint. Use [field mapping](/en/products/matcher/configuration/matcher-field-mapping) to translate ERP-specific fields into Matcher's canonical format.

## Payment processor connections

***

### Stripe

```json theme={null}
{
  "name": "Stripe Payments",
  "type": "GATEWAY",
  "side": "RIGHT",
  "config": {
    "provider": "stripe"
  }
}
```

### Adyen

```json theme={null}
{
  "name": "Adyen Settlements",
  "type": "GATEWAY",
  "side": "RIGHT",
  "config": {
    "provider": "adyen",
    "merchant_account": "CompanyECOM"
  }
}
```

Export settlement reports from your payment processor and upload them through Matcher's file upload endpoint. For Stripe, PagBank, and Pix BCB, Matcher can also extract the data through a [REST connection](/en/products/matcher/integrations/matcher-discovery#create-a-rest-connection).

### Card networks

For card network settlement files (Visa, Mastercard, Elo), use the `CUSTOM` source type:

```json theme={null}
{
  "name": "Visa Settlement",
  "type": "CUSTOM",
  "side": "RIGHT",
  "config": {
    "network": "VISA"
  }
}
```

## Connection security

***

### Webhook signatures

Matcher verifies inbound aggregator webhooks with an HMAC-SHA256 signature or a source IP allowlist, as [Aggregator connections](/en/products/matcher/integrations/matcher-aggregator-connections) describes. Source entities do not have a `settings.webhook` configuration.

## Data format requirements

***

### Required fields

Field maps use a closed canonical vocabulary: the mapping *keys* are fixed, and the *values* name the source's raw column. These canonical keys are required:

| Canonical key | Type | Description |
| - | - | - |
| `external_id` | String | Source-system transaction identifier |
| `amount` | Decimal | Transaction amount |
| `currency` | String | ISO 4217 code |
| `date` | Date | Transaction date |

### Optional fields

| Canonical key | Type | Description |
| - | - | - |
| `description` | String | Reference/description text (feeds the transaction's description column) |
| `fee_amount` | Decimal | Fee slot: source column carrying the fee amount |
| `fee_currency` | String | Fee slot: source column carrying the fee currency |
| `direction` | Object | Debit or credit indicator: `{column, debit, credit}` |

Matcher accepts no other keys.

Use `direction` when a file marks each row as debit or credit in a separate column. `column` names that column, and `debit` and `credit` are the values it holds. Matcher imports a debit row with a negative amount and a credit row with a positive one. When you map `direction`, the amount cells must carry no sign. A signed amount, an empty direction cell, or an unknown direction value rejects the row. Matcher applies `direction` to CSV, JSON, and XML input only.

### Field mapping

Manage field maps with the dedicated endpoint (not the source's `config` object). The request body is a single `mapping` object of `{ canonicalKey: sourceColumnName }` pairs:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{sourceId}/field-maps" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mapping": {
     "external_id": "TXN_ID",
     "amount": "trans_amount",
     "currency": "CCY",
     "date": "POST_DATE",
     "description": "memo",
     "fee_amount": "mdr_fee",
     "fee_currency": "fee_ccy"
   }
 }'
```

Refer to [Field Mapping](/en/products/matcher/configuration/matcher-field-mapping) for details.

## Best practices

***

> **Validate files before uploading**
>
> Check that uploaded files contain columns for the required canonical fields (external\_id, amount, currency, date) before uploading. This prevents ingestion errors.

> **Use consistent file formats**
>
> Standardize on a single format (CSV, JSON, or XML) per source to simplify field mapping and reduce errors.

> **Secure credentials properly**
>
> Never include credentials in configuration payloads.

> **Test with sample data first**
>
> Validate field mapping and data quality with sample files before uploading production data.

## Next steps

***

> **[Field Mapping](/en/products/matcher/configuration/matcher-field-mapping)**
>
> Configure how source fields map to Matcher.

> **[Uploading Files](/en/products/matcher/daily-reconciliation/matcher-uploading-files)**
>
> Manual file upload procedures.


# Matcher and Midaz
Source: https://docs.lerian.studio/en/products/matcher/integrations/matcher-midaz-integration

See how Matcher works alongside Midaz Ledger: two independent services that share data through exports and imports rather than a live API connection.

> [!NOTE]
>
> There's no direct Matcher-to-Midaz connector. Matcher is a stand-alone reconciliation service. It doesn't open a live connection to Midaz, and it has no Midaz-specific configuration. This page explains how the two products work together conceptually.

Matcher and [Midaz](/en/products/midaz/what-is-midaz) are separate Lerian services with distinct jobs:

* **Midaz** is the ledger, the system of record for balances and postings.
* **Matcher** is the reconciliation engine. It compares two independent datasets and reports what agrees, what doesn't, and why.

They complement each other and stay decoupled. You use Midaz and Matcher together by reconciling ledger data against an external dataset (a bank statement, a gateway settlement report). The data moves between them by export and import, with no real-time link.

## How they fit together

***

A typical Lerian reconciliation flow:

1. **Midaz records postings.** Midaz books transactions in the ledger as usual.
2. **You export the ledger data** for the period you want to reconcile (for example, a day's cash-account entries).
3. **You import that export into Matcher** as one side of a context, a source of type `LEDGER`.
4. **You import the counterparty data** (the bank statement or gateway report) as the other side.
5. **Matcher matches the two sides** using your match rules and surfaces exceptions for review.

Midaz is the origin of one dataset. The bank or gateway is the origin of the other. Matcher never talks to Midaz directly. It works from the exported data you feed it.

## Modeling Midaz as a source

***

Inside a Matcher context, ledger data from Midaz is represented by a source with type `LEDGER`. `LEDGER` is Matcher's category for "internal ledger / accounting system" data. It is not a Midaz driver.

```json theme={null}
{
  "name": "Midaz Cash Ledger",
  "type": "LEDGER",
  "side": "LEFT",
  "config": {}
}
```

> [!TIP]
>
> API Reference: [Create source](/en/reference/products/matcher/create-source)

The other side of the context is the external dataset you're reconciling against, usually a `BANK` or `GATEWAY` source on the opposite `side`.

Source types available in Matcher:

| Type | Meaning |
| - | - |
| `LEDGER` | Internal ledger / accounting system (e.g. Midaz exports) |
| `BANK` | Bank statement feed |
| `GATEWAY` | Payment gateway report |
| `CUSTOM` | Any other bespoke feed |
| `FETCHER` | Discovery-engine pull |

## Getting ledger data into Matcher

***

Matcher ingests the data you export from Midaz the same way it ingests any other source. There's no Midaz-specific transport.

* **File upload.** Export ledger entries (CSV/JSON) and upload the file to the source. This is the most common path.
* **Discovery-engine query rail.** For sources bound on the `query` rail, Matcher pulls rows through a discovery-engine connection instead of a file. This is a generic ingestion rail, not a Midaz connector.

Then define a [field map](/en/products/matcher/configuration/matcher-field-mapping) that renames the exported columns to Matcher's canonical fields (`external_id`, `amount`, `currency`, `date`, and optional `description`, `fee_amount`, `fee_currency`).

A Midaz operation carries its type, `DEBIT` or `CREDIT`. If your export keeps the type in its own column and the amount unsigned, map that column with the optional `direction` key. Matcher then imports a debit row with a negative amount and a credit row with a positive one.

> [!TIP]
>
> API Reference: [Upload transaction file](/en/reference/products/matcher/upload-transaction-file)

### Custom field mapping

Most ledger columns map straight across. Field-map lookups are flat. A mapping value must name a column that exists at the top level of the exported row, so a value that lives inside transaction metadata must be exported as its own flat column before Matcher can match on it.

For example, Brazil's Pix `endToEndId` is stored in Midaz transaction metadata. To reconcile on it, export it as a flat column (here `endToEndId`) and map `external_id` to that column. `external_id` is the reference the matching engine compares across sources, so both sides of the context must map it to a value they share (the `description` key is display-only and never feeds matching):

```json theme={null}
{
  "mapping": {
    "external_id": "endToEndId",
    "amount": "amount",
    "currency": "asset_code",
    "date": "created_at"
  }
}
```

Every field map must declare all four required canonical keys (`external_id`, `amount`, `currency`, `date`) explicitly. No automatic mapping happens. See [Field mapping](/en/products/matcher/configuration/matcher-field-mapping) for the full canonical vocabulary.

## Shared platform foundations

***

Although there's no live integration, Matcher is built for the same platform as Midaz and mirrors several of its patterns:

* **Authentication.** Matcher uses the shared Lerian auth stack, so the same Access Manager and tokens used across the platform apply.
* **Tenant isolation.** Matcher keeps each tenant's data separate.

These commonalities are platform-level and form no Matcher-to-Midaz data channel.

## What this integration is *not*

***

* There is no real-time sync mode and no `account_filter` for a Midaz source.
* Matcher doesn't subscribe to Midaz events or open a gRPC/HTTP connection to Midaz.

Reconciling Midaz data means exporting it and importing it into Matcher like any other source.

## Best practices

***

> **Export the smallest relevant slice**
>
> Export only the ledger accounts and period you need to reconcile. Smaller, targeted exports keep contexts fast and matching precise.

> **Keep export cadence aligned with reconciliation**
>
> If you reconcile daily, export daily. Match the export schedule to the counterparty data (bank statement) availability.

> **Normalize before upload where you can**
>
> Produce exports whose amounts, dates, and currency codes are already in the shapes your match rules expect.

> **Carry references through metadata columns**
>
> Include stable references (invoice numbers, external IDs) as columns in the export so match rules can key on them for higher match rates.

## Next steps

***

> **[External sources](/en/products/matcher/integrations/matcher-external-sources)**
>
> Connect the bank or gateway side of the reconciliation.

> **[Field mapping](/en/products/matcher/configuration/matcher-field-mapping)**
>
> Map exported ledger columns to Matcher's canonical fields.


# Webhooks and callbacks
Source: https://docs.lerian.studio/en/products/matcher/integrations/matcher-webhooks-callbacks

Consume Matcher lifecycle events from the streaming backbone, and receive resolution callbacks so external systems keep exceptions in sync.

This guide covers the events Matcher publishes and the inbound callbacks that external systems send to Matcher.

## Overview

***

* **Outbound events**: Matcher publishes its lifecycle event catalog on the platform's streaming backbone. Those events reach you as a stream, not as HTTP webhooks.
* **Inbound callbacks**: External systems, such as a ticketing tool, notify Matcher when they act on an exception. Matcher then updates the exception status.

## Outbound events

***

Matcher emits events when significant actions occur in the reconciliation process, and publishes them on the streaming backbone. Each event follows its own schema on the event stream.

### Available events

The tables below list the event catalog by domain.

**Configuration**

| Event | Trigger | Typical Use |
| - | - | - |
| `reconciliation_context.created` | Reconciliation context created | Provisioning sync |
| `reconciliation_context.updated` | Context metadata or status changed | Config change tracking |
| `reconciliation_source.created` | Source created within a context | Source onboarding |
| `match_rule.created` | Match rule created | Rule change audit |
| `match_rule.reordered` | Rule priorities reordered | Rule change audit |

**Discovery**

| Event | Trigger | Typical Use |
| - | - | - |
| `fetcher_connection.synced` | Connection and schema snapshot synchronized | Discovery monitoring |
| `fetcher_connection.unreachable` | Connection marked unreachable | Connectivity alerting |
| `extraction_request.created` | Extraction request created | Extraction monitoring |
| `extraction_request.submitted` | Extraction accepted by the extraction engine | Extraction monitoring |
| `extraction_request.completed` | Extraction completed and handed to ingestion | Data readiness |
| `extraction_request.failed` | Extraction failed | Error alerting |

**Ingestion**

| Event | Trigger | Typical Use |
| - | - | - |
| `ingestion.completed` | File import finished | Data pipeline monitoring |
| `ingestion.failed` | File import failed | Error alerting |
| `transaction.ignored` | Unmatched transaction marked ignored | Audit trail |

**Matching**

| Event | Trigger | Typical Use |
| - | - | - |
| `match_run.completed` | Match job finished | Job monitoring, reporting |
| `match_run.failed` | Match job failed | Error alerting |
| `match_group.confirmed` | Match group confirmed | Downstream updates |
| `match_group.unmatched` | Confirmed match reverted | Correction tracking |
| `transaction.matched` | Transaction marked matched | Audit logging |
| `transaction.pending_review` | Non-automatic candidate needs review | Review queue triggers |
| `fee_variance.created` | Fee variance detected | Fee investigation |

**Exceptions and disputes**

| Event | Trigger | Typical Use |
| - | - | - |
| `exception.assigned` | Exception assigned to an owner | User notification |
| `exception.resolved` | Exception resolved | Status sync |
| `exception.dispatched` | Exception dispatched to a target system | Audit trail |
| `exception.callback_processed` | External callback processed | Status sync |
| `exception.force_match_resolved` | Exception resolved via force match | Approval workflows |
| `exception.adjust_entry_resolved` | Exception resolved via adjustment entry | Audit trail |
| `exception_comment.added` | Comment added to an exception | Collaboration sync |
| `exception_comment.deleted` | Exception comment deleted | Collaboration sync |
| `dispute.opened` | Dispute opened for an exception | Dispute tracking |
| `dispute.won` | Dispute closed as won | Status sync |
| `dispute.lost` | Dispute closed as lost | Status sync |
| `evidence.submitted` | Evidence submitted to a dispute | Dispute tracking |

**Governance and reporting**

| Event | Trigger | Typical Use |
| - | - | - |
| `audit_log.created` | Audit log entry appended | Compliance monitoring |
| `archive_metadata.created` | Archive lifecycle started | Archival monitoring |
| `archive.uploaded` | Archive object uploaded | Archival monitoring |
| `archive.completed` | Archive verified and completed | Archival monitoring |
| `actor.pseudonymized` | Actor mapping pseudonymized | Compliance monitoring |
| `export_job.created` | Export job queued | Export monitoring |
| `export_job.succeeded` | Export job completed | Download readiness |
| `export_job.failed` | Export job failed | Error alerting |
| `export_job.expired` | Export artifact expired | Export lifecycle |

## Inbound callbacks

***

External systems send callbacks to Matcher to update exception status after processing. The callback endpoint accepts status updates, resolution notes, and assignee changes from any external system.

### Process a callback

The `X-Callback-Token` header authenticates the callback endpoint. An operator JWT does not authenticate it. The header carries an opaque token from the [callback credentials](#callback-credentials) surface. Every field below is mandatory. `dueAt` and `updatedAt` accept `null`, and `payload` can be an empty object:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/callback" \
 -H "X-Callback-Token: ***" \
 -H "X-Idempotency: callback-jira-1234" \
 -H "Content-Type: application/json" \
 -d '{
   "callbackType": "status_update",
   "externalSystem": "JIRA",
   "externalIssueId": "RECON-1234",
   "status": "RESOLVED",
   "resolutionNotes": "Verified: amount difference is expected bank wire fee",
   "assignee": "john.doe@company.com",
   "dueAt": null,
   "updatedAt": "2026-01-20T14:30:00Z",
   "payload": {}
 }'
```

The `externalSystem` field identifies the external system that processed the exception. Common values include `"JIRA"`, `"SERVICENOW"`, or `"WEBHOOK"`, but callbacks can report any system identifier. Omitting any of the nine required fields returns a `422`.

#### Response

```json theme={null}
{
  "status": "accepted"
}
```

> [!TIP]
>
> API Reference: [Process callback](/en/reference/products/matcher/process-exception-callback)

When Matcher processes a callback, it updates the exception status and records the resolution in the audit trail.

The `X-Idempotency` header is required. Matcher reads the idempotency key only from this header. A request that carries a key only in `X-Idempotency-Key` or `Idempotency-Key` is refused with `400` (`MTCH-0015`), and nothing is processed. Matcher deduplicates a callback by its external system, its exception, and its key together. The same key on another exception or from another external system is a new callback.

### Callback status

* `status` moves the exception to `ASSIGNED` or `RESOLVED`. Matcher reads the value without case sensitivity.
* To move the exception to `ASSIGNED`, send a non-blank `assignee`.
* When `status` is the current status of the exception, Matcher keeps the status and updates `assignee` and `dueAt` if you send them.

### Callback refusals

| Status | Code | Meaning |
| - | - | - |
| `400` | `MTCH-0015` | The key arrived only in `X-Idempotency-Key` or `Idempotency-Key`. |
| `400` | `MTCH-0001` | The callback is not valid. For example, the `X-Idempotency` value is not 1 to 128 letters, digits, `:`, `_`, or `-`, or an `ASSIGNED` callback has no `assignee`. |
| `409` | `MTCH-0504` | Another callback with the same key is still in process. Send the request again later. |
| `409` | `MTCH-0505` | Matcher cannot confirm the state of an earlier callback with the same key. Send the request again later. |
| `429` | `MTCH-0506` | The external system sent more callbacks than its rate limit allows. Send the request again later. |

An unknown or revoked callback token answers `404`. When Matcher cannot check the token, it answers `503`.

### Automatic retry for failed callbacks

If a previous callback for the same idempotency key failed during processing, Matcher automatically attempts to reacquire the idempotency lock and reprocess the callback. You don't need to generate a new idempotency key when retrying a failed callback. Resend the same request and Matcher handles the recovery.

The retry behavior applies only to callbacks with an internal `failed` state. Matcher still deduplicates callbacks that completed successfully.

## Callback credentials

***

An opaque bearer token authenticates inbound callbacks. The external system sends this token in the `X-Callback-Token` header. You mint, list, rotate, and revoke these **callback credentials** through a dedicated CRUD surface under `/v1/exceptions/callbacks/credentials`. Each credential belongs to the caller's tenant. Matcher stores only the token's SHA-256 hash server-side. The mint and rotate responses return the raw token exactly once.

| Action | Method & path | Notes |
| - | - | - |
| Mint credential | `POST /v1/exceptions/callbacks/credentials` | Creates a credential and returns the raw token once (`201`). |
| List credentials | `GET /v1/exceptions/callbacks/credentials` | Lists credential metadata for the tenant (never the raw tokens). |
| Rotate credential | `POST /v1/exceptions/callbacks/credentials/{credentialId}/rotate` | Atomically supersedes a live credential with a freshly minted one (same label) and returns the new raw token once; the old one is revoked in the same transaction. |
| Revoke credential | `DELETE /v1/exceptions/callbacks/credentials/{credentialId}` | Terminally revokes a credential (`204`); append-only audited. |

> [!TIP]
>
> API Reference:
>
> * [Mint callback credential](/en/reference/products/matcher/mint-callback-credential)
> * [List callback credentials](/en/reference/products/matcher/list-callback-credentials)
> * [Rotate callback credential](/en/reference/products/matcher/rotate-callback-credential)
> * [Revoke callback credential](/en/reference/products/matcher/revoke-callback-credential)

### Mint a credential

The request needs a JSON body. Send `{}` if you do not set a label. The `externalSystem` field is optional. Provide it as an operator-legible label for the system this token authenticates.

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/callbacks/credentials" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{ "externalSystem": "stripe" }'
```

The `201` response (`CredentialSecretResponse`) returns:

| Field | Description |
| - | - |
| `token` | Raw bearer token, surfaced once. Configure it as the `X-Callback-Token` header value in the external system. |
| `credentialId` | Surrogate id of the minted credential (used for rotate/revoke). |
| `createdAt` | Mint time (RFC 3339, UTC). |
| `externalSystem` | The label echoed back for confirmation. |
| `webhookUrlHint` | Informational inbound-callback URL shape to configure externally; the `{exceptionId}` placeholder is filled per callback. |

> [!WARNING]
>
> Only the mint and rotate responses show the raw `token`. Store it securely on receipt. You cannot retrieve it again. If you lose or leak the token, rotate or revoke the credential.

### Rotate a credential

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/callbacks/credentials/{credentialId}/rotate" \
 -H "Authorization: Bearer $TOKEN"
```

Rotation returns a new `CredentialSecretResponse` (`201`, new raw token) and revokes the previous credential in the same transaction. Callbacks that still send the old token fail, so update the external system with the new token at once.

### Revoke a credential

```bash cURL theme={null}
curl -X DELETE "https://api.matcher.example.com/v1/exceptions/callbacks/credentials/{credentialId}" \
 -H "Authorization: Bearer $TOKEN"
```

Revocation is terminal: the credential can no longer authenticate inbound callbacks.

## Next steps

***

> **[Exception Routing](/en/products/matcher/configuration/matcher-exception-routing)**
>
> Configure rules that route exceptions.

> **[External Sources](/en/products/matcher/integrations/matcher-external-sources)**
>
> Set up data sources. Among them, only aggregator connections receive webhooks.


# Architecture
Source: https://docs.lerian.studio/en/products/matcher/matcher-architecture

Explore Matcher's modular monolith built on DDD, hexagonal architecture, and CQRS, with bounded contexts that evolve independently.

Matcher is a **modular monolith** with Domain-Driven Design (DDD) and hexagonal architecture. CQRS separates commands (writes) from queries (reads).

This keeps operations simple and boundaries clear. Each module can evolve independently without the complexity of microservices.

## Architecture overview

***

![Matcher Architecture](https://mintcdn.com/lerian-49cb71fc/pdfpHj06Qv6abx_7/images/en/d2/matcher-architecture.svg?fit=max\&auto=format\&n=pdfpHj06Qv6abx_7\&q=85\&s=a3d5acf47c4ec626225354ef42294707)

Matcher architecture overview

## Bounded contexts

***

Matcher is split into modules. Each owns its data and exposes clean interfaces to the others.

* **Configuration**: What you're reconciling (contexts, sources, field maps, rules)
* **Discovery**: External data source connections, schema detection, and extraction orchestration with Matcher's embedded extraction engine
* **Ingestion**: Getting data in (parsing, validation, normalization)
* **Matching**: The engine (rule execution, confidence scoring)
* **Exception**: Handling unmatched items (workflow, assignment, resolution)
* **Governance**: Audit trails (append-only logs for compliance)
* **Reporting**: Visibility (reports, exports, dashboards)

### Configuration

Defines what you're reconciling and how.

**Handles:**

* Contexts (what you reconcile)
* Sources (where data comes from)
* Field maps (translating external fields)
* Rules (how to match)

**Key models:**

* `ReconciliationContext`: The reconciliation scope
* `ReconciliationSource`: Source configuration
* `FieldMap`: Field translation rules
* `MatchRule`: Matching logic

### Discovery

The Discovery bounded context manages external data source connectivity, schema detection, and extraction orchestration with the extraction engine. Discovery runs inside Matcher.

**Responsibilities:**

* Manage external data source connections
* Detect and cache source schemas
* Run in-process extractions and hand results directly to Ingestion
* Track connection and extraction lifecycles
* Manage REST API connections and keep each connection's schema history

**Key entities:**

* `ExtractionRequest`: Tracks an extraction lifecycle run by the embedded engine

> [!NOTE]
>
> See [Discovery](/en/products/matcher/integrations/matcher-discovery) for how Discovery connects to external databases with the extraction engine.

### Ingestion

The Ingestion bounded context handles data intake and normalization.

**Responsibilities:**

* Parse uploaded files
* Validate incoming data against configured schemas
* Normalize external data into a canonical representation
* Detect and handle duplicate records
* Emit domain events when ingestion completes

**Key entities:**

* `IngestionJob`: Tracks ingestion lifecycle and status
* `Transaction`: Normalized canonical transaction record

**Events published:**

* `ingestion.completed`: Indicates data readiness for matching

### Matching

The Matching bounded context contains the reconciliation engine.

**Responsibilities:**

* Load applicable rules for a reconciliation context
* Execute matching strategies (exact, tolerance, fuzzy, date-based)
* Calculate confidence scores
* Create match groups and allocate transactions
* Identify unmatched transactions

**Key entities:**

* `MatchRun`: Execution of a matching job
* `MatchGroup`: Group of reconciled transactions
* `MatchItem`: Individual transaction allocation

**Events published:**

* `match_group.confirmed`: A match group has been finalized
* `match_group.unmatched`: A previously confirmed match was reverted
* `transaction.pending_review`: A non-automatic candidate needs review

### Exception management

The Exception bounded context manages unresolved transactions.

**Responsibilities:**

* Classify exceptions by severity
* Assign exceptions to your team
* Support manual overrides, adjustments, and disputes
* Track resolution status
* Receive resolution callbacks from external systems

**Key entities:**

* `Exception`: An unresolved transaction

### Governance

The Governance bounded context preserves reconciliation traceability.

**Responsibilities:**

* Record configuration changes and exception resolutions in append-only audit logs
* Provide queryable audit history
* Support regulatory and compliance reporting

**Key entities:**

* `AuditLog`: Append-only record of instrumented auditable mutation workflows

> [!WARNING]
>
> Audit logs are append-only. Archival exports old monthly partitions to object storage and then drops them from the database.

### Reporting

The Reporting bounded context provides operational visibility.

**Responsibilities:**

* Generate reconciliation reports
* Expose dashboard metrics
* Export reconciliation data in multiple formats

**Key entities:**

* `Report`: Reconciliation summary
* `Dashboard`: Aggregated operational metrics
* `ExportJob`: Asynchronous export execution

## Data flow

***

Reconciliation follows a deterministic pipeline across bounded contexts:

**1. Configuration**

You define reconciliation contexts, sources, field mappings, and rules through the API.

**2. Discovery**

Discovery connects to external sources, detects their schemas, and runs extractions in-process with the extraction engine. Discovery hands extracted results directly to Ingestion.

**3. Ingestion**

Ingestion parses, validates, normalizes, and deduplicates uploaded files and the data that Discovery extracts. Ingestion emits an `ingestion.completed` event.

**4. Matching**

Matching applies rules to eligible transactions and produces match groups with confidence scores on an integer scale of 0 to 100. Groups from `EXACT` and `TOLERANCE` rules with a confidence of at least 90 out of 100 auto-confirm. Groups from `FUZZY` and `DATE_LAG` rules always require manual review. Unmatched items become exceptions.

**5. Exception handling**

The Exception context classifies exceptions, and your team assigns and resolves them. External systems can report resolutions through callbacks. Resolution updates return to Matcher.

**6. Governance**

Governance records configuration changes and exception resolutions in append-only audit logs.

**7. Reporting**

Users access reports and dashboards showing reconciliation status, match rates, and exception aging.

## Infrastructure components

***

Matcher relies on the following infrastructure services:

| Component | Purpose | Usage |
| - | - | - |
| **PostgreSQL** | Primary data store | Domain data |
| **Valkey (Redis-compatible)** | Cache and coordination | Deduplication, locks, idempotency keys |
| **Streaming backbone** | Business-event publication | Domain events |
| **Object storage (S3-compatible)** | File storage | Export files, dispute evidence, documents queued for extraction, audit-log archives |

### Database architecture

* **Eventual consistency** for reporting views

### Tenant resolution

Matcher resolves the tenant as follows:

* Matcher never accepts tenant identifiers from request parameters

> [!NOTE]
>
> For details, see [Security](/en/products/matcher/reference/matcher-security).

## Design patterns

***

### Outbox pattern

Matcher uses per-event delivery policies. Matcher persists an outbox record for outbox-backed events and dispatches them asynchronously. Other events can use direct delivery with an outbox fallback when the circuit is open.

## Next steps

***

> **[Quick start](/en/products/matcher/getting-started/matcher-quick-start)**
>
> Explore the architecture through a guided example.

> **[Security](/en/products/matcher/reference/matcher-security)**
>
> Review authentication, authorization, and tenant isolation mechanisms.


# Matcher concepts
Source: https://docs.lerian.studio/en/products/matcher/matcher-concepts

Learn Matcher's five core concepts that shape every reconciliation you build: contexts, sources, field maps, match rules, and matches.

The five core concepts in Matcher: **contexts**, **sources**, **field maps**, **rules**, and **matches**.

## Context

***

A **context** defines what you reconcile. It is the configuration container for sources and rules. Its inline sources and rules are optional.

> [!NOTE]
>
> A context answers: *what do I match against what?*

> [!NOTE]
>
> You can start with an empty draft. To activate it, configure at least one `LEFT` source and one `RIGHT` source, map every source (or declare valid `camt053` options, which self-map), and add a match rule. If you enable fee normalization, add a fee rule too.

### Context types

| Type | Description | Example |
| - | - | - |
| **1:1** | One-to-one reconciliation | Bank statement vs ERP records |
| **1:N** | One-to-many reconciliation | One payment covering multiple invoices |
| **N:M** | Many-to-many reconciliation | Netting or aggregation scenarios |

The type also fixes the sources per side. A `1:1` context needs exactly one `LEFT` and one `RIGHT` source, a `1:N` context needs exactly one `LEFT` source, and an `N:M` context needs at least one source on each side. A matching run fails when the sources do not fit the type.

### Example

A context named **"Chase Bank vs ERP System"** would:

* Define Chase Bank as one reconciliation source
* Define your ERP system as another source
* Specify the rules used to reconcile transactions between them

## Source

***

A **source** is where transactions come from. A draft context can start without sources. An activatable context needs at least one source on each matching side.

### Source types

* **LEDGER**: Ledger source category
* **BANK**: Bank source category
* **GATEWAY**: Payment-gateway source category
* **CUSTOM**: Custom source category
* **FETCHER**: A Discovery source category

### Source setup

Each source requires:

* **Name**: Label it (e.g., "Chase Checking")
* **Type**: Category (`LEDGER`, `BANK`, `GATEWAY`, `CUSTOM`, or `FETCHER`)
* **Side**: Which matching side it feeds (`LEFT` or `RIGHT`)

**Config** is optional. If you omit it, Matcher stores an empty config and uses parser defaults for absent policy keys.

Field maps translate each source's fields into Matcher's standard schema.

## Field map

***

A **field map** translates external field names into Matcher's standard schema. Every system calls things differently. Field maps normalize that.

### Standard fields

| Field | Required | Type | Description |
| - | - | - | - |
| `external_id` | Yes | String | Source-system transaction identifier |
| `amount` | Yes | Decimal | Transaction amount (positive or negative) |
| `currency` | Yes | String | ISO 4217 currency code |
| `date` | Yes | DateTime | Transaction date |
| `description` | No | String | Transaction description |
| `fee_amount` | No | Decimal | Optional fee amount column |
| `fee_currency` | No | String | Optional fee currency column |
| `direction` | No | Object | `{column, debit, credit}`: the column that marks each row as debit or credit. A debit row imports with a negative amount, a credit row with a positive one. CSV, JSON, and XML only |

The canonical vocabulary stays closed. Matcher rejects a field map that declares any other key.

When you map `direction`, use an unsigned amount column. Matcher rejects a row with a signed amount, an empty direction cell, or an unknown direction value.

When you upload a file with format `camt053`, Matcher uses its built-in ISO 20022 mapping and ignores the field map. Activation treats a source that declares `camt053` options as mapped.

### Example mapping

You map a bank statement that exposes `TXN_ID`, `VALUE`, `CCY`, and `POST_DATE` like this:

```json theme={null}
{
  "external_id": "TXN_ID",
  "amount": "VALUE",
  "currency": "CCY",
  "date": "POST_DATE"
}
```

## Match rule

***

A **match rule** tells Matcher how to compare transactions. Rules run in ascending priority. A transaction claimed by an earlier rule is unavailable to later rules, which still evaluate the remaining transactions.

### Rule types

* **EXACT**: Compares configured fields exactly. Amount, currency, date (by day), and reference are enabled by default.
* **TOLERANCE**: Matches amounts inside the configured absolute and/or percentage tolerance. Currency and reference must also match by default. Omitted amount tolerances and `dateWindowDays` default to `0`, so the rule allows no drift or date window until you configure one.
* **DATE\_LAG**: Matches within a configured day-difference band. `minDays` and `maxDays` both default to `0` (same day). DATE\_LAG only proposes. It never auto-confirms.
* **FUZZY**: Grades normalized transaction references. It uses `Reference`, populated from the transaction's `ExternalID`. A field-map `description` is not a FUZZY input. FUZZY only proposes. It never auto-confirms, so a human reviews every fuzzy link.

### Priority order

Lower numbers run first. A rule claims its matching transactions. Later rules continue with the remaining transactions.

| Priority | Rule | Description |
| - | - | - |
| 1 | Exact match | Amount, date, and reference must match |
| 2 | Same-day tolerance | Same date, amount within 0.5% |
| 3 | Week tolerance | Within 7 days, amount within 1% |

> [!NOTE]
>
> These priorities and values are illustrative rules, not engine defaults. Configure the values for your reconciliation policy.

### Rule parameters

| Rule type | Parameters |
| - | - |
| EXACT | `matchAmount`, `matchCurrency`, `matchDate`, `matchReference`: which fields must match exactly |
| TOLERANCE | Top-level non-negative `percentTolerance` and/or `absTolerance` values (numbers or decimal strings). `percentTolerance` is a fraction: `0.005` is 0.5%. The allowed difference is the larger of `absTolerance` and `percentTolerance` times the larger absolute amount, with the default `percentageBase`. Optionally set `dateWindowDays` (`0` by default; maximum `3650`). Do not wrap these values in a `tolerance` object. |
| DATE\_LAG | `minDays`, `maxDays`: allowed day-difference band. Both default to `0`, must be from `0` to `3650`, and `maxDays` must be at least `minDays`; `inclusive` defaults to `true` and controls both bounds. Amounts must be equal unless you set `feeTolerance`. |
| FUZZY | `minSimilarity`: normalized-reference threshold from `0` to `1` (defaults to `0.80`), plus amount, currency, and date checks, which are on by default. |

## Match

***

A **match** is when transactions from different sources are reconciled together.

### Match status

| Status | Description |
| - | - |
| `PROPOSED` | Matcher found it, waiting for confirmation |
| `CONFIRMED` | Auto-approved or manually approved |
| `REJECTED` | Manually rejected |
| `REVOKED` | A previously confirmed match was unmatched, returning its transactions to `UNMATCHED` |

### Match patterns

#### 1:1 match

One transaction from each source is reconciled.

```
Bank: $100.00 on Jan 15 → ERP: $100.00 on Jan 15
```

#### 1:N match

One transaction is reconciled against multiple transactions.

```
Bank: $300.00 → ERP: $100.00 + $100.00 + $100.00
```

#### N:1 match

Multiple transactions are reconciled against a single transaction.

```
Bank: $50.00 + $50.00 + $50.00 → ERP: $150.00

```

#### N:M match

Multiple transactions on each side are reconciled together. N:M evaluation only executes `EXACT` and `TOLERANCE` rules. It considers up to four transactions per side in a group. It skips a candidate bucket that holds more than 40 transactions on a side.

```
Bank: $100.00 + $200.00 → ERP: $150.00 + $150.00
```

### Match items

Each match group contains **match items**, which record transaction participation and allocation.
This enables partial reconciliation in split and aggregation scenarios.

## Exception

***

An **exception** records a transaction that needs review, including unmatched transactions and matched transactions with residual conditions such as FX-rate variance.

### Exception status

| Status | Description |
| - | - |
| `OPEN` | Waiting for assignment |
| `ASSIGNED` | Someone's investigating |
| `PENDING_RESOLUTION` | A resolution is in progress, awaiting completion |
| `RESOLVED` | Handled |

### Severity

Matcher auto-classifies exceptions so you know what to prioritize. The amount is the absolute value of the transaction's base amount, or of its amount when it has no base amount. For an aged open item, it is the absolute value of the open balance.

| Severity | Default criteria |
| - | - |
| **Critical** | Amount ≥ 100,000 or age ≥ 120 hours |
| **High** | Amount ≥ 10,000 or age ≥ 72 hours |
| **Medium** | Amount ≥ 1,000 or age ≥ 24 hours |
| **Low** | All other cases |

The classifier evaluates the criteria from top to bottom. When an exception meets the criteria of more than one severity, the highest matching severity applies.

Matcher caps an exception with reason `FEE_DATA_MISSING` at **Medium**, whatever its amount or age.

### Resolution workflows

* **Resolve**: Record a resolution label and optional reason to close an exception.
* **Force match**: Resolve an exception by forcing a match with an override reason and notes after manual review.
* **Adjust entry**: Resolve an exception by creating an adjustment entry with a reason, notes, positive amount, currency, and effective time.

## Confidence score

***

A **confidence score** indicates the reliability of an automated match on a 0–100 scale.
Higher scores represent stronger alignment between transactions.

### Score calculation

| Component | Weight | Description |
| - | - | - |
| Amount match | 40% | Full weight when the amounts match under the rule or the rule does not check amounts, else `0` |
| Currency match | 30% | Full weight when the currencies match, else `0` |
| Date tolerance | 20% | Full weight when the dates fall inside the rule's window or the rule does not check dates, else `0` |
| Reference | 10% | Normalized reference alignment (graded 0–1 for FUZZY rules) |

### Confidence tiers

| Tier | Score range | System behavior |
| - | - | - |
| **Auto-approved** | ≥ 90 | Confirmed automatically for EXACT and TOLERANCE matches. FUZZY and DATE\_LAG matches always go to review |
| **Needs review** | 60–89 | Flagged for manual review |

> [!NOTE]
>
> Confidence weights and tier thresholds are fixed by the engine. They are not configurable.

## Audit log

***

An **audit log** is an immutable, append-only record created by an instrumented workflow.
It provides traceability for the actions Matcher records.

### Logged events

Only workflows instrumented to emit an audit event create entries. Verified producers include:

* Context, source, field-map, and rule mutations
* Exception workflows, including force match and adjust entry

### Audit entry contents

| Field | Description |
| - | - |
| `createdAt` | Record creation timestamp (UTC), which can differ from the audited action time |
| `actorId` | Actor identifier, when supplied |
| `action` | Action performed |
| `entityType` | Affected entity type |
| `entityId` | Identifier of the affected entity |
| `changes` | Structured JSON event data; emitted events include `occurred_at` and any supplied changes |
| `tenantSeq` | Per-tenant sequence number |
| `prevHash` / `recordHash` | Hash chain linking each entry to the previous one |

> [!WARNING]
>
> Audit logs are append-only. Archival exports old monthly partitions to object storage and then drops them from the database.

## Next steps

***

> **[Architecture](/en/products/matcher/matcher-architecture)**
>
> See how the bounded contexts implement these concepts.

> **[Quick start](/en/products/matcher/getting-started/matcher-quick-start)**
>
> Apply these concepts in a guided, hands-on flow.


# Rule suggestions
Source: https://docs.lerian.studio/en/products/matcher/matching/matcher-rule-suggestions

Produce AI-suggested match rules, review them in a human-in-the-loop queue, and approve or reject each candidate before any rule is created.

Matcher can propose config-only match rules from a context's history using AI, but AI output is never authoritative. Producing a suggestion creates no rule. Matcher creates a rule only when a human approves a suggestion. This guide covers the human-in-the-loop (HITL) rule-suggestion queue.

> [!NOTE]
>
> When Lerian enables rule suggestions for your environment, Matcher sends each suggestion request to the language-model provider Lerian configures for your environment. When the feature is not available in your environment, the operation answers `503`. The payload is aggregates only. No raw transaction, money, or PII leaves Matcher.

## Produce suggestions

***

Build aggregate, privacy-safe history features for a context, ask the AI advisor for candidate rules, and enqueue each surviving candidate in the review queue.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/rule-suggestions" \
  -H "Authorization: Bearer $TOKEN"
```

The response returns the newly created `PENDING_REVIEW` reviews (producing them creates no rule):

```json theme={null}
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "contextId": "550e8400-e29b-41d4-a716-446655440000",
      "candidate": {
        "type": "TOLERANCE",
        "priority": 10,
        "config": { "percentTolerance": "0.01" },
        "rationale": "near-miss amounts cluster under 1%",
        "expectedImprovement": "+8% auto-match",
        "confidence": 0.82
      },
      "status": "PENDING_REVIEW",
      "version": 1,
      "createdAt": "2026-06-16T10:30:00Z",
      "updatedAt": "2026-06-16T10:30:00Z"
    }
  ],
  "count": 1
}
```

Candidate types come from the closed vocabulary: `EXACT` (strict equality), `TOLERANCE` (within an amount band), or `DATE_LAG` (allowing a settlement-date offset). The candidate is config only. It never carries a transaction, but its config can set monetary thresholds such as `absTolerance`.

## List suggestions

***

Cursor-paginated list of rule suggestions for a context, optionally filtered by status.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/matching/contexts/{contextId}/rule-suggestions?status=PENDING_REVIEW&limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

Query parameters: `status` (`PENDING_REVIEW`, `APPROVED`, `REJECTED`), `limit` (1–200), and `cursor`. Reading the queue egresses nothing.

## Approve a suggestion

***

Approving a `PENDING_REVIEW` suggestion creates the match rule through the deterministic configuration write path. This is the only path from an AI suggestion to an active match rule, and it runs only on explicit human approval.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/rule-suggestions/{suggestionId}/approve" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "reviewId": "550e8400-e29b-41d4-a716-446655440000",
  "createdRuleId": "550e8400-e29b-41d4-a716-446655440000"
}
```

## Reject a suggestion

***

Rejecting a `PENDING_REVIEW` suggestion discards it and creates no rule. The request body is mandatory, but its `reason` field is optional (send `{}` to reject without a reason).

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/rule-suggestions/{suggestionId}/reject" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "too aggressive" }'
```

Matcher records the approving/rejecting principal for audit.

## Lifecycle after approval

***

Once a suggestion is `APPROVED`, its `createdRuleId` links to a real match rule that participates in match runs exactly like a hand-authored rule. A review is a one-way state machine: a `PENDING_REVIEW` suggestion transitions to `APPROVED` or `REJECTED` once and cannot be re-decided. Attempting to re-decide, or to approve an already-linked review, returns `409`. An approved candidate that fails validation returns `422`.

> [!TIP]
>
> Preview how a candidate rule would behave before you approve it with the read-only simulate endpoint. See [Simulation](/en/products/matcher/matching/matcher-simulate).

## Response codes

***

| Status | Meaning |
| - | - |
| `200` | Suggestions produced, listed, approved, or rejected |
| `403` | Missing permission, inactive context, or (producing suggestions only) consent for rule suggestions not granted for your environment |
| `404` | Rule suggestion not found |
| `409` | Invalid state transition / already linked |
| `422` | Invalid status filter or id, or approved suggestion failed validation |
| `503` | Rule suggestion or advisor not available (author rules manually) |


# Simulation
Source: https://docs.lerian.studio/en/products/matcher/matching/matcher-simulate

Dry-run a match rule and preview fee-schedule calculations in Matcher. Both endpoints are read-only, so you can validate config before committing anything.

Matcher exposes two read-only simulation endpoints so you can answer "what would happen?" before you commit configuration. They are **match simulation** (will this rule match?) and **fee simulation** (what fees would this schedule charge?). Neither persists anything.

## Match simulation

***

Preview how a single rule would match a context's unmatched transactions, without committing anything. Choose an existing configured rule (`ruleId`) or an inline candidate rule (`rule`).

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/matching/simulate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "contextId": "550e8400-e29b-41d4-a716-446655440000",
    "rule": {
      "type": "TOLERANCE",
      "config": { "percentTolerance": "0.01" }
    },
    "sampleLimit": 25
  }'
```

Supply exactly one of:

* `ruleId`: preview an existing configured rule of the context.
* `rule`: preview an un-persisted candidate definition (`type` is one of `EXACT`, `TOLERANCE`, `DATE_LAG`, `FUZZY`, plus its `config`).

Supplying both, or neither, returns `400`. `sampleLimit` (1–200, default 25) caps the returned would-match pairs.

The response reports how many 1:1 groups the rule would form and the per-side unmatched counts. It also returns a bounded sample of would-match pairs, each with a confidence score. In `why`, the booleans report whether the two amounts, currencies, and dates are equal, not the score components:

```json theme={null}
{
  "ruleType": "TOLERANCE",
  "matchedGroups": 12,
  "unmatchedLeft": 3,
  "unmatchedRight": 5,
  "sampleTruncated": false,
  "sample": [
    {
      "left":  { "id": "...", "amount": "100", "currency": "BRL", "date": "2025-06-01T00:00:00Z" },
      "right": { "id": "...", "amount": "100", "currency": "BRL", "date": "2025-06-01T00:00:00Z" },
      "score": 100,
      "why": { "amountMatch": true, "currencyMatch": true, "dateMatch": true, "referenceScore": 1 },
      "amountDelta": "0",
      "dateDeltaDays": 0
    }
  ]
}
```

> [!NOTE]
>
> Scope: the simulation reads at most 5,000 of the context's unmatched transactions, and the context's sources must resolve into two sides. It scores by the deterministic rule engine over the raw transaction amounts. It does not apply run-time fee normalization, FX conversion, or the FX-variance band, and it previews only 1:1 pairwise grouping (no 1:N/N:M allocation). The simulation does not count a pair that only matches after fee normalization, after FX conversion, inside the FX band, or via allocation.

## Fee simulation

***

Calculate fees for a given gross amount using a specific fee schedule. `currency` must equal the schedule's currency. Use it to validate a schedule's rules before you attach it to a context.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/fee-schedules/{scheduleId}/simulate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "grossAmount": "100.00", "currency": "USD" }'
```

The response returns the net amount, the total fee, and a per-item breakdown:

```json theme={null}
{
  "grossAmount": "100",
  "netAmount": "97.7",
  "totalFee": "2.3",
  "currency": "USD",
  "items": [
    { "name": "interchange", "fee": "1.5", "baseUsed": "100" },
    { "name": "processing", "fee": "0.8", "baseUsed": "100" }
  ]
}
```

> [!NOTE]
>
> Fee simulation has no transaction metadata, so expression-fee items that require a transaction identifier surface their missing-identifier error as a `4xx`. A missing schedule returns `404`.

## When to use each

***

| Use | When |
| - | - |
| **Match simulation** (`/matching/simulate`) | You are authoring or reviewing a match rule and want to see how many transactions it would group, and which pairs, before committing it. |
| **Fee simulation** (`/fee-schedules/{scheduleId}/simulate`) | You are configuring a fee schedule and want to verify the net/fee breakdown it would produce for a representative gross amount. |

Both endpoints remain strictly read-only. They never persist a run, group, item, rule, or transaction.

## Response codes

***

| Status | Meaning |
| - | - |
| `200` | Simulation returned |
| `400` | Invalid input (ambiguous/missing rule, sides that do not resolve, invalid gross amount) |
| `404` | Context, rule, or fee schedule not found |
| `422` | Malformed field, such as an invalid id or an unknown rule type |
| `503` | Match simulation not available |


# Confidence scoring
Source: https://docs.lerian.studio/en/products/matcher/reference/matcher-confidence-scoring

See how Matcher computes a 0–100 confidence score from amount, currency, date, and reference checks, and how EXACT, TOLERANCE, DATE_LAG, and FUZZY rules score.

Confidence scores indicate the reliability of an automated match on a scale of 0-100. Higher scores mean greater certainty that two transactions represent the same financial event.

## Overview

***

When Matcher identifies a potential match, it assigns a confidence score based on multiple factors.

This score defines how Matcher handles the match:

* High scores (90+) from EXACT and TOLERANCE rules are auto-approved
* All other proposed matches require review

![Matcher Confidence Scoring](https://mintcdn.com/lerian-49cb71fc/DDbrUgbtobpkB1Zl/images/en/d2/matcher-confidence-scoring.svg?fit=max\&auto=format\&n=DDbrUgbtobpkB1Zl\&q=85\&s=672c817e7dae37cfd577e4d13063c474)

Matcher confidence scoring.

## Score components

***

Matcher uses a weighted scoring system with four components. The amount, currency, and date components each score a full match (1.0) or no match (0.0). The reference component does the same for EXACT, TOLERANCE, and DATE\_LAG rules. For FUZZY rules, it scores the graded reference similarity, from 0.0 to 1.0.

| Component | Weight | Points (match / no match) |
| - | - | - |
| Amount match | 40% | 40 / 0 |
| Currency match | 30% | 30 / 0 |
| Date proximity | 20% | 20 / 0 |
| Reference match | 10% | 10 / 0 |

On a proposed match, the amount and date components always score their full points. A rule that checks them rejects a pair that fails them. A rule that does not check them scores them as matched. Only the currency and reference components can lower the score.

### Amount match (40%)

The amount component has the highest weight because amount discrepancies often indicate different transactions.

| Condition | Score |
| - | - |
| Amounts match (within rule tolerance) | 40 points |
| Amounts do not match | 0 points |

Amount matching depends on the active rule type. An EXACT rule requires identical amounts. A TOLERANCE rule allows variance within the configured `percentTolerance` and `absTolerance`.

### Currency match (30%)

Currency verification is binary. Currencies either match or they don't.

| Condition | Score |
| - | - |
| Same currency | 30 points |
| Different currency | 0 points |

### Date proximity (20%)

Date scoring checks whether the transaction dates fall within the configured window.

| Condition | Score |
| - | - |
| Dates within allowed window | 20 points |
| Dates outside allowed window | 0 points |

The allowed window depends on the rule. An EXACT rule requires the same date, and it respects `datePrecision`. A DATE\_LAG rule accepts a day difference inside its `[minDays, maxDays]` band. The `inclusive` flag controls whether `minDays` and `maxDays` themselves count.

### Reference match (10%)

For EXACT and TOLERANCE rules, reference comparison is binary, and `matchReference` is on by default. With `matchReference` off, an EXACT rule scores the full 10 points and a TOLERANCE rule scores `0`.

| Condition | Score |
| - | - |
| References match (exact or case-insensitive) | 10 points |
| Both references absent | 10 points (unless the rule sets `referenceMustSet`, which scores any absent reference as 0) |
| References do not match, or only one is absent | 0 points |

> [!NOTE]
>
> **FUZZY rules score the reference on a continuous scale.** For a FUZZY rule, the 10% reference slot carries a graded `ReferenceScore` between `0.0` and `1.0`. This value is a similarity measure, so it is not limited to a strict `0` or `1`. A near-identical reference contributes close to the full 10 points while one that barely clears the fuzzy gate contributes proportionally less. As a result, FUZZY matches can produce non-multiple-of-10 scores such as 97 or 99. See [Possible scores](#possible-scores) below.

> [!WARNING]
>
> **DATE\_LAG rules do not score references.** For DATE\_LAG rules the `ReferenceScore` is always `0.0`, so the 10% reference component contributes `0` points regardless of the reference values. The maximum DATE\_LAG score is therefore 90 (40 + 30 + 20 + 0).

## Calculation formula

***

The confidence score formula:

```
confidence = round(
  (amountMatch × 0.40 +
   currencyMatch × 0.30 +
   dateMatch × 0.20 +
   referenceScore × 0.10) × 100
)
```

`amountMatch`, `currencyMatch`, and `dateMatch` are each `1.0` (match) or `0.0` (no match). `referenceScore` is between `0.0` and `1.0`.

The weights are hardcoded constants and are not configurable per context.

### Possible scores

For **EXACT**, **TOLERANCE**, and **DATE\_LAG** rules, every component is binary, so a proposed match scores one of these values:

**60, 70, 90, 100**

A DATE\_LAG match scores 60 or 90, because its reference component is always `0`. An FX rate-variance match has a fixed score of 75. See [Multi-currency matching](/en/products/matcher/reference/matcher-multi-currency#fx-rate-variance-band).

For **FUZZY** rules this does not hold. Because the reference component is a continuous `ReferenceScore` (0.0–1.0), FUZZY matches can produce intermediate scores such as **97** or **99**. Regardless of the resulting score, a FUZZY match is **never auto-confirmed**. See [Rule types that never auto-confirm](#rule-types-that-never-auto-confirm).

## Calculation examples

***

### Exact match (score: 100)

Two transactions with identical values on the same day:

| Component | Comparison | Points |
| - | - | - |
| Amount | $1,000.00 vs $1,000.00 ✓ | 40 |
| Currency | USD vs USD ✓ | 30 |
| Date | 2024-01-15 vs 2024-01-15 ✓ | 20 |
| Reference | PAY-001 vs PAY-001 ✓ | 10 |

**Final Score: 100** → Auto-confirmed

### High confidence match (score: 90)

Amount, currency, and date match. The rule is TOLERANCE with `matchReference` off, so the reference scores `0`:

| Component | Comparison | Points |
| - | - | - |
| Amount | $1,000.00 vs $1,000.00 ✓ | 40 |
| Currency | USD vs USD ✓ | 30 |
| Date | 2024-01-15 vs 2024-01-15 ✓ | 20 |
| Reference | PAY-001 vs — ✗ | 0 |

**Final Score: 90** → Auto-confirmed

### Medium confidence (score: 70)

Amount, date, and reference match. The currencies differ, and the rule does not check currency:

| Component | Comparison | Points |
| - | - | - |
| Amount | 1,000.00 vs 1,000.00 ✓ | 40 |
| Currency | USD vs EUR ✗ | 0 |
| Date | 2024-01-15 vs 2024-01-15 ✓ | 20 |
| Reference | PAY-001 vs PAY-001 ✓ | 10 |

**Final Score: 70** → Needs review

## Confidence tiers

***

Matcher categorizes matches into tiers based on score:

| Tier (score) | System behavior |
| - | - |
| **Auto-Approved** (≥ 90) | Automatically confirmed when the rule is EXACT or TOLERANCE. FUZZY and DATE\_LAG matches are queued for manual review |
| **Needs Review** (60-89) | Queued for manual review |

Every proposed match scores at least 60, because the amount and date components always score their full points on a proposal.

### How confidence tiers are applied

When Matcher proposes a match, it evaluates the confidence score and applies the following steps:

1. If the score is **90 or higher** and the rule is EXACT or TOLERANCE, Matcher confirms the match automatically.
2. Otherwise, Matcher queues the match for manual review.

### Rule types that never auto-confirm

Matches produced by **FUZZY** and **DATE\_LAG** rules are **never auto-confirmed**, regardless of their confidence score. Even a FUZZY or DATE\_LAG match scoring 90 or above is always queued for manual review.

A fuzzy reference only contributes the 10% reference slot, so the financial fields (amount + currency + date) alone can already reach the 90 threshold. A DATE\_LAG rule does not score the reference, so its score is at most 90.

## Confidence thresholds

***

Matcher uses fixed thresholds to determine how it handles matches:

| Threshold | Score | Behavior |
| - | - | - |
| Auto-confirm | >= 90 | Match is automatically confirmed when the rule is EXACT or TOLERANCE |
| Match | >= 60 | Match is proposed for manual review |

These thresholds are not configurable per context.

## Weights

***

The component weights (40/30/20/10) are hardcoded constants. You cannot adjust them per context or per rule.

| Component | Weight | Rationale |
| - | - | - |
| Amount | 40% | Amount is the strongest indicator of a valid match |
| Currency | 30% | Currency mismatch usually means different transactions |
| Date | 20% | Date proximity adds confidence but allows for settlement delays |
| Reference | 10% | References are helpful but often missing or inconsistent |

## Best practices

***

> **Monitor tier distribution**
>
> Track the percentage of transactions in each tier. Unusual shifts may indicate data quality issues or rule misconfiguration.

> **Use dry-run mode to test rules**
>
> Since confidence depends on which rules match, always dry-run rule changes before committing. This prevents unexpected increases in manual review volume.

> **Understand scores as rule outcomes**
>
> For EXACT, TOLERANCE, and DATE\_LAG rules, scoring is binary. A score of 70 means that amount, date, and reference matched and currency did not. A score of 90 means that the reference scored `0`. Use this to diagnose matching issues.
>
> FUZZY rules are the exception. Their graded reference component can yield intermediate scores (e.g. 97). Read a FUZZY score as "financial fields matched plus a partial reference similarity."

## Next steps

***

> **[Match Rules](/en/products/matcher/configuration/matcher-match-rules)**
>
> Configure rules that influence scoring.

> **[Multi-Currency](/en/products/matcher/reference/matcher-multi-currency)**
>
> How FX affects confidence scoring.


# Exports & disputes
Source: https://docs.lerian.studio/en/products/matcher/reference/matcher-export-disputes

Run asynchronous export jobs to generate downloadable reconciliation reports, and open, evidence, and resolve disputes against exceptions.

This guide covers two operator workflows that both end in a downloadable or resolved artifact. With **export jobs** you queue a report, poll until it succeeds, and download the file. With **disputes** you open a dispute against an exception, attach evidence, then close it won or lost.

## Export jobs

***

Exports are asynchronous. You create a job scoped to a context, poll its status by ID, and download the file once it reaches `SUCCEEDED`. Statuses are `QUEUED`, `RUNNING`, `SUCCEEDED`, `FAILED`, `EXPIRED`, and `CANCELED`.

### Create an export job

`POST` to the context's export-jobs collection. Responds `202 Accepted` with the job ID and a poll URL.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/export-jobs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reportType": "MATCHED",
    "format": "CSV",
    "dateFrom": "2025-01-01",
    "dateTo": "2025-01-31",
    "sourceId": "550e8400-e29b-41d4-a716-446655440000"
  }'
```

```json theme={null}
{
  "jobId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "QUEUED",
  "statusUrl": "/v1/export-jobs/550e8400-e29b-41d4-a716-446655440000"
}
```

* `reportType`: one of `MATCHED`, `UNMATCHED`, `VARIANCE`, `EXCEPTIONS` (the aliases `MATCHES` and `UNMATCHED_TRANSACTIONS` normalize to these values).
* `format`: `CSV`, `JSON`, or `XML`, in uppercase.
* `dateFrom` / `dateTo`: optional `YYYY-MM-DD`. `dateFrom` defaults to 30 days before `dateTo`, and `dateTo` defaults to tomorrow (UTC).
* `sourceId`: optional source filter.

> [!NOTE]
>
> Async export jobs do not support `SUMMARY` (`400`) or `PDF` (`422`). The date window spans at most 365 days, and a longer window returns `400`. Job creation returns `503` when asynchronous exports are not enabled for your environment.

### Poll job status

Read the top-level job route (the `statusUrl` from creation).

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/export-jobs/{jobId}" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "reportType": "MATCHED",
  "format": "CSV",
  "status": "SUCCEEDED",
  "recordsWritten": 4250,
  "bytesWritten": 524288,
  "fileName": "MATCHED_550e8400_20250101-20250131.csv",
  "createdAt": "2025-01-15T10:30:00Z",
  "startedAt": "2025-01-15T10:30:05Z",
  "finishedAt": "2025-01-15T10:35:00Z",
  "expiresAt": "2025-01-22T10:30:00Z",
  "downloadUrl": "/v1/export-jobs/550e8400-e29b-41d4-a716-446655440000/download"
}
```

`contextId` names the context the job exports. `error` carries the job's last failure reason, when it has one. `downloadUrl` is the download route below, and it appears only once the job has `SUCCEEDED` and the file is still available. You can list a context's jobs with `GET /v1/contexts/{contextId}/export-jobs`, list all jobs with `GET /v1/export-jobs`, and cancel a queued/running job with `POST /v1/export-jobs/{jobId}/cancel`.

### Download the file

Returns a presigned URL, the original file name, a SHA-256 checksum, and the URL's remaining lifetime in seconds.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/export-jobs/{jobId}/download" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "downloadUrl": "https://storage.example.com/exports/report.csv?token=abc",
  "fileName": "MATCHED_550e8400_20250101-20250131.csv",
  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "expiresIn": 3600
}
```

> [!WARNING]
>
> Export files are purged after `expiresAt`, 7 days after the job was created. After that, the file is no longer downloadable. Re-run the export to regenerate it.

## Disputes

***

You open a dispute against a specific **exception** when you need to contest a reconciliation discrepancy. A new dispute is `OPEN`. Closing it sets `WON` or `LOST`, and both outcomes are terminal.

### Open a dispute

`POST` to the exception's disputes collection. Responds `201 Created`.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/exceptions/{exceptionId}/disputes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "BANK_FEE_ERROR",
    "description": "Transaction amount differs from invoice"
  }'
```

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "exceptionId": "550e8400-e29b-41d4-a716-446655440001",
  "category": "BANK_FEE_ERROR",
  "state": "OPEN",
  "description": "Transaction amount differs from invoice",
  "openedBy": "user@example.com",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}
```

`category` is one of `BANK_FEE_ERROR`, `UNRECOGNIZED_CHARGE`, `DUPLICATE_TRANSACTION`, `AMOUNT_MISMATCH`, or `OTHER`. The response omits `evidence` until the dispute has some. The `openedBy` field records the opening principal.

Matcher refuses to open a dispute with `409` (`MTCH-0511`) when the exception is `RESOLVED` or `PENDING_RESOLUTION`. It answers `409` (`MTCH-0510`) while a settlement is in progress on the exception. Retry that request after the settlement completes.

### Submit evidence by URL

Attach a reference to an already-hosted evidence file plus a describing comment. `fileUrl` must be an `https` URL.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/disputes/{disputeId}/evidence" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "comment": "Attached bank statement showing correct amount",
    "fileUrl": "https://storage.example.com/evidence/doc123.pdf"
  }'
```

### Upload an evidence file

Stream the raw file bytes directly to tenant-scoped object storage. The comment travels as a query parameter and the file as the request body. Responds `201 Created` with the updated dispute. Allowed content types are `application/pdf`, `image/png`, `image/jpeg`, and `text/csv`. The body has a 10 MiB limit.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/disputes/{disputeId}/evidence/upload?comment=Bank%20statement%20showing%20correct%20amount" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/pdf" \
  --data-binary @statement.pdf
```

The dispute's `evidence` array lists each stored evidence item. For an uploaded file, `fileUrl` holds the object-storage key, not a download URL:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "disputeId": "550e8400-e29b-41d4-a716-446655440001",
  "comment": "Bank statement showing correct amount",
  "submittedBy": "user@example.com",
  "fileUrl": "<tenant-id>/dispute-evidence/550e8400-e29b-41d4-a716-446655440001/<object-id>.pdf",
  "submittedAt": "2025-01-15T10:30:00Z"
}
```

> [!NOTE]
>
> The upload endpoint returns `503` when evidence storage is unavailable. It rejects oversize bodies with `413` and content types outside the allowlist with `415`.

### Close a dispute

Record the outcome. `won: true` sets the state to `WON` and `won: false` sets it to `LOST`. A `resolution` note is required.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/disputes/{disputeId}/close" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "won": true,
    "resolution": "Counterparty acknowledged the error and issued correction"
  }'
```

You can list disputes with `GET /v1/disputes` and fetch one with `GET /v1/disputes/{disputeId}`. The list endpoint filters by `state`, `category`, and date range, and it supports sorting and cursor pagination.

## Response codes

***

| Status | Meaning |
| - | - |
| `200` | Export/dispute data returned |
| `201` | Dispute opened or evidence file uploaded |
| `202` | Export job accepted |
| `400` | Invalid input (`SUMMARY` report type, bad date range, invalid category) |
| `404` | Context, export job, exception, or dispute not found |
| `409` | Export job not ready for download, or already in a terminal state when canceled. Exception not open to a new dispute, or a settlement in progress on it |
| `410` | Export file expired |
| `413` | Evidence file exceeds the 10 MiB cap |
| `415` | Evidence content type not in the allowlist |
| `422` | Malformed field (including a lowercase or unsupported `format`), or invalid dispute state transition |
| `429` | Rate limit exceeded |
| `503` | Asynchronous exports not enabled for your environment, or export or evidence storage unavailable |


# Multi-currency matching
Source: https://docs.lerian.studio/en/products/matcher/reference/matcher-multi-currency

Reconcile transactions across currencies in Matcher by converting to a base amount using per-transaction FX hints, then apply your existing match rules.

Matcher lets you reconcile transactions in different currencies by converting amounts to a common base currency before comparison. This enables matching across international transactions, treasury operations, and multi-entity reconciliations.

## Overview

***

Multi-currency matching converts both transaction amounts to a base currency using the appropriate FX rate, then applies standard matching rules. If the converted amounts fall within tolerance, Matcher creates a match. Otherwise, it creates an exception for review.

![Multi-currency matching flow.](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/matcher-multicurrency-matching.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=9f773cf7a55bda246a46349536efbbe4)

Multi-currency matching flow.

## How it works

***

Multi-currency support lives in the existing context types (`1:1`, `1:N`, `N:M`) and match rules. There is no separate "multi-currency" context type.

At match time, Matcher computes a base amount and a base currency for each transaction from FX hints in the transaction's own metadata (see [FX from transaction metadata](#fx-from-transaction-metadata) below). Rules that set `matchBaseAmount` or `matchBaseCurrency` compare these base values. You cannot upload a base amount directly.

There is no external FX provider or rate-lookup service. The rate always comes from the transaction row itself.

### Key components

| Component | Where it lives | Purpose |
| - | - | - |
| Base amount / base currency | Computed at match time, not stored | Values that base-amount rules compare, derived from FX metadata |
| `matchBaseAmount` / `matchBaseCurrency` | Rule config | Make a rule compare base amounts and base currencies |
| `fx_rate`, `fx_base_currency`, `fx_notional_expr` | Transaction metadata | Per-transaction FX hints used to derive the base amount at match time |

## Configuring rules for multi-currency

***

Enable multi-currency comparison by setting `matchBaseAmount` and `matchBaseCurrency` to `true` in the rule config.

The checks on the original values stay active. An EXACT rule compares `amount` while `matchAmount` is on, and EXACT and TOLERANCE rules compare `currency` while `matchCurrency` is on. Both are on by default, so a cross-currency rule turns them off.

### Exact rule with base amount matching

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "EXACT",
   "priority": 1,
   "config": {
     "matchAmount": false,
     "matchCurrency": false,
     "matchBaseAmount": true,
     "matchBaseCurrency": true,
     "matchDate": true,
     "matchReference": false
   }
 }'
```

`matchBaseAmount` compares the base amounts, and `matchBaseCurrency` compares the base currencies. A transaction without a base amount fails both checks.

### Tolerance rule with base amount matching

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "TOLERANCE",
   "priority": 2,
   "config": {
     "matchCurrency": false,
     "matchBaseAmount": true,
     "matchBaseCurrency": true,
     "matchReference": false,
     "percentTolerance": 0.02,
     "absTolerance": 10.0
   }
 }'
```

With `matchBaseAmount`, a TOLERANCE rule compares base amounts in place of the original amounts, and `absTolerance` is in base-currency units.

### Confidence scoring

Base-amount rules use the same fixed component weights as all other rules. For the full scoring model, see [Confidence scoring](/en/products/matcher/reference/matcher-confidence-scoring).

## FX from transaction metadata

***

When a transaction has no base amount yet, Matcher converts it at match time using FX hints carried in that transaction's `metadata`. Matcher does not call any external rate provider. The rate travels with the row.

Conversion only runs when `fx_base_currency` is present. Conversion never changes the original `amount` and `currency`, because it changes only the comparison. Matcher rounds the converted amount to the largest `roundingScale` among the context's TOLERANCE rules, or to 2 decimal places when the context has none. Match simulation does not convert, so base-amount rules find no matches in a simulation.

### Metadata fields

| Metadata field | Required | Purpose |
| - | - | - |
| `fx_base_currency` | Yes (to trigger) | The base currency the amount is converted into. The comparison is case-sensitive, so use the same code on both sides. |
| `fx_rate` | Yes, unless `fx_notional_expr` is set | Multiplicative rate. `amountBase = amount * fx_rate`. |
| `fx_notional_expr` | No | Expression evaluated against the transaction metadata to derive the base notional directly. When present, it takes precedence over `fx_rate`. |

### Example transaction with FX metadata

```json theme={null}
{
  "external_id": "txn_001",
  "amount": 1000.00,
  "currency": "EUR",
  "date": "2024-01-15",
  "fx_base_currency": "USD",
  "fx_rate": "1.085"
}
```

> [!NOTE]
>
> When the hints are absent or invalid (unparseable rate, failed expression), the transaction gets no base amount. It cannot match under a base-amount rule and stays unmatched. The run continues.

## FX rate-variance band

***

Cross-currency amounts often disagree slightly, because each side converts at a different rate or on a different day. The `fxVarianceBand` key on TOLERANCE rules handles this. It defines a second threshold stacked above the match tolerance, expressed as a decimal fraction (`0.0001` = 1 basis point).

After the strict-tolerance pass, Matcher rescans unmatched cross-currency `1:1` pairs. A pair whose base-amount residual exceeds the match tolerance but stays within the band still matches. The pair becomes a proposed group with a fixed confidence of 75, below the auto-confirm threshold, so it always requires human review. Matcher flags both transactions with the `FX_RATE_VARIANCE` exception reason. The residual then becomes a typed exception instead of collapsing to `UNMATCHED`.

The band applies only when:

* both sides carry a base amount and the same base currency.
* the original currencies differ (same-currency drift is a plain mismatch, not an FX case).
* all of the rule's other checks (date window, reference, composite fields) still pass. The rule must set `matchCurrency` to `false`, because the currency check rejects pairs whose original currencies differ.

A zero or absent `fxVarianceBand` disables the band.

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer ***" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "TOLERANCE",
   "priority": 3,
   "config": {
     "matchCurrency": false,
     "matchBaseAmount": true,
     "matchBaseCurrency": true,
     "matchReference": false,
     "percentTolerance": 0.01,
     "fxVarianceBand": "0.005"
   }
 }'
```

## Example: cross-currency reconciliation

***

**Source (EUR account):**

| ID | Amount | Base amount |
| - | - | - |
| txn\_001 | 1,000.00 EUR | 1,085.00 USD |

**Target (USD account):**

| ID | Amount | Base amount |
| - | - | - |
| txn\_002 | 1,095.00 USD | 1,095.00 USD |

Both transactions carry `fx_base_currency: "USD"`. txn\_001 carries `fx_rate: "1.085"` and txn\_002 carries `fx_rate: "1"`.

With a TOLERANCE rule (`matchCurrency: false`, `matchBaseAmount: true`, `matchReference: false`, `percentTolerance: 0.02`):

* Base amounts: $1,085.00 vs $1,095.00
* Difference: \$10.00
* Threshold: 2% of the larger amount, \$21.90
* Result: **Match** ($10.00 < $21.90)

## Best practices

***

> **Supply stable FX metadata per transaction**
>
> Attach `fx_base_currency` and `fx_rate` (or `fx_notional_expr`) to each transaction's metadata at the source, using the rate that applied when the transaction settled. Because the rate travels with the row, results are reproducible across runs, with no runtime rate lookups.

> **Combine with tolerance rules**
>
> FX conversions introduce small variances. Use TOLERANCE rules with matchBaseAmount to allow for rounding and rate timing differences.

> **Document your base currency choice**
>
> Use a consistent base currency across all contexts. USD is common for international operations. Use your reporting currency for domestic + international.

## Next steps

***

> **[Confidence Scoring](/en/products/matcher/reference/matcher-confidence-scoring)**
>
> How match scores work and what thresholds apply.

> **[Match Rules](/en/products/matcher/configuration/matcher-match-rules)**
>
> Full reference for rule types and config fields.


# Split and aggregate matches
Source: https://docs.lerian.studio/en/products/matcher/reference/matcher-split-aggregate

Reconcile 1:1, 1:N (split and aggregate), and N:M transaction patterns using context types and rule allocation flags to control how amounts are distributed.

Real-world reconciliation often involves transactions that don't match 1:1. A single payment may cover multiple invoices, or several deposits may consolidate into one bank entry. Matcher handles these complex scenarios through split and aggregate matching.

## Overview

***

The **context type** controls matching cardinality. Matcher supports three context types:

| Context type | Description | Example |
| - | - | - |
| **1:1** (one to one) | One source to one target | Single invoice payment |
| **1:N** (one to many) | One left-side transaction to many right-side transactions, for a **split** or an **aggregate** | Bulk payment covering invoices; deposits consolidated at a bank |
| **N:M** (many to many) | Any combination of sources and targets | Complex netting |

> [!NOTE]
>
> There is no separate `N:1` context type. The single transaction is always on the left side. For an aggregate, put the source that carries the consolidated entry on the left side.

## How it works

***

Two mechanisms control split and aggregate behavior:

1. **Context type**: determines the matching cardinality (`1:1`, `1:N`, or `N:M`).
2. **Rule allocation flags**: control how Matcher distributes amounts within a match group.

There is no separate "split" or "aggregate" setting on the context. The context type defines the allowed patterns, and the rule config controls allocation behavior.

### Context type mapping

| Context type | Allowed patterns |
| - | - |
| `1:1` | One source to one target only |
| `1:N` | One left-side transaction to many right-side transactions |
| `N:M` | Any combination of sources and targets |

### Rule allocation settings

All rule types accept allocation flags in their `config`. Matcher applies them in `1:N` contexts:

| Field | Type | Description |
| - | - | - |
| `allowPartial` | Boolean | Allow partial allocation of transaction amounts |
| `allocationToleranceMode` | String | How tolerance is measured: `ABS` (absolute) or `PERCENT` |
| `allocationToleranceValue` | Decimal | Tolerance threshold for allocation residuals |
| `allocationUseBaseAmount` | Boolean | Allocate base (converted) amounts. |
| `feeAware` | Boolean | Fee-aware 1:N allocation: consume each candidate's gross share (net + fee) instead of net only. Useful for marketplace splits where the payout is net of fees |
| `nmDeductionBand` | Decimal | TOLERANCE rules in `N:M` contexts only. Short-pay band for the N:M solver, as a decimal fraction of the short invoice face (`0.05` = 5%). Lets a payment subset under-pay an invoice subset within the band. Zero or absent disables it |

### Example: split rule with allocation

In a `1:N` context, each right-side transaction must pass the rule's checks against the left-side transaction. A rule that compares amounts matches only legs equal to the whole, so a split rule turns `matchAmount` off and lets allocation check the total. TOLERANCE rules always compare amounts.

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "EXACT",
   "priority": 2,
   "config": {
     "matchAmount": false,
     "matchReference": false,
     "allowPartial": true,
     "allocationToleranceMode": "ABS",
     "allocationToleranceValue": 10.0
   }
 }'
```

## Creating a 1:N context

***

To enable split or aggregate matching, create a context with type `1:N`:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Payment Reconciliation",
   "type": "1:N",
   "interval": "daily"
 }'
```

> [!TIP]
>
> API Reference: [Create context](/en/reference/products/matcher/create-context)

## 1:N split matching

***

One left-side transaction matches many right-side transactions.

### Common use cases

* **Bulk payment**: Single wire covering multiple invoices
* **Payroll**: One bank debit for multiple salary payments
* **Settlement**: One gateway payout for multiple orders

### Example: bulk invoice payment

**Left side (Bank Statement):**

| ID | Amount | Reference |
| - | - | - |
| bank\_001 | \$15,000.00 | BULK-PAY-2024-001 |

**Right side (Ledger Entries):**

| ID | Amount | Invoice |
| - | - | - |
| inv\_001 | \$5,000.00 | INV-2024-001 |
| inv\_002 | \$7,500.00 | INV-2024-002 |
| inv\_003 | \$2,500.00 | INV-2024-003 |

**Result:** 1:3 match with full allocation

## Aggregate matching (many-to-one)

***

Many transactions match one consolidated transaction. This uses the `1:N` context type with the consolidated source on the left side. There is no separate `N:1` type.

### Common use cases

* **Bank deposits**: Multiple checks deposited as one credit
* **Card settlements**: Daily batch of transactions as one deposit
* **Cash consolidation**: Multiple register receipts to one deposit

### Example: consolidated deposit

**Right side (Point of Sale):**

| ID | Amount | Register |
| - | - | - |
| pos\_001 | \$1,250.00 | REG-01 |
| pos\_002 | \$980.00 | REG-02 |
| pos\_003 | \$1,770.00 | REG-03 |

**Left side (Bank Statement):**

| ID | Amount | Reference |
| - | - | - |
| bank\_002 | \$4,000.00 | DEPOSIT-20240120 |

**Result:** 3:1 match with full allocation

## N:M many-to-many matching

***

Multiple source transactions match multiple target transactions. This is the most complex pattern.

### Common use cases

* **Intercompany netting**: Multiple invoices netted against multiple payments
* **Trade settlements**: Complex clearing with partial fills
* **Revenue recognition**: Multiple deliveries against multiple advances

### Example: intercompany netting

**Sources (Company A Payables):**

| ID | Amount | Reference |
| - | - | - |
| pay\_001 | \$10,000.00 | IC-PAY-001 |
| pay\_002 | \$8,000.00 | IC-PAY-002 |

**Targets (Company A Receivables):**

| ID | Amount | Reference |
| - | - | - |
| rec\_001 | \$12,000.00 | IC-REC-001 |
| rec\_002 | \$6,000.00 | IC-REC-002 |

**Result:** 2:2 match, \$18,000 total matched

To enable N:M matching, create a context with type `N:M`:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Intercompany Netting",
   "type": "N:M",
   "interval": "weekly"
 }'
```

## Running and reviewing matches

***

After configuring the context and rules, trigger a matching run and review the resulting groups.

### Run matching

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mode": "DRY_RUN"
 }'
```

A `DRY_RUN` run reports its statistics but stores no match groups. To list match groups, run with `COMMIT`.

### View match run history

```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/matching/contexts/{contextId}/runs" \
 -H "Authorization: Bearer $TOKEN"
```

### View a run's match groups

You must send the `contextId` query parameter. The response is a cursor-paginated list of match groups, each containing its matched transactions (across all cardinalities) and confidence scores.

```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/matching/runs/{runId}/groups?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN"
```

### Break (unmatch) a match group

To reverse an incorrect group, unmatch it. Matcher rejects a `PROPOSED` group and revokes a `CONFIRMED` group. In both cases, its transactions return to `UNMATCHED`. Revoking a `CONFIRMED` group also withdraws its open-item residuals, voids its fee variances, and withdraws the exceptions it raised, in the same transaction. You must send the `contextId` query parameter and a `reason` in the body.

```bash cURL theme={null}
curl -X DELETE "https://api.matcher.example.com/v1/matching/groups/{matchGroupId}?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "reason": "incorrect match - amounts do not match"
 }'
```

## Matching algorithm

***

The algorithm depends on the context type.

### 1:N deterministic sequential allocation

For split and aggregate (`1:N`) scenarios, Matcher uses deterministic sequential allocation:

1. **Sort**: Matcher sorts transactions deterministically to ensure reproducible results across runs.
2. **Collect**: For each left-side transaction, Matcher collects the right-side transactions that pass the rule's checks against it.
3. **Allocate**: Matcher allocates the collected transactions in sort order and stops when the remaining amount is within the allocation tolerance. It skips a transaction in another currency. It allocates only transactions with the settling sign of the context's `signConvention`: the sign of the left-side transaction under `SAME` (the default), the opposite sign under `OPPOSITE`.
4. **Track residuals**: Matcher tracks any remaining unallocated amounts. If `allowPartial` is `true`, Matcher caps an overshooting leg to the remaining amount. An under-covered split still surfaces a diagnostic exception.

### N:M set-matching solver

For `N:M` scenarios, Matcher does not allocate sequentially. It uses a bounded subset-selection solver. The solver buckets candidates by the rule's match identity. It then searches for a subset of left transactions and a subset of right transactions that reconcile against each other.

A group holds at most 4 transactions per side. Matcher skips a bucket that holds more than 40 transactions on either side. Only EXACT and TOLERANCE rules run in `N:M` contexts.

Selection remains deterministic over the sorted input. Each proposed group must clear the fixed confidence gate (minimum score 60). No transaction lands in two proposed groups within a run. On TOLERANCE rules, the `nmDeductionBand` key lets the solver admit a payment subset that under-pays an invoice subset within the band.

### Exception reasons

Transactions that Matcher cannot fully reconcile surface as typed exceptions:

* `SPLIT_INCOMPLETE`: allocations exist but do not fully cover the target amount, regardless of `allowPartial`.
* `OVER_SETTLED`: a transaction over-settled an obligation that an earlier run carried open. Matcher surfaces the over-settled remainder as a typed break.

You can filter the exceptions list by these `reason` values.

## Best practices

***

> **Start with 1:N before N:M**
>
> Many-to-many matching is complex. Start with simpler patterns and enable N:M only when necessary.

> **Use allocation tolerance for rounding**
>
> Small rounding differences are common in split payments. Set allocationToleranceValue to a few cents to avoid false exceptions.

> **Enable partial allocation deliberately**
>
> Set allowPartial to true only when you expect partial matches. This prevents false matches from incomplete data.

> **Dry-run before committing**
>
> Always test split and aggregate matching in DRY\_RUN mode first, and read the run statistics. A dry run stores no match groups.

> **Monitor residuals**
>
> Track residual amounts over time. Growing residuals may indicate systematic matching issues.

## Next steps

***

> **[Match Rules](/en/products/matcher/configuration/matcher-match-rules)**
>
> Configure rules and allocation settings.

> **[Security](/en/products/matcher/reference/matcher-security)**
>
> Security and access control.


# Context field maps
Source: https://docs.lerian.studio/en/products/matcher/ui/context-field-maps

Map each source's columns to the fields Matcher compares, from the Field Maps tab of a context in the Matcher module of Lerian Console.

Use the **Field Maps** tab of a context to tell Matcher how to read each source. A field map translates a source's columns into the canonical fields that the matching engine compares.

## Accessing the Field Maps tab

***

**Step 1**

In the Matcher module, select **Configure → Contexts**.

**Step 2**

Click a context to open its detail page.

**Step 3**

Select the **Field Maps** tab.

The **Map fields** step of the [Context setup wizard](/en/products/matcher/ui/context-setup-wizard) shows the same tab.

## Field map list

***

The tab shows one row for each source of the context. Archived sources do not appear. Each row shows the source name, its type, its side, and a summary of its map:

* **No field map yet**: the source has no map. Click **Add map** to create one.
* A count of mapped fields, followed by the first canonical fields. Use the pencil button to edit the map and the trash button to delete it.

If the context has no sources, the tab asks you to add them first. Click **Go to sources** to open the **Sources** tab.

> [!NOTE]
>
> Matcher activates a context only when each source on this tab has a field map. A source with a **camt.053 options** value other than **Auto** needs no field map. The camt.053 parser uses the ISO 20022 mapping. See [Context sources](/en/products/matcher/ui/context-sources).

## Creating or editing a field map

***

**Step 1**

Click **Add map** on a source row, or the pencil button on a mapped source. The **Create field map** or **Edit field map** side sheet opens.

**Step 2**

Add one mapping row for each canonical field. In each row, type the canonical field on the left and the source column on the right. Click **Add field** to add a row. Click the trash button on a row to remove it.

**Step 3**

Optionally, fill in the **Debit and credit column** fields. See [Debit and credit column](#debit-and-credit-column).

**Step 4**

Click **Create map** for a new map, or **Save map** for an existing one.

Matcher refuses a map that misses a required field or uses a field outside this list:

| Canonical field | Required | Description |
| - | - | - |
| `external_id` | Yes | The transaction reference in the source |
| `amount` | Yes | The transaction amount |
| `currency` | Yes | The transaction currency |
| `date` | Yes | The transaction date |
| `description` | No | A description of the transaction |
| `fee_amount` | No | The fee charged on the transaction. Fee verification reads it |
| `fee_currency` | No | The currency of the fee |

Matcher keeps the source columns that the map does not use as transaction metadata. [Fee rules](/en/products/matcher/ui/context-fee-rules) can test those metadata fields.

### Debit and credit column

Some files do not put a minus sign on debit amounts. They mark each row as a debit or a credit in a separate column. For these files, fill in the three fields:

| Field | Description |
| - | - |
| **Column** | The source column that holds the debit or credit marker |
| **Value for a debit** | The marker of a debit row, for example `D` |
| **Value for a credit** | The marker of a credit row, for example `C` |

If you fill in one of the fields, fill in all three. The debit and credit values must be different. Matcher compares them without regard to case.

Matcher imports debit rows as negative amounts and credit rows as positive amounts. The amount column must then hold amounts without a sign. A row with a signed amount, or with a marker that matches neither value, fails to import.

## Suggesting mappings with AI

***

The editor has a **Suggest mappings with AI** panel. It reads a sample of the source file and proposes source columns for the canonical fields. Matcher sends a capped slice of the sample to the language-model provider Lerian configures for your environment.

**Step 1**

Paste a sample of the source file into **Source sample**. A header row and a few lines are enough.

**Step 2**

Click **Suggest mappings**. The panel lists each proposed mapping with a confidence meter.

**Step 3**

Click **Accept** on a proposal to copy it into the mapping rows.

**Step 4**

Review the rows, then save the map.

A proposal changes nothing in Matcher. Only the map you save takes effect.

If the panel shows **AI assist unavailable**, the mapping advisor is not available. Map the fields by hand.

## Deleting a field map

***

Click the trash button on a mapped source. A **Delete field map?** dialog opens. Click **Delete** to remove the map. Matcher keeps the source.


# Context setup wizard
Source: https://docs.lerian.studio/en/products/matcher/ui/context-setup-wizard

Set up a reconciliation context step by step in the Matcher module of Lerian Console: create it, add sources, map fields, add rules, activate it, and run the first match.

The **Manual Setup** wizard in the Matcher module of Lerian Console guides you through the setup of one context. It takes you from a new context to a first completed match run. The source, field map, and rule steps use the same screens as the context detail page.

## Opening the wizard

***

You can open the wizard from two places:

* On the **Configure → Contexts** page, click **Set up by hand**. The wizard starts with a new context.
* On the Matcher dashboard, the **Getting started** checklist has a **Set up by hand** button. The wizard opens on the active context, at the first step that you have not completed.

## How the wizard works

***

The wizard shows the six steps in a rail. The header shows how many steps are complete.

* The wizard opens on the first step that you have not completed.
* You can open a completed step or the next step to do. The other steps stay locked.
* Matcher decides when you complete the source, field map, and rule steps. The wizard reads the setup progress of the context from Matcher.
* Click **Back** to go to the previous step. Click **Continue** to go to the next step. **Continue** becomes available when you complete the current step.
* Click **Exit setup** to leave the wizard and go to the Matcher dashboard. Your work stays saved. You can resume later.

## Setup steps

***

| Step | What you do | Done when |
| - | - | - |
| **1. Create context** | Fill in the context form and click **Create context**. See [Managing contexts](/en/products/matcher/ui/managing-contexts) for the fields | The context exists |
| **2. Add sources** | Add at least one left-side source and one right-side source. See [Context sources](/en/products/matcher/ui/context-sources) | Matcher no longer asks for a source |
| **3. Map fields** | Add a field map for each source. See [Context field maps](/en/products/matcher/ui/context-field-maps) | Matcher no longer asks for a field map |
| **4. Create rules** | Add at least one match rule. See [Context rules](/en/products/matcher/ui/context-rules) | Matcher no longer asks for a match rule or a fee rule |
| **5. Activate context** | Review the setup and click **Activate context** | The context is **Active** |
| **6. Run first match** | Upload data on both sides and click **Run first match** | A match run over data from both sides completes |

### Step 1: Create context

The step shows the same form as **New context**. Click **Create context** to save it. The new context becomes the active context in the Matcher sidebar. The wizard then moves to **Add sources**.

When you resume the wizard on an existing context, this step shows the context name, type, and interval.

### Step 4: Create rules

The step shows the **Rules** tab first. Add your match rules there.

A context with a fee normalization mode also needs a fee rule. After you add the match rules, Matcher can ask for a fee rule. The step then shows the **Fee Rules** tab. Add a fee rule there. See [Context fee rules](/en/products/matcher/ui/context-fee-rules).

### Step 5: Activate context

The step shows how many sources and match rules the context has. If Matcher still needs something, a **Setup incomplete** panel lists each missing item. For example: "Configure at least one fee rule."

The **Activate context** button becomes available when Matcher reports that the context is ready. Click it to activate the context.

### Step 6: Run first match

**Step 1**

Upload a transaction file for a left-side source. Then upload a file for a right-side source. See [Uploading reconciliation data](/en/products/matcher/ui/uploading-reconciliation-data).

**Step 2**

Wait until each side shows its imported rows. **Run first match** becomes available when both sides have a completed import.

**Step 3**

Click **Run first match**. The wizard follows the run until it ends.

When the run completes, the wizard shows **First match complete** with the run figures. Click **View exceptions** to open the exceptions of the run. Click **Go to dashboard** to open the Matcher dashboard.

If the run fails, the wizard shows the reason. Click **Retry run** to start it again.


# Context sources
Source: https://docs.lerian.studio/en/products/matcher/ui/context-sources

Add, edit, and archive the data sources of a reconciliation context from its Sources tab in the Matcher module, and run per-source ingestion actions.

Use the **Sources** tab of a context in the Matcher module of Lerian Console to set up the data sources of a reconciliation. Sources feed the two sides of the context. Each source declares the side it belongs to and how Matcher reads its files.

## Accessing the Sources tab

***

**Step 1**

In the Matcher sidebar, go to **Configure → Contexts**.

**Step 2**

Click the name of a context to open its page.

**Step 3**

Select the **Sources** tab.

## Sources list

***

The tab groups sources under **Left side** and **Right side**. Each row shows the source name and a type badge. A live source row can show these buttons:

| Button | Action |
| - | - |
| Calendar | [Manage ingestion schedules](#managing-ingestion-schedules) |
| Download | [Run a manual fetch](#running-a-manual-fetch) |
| Document | [Extract from a document](#extracting-from-a-document) |
| Pencil | [Edit the source](#editing-a-source) |
| Archive | [Archive the source](#archiving-and-restoring-a-source) |

Select **Show archived** to include archived sources. Archived sources show an **Archived** badge.

Before you can activate a context, it needs at least one live source on each side. Archived sources do not count.

## Creating a source

***

**Step 1**

On the **Sources** tab, click **Add source**. The **Add source** sheet opens.

**Step 2**

Fill in the source details:

| Field | Description |
| - | - |
| **Name** (required) | A name for the source, up to 50 characters |
| **Type** | The kind of system the data comes from, for example **Bank** or **Ledger**. A new source starts as **Bank** |
| **Side** | **Left** or **Right**. A new source starts as **Left** |

**Step 3**

Set how Matcher reads and imports the files of the source:

| Section | Description |
| - | - |
| **File dialect** | **Encoding**, **Delimiter**, **Decimal style**, and **Date style**. **Auto** uses the defaults: UTF-8, comma delimiter, dot decimals, and ISO dates |
| **Duplicate key** | The mapped fields that identify the same row. See [Duplicate detection](#duplicate-detection) |
| **Duplicate handling** | What Matcher does with a row that repeats the duplicate key. See [Duplicate detection](#duplicate-detection) |
| **Blank reference handling** | What Matcher does with a row that has no external ID. **Reject as errors** (the default) records an import error. **Import for review** imports the row as a transaction with pending-review status |
| **camt.053 options** | For camt.053 files: the **Date basis** (booking date or value date) and the **Entry reference** field. **Auto** uses the booking date and `NtryRef` |
| **Advanced config (JSON)** | Optional parser settings as a JSON object. Leave it empty for the defaults |

**Step 4**

Click **Save**.

> [!NOTE]
>
> You map source columns to Matcher fields on the context's [Field Maps](/en/products/matcher/ui/context-field-maps) tab, not in the source form. Each live source needs a field map before you can activate the context. A source with a camt.053 option other than **Auto** does not need one. Matcher reads camt.053 files with the ISO 20022 mapping.

## Duplicate detection

***

The **Duplicate key** fieldset sets which mapped fields make two rows the same row. Select one or more of `external_id`, `amount`, `currency`, `date`, `description`, `fee_amount`, and `fee_currency`. The default key is `external_id` alone.

You can select `description`, `fee_amount`, and `fee_currency` only when the field map of the source fills them. A new source has no field map yet, so these three stay unavailable until you map them and edit the source.

The form can show **Detection last changed** with a date. Rows that Matcher imported before that date keep the key they had. Matcher does not detect a duplicate that spans that date.

Matcher does not import a row that repeats the duplicate key of an earlier row. **Duplicate handling** sets what happens next:

| Option | Result |
| - | - |
| **Flag as exception (default)** | Matcher keeps the original row and opens a duplicate exception for review. You find it in [Exceptions](/en/products/matcher/ui/managing-exceptions) |
| **Keep first** | Matcher keeps the original row and drops the repeat. No exception opens |
| **Reject as errors** | Matcher records each repeat as an import error |

## Editing a source

***

Click the pencil button on a source. The **Edit source** sheet opens with the same fields. Change the fields and click **Save**.

## Managing ingestion schedules

***

An ingestion schedule sets when a source pulls in data by itself. It is separate from the [matching schedules](/en/products/matcher/ui/context-schedules) of the context, which set when matching runs.

**Step 1**

Click the calendar button on a source. The **Ingestion schedules** sheet opens. It lists the schedules of the source, enabled and disabled.

**Step 2**

Click **Add ingestion schedule**.

**Step 3**

Fill in the schedule:

| Field | Description |
| - | - |
| **Rail** | **File** pulls files over a transport. **Query** reads data through a [discovery connection](/en/products/matcher/ui/discovery-connections). You cannot change the rail later |
| **Format** (required) | The format of the data that the schedule pulls in |
| **Schedule** (required) | How often the source pulls, as a duration such as `15m`, `1h`, or `24h` |
| **Enabled** | On by default. A disabled schedule does not run |
| **Transport** | For a **File** rail: the **Protocol**, **Host**, **Path**, and the other fields of the remote endpoint. **Host** is required |
| **Connection** | For a **Query** rail: the discovery connection to read from |

**Step 4**

Click **Create schedule**.

To change a schedule, click its pencil button, change the fields, and click **Save**. To delete a schedule, click its trash button. In the **Delete ingestion schedule?** dialog, click **Delete**. The schedule stops running, and you cannot undo the delete.

## Running a manual fetch

***

A manual fetch pulls files from a remote endpoint and imports them now.

**Step 1**

Click the download button on a source. The **Run a manual fetch** sheet opens.

**Step 2**

Fill in the **Transport** fields. The sheet marks the required fields.

**Step 3**

Optionally, type a **Format hint (optional)**, such as `csv`. Matcher uses it for files that do not declare a format.

**Step 4**

Click **Run fetch**.

The sheet then lists each file it processed, with its transaction count or its error. When no file matches the path, the sheet says so. When manual fetch is off, the sheet shows a message and fetches nothing.

## Extracting from a document

***

Use document extraction to get transactions out of a PDF statement. Matcher sends a capped slice of the document's text layer to the language-model provider Lerian configures for your environment. When the PDF has no text layer, Matcher sends the PDF itself. Matcher proposes candidate transactions. Matcher imports nothing until you approve them.

**Step 1**

Click the document button on a source. The **Extract from a document** dialog opens.

**Step 2**

Select one PDF file in **PDF document**. The file can be up to 100 MB.

**Step 3**

Click **Extract**.

**Step 4**

When the dialog shows the number of candidates, click **Open review**. You review the candidates on the [Extraction Review](/en/products/matcher/ui/extraction-review) page.

When document extraction is off, the dialog shows a message and extracts nothing.

## Archiving and restoring a source

***

You cannot delete a source. You archive it instead. An archived source leaves the live sources, the setup readiness, and matching of the context. Matcher keeps its imported transactions and its field map.

**Step 1**

Click the archive button on a source. The **Archive source?** dialog opens.

**Step 2**

Click **Archive** followed by the source name.

**Step 3**

To bring the source back, select **Show archived** and click the restore button on the source. In the **Restore source?** dialog, click **Restore** followed by the source name.


# Managing contexts
Source: https://docs.lerian.studio/en/products/matcher/ui/managing-contexts

Create and manage reconciliation contexts in the Matcher module of Lerian Console: set the type, interval, sign convention, aging and fee normalization, then follow the next setup step.

Use the **Contexts** page in the Matcher module of Lerian Console to create and manage reconciliation contexts. A context groups the sources, field maps, rules, and schedules of one reconciliation.

## Accessing the Contexts page

***

In the Matcher module, select **Configure → Contexts**.

## Context list

***

The table hides archived contexts until you set the **Status** filter to **Archived**. You can also filter by **Type**. The list shows 50 contexts per page, with **Previous** and **Next** controls.

| Column | Description |
| - | - |
| **Name** | The context name. Click it to open the context detail page |
| **Type** | Matching cardinality: **One-to-one**, **One-to-many**, or **Many-to-many** |
| **Interval** | The cadence label of the context |
| **Status** | Current state of the context |
| **Created** | When the context was created |

### Context statuses

| Status | Description |
| - | - |
| **Draft** | You configure the context before you activate it |
| **Active** | The context is operational and accepts match runs |
| **Paused** | The context is temporarily suspended |
| **Archived** | The context is retired. Matcher keeps its history |

You archive and restore contexts. You do not delete them. See [Context actions](#context-actions).

## Creating a new context

***

The Contexts page gives you two ways to create a context:

* **New context** opens a side sheet with the context form. Fill in the fields and click **Save**. The Console then opens the detail page of the new context.
* **Set up by hand** opens the guided setup. It takes you from the context form to a first match run in six steps. See [Context setup wizard](/en/products/matcher/ui/context-setup-wizard).

Both paths create the context in the **Draft** status. The form has these fields:

| Field | Description |
| - | - |
| **Name** (required) | A descriptive name for the context, up to 100 characters (e.g., "Bank Reconciliation Q1") |
| **Type** (required) | Matching cardinality: **One-to-one** (`1:1`), **One-to-many** (`1:N`), or **Many-to-many** (`N:M`). You cannot change it after you create the context |
| **Interval** (required) | A free-text cadence label of up to 100 characters, such as `daily` or `weekly`. It does not start runs. To run matching on a timetable, add a [matching schedule](/en/products/matcher/ui/context-schedules) |
| **Auto-match on upload** | When on, a match run starts after each upload to an **Active** context completes |
| **How a payment appears** | The sign that a payment carries next to the invoice or charge it pays. See [Sign convention](#sign-convention) |
| **Aging threshold (days)** | Under **Open-item aging**. The number of days after which Matcher flags an open-item residual as aged. Leave it empty to disable aging for this context |
| **Aging calendar** | Under **Open-item aging**. How Matcher measures the age: **Raw calendar days**, **US Federal**, or **Brazil ANBIMA** business days |
| **Mode** | Under **Fee normalization**. **None**, **Net**, or **Gross**. **Net** compares amounts after fees. **Gross** compares amounts before fees |
| **Abs tolerance** and **Pct tolerance** | Under **Fee normalization**. They appear after you select a mode. They set how far the actual fee can differ from the expected fee. Matcher applies the larger of the two |

If you select a fee normalization mode, add a fee rule on the [Fee Rules](/en/products/matcher/ui/context-fee-rules) tab. You define the fee schedules themselves in **Settings → Fee Schedules**. See [Managing fee schedules](/en/products/matcher/ui/managing-fee-schedules).

### Sign convention

The **How a payment appears** field has two options:

* **Same sign as what it pays** (default): a payment carries the same sign as the item it settles. A negative amount is a reversal.
* **Opposite sign of what it pays**: a payment carries the opposite sign of the invoice it settles.

Choose the convention before the first match run. Matcher refuses a change after the context carries an open-item balance. It also refuses a change while a match run is in progress.

## Context detail page

***

Click a context name in the list to open its detail page.

### Next step card

While a context is not ready, a **Next step** card appears above the tabs. It tells you what Matcher needs next, for example: "Add at least one right-side source."

Click **Continue setup** to open the tab where you complete that step. The card disappears when the context meets every activation requirement.

### Tabs

| Tab | Description |
| - | - |
| **General Information** | The current settings of the context and when it was created and updated |
| **Sources** | The data sources of the context. See [Context sources](/en/products/matcher/ui/context-sources) |
| **Field Maps** | How each source's columns map to the fields that Matcher compares. See [Context field maps](/en/products/matcher/ui/context-field-maps) |
| **Rules** | The match rules of the context. See [Context rules](/en/products/matcher/ui/context-rules) |
| **Matching schedules** | When matching runs automatically. See [Context schedules](/en/products/matcher/ui/context-schedules) |
| **Fee Rules** | Which fee schedule applies to which transactions. See [Context fee rules](/en/products/matcher/ui/context-fee-rules) |

### Context actions

The actions sit in the page header, so you can use them from every tab:

| Action | Description |
| - | - |
| **Edit context** | Opens a side sheet with the context form. You can change every field except **Type**. Click **Save** to apply |
| **Clone context** | Creates a new context from this setup. Enter a **Clone name**. **Include sources** copies the sources and their field maps. **Include rules** copies the match rules and fee rules. Click **Create clone** |
| **Archive context** | Retires the context. Matcher keeps its history, and you can restore the context later |
| **Restore context** | Appears on an archived context. It returns the context to **Draft**. Activate it again to resume matching |

The edit form also has a **Status** field with **Active**, **Paused**, and **Archived**. A **Draft** context also lists **Draft**. To pause or resume a context, change its status there. To activate a **Draft** context, set its status to **Active**. Matcher refuses the activation until the setup is complete. The **Next step** card names the next item to set up.

> [!NOTE]
>
> You manage sources, field maps, rules, matching schedules, and fee rules inside the context detail page. They have no separate pages.


# Matcher dashboard
Source: https://docs.lerian.studio/en/products/matcher/ui/matcher-dashboard

Watch reconciliation health for the active Matcher context: match rate, cash impact, exception SLA, match-rate trend, and source breakdown.

The Matcher module in Lerian Console opens on the **Reconciliation dashboard**. The dashboard shows the health of one reconciliation context over a period. It shows how much of the pool matched and what stays open. It also shows the unmatched cash exposure and how fast your team resolves exceptions.

## Accessing the dashboard

***

Click **Dashboard** in the Matcher sidebar.

The dashboard shows the **Active context** that you select in the Matcher sidebar. To see another context, change the **Active context**. Choose the period with the buttons in the page header. The options are **Last 7 days**, **Last 30 days**, and **Last 90 days**. The default is **Last 90 days**.

> [!NOTE]
>
> The dashboard refreshes every 30 seconds. The status rail shows when the figures last updated, with a **Refresh** button. If a refresh fails, the rail says so and shows a **Retry** button. The figures on the page can then be out of date.

The sections below follow the order of the page, from top to bottom.

## Status rail

***

A rail across the top of the page shows these items:

| Item | Description |
| - | - |
| Context name | The active context. |
| **Total pending** | Pending exceptions, within SLA and overdue together. |
| **Pending overdue** | Pending exceptions past their SLA. The badge turns red when the count is above zero. |
| Last update | The time of the last refresh, for example **Updated just now**, and the **Refresh** button. |

## Match rate

***

The **Match rate** card is the main figure of the page. A bar splits the transactions of the context into matched and unmatched, by count. A marker on a 0 to 100 ruler shows the match rate.

Below the bar, two columns show the **Matched** and **Unmatched** totals. Each column holds a transaction count and an amount. The unmatched amount shows in red when unmatched transactions exist.

When the figures share one currency, a **By amount** line shows the match rate by amount. It also shows the difference from the rate by count (**Δ vs count**). With more than one currency in the figures, the amounts show a dash. The note **Currency not available for this total** explains the dash.

## Cash impact and exception SLA

***

Two cards sit next to the **Match rate** card:

| Card | Description |
| - | - |
| **Cash impact** | The unmatched cash exposure for the period, per currency, with the transaction count of each currency. A **By aging** list splits the exposure into age buckets. With more than one currency, the bucket amounts show a dash. |
| **Exception SLA** | **SLA compliance** as a percentage, then **Resolved on time** (with the late count), **Pending (within SLA)**, **Pending overdue**, and **Average resolution**. An **Exception aging** list counts exceptions in three age buckets: `<24h`, `1-3d`, and `>3d`. |

## Match rate over time

***

The **Match rate over time** card plots the daily match rate for the period. Days with no imported data do not appear on the line. Above the line, **pts vs prior day** shows the change from the previous day on the line, in percentage points.

Watch the line for a fall in the match rate. A fall can point to a rule that no longer fits your data, or to a problem in the data.

With only one day of activity, the card shows the rate of that day instead of a line. With no activity in the period, the card says that the line needs at least two days.

## Source breakdown

***

The **Source breakdown** card lists each source with its match rate and a small balance bar. It also gives the matched and unmatched transaction counts of each source. Use it to find the sources that leave the most items unmatched. The card does not show when the period has no data per source.

## First-run states

***

The dashboard needs a context with reconciliation data. Until then, it shows one of these states:

| State | What the page shows |
| - | - |
| No context exists | A message that asks you to pick a reconciliation context, and a **Go to contexts** button that opens the **Contexts** page, where you create one. |
| The context has no data in the period | A message that the context has no reconciliation data yet. One button opens the next setup step, for example **Add sources** or **Run a match**. |

## Getting started checklist

***

When the context has data but its setup is not complete, a **Getting started** checklist shows below the status rail. It counts the complete steps and lists these five steps:

1. **Create a reconciliation context**
2. **Add both data sources**
3. **Create a match rule**
4. **Activate the context**
5. **Complete your first match run**

The current step has a button that opens the place where you complete it. Use **Set up by hand** to open the guided setup for the context. See [Context setup wizard](/en/products/matcher/ui/context-setup-wizard). Use the arrow button to collapse or expand the list.

The checklist closes when all five steps are complete. Click **Dismiss** to close it at once. After either event, the checklist does not come back in the same browser.

## Where the runs live

***

The dashboard summarizes health. It does not list runs. To start a run, use **Operate → Reconciliations**. See [Running reconciliations](/en/products/matcher/ui/executing-reconciliation). For the full run and import history, see [Operational history](/en/products/matcher/ui/operational-history).


# Matcher module pages
Source: https://docs.lerian.studio/en/products/matcher/ui/matcher-module

Find each screen of the Matcher module in Lerian Console by sidebar group: configure contexts, import data, run matches, resolve exceptions, and report.

The **Matcher module** of Lerian Console is where you operate Matcher, Lerian's reconciliation engine. You configure contexts and match rules, import transaction data, run reconciliations, review results, and resolve exceptions. This page lists the main pages of the module by sidebar group. If you're new to it, start with [Matcher in Lerian Console](/en/products/matcher/ui/matcher-ui-overview).

> [!WARNING]
>
> Matcher is only available if you've acquired the Matcher product. For access, [get in touch with our team](https://lerian.studio/contact).

## Dashboard

***

The module opens on the **Dashboard**, which shows the reconciliation health of the active context.

> **[Matcher dashboard](/en/products/matcher/ui/matcher-dashboard)**
>
> See a walkthrough of the Dashboard: the match rate card, the match-rate trend, cash impact, and exception SLA.

## Available pages

***

The sidebar groups pages by workflow phase.

### Configure

> **[Contexts](/en/products/matcher/ui/managing-contexts)**
>
> Create and manage reconciliation contexts. Each context groups sources, field maps, rules, schedules, and fee rules.

> **[Guided setup](/en/products/matcher/ui/context-setup-wizard)**
>
> Build a context step by step, from its creation to its first match run. It opens from the Contexts page.

> **[Rule Suggestions](/en/products/matcher/ui/rule-suggestions)**
>
> Review the match rules Matcher proposes for a context, then approve or reject them.

### Operate

> **[Reconciliations](/en/products/matcher/ui/executing-reconciliation)**
>
> Start reconciliation runs for the active context and follow their progress. Each run's detail page holds its match groups.

> **[Operational History](/en/products/matcher/ui/operational-history)**
>
> Track reconciliation runs and import jobs for the active context.

> **[New Reconciliation](/en/products/matcher/ui/uploading-reconciliation-data)**
>
> Upload a transaction file into a source of the active context and follow the import.

> **[Match groups](/en/products/matcher/ui/managing-matches)**
>
> Review the match groups of a run on its detail page, which opens from Reconciliations.

### Resolve

> **[Unmatched](/en/products/matcher/ui/manual-matching)**
>
> Work the transactions the engine could not match. Pair them manually or ignore them.

> **[Open Items](/en/products/matcher/ui/open-items)**
>
> Follow the remainders that partial matches carry forward.

> **[Extraction Review](/en/products/matcher/ui/extraction-review)**
>
> Check the transactions Matcher extracted from a document before they enter a source.

### Exception Handling

> **[Exceptions](/en/products/matcher/ui/managing-exceptions)**
>
> View and resolve the transactions that the engine could not match.

> **[Disputes](/en/products/matcher/ui/managing-disputes)**
>
> Manage disputed transactions that need evidence and a decision.

### Reporting

> **[Portfolio, Reports, and Exports](/en/products/matcher/ui/reports-and-exports)**
>
> Compare contexts, read reconciliation reports, and download exports.

> **[Audit Logs](/en/products/matcher/ui/managing-audit-logs)**
>
> View the hash-chained record of configuration and operational changes.

> **[Archives](/en/products/matcher/ui/managing-archives)**
>
> Browse and download completed audit-log archives.

### Settings

> **[Layout Templates](/en/products/matcher/ui/layout-templates)**
>
> Describe fixed-width file layouts so Matcher can read them.

> **[Fee Schedules](/en/products/matcher/ui/managing-fee-schedules)**
>
> Define expected fee structures (flat, percentage, tiered, or expression-based) for fee verification during reconciliation.

> **[Actor Mappings](/en/products/matcher/ui/managing-actor-mappings)**
>
> Link opaque actor IDs to a display name or email.

> **[Discovery](/en/products/matcher/ui/discovery-connections)**
>
> Connect external data sources, browse their schemas, and extract data from them.

> **[Aggregators](/en/products/matcher/ui/aggregator-connections)**
>
> Connect open-finance data aggregators that feed transactions into Matcher.


# Matcher in Lerian Console
Source: https://docs.lerian.studio/en/products/matcher/ui/matcher-ui-overview

Operate Matcher from its Lerian Console module: configure contexts, sources, and rules, import files, run matches, and resolve exceptions without writing API calls.

Matcher, Lerian's reconciliation engine, has a module in Lerian Console. The **Matcher module** puts the reconciliation workflow behind a visual interface. You configure contexts, sources, and match rules, import transaction files, run reconciliations, review matches, and resolve exceptions, all without writing API calls.

> [!WARNING]
>
> Matcher is only available if you've acquired the Matcher product. For access, [get in touch with our team](https://lerian.studio/contact).

## Opening the Matcher module

***

To use the module, turn on Matcher for your organization in **Settings → Products**. See [Products](/en/platform/console/settings-products).

To open the module, select the **Matcher** card on the Lerian Console home page. If Matcher is off for your organization, each Matcher page shows a message that says so.

## Active context

***

The Matcher sidebar holds the **Active context** selector. Screens that work on one reconciliation context, such as the Dashboard, Reconciliations, and Unmatched, use the active context. Switch it to change the data these screens show.

The Console keeps your choice in this browser. If the stored context no longer exists, the Console selects the first context in the list.

## Main work surfaces

***

> **[Dashboard](/en/products/matcher/ui/matcher-dashboard)**
>
> Reconciliation health at a glance for the active context: match rate, cash impact, and exception SLA.

> **[Reconciliation setup](/en/products/matcher/ui/managing-contexts)**
>
> Create contexts and manage their sources, field maps, rules, schedules, and fee rules from each context's detail page.

> **[Imports and runs](/en/products/matcher/ui/executing-reconciliation)**
>
> Import transaction files and start reconciliation runs, then follow their progress.

> **[Matches](/en/products/matcher/ui/managing-matches)**
>
> Review the match groups of each run, or pair the remaining transactions in the Unmatched workbench.

> **[Exceptions and disputes](/en/products/matcher/ui/managing-exceptions)**
>
> Work the queue of transactions that did not match automatically. Resolve them, or escalate them into disputes.

> **[Reporting](/en/products/matcher/ui/reports-and-exports)**
>
> Portfolio health, reports, exports, audit logs, and archives.

For a directory of the module's screens by sidebar group, see [Matcher module pages](/en/products/matcher/ui/matcher-module).

## Beyond the Matcher module

***

The Matcher module works through the Matcher API, so you can mix surfaces:

* **API**: automate any workflow programmatically. Start with the [developer quick start](/en/reference/products/matcher/matcher-developer-quick-start).
* **MCP server**: let an AI assistant operate Matcher through the [Model Context Protocol](/en/products/matcher/mcp/matcher-mcp-overview).


# Pix reconciliation
Source: https://docs.lerian.studio/en/products/matcher/use-case-guides/matcher-pix-reconciliation

Configure Matcher to reconcile Pix cash-in and cash-out flows between Midaz Ledger and BACEN's SPI settlement extract using endToEndId as the matching key.

This guide walks through reconciling Pix transactions between Midaz Ledger and BACEN (Brazil's Central Bank) settlement data using Matcher. It covers both Pix sent (cash-out) and Pix received (cash-in), from configuration to daily operation and exception handling.

By the end of this guide, you will have a Matcher context that reconciles your Pix transactions against BACEN's SPI settlement extracts every day.

## Pix transaction flows

***

The two flows below show what Matcher needs to reconcile on each side.

### Pix sent (cash-out)

![Pix sent cash-out flow](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/matcher-pix-cashout-flow.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=fe721fcb3a4d1d78dc81387176d2fea4)

Cash-out flow: from client initiation through SPI settlement to reconciliation in Matcher.

1. **Client initiates Pix**: The end user triggers a Pix payment via the app or API.
2. **Plugin creates initiation**: The Pix plugin creates an initiation record and resolves the destination account via DICT lookup.
3. **Plugin processes payment**: The plugin debits the client account in Midaz (transaction in `pending` status) and sends the payment instruction to SPI.
4. **Settlement confirmed**: SPI sends a webhook confirming settlement. The Midaz transaction becomes committed.
5. **Matcher reconciles**: Matcher compares the committed Midaz transaction against the corresponding entry in the BACEN SPI settlement extract.

### Pix received (cash-in)

![Pix received cash-in flow](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/matcher-pix-cashin-flow.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=66eac6d7ed7a511890619ecd5c42a989)

Cash-in flow: from inbound SPI notification through Midaz credit to reconciliation in Matcher.

1. **Inbound Pix arrives**: SPI sends a synchronous webhook containing the inbound Pix data.
2. **Plugin validates**: The Pix plugin validates the payload and approves the transaction.
3. **Credit transaction created**: The plugin creates a CREDIT transaction in Midaz for the recipient account.
4. **Settlement confirmed**: The settlement webhook confirms the transaction is final.
5. **Matcher reconciles**: Matcher compares the Midaz credit transaction against the corresponding entry in the BACEN SPI settlement extract.

> [!NOTE]
>
> In both flows, the **endToEndId** is the unique identifier that links the Midaz transaction to the BACEN settlement record. This is the primary key for reconciliation.

## Configuration step-by-step

***

**1. Create the context**

Create a reconciliation context for Pix transactions. Use type `1:1` because each Pix transaction has exactly one corresponding BACEN settlement entry.

```json theme={null}
{
  "name": "Pix Daily Reconciliation",
  "type": "1:1",
  "interval": "daily",
  "autoMatchOnUpload": false
}
```

Pix transactions have no intermediate fees or partial settlements. A Pix of R$ 150.00 in Midaz must appear as exactly R$ 150.00 in the BACEN extract. The match rules below compare amounts exactly.

Setting `autoMatchOnUpload` to `false` gives you control over when matching runs. Use that control when you need both sources ingested before the run executes.

> [!TIP]
>
> See the full request schema at [Create context](/en/reference/products/matcher/create-context).

**2. Create the sources**

Each context needs two sources: one for Midaz transactions and one for the BACEN settlement extract.

**Source A, Midaz (type `LEDGER`):**

```json theme={null}
{
  "name": "Midaz - Pix Transactions",
  "type": "LEDGER",
  "side": "LEFT",
  "config": {}
}
```

`LEDGER` is Matcher's category for internal ledger data. It is not a live Midaz connector. You export the day's Pix transactions from Midaz, including the `endToEndId` metadata as a flat column. You then upload the export to this source, manually or via an automated pipeline. See [Matcher and Midaz](/en/products/matcher/integrations/matcher-midaz-integration) for the export/import flow.

**Source B, BACEN SPI extract (type `CUSTOM`):**

```json theme={null}
{
  "name": "BACEN SPI Settlement Extract",
  "type": "CUSTOM",
  "side": "RIGHT",
  "config": {
    "description": "Daily SPI settlement file from BACEN"
  }
}
```

The BACEN source uses type `CUSTOM` because you upload the SPI settlement file manually or via an automated pipeline each day.

Each source must declare a `side` (`LEFT` or `RIGHT`). A context reconciles its `LEFT` source against its `RIGHT` source. Assign one side to Midaz and the other to BACEN. Keep the assignment consistent across both sources.

> [!TIP]
>
> See the full request schema at [Create source](/en/reference/products/matcher/create-source).

**3. Create field maps**

Field maps tell Matcher how to translate fields from each source into the canonical fields used for matching.

A field map is a JSON object whose keys come from Matcher's closed vocabulary: `external_id`, `amount`, `currency`, and `date`, plus the optional `description`, `fee_amount`, `fee_currency`, and `direction`. The `direction` key takes an object, `{column, debit, credit}`, for a file that marks each row as debit or credit in a separate column. Every other key takes a raw column name in the source. Lookups are flat. A mapping value must name a top-level column in the row. The Midaz export must therefore carry `endToEndId` as its own flat column (see [Matcher and Midaz: custom field mapping](/en/products/matcher/integrations/matcher-midaz-integration#custom-field-mapping)).

> [!WARNING]
>
> `external_id` is the **cross-side matching reference**: the value the engine compares between the two sources when a rule sets `matchReference`. Map it to the `endToEndId` on both sides. Do not map side-local row IDs (the Midaz transaction `id`, the BACEN `id_liquidacao`) into `external_id`. Those values never agree across sources, so reference matching would never find a counterpart.

The following table shows how each canonical field maps to the column in each source:

| Canonical field | Midaz export column | BACEN extract column |
| - | - | - |
| `external_id` | `endToEndId` | `end_to_end_id` |
| `amount` | `amount` | `valor` |
| `currency` | `asset_code` | `moeda` |
| `date` | `created_at` | `data_liquidacao` |

**Midaz source field map:**

```json theme={null}
{
  "mapping": {
    "external_id": "endToEndId",
    "amount": "amount",
    "currency": "asset_code",
    "date": "created_at"
  }
}
```

**BACEN source field map:**

```json theme={null}
{
  "mapping": {
    "external_id": "end_to_end_id",
    "amount": "valor",
    "currency": "moeda",
    "date": "data_liquidacao"
  }
}
```

> [!TIP]
>
> See [Create field map](/en/reference/products/matcher/create-field-map) for the full request schema and [Field mapping](/en/products/matcher/configuration/matcher-field-mapping) for the canonical vocabulary.

**4. Create match rules**

Match rules define how Matcher compares transactions across sources. For Pix reconciliation, two rules cover the vast majority of scenarios.

**Rule 1 (exact match by endToEndId, priority 1):**

```json theme={null}
{
  "type": "EXACT",
  "priority": 1,
  "config": {
    "matchAmount": true,
    "matchCurrency": true,
    "matchDate": true,
    "matchReference": true,
    "datePrecision": "DAY",
    "caseInsensitive": false,
    "referenceMustSet": true
  }
}
```

This rule resolves approximately 95% of cases. The `endToEndId` is unique per Pix transaction across the entire ecosystem. A match on reference, amount, currency, and date gives a confirmed reconciliation with maximum confidence. The rule sets `caseInsensitive` to `false` because `endToEndId` values are case-sensitive. The rule sets `referenceMustSet` to `true`, so both sides must carry the `endToEndId` before comparison. This prevents false positives on amount and date alone.

**Rule 2 (date tolerance fallback, priority 51):**

```json theme={null}
{
  "type": "DATE_LAG",
  "priority": 51,
  "config": {
    "maxDays": 1,
    "minDays": 0,
    "inclusive": true,
    "direction": "ABS",
    "feeTolerance": 0,
    "matchCurrency": true
  }
}
```

A Pix initiated at 23:58 may settle in BACEN on the following calendar day. This rule allows a 1-day window to cover D+1 settlement scenarios. This rule relies on amount and currency matching only. Rule 1 handles the `endToEndId` comparison.

> [!TIP]
>
> See [Create match rule](/en/reference/products/matcher/create-match-rule) for the full request schema and all available rule types.

**5. Activate and schedule**

Once all configuration is in place, activate the context and create a daily schedule.

**Activate the context:**

```bash theme={null}
curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{ "status": "ACTIVE" }'
```

**Create a schedule to run daily at 07:00 UTC:**

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/schedules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "cronExpression": "0 7 * * *",
   "enabled": true
 }'
```

Running at 07:00 UTC provides enough margin for D+1 settlements to appear in the BACEN extract. It also gives you time to upload the daily file before the matching run executes.

> [!TIP]
>
> See [Update context](/en/reference/products/matcher/update-context) and [Create schedule](/en/reference/products/matcher/create-schedule) for the full request schemas.

## Daily operation

***

Once configured, the daily reconciliation workflow follows five steps.

**1. Upload BACEN extract**

Upload the previous day's SPI settlement file to the BACEN source. Matcher parses CSV, JSON, XML, and other formats from its [format catalog](/en/products/matcher/imports/matcher-import-formats).

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{sourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: multipart/form-data" \
 -F "format=csv" \
 -F "file=@bacen_spi_2026-03-17.csv"
```

You can automate this step with a pipeline that fetches the SPI file and uploads it before the scheduled matching run.

**2. Upload the Midaz export**

Export the previous day's committed Pix transactions from Midaz, including the `endToEndId` metadata as a flat column. Upload the export to the Midaz source the same way. The same pipeline usually automates this step. See [Matcher and Midaz](/en/products/matcher/integrations/matcher-midaz-integration) for the export/import flow.

**3. Matcher runs at 07:00 (or manually)**

The scheduled run executes automatically at 07:00 UTC. To run matching manually, use the run endpoint.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{ "mode": "DRY_RUN" }'
```

Use `DRY_RUN` first to preview results without committing them. When satisfied, run again with `COMMIT`:

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{ "mode": "COMMIT" }'
```

**4. Review results**

After the run completes, retrieve the matched groups to see the results.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/matching/runs/{runId}/groups?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN"
```

Each group shows the matched Midaz transaction and its corresponding BACEN settlement entry, along with the rule that matched them and the confidence score.

**5. Resolve exceptions**

Unmatched transactions appear as exceptions. These require investigation: a transaction present in one source but not the other, or a mismatch in amount or date beyond the configured tolerance.

Review exceptions, determine the root cause, and resolve them by force matching, ignoring, or correcting the underlying data.

> [!TIP]
>
> Always run a `DRY_RUN` first when testing new rules or after configuration changes. This prevents Matcher from committing unintended matches.

## Practical example: one day of data

***

The following example illustrates a complete reconciliation run for March 17, 2026.

### Midaz transactions (Source A)

| ID (type) | endToEndId | Amount · date |
| - | - | - |
| txn-001 (Pix OUT) | E123456789202603170001 | 150.00 · 2026-03-17 10:15 |
| txn-002 (Pix IN) | E987654321202603170042 | 3200.50 · 2026-03-17 11:30 |
| txn-003 (Pix OUT) | E555666777202603170099 | 89.90 · 2026-03-17 23:58 |
| txn-004 (Pix IN) | E111222333202603170007 | 500.00 · 2026-03-17 14:00 |

### BACEN SPI extract (Source B)

| id\_liquidacao | end\_to\_end\_id | valor / data\_liquidacao |
| - | - | - |
| liq-8801 | E123456789202603170001 | 150.00 / 2026-03-17 |
| liq-8802 | E987654321202603170042 | 3200.50 / 2026-03-17 |
| liq-8803 | E555666777202603170099 | 89.90 / 2026-03-18 |
| liq-8804 | E444555666202603170055 | 750.00 / 2026-03-17 |

### Match results

| endToEndId | Midaz ↔ BACEN | Result (rule) |
| - | - | - |
| E12345...0001 | txn-001 ↔ liq-8801 | Match (EXACT, score: 100) |
| E98765...0042 | txn-002 ↔ liq-8802 | Match (EXACT, score: 100) |
| E55566...0099 | txn-003 ↔ liq-8803 | Proposed, D+1 (DATE\_LAG, score: 90) |
| E11122...0007 | txn-004 ↔ none | Exception (no rule) |
| E44455...0055 | none ↔ liq-8804 | Exception (no rule) |

### Analysis

* **txn-001 and txn-002:** Exact match on endToEndId, amount, currency, and date. Rule 1 resolved these with confidence score 100.
* **txn-003:** Pix initiated at 23:58, settled in BACEN on 2026-03-18. Rule 2 (DATE\_LAG with 1-day window) proposed this pair with confidence score 90. Matcher never confirms a `DATE_LAG` group automatically: it proposes the group, whatever its score. To pair the two transactions, un-match the proposed group, then create a manual match.
* **txn-004:** Present in Midaz but absent from BACEN. Possible settlement failure or SPI timeout. Investigate the transaction status via the Pix plugin.
* **liq-8804:** Present in BACEN but absent from Midaz. This inbound Pix did not reach the ledger. Check webhook delivery or reprocess the message.

## Handling Pix exceptions

***

The following table covers the most common Pix exception scenarios and recommended actions.

| Scenario | Probable cause | Recommended action |
| - | - | - |
| In Midaz, not in BACEN | Settlement failure, SPI timeout, rejected transaction | Check transaction status in the Pix plugin. If rejected, revert in Midaz. |
| In BACEN, not in Midaz | Inbound Pix not processed, webhook failure | Reprocess the message. Create a manual transaction if needed. |
| Amount mismatch | Rare in Pix (no intermediate fees). | Investigate original records. Create a manual match if the difference is acceptable. |
| Date mismatch (>1 day) | Held transaction, reprocessing | Verify it is the same Pix. Create a manual match, or ignore the transaction. |

### Manual match

When you have confirmed that two records represent the same Pix transaction but Matcher could not match them automatically, pair them with a manual match. Matcher creates a `CONFIRMED` match group at confidence 100.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/matching/manual?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "transactionIds": ["{midazTransactionId}", "{bacenTransactionId}"],
   "notes": "Same Pix confirmed via endToEndId lookup in SPI. D+2 settlement delay confirmed with BACEN"
 }'
```

### Ignore transaction

When you must exclude a transaction from reconciliation (for example, a duplicate entry or an already-reversed Pix), mark it as ignored.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/transactions/{transactionId}/ignore" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "reason": "Pix reversal already processed — duplicate entry"
 }'
```

> [!TIP]
>
> See [Create manual match](/en/reference/products/matcher/create-manual-match) and [Ignore transaction](/en/reference/products/matcher/ignore-transaction) for the full request schemas.

## Pix refunds (devoluções)

***

Pix refunds generate reverse transactions that also need reconciliation. When the Pix plugin processes a refund, it creates a new transaction in Midaz with:

* The `originalEndToEndId` linking back to the original Pix transaction
* A new `returnIdentification` (rtrId) that uniquely identifies the refund in SPI

BACEN's settlement extract includes refund entries with both identifiers, so Matcher can reconcile them against the corresponding Midaz refund transactions.

For low refund volumes, you can reconcile these within the same Pix Daily Reconciliation context. For high volumes, create a separate context dedicated to refund reconciliation. This simplifies exception triage and keeps refund metrics isolated from standard Pix flow metrics.

> [!NOTE]
>
> Refund initiation via `POST /v1/transfers/{id}/refunds` is a Pix plugin endpoint, not a Matcher endpoint. Matcher does not initiate transfers or refunds. It only reconciles the resulting transactions. Each refund carries the `originalEndToEndId` and a new `returnIdentification` for end-to-end tracking, which Matcher then uses to match the refund against BACEN's settlement extract. For refund initiation, see the [Pix plugin documentation](/en/interfaces/pix/pix-overview).

## Best practices

***

> **Use endToEndId as the primary reference**
>
> The `endToEndId` is the unique Pix identifier across the entire ecosystem, from the initiating institution through SPI to the receiving institution. Store it in Midaz transaction metadata and make sure the BACEN extract carries it. Without it, reconciliation falls back to amount and date matching, which is far less reliable.

> **Run reconciliation the following day**
>
> Pix transactions near end of day may settle in BACEN on D+1. Scheduling Matcher for 07:00 UTC ensures the BACEN extract includes all settlements from the previous day before matching runs. This eliminates false exceptions caused by timing.

> **Separate Pix IN and Pix OUT for high volume**
>
> When processing high Pix volumes, create two separate contexts, one for cash-out and one for cash-in. This simplifies exception triage, provides more granular metrics per flow, and allows independent scheduling if needed.

> **Monitor match rate**
>
> A healthy Pix reconciliation achieves greater than 99% automatic match rate. If the rate drops below 95%, investigate systemic issues such as plugin failures, BACEN format changes, or missing metadata in Midaz transactions.

> **Zero tolerance is the default**
>
> Pix has no intermediate fees, partial settlements, or processing charges. If amounts diverge between Midaz and BACEN, it indicates a real problem, not rounding. Keep `feeTolerance` at `0` on the `DATE_LAG` rule.

> **Preview before committing**
>
> Always run a `DRY_RUN` before `COMMIT`, especially after rule or field map changes. This lets you review match results and catch configuration errors before they affect production data.

## Key metrics

***

Track these metrics to monitor the health of your Pix reconciliation process.

| Metric | Healthy value | Alert threshold |
| - | - | - |
| Automatic match rate | Above 99% | Below 95% |
| Daily exceptions | Below 0.5% of volume | Above 2% |
| Average resolution time | Under 4 hours | Over 24 hours |
| Unresolved exceptions 48h+ | 0 | More than 5 |

> [!TIP]
>
> Use Matcher's dashboard endpoints to monitor these metrics. See [Dashboard metrics](/en/reference/products/matcher/get-dashboard-metrics).

## Next steps

***

> **[Contexts and sources](/en/products/matcher/configuration/matcher-contexts-and-sources)**
>
> Learn how to configure and manage reconciliation contexts and data sources.

> **[Match rules](/en/products/matcher/configuration/matcher-match-rules)**
>
> Explore all available rule types and advanced matching configurations.

> **[Midaz integration](/en/products/matcher/integrations/matcher-midaz-integration)**
>
> Learn about automatic field mapping and the Midaz Ledger data source.

> **[Resolving exceptions](/en/products/matcher/daily-reconciliation/matcher-resolving-exceptions)**
>
> Detailed guide on investigating, force matching, and managing reconciliation exceptions.


# What is Matcher?
Source: https://docs.lerian.studio/en/products/matcher/what-is-matcher

Discover Matcher, Lerian's reconciliation engine that automates transaction matching, confidence scoring, exception routing, and audit trails for compliance.

**Matcher** is Lerian's reconciliation (The process of comparing two sets of records (for example, your internal ledger against bank statements) to verify they match and flag discrepancies.) engine that automates transaction reconciliation between any data sources: internal systems, banks, payment processors, ERPs (Enterprise Resource Planning, business management software (SAP, Oracle, NetSuite) that integrates accounting, procurement, and inventory processes.), or payment gateways. Matcher is available to licensed institutions. Lerian maintains its repository internally.

You configure matching rules once. Matcher handles the repetitive work: matching transactions, flagging discrepancies, and maintaining audit trails for compliance.

## Why use Matcher

***

Every financial institution reconciles transactions, comparing internal records against bank statements, payment processors, and ERPs. Most do it manually in spreadsheets. This does not scale: matching takes hours, errors go unnoticed, and month-end close becomes stressful.

Matcher solves this:

* **Automate matching**: Configure rules once, let the system handle routine matches
* **Know what's reliable**: Confidence scores tell you which matches are solid and which need review
* **Stay compliant**: An append-only audit log records configuration changes and exception resolutions

## What Matcher does

***

* **Match automatically**: Apply your match rules. Get confidence scores (0-100) for every match
* **Handle multiple sources**: Reconcile between banks, ERPs, payment processors, ledgers, all at once if needed
* **Manage exceptions**: Unmatched items get classified, assigned, and tracked until resolved
* **Audit changes**: An append-only audit trail (A chronological, immutable record of every action and transaction in the system, essential for regulatory compliance and dispute resolution.) records configuration changes and exception resolutions

### Matching features

* **Exact matching**: Match transactions by ID, amount, date, and custom attributes
* **Tolerance matching**: Allow controlled variance in amounts, defined as absolute values or percentages
* **Date range matching**: Handle timing differences using configurable date windows
* **Multi-currency support**: Reconcile transactions across currencies with FX rate handling
* **Split and aggregate matching**: Support 1:N, N:1, and N:M transaction relationships
* **Confidence scoring**: Assign a 0–100 score indicating match reliability
* **Dry run mode**: Preview matching results before committing changes
* **Adjustments**: Record a balancing entry, such as a bank fee or an FX difference, on a match group or a transaction

### Data ingestion

* Import data in **CSV**, **JSON**, **XML**, or **ISO 20022 camt.053** format, plus a catalog of regional layouts (CNAB, OFX, acquirer EDI files). See [Formats and templates](/en/products/matcher/imports/matcher-import-formats)
* Automatic validation and duplicate detection
* Flexible field mapping for heterogeneous data sources
* Pull transactions through database and REST API connections
* Optional: reconcile Midaz Ledger exports that you import as a `LEDGER` source

### Workflow integration

* Receive resolution callbacks from external systems

## Common use cases

***

> **Bank reconciliation**
>
> Match your internal records against daily bank statements. Upload CSVs, map fields, run matching. Review exceptions where the bank and your systems don't align.

> **Payment processors**
>
> Reconcile Stripe or Adyen settlements against your ledger or ERP. Handle splits (one payment, many invoices) and aggregates (many payments, one deposit) automatically.

> **Card networks**
>
> Match Visa, Mastercard, or Elo settlement files against your transaction records. Tolerance rules handle fee variances and timing differences between authorization and settlement.

> **Acquiring reconciliation (Interchange Plus)**
>
> Reconcile acquiring transactions with complex rate structures. Handle MCC-based rates, transaction type variations, and Interchange Plus models where rates vary by card type, merchant segment, and transaction method.

> **ERP sync**
>
> Verify SAP, Oracle, or NetSuite transactions against your other systems. Catch discrepancies before month-end close or audits.

## How Matcher works

***

**1. Configure**

Define what you're reconciling (contexts), where data comes from (sources), and how to match (rules).

**2. Ingest**

Upload files or pull data automatically. Matcher validates, normalizes, and deduplicates everything.

**3. Match**

Run a matching job. Matcher applies your rules and assigns confidence scores to each proposed match.

**4. Review**

Matcher confirms `EXACT` and `TOLERANCE` matches with a score of 90 or above automatically. Matcher never confirms a `FUZZY` or `DATE_LAG` match automatically: it sends the match to review, whatever its score. Lower scores and unmatched items go to your review queue.

**5. Resolve**

Handle exceptions: force a match, create an adjustment, or open a dispute.

**6. Report**

Export reconciliation reports. The audit log records configuration changes and exception resolutions.

## Integrations with the lerian ecosystem

***

Matcher is a stand-alone product that can optionally integrate with other components of the Lerian ecosystem.

| Product | Integration |
| - | - |
| [Midaz](/en/products/midaz/about-midaz) | Optional: Reconcile exported Ledger (The core financial book that records all transactions, balances, and operations for an organization. It is the single source of truth for a business unit's finances.) data that you import as a `LEDGER` source |

> [!NOTE]
>
> Matcher works independently or as part of the Lerian Studio ecosystem. Use it alone or connect it to Midaz and other financial components as needed.

> [!NOTE]
>
> Matcher reads an idempotency key only from the `X-Idempotency` header, and only when you send one. Matcher does not use a key that you send in `X-Idempotency-Key` or `Idempotency-Key`.

## Next steps

***

> **[Core concepts](/en/products/matcher/matcher-concepts)**
>
> Understand the key concepts: contexts, sources, rules, matches, and exceptions.

> **[Architecture](/en/products/matcher/matcher-architecture)**
>
> Explore Matcher's architecture and data flow.

> **[Quick start](/en/products/matcher/getting-started/matcher-quick-start)**
>
> Run your first reconciliation, then review matches and exceptions with confidence.

> **[Match rules](/en/products/matcher/configuration/matcher-match-rules)**
>
> Learn how to configure exact, tolerance, and date-based matching rules.

> [!TIP]
>
> [Explore the Matcher API](/en/reference/products/matcher/matcher-developer-quick-start). Browse endpoints for reconciliation contexts, sources, and matching rules.


# Billing Runs
Source: https://docs.lerian.studio/en/products/midaz/fees/console/billing-runs

Use Billing Runs in the Midaz Console to preview volume and maintenance fees for a daily, weekly, or monthly period before any charges are posted to accounts.

A **Billing Run** previews the fees for a given period, based on your configured packages. It does not charge anything. It only calculates a preview. Use it to check amounts, reconcile expected revenue, and review the results before you apply any charge.

> [!NOTE]
>
> Enable the Fees Engine in [Midaz module settings](/en/platform/console/plugin-settings) before you use this page.

## Key concepts

***

* **Preview only**: A Billing Run shows an extract of what it *would* bill for the selected period. It posts nothing.
* **Period type**: The length of the period, either **daily**, **weekly**, or **monthly**. With a reference date, it sets the date range that the run evaluates.
* **Reference date**: The date that sets the period range. A monthly run covers the full month, a weekly run the ISO week, a daily run that day.
* **Package type**: Which packages the run includes.
  * **Volume**: fees on the number of transactions.
  * **Maintenance**: a fixed fee per account.
  * **All**: both Volume and Maintenance packages.
* **Extract**: The result of the run. It has a summary and one preview line per package. The summary shows the total results, the Volume and Maintenance totals, and a net total.

## Accessing Billing Runs

***

**1. Open the Fees Engine**

In the Midaz Module sidebar, expand **Fees Engine**.

**2. Select Billing Runs**

Choose **Billing Runs** to open the run page.

**3. Set the run parameters**

Pick the **period type** and **reference date**. Choose the **package type**.

**4. Calculate the preview**

Run the calculation to see the extract. Review the summary and the per-package results. If the period has no fees to bill, the preview shows an empty state.

## Where to go next

***

> **[Fees Engine overview](/en/products/midaz/fees/console/fees-engine-overview)**
>
> Understand how the Fees Engine, packages, and rules fit together.


# APIX 001 guidance withdrawn
Source: https://docs.lerian.studio/en/products/reporter/apix-001

The previous APIX 001 template guidance is withdrawn pending an authoritative Pix contract.

The previous APIX 001 template instructions were withdrawn. The current Reporter product source does not establish the Pix data model, APIX fields, submission schedule, or regulatory mapping needed to validate those instructions.

Reporter can render templates from configured data sources, but it does not turn an unverified field mapping into a regulatory contract.

Do not use the previous examples to produce or submit an APIX 001 report. Define the data mapping and output with an authoritative Pix or BACEN contract, then validate it with your compliance team before operational use.


# APIX 002 guidance withdrawn
Source: https://docs.lerian.studio/en/products/reporter/apix-002

The previous APIX 002 template guidance is withdrawn pending an authoritative Pix contract.

The previous APIX 002 template instructions were withdrawn. The current Reporter product source does not establish the Pix data model, APIX fields, submission schedule, or regulatory mapping needed to validate those instructions.

Reporter can render templates from configured data sources, but it does not turn an unverified field mapping into a regulatory contract.

Do not use the previous examples to produce or submit an APIX 002 report. Define the data mapping and output with an authoritative Pix or BACEN contract, then validate it with your compliance team before operational use.


# CADOC 4010 and 4016: validation required
Source: https://docs.lerian.studio/en/products/reporter/cadoc-4010-and-4016

Use authoritative regulatory requirements to validate any CADOC 4010 or 4016 mapping before operational use.

The previous ready-to-submit template guidance on this page has been withdrawn.

Reporter can render templates from configured data sources, but the current product source does not establish a CADOC regulatory mapping. In particular, Midaz treats `OperationRoute.code` as an unconstrained legacy string. It does not make that field a 10-digit COSIF account code.

The source also does not establish `available_balance_after` (including a value grouped by account and route) as a supported regulatory balance. Do not use the previous examples as a basis for a CADOC submission.

## What to do instead

***

1. Obtain the applicable official CADOC layout and validation rules.
2. Define the mapping from your institution's source data to that layout.
3. Validate field semantics, aggregation, dates, and identifiers with your compliance team.
4. Test the generated file against the authoritative validator before operational use.


# CADOC 4111: validation required
Source: https://docs.lerian.studio/en/products/reporter/cadoc-4111

Use authoritative regulatory requirements to validate any CADOC 4111 mapping before operational use.

The previous ready-to-submit template guidance on this page has been withdrawn.

Reporter can render templates from configured data sources, but the current product source does not establish a CADOC 4111 regulatory mapping. Midaz treats `OperationRoute.code` as an unconstrained legacy string. It does not make that field a 10-digit COSIF account code.

The source also does not establish `available_balance_after`, including a value selected or grouped by account and route, as a supported regulatory balance. Do not use the previous examples as a basis for a CADOC 4111 submission.

## What to do instead

***

1. Obtain the applicable official CADOC 4111 layout and validation rules.
2. Define the mapping from your institution's source data to that layout.
3. Validate field semantics, aggregation, dates, and identifiers with your compliance team.
4. Test the generated file against the authoritative validator before operational use.


# CCS Reports
Source: https://docs.lerian.studio/en/products/reporter/ccs-reports

Build CCS XML files (ACCS001, ACCS005, ACCS010) for BACEN by combining Lerian CRM and Midaz data through Reporter templates and scheduled generation.

Reporter generates XML-based CCS (Cadastro de Clientes do Sistema Financeiro Nacional) files as defined by the Central Bank of Brazil (BACEN).

This guide shows how to create automated CCS reports with Reporter: ACCS001, ACCS005, and ACCS010. You combine CRM data (holders and aliases) with Midaz structures.

## Before using the CCS templates

***

The examples below map the reserved CRM datasource named `plugin_crm`. Configure that datasource before importing or saving a CCS template: it needs the CRM MongoDB connection and `DATASOURCE_CRM_MIDAZ_ORGANIZATION_ID`, which scopes CRM records to one Midaz organization. Follow [Reporter via Helm](https://github.com/LerianStudio/helm/tree/main/charts/reporter) or the [environment-variable reference](/en/products/reporter/reporter-environment-variables#reserved-crm-datasource).

`plugin_crm` is environment-managed. Do not try to create or PATCH it through the regular datasource API. Manager can seed the entry and fill a missing or empty organization ID at startup. Manager keeps a non-empty persisted value.

Before treating a CCS template as ready, import or save it, generate a report, confirm that CRM fields decrypt, and verify that the output contains records only from the intended Midaz organization. `RPT-0075` is a fail-closed scope check: it can mean the organization metadata is absent or empty, but it can also mean Reporter could not read the datasource registry. Use [RPT-0075 troubleshooting](/en/reference/products/reporter/reporter-error-list#rpt-0075-crm-organization-scope-unresolved) instead of assuming a missing environment variable.

> [!CAUTION]
>
> CCS reports must strictly follow the layouts defined by BACEN. Reporter lets you automate the XML generation, but you remain responsible for validating the output and ensuring compliance with regulatory requirements.

## What is CCS?

***

The **CCS (Cadastro de Clientes do Sistema Financeiro Nacional)** is a registry that maps relationships between customers and financial institutions.

It lets regulators and other authorized entities identify where a customer holds financial relationships.

Institutions must submit CCS reports in XML format, following BACEN’s ACCS schemas. Each file type has a specific function, from daily updates to relationship transfers.

## ACCS001: Daily update file

***

### What it is

The ACCS001 is the **daily update file**. It reports inclusions, changes, or exclusions of customer relationships (individual or corporate) with the institution. This is the most frequent CCS file. It keeps the registry in sync with daily operations.

### Full template

```
{# reporter:output-encoding=utf-16be #}<?xml version="1.0" encoding="UTF-16"?>
<CCSDOC xmlns="http://www.bcb.gov.br/ccs/ACCS001.xsd">
    <BCARQ>
        <IdentdEmissor>12345678</IdentdEmissor>
        <IdentdDestinatario>00000000</IdentdDestinatario>
        <NomArq>ACCS001</NomArq>
        <NumRemessaArq>12233444</NumRemessaArq>
    </BCARQ>
    <SISARQ>
        <CCSArqAtlzDiaria>
            <Repet_ACCS001_Pessoa>
{%- for alias in plugin_crm.aliases -%}
{%- for holder in plugin_crm.holders -%}
{%- if holder.document == alias.document %}
                <Grupo_ACCS001_Pessoa>
                    <TpOpCCS>I</TpOpCCS>
                    <QualifdrOpCCS>N</QualifdrOpCCS>
                    <TpPessoa>{%- if holder.type == "NATURAL_PERSON" -%}F{%- else -%}J{%- endif -%}</TpPessoa>
                    <CNPJ_CPFPessoa>{{holder.document}}</CNPJ_CPFPessoa>
                    <DtIni>{{alias.banking_details.opening_date}}</DtIni>
                    <DtFim></DtFim>
                </Grupo_ACCS001_Pessoa>
{%- endif -%}
{%- endfor %}
{%- endfor %}
            </Repet_ACCS001_Pessoa>
            <QtdOpCCS>{% count_by plugin_crm.aliases %}</QtdOpCCS>
            <DtMovto>{% date_time "YYYY-MM-dd" %}</DtMovto>
        </CCSArqAtlzDiaria>
    </SISARQ>
</CCSDOC>
```

### Applied logic

Nested loops cross-reference plugin\_crm.aliases (accounts) with plugin\_crm.holders (holders) to accurately associate account data with their respective owners.

* The `<TpPessoa>` field is conditional:
  * F for **natural persons**
  * J for **legal entities**
* **Fixed values in this example:**
  * `<TpOpCCS>` = I (Inclusion)

    This scenario sets the field to I. The field must still reflect the actual operation that you report.\
    Valid values according to BACEN are:

    * I = **Inclusion** (new accounts in the institution's database)
    * A = **Update** (changes to existing account information)
    * E = **Exclusion** (the original record must be disregarded)
  * `<QualifdrOpCCS>` = N (Normal)

    Similarly, this field should represent the correct qualifier for the account.\
    Valid values include:

    * N = **Normal**
    * P = **Popular**
    * C = **Conglomerate**
* **Functions used:**
  * count\_by plugin\_crm.aliases counts alias records per account.
  * date\_time "YYYY-MM-dd" dynamically inserts the current date in the specified format.

### Rendered example

```
<?xml version="1.0" encoding="UTF-16"?>
<CCSDOC xmlns="http://www.bcb.gov.br/ccs/ACCS001.xsd">
    <BCARQ>
        <IdentdEmissor>12345678</IdentdEmissor>
        <IdentdDestinatario>00000000</IdentdDestinatario>
        <NomArq>ACCS001</NomArq>
        <NumRemessaArq>12233444</NumRemessaArq>
    </BCARQ>
    <SISARQ>
        <CCSArqAtlzDiaria>
            <Repet_ACCS001_Pessoa>
                <Grupo_ACCS001_Pessoa>
                    <TpOpCCS>I</TpOpCCS>
                    <QualifdrOpCCS>N</QualifdrOpCCS>
                    <TpPessoa>F</TpPessoa>
                    <CNPJ_CPFPessoa>12345678900</CNPJ_CPFPessoa>
                    <DtIni>2025-02-01</DtIni>
                    <DtFim></DtFim>
                </Grupo_ACCS001_Pessoa>
            </Repet_ACCS001_Pessoa>
            <QtdOpCCS>1</QtdOpCCS>
            <DtMovto>2025-02-01</DtMovto>
        </CCSArqAtlzDiaria>
    </SISARQ>
</CCSDOC>
```

## ACCS005: Relationship detail file

***

### What it is

You generate the ACCS005 with Reporter when BACEN requests detailed information on client relationships. It lists all the links between a customer and financial assets (BDVs: Bens, Direitos e Valores). It can also include **related persons** such as partners or legal representatives.

### Full template

```
{# reporter:output-encoding=utf-16be #}<?xml version="1.0" encoding="UTF-16"?>
<CCSDOC xmlns="http://www.bcb.gov.br/ccs/ACCS005.xsd">
    <BCARQ>
        <IdentdEmissor>12345678</IdentdEmissor>
        <IdentdDestinatario>00000001</IdentdDestinatario>
        <NomArq>ACCS005</NomArq>
        <NumRemessaArq>{% date_time "YYYYMMddHHmm" %}</NumRemessaArq>
    </BCARQ>
    <SISARQ>
        <CCSArqInfDettRelctPessoa>
            <CNPJBaseEntRespons>{{plugin_crm.holders.0.document|slice:':8'}}</CNPJBaseEntRespons>
            <NumCtrlCCSOr>000000</NumCtrlCCSOr>
            <Repet_CCS0005_BDV>
                {%- for account in midaz_onboarding.account %}
                {%- for alias in plugin_crm.aliases %}
                {%- if alias.account_id == account.id %}
                {%- for holder in plugin_crm.holders %}
                {%- if holder.document == alias.document %}
                <Grupo_CCS0005_BDV>
                    <SitInfDettPessoa></SitInfDettPessoa>
                    <Grupo_CCS0005_Part>
                        <CNPJBasePart>{{holder.document|slice:"0:8"}}</CNPJBasePart>
                        <TpBDV>{% if account.type == "deposit" %}1{% elif account.type == "savings" %}2{% elif account.type == "payment" %}3{% else %}6{% endif %}</TpBDV>
                        {%- if alias.banking_details.branch %}
                        <AgIF>{{alias.banking_details.branch}}</AgIF>
                        {%- endif %}
                        {%- if alias.banking_details.type == "CACC" %}
                        <CtCli>{{alias.banking_details.account}}</CtCli>
                        {%- elif alias.banking_details.type == "payment" %}
                        <CtPgto>{{alias.banking_details.account}}</CtPgto>
                        {%- endif %}
                        <TpVincBDV>1</TpVincBDV>
                        <NomPessoa>{{holder.name}}</NomPessoa>
                        <DtIni>{{alias.banking_details.opening_date}}</DtIni>
                        <DtFim></DtFim>
                        {%- if holder.type == "NATURAL_PERSON" and holder.natural_person %}
                        <Repet_CCS0005_Vincd>
                            <Grupo_CCS0005_Vincd>
                                <Grupo_CCS0005_PessoaVincd>
                                    <TpVinc>3</TpVinc>
                                    <CNPJ_CPFPessoaVincd>{{holder.document}}</CNPJ_CPFPessoaVincd>
                                    <NomPessoaVincd>{{holder.natural_person.mother_name}}</NomPessoaVincd>
                                    <DtIniVinc>{{alias.banking_details.opening_date}}</DtIniVinc>
                                    <DtFimVinc></DtFimVinc>
                                </Grupo_CCS0005_PessoaVincd>
                            </Grupo_CCS0005_Vincd>
                        </Repet_CCS0005_Vincd>
                        {%- endif %}
                    </Grupo_CCS0005_Part>
                </Grupo_CCS0005_BDV>
                {%- endif %}
                {%- endfor %}
                {%- endif %}
                {%- endfor %}
                {%- endfor %}
            </Repet_CCS0005_BDV>
            <DtMovto>{% date_time "YYYY-MM-dd" %}</DtMovto>
        </CCSArqInfDettRelctPessoa>
    </SISARQ>
</CCSDOC>
```

### Applied logic

Nested loops iterate through accounts, aliases, and holders to extract all relevant entities in a structured way.

* The `<TpBDV>` field uses conditional logic to determine the account type:
  * 1 = deposit
  * 2 = savings
  * 3 = payment
  * 6 = others
* For CNPJ extraction, slice:"0:8" retrieves only the first 8 digits (base of the CNPJ).

The example below includes the **mother’s name** as a placeholder for a vinculated person. The `<Repet_CCS0005_Vincd>` element does not refer to the mother. The example shows the feature in action.

* The `date_time` function generates timestamps at runtime, so the report reflects the current execution context.

### Rendered example

```
<?xml version="1.0" encoding="UTF-16"?>
<CCSDOC xmlns="http://www.bcb.gov.br/ccs/ACCS005.xsd">
    <BCARQ>
        <IdentdEmissor>12345678</IdentdEmissor>
        <IdentdDestinatario>00000001</IdentdDestinatario>
        <NomArq>ACCS005</NomArq>
        <NumRemessaArq>202502011230</NumRemessaArq>
    </BCARQ>
    <SISARQ>
        <CCSArqInfDettRelctPessoa>
            <CNPJBaseEntRespons>12345678</CNPJBaseEntRespons>
            <NumCtrlCCSOr>000000</NumCtrlCCSOr>
            <Repet_CCS0005_BDV>
                <Grupo_CCS0005_BDV>
                    <SitInfDettPessoa></SitInfDettPessoa>
                    <Grupo_CCS0005_Part>
                        <CNPJBasePart>12345678</CNPJBasePart>
                        <TpBDV>1</TpBDV>
                        <AgIF>001</AgIF>
                        <CtCli>12345-6</CtCli>
                        <TpVincBDV>1</TpVincBDV>
                        <NomPessoa>João Silva</NomPessoa>
                        <DtIni>2020-01-01</DtIni>
                        <DtFim></DtFim>
                        <Repet_CCS0005_Vincd>
                            <Grupo_CCS0005_Vincd>
                                <Grupo_CCS0005_PessoaVincd>
                                    <TpVinc>3</TpVinc>
                                    <CNPJ_CPFPessoaVincd>12345678900</CNPJ_CPFPessoaVincd>
                                    <NomPessoaVincd>Maria Silva</NomPessoaVincd>
                                    <DtIniVinc>2020-01-01</DtIniVinc>
                                    <DtFimVinc></DtFimVinc>
                                </Grupo_CCS0005_PessoaVincd>
                            </Grupo_CCS0005_Vincd>
                        </Repet_CCS0005_Vincd>
                    </Grupo_CCS0005_Part>
                </Grupo_CCS0005_BDV>
            </Repet_CCS0005_BDV>
            <DtMovto>2025-02-01</DtMovto>
        </CCSArqInfDettRelctPessoa>
    </SISARQ>
</CCSDOC>
```

## ACCS010: Relationship transfer file

***

### What it is

You generate the ACCS010 with Reporter when institutions transfer client relationships, which is common in portfolio sales or mergers. It lists the transferred relationships and identifies the new responsible institution.

### Full template

```
{# reporter:output-encoding=utf-16be #}<?xml version="1.0" encoding="UTF-16"?>
<CCSDOC xmlns="http://www.bcb.gov.br/ccs/ACCS010.xsd">
    <BCARQ>
        <IdentdEmissor>12345678</IdentdEmissor>
        <IdentdDestinatario>00000000</IdentdDestinatario>
        <NomArq>ACCS010</NomArq>
        <NumRemessaArq>{% date_time "YYYYMMdd" %}0001</NumRemessaArq>
    </BCARQ>
    <SISARQ>
        <CCSArqTransRelac>
            <CNPJBaseNovRespons>12345679</CNPJBaseNovRespons>
            {%- for alias in plugin_crm.aliases %}
            {%- for holder in plugin_crm.holders %}
            {%- if alias.holder_id == holder._id and (holder.type == "LEGAL_PERSON" or holder.type == "NATURAL_PERSON") %}
            <Repet_ACCS010_Pessoa>
                <CNPJBasePart></CNPJBasePart>
                <TpPessoa>{% if holder.type == "NATURAL_PERSON" %}F{% else %}J{% endif %}</TpPessoa>
                <CNPJ_CPFPessoa>{{holder.document}}</CNPJ_CPFPessoa>
                <DtIni>{{alias.banking_details.opening_date}}</DtIni>
                <DtFim></DtFim>
            </Repet_ACCS010_Pessoa>
            {%- endif %}
            {%- endfor %}
            {%- endfor %}
            <QtdOpCCS>{% count_by plugin_crm.aliases %}</QtdOpCCS>
        </CCSArqTransRelac>
    </SISARQ>
</CCSDOC>
```

### Applied logic

* **Dual loops** iterate through aliases and holders.
* `<TpPessoa>` defines whether the holder is natural (**F**) or legal (**J**).
* `<CNPJBaseNovRespons>` identifies the new responsible institution.
* `<QtdOpCCS>` uses count\_by to ensure the number of reported relationships matches the dataset.
* Dates (`<DtIni>` and `<DtFim>`) track relationship validity.

### Rendered example

```
<?xml version="1.0" encoding="UTF-16"?>
<CCSDOC xmlns="http://www.bcb.gov.br/ccs/ACCS010.xsd">
    <BCARQ>
        <IdentdEmissor>12345678</IdentdEmissor>
        <IdentdDestinatario>00000000</IdentdDestinatario>
        <NomArq>ACCS010</NomArq>
        <NumRemessaArq>202502010001</NumRemessaArq>
    </BCARQ>
    <SISARQ>
        <CCSArqTransRelac>
            <CNPJBaseNovRespons>87654321</CNPJBaseNovRespons>
            <Repet_ACCS010_Pessoa>
                <CNPJBasePart>12345678</CNPJBasePart>
                <TpPessoa>F</TpPessoa>
                <CNPJ_CPFPessoa>12345678900</CNPJ_CPFPessoa>
                <DtIni>2019-05-10</DtIni>
                <DtFim></DtFim>
            </Repet_ACCS010_Pessoa>
            <QtdOpCCS>1</QtdOpCCS>
        </CCSArqTransRelac>
    </SISARQ>
</CCSDOC>
```

> [!WARNING]
>
> While Reporter provides the technical automation, institutions must ensure the accuracy and consistency of the data submitted to BACEN. Always validate rendered XML against the official schema before submission, and involve accounting or compliance teams in the review process.


# Connect Reporter to Midaz
Source: https://docs.lerian.studio/en/products/reporter/connecting-reporter-to-midaz

Connect Reporter to Midaz through a named data source, protect the source database with least-privilege credentials, and verify the connection end to end.

Reporter reads Midaz data through a named **data source**. A report template references that name, and Reporter turns its placeholders and filters into queries against the source database.

For example, a template can list the accounts from the `midaz_onboarding` data source:

```text theme={null}
{% for account in midaz_onboarding.account %}{{ account.name }}{% endfor %}
```

Reporter builds `SELECT` queries for PostgreSQL sources and `Find` operations for MongoDB sources. It then renders the returned data through the template. Reporter does not write back to the source databases or persist report results in Midaz.

## Before you start

***

You need:

* Network access from Reporter to the Midaz database.
* A database user with read-only permissions.
* Preferably, a read replica so report workloads do not compete with ledger workloads. The reference setup uses the host `midaz-postgres-replica` as an example.
* The database, schemas, and tables that your templates need.

> [!WARNING]
>
> Reporter generates read operations, but this behavior does not enforce database permissions. Use read-only database credentials. Do not give Reporter a user that can insert, update, delete, or change schemas.

## Choose who manages the connection

***

Your deployment model determines who configures the data source:

* **Managed (Lerian-hosted):** onboarding sets up the connection to your Lerian product data. Confirm the data source name and availability with your Lerian contact before you build templates.
* **Self-hosted:** your operator can seed the connection at startup with `DATASOURCE_<NAME>_*` variables and owns its network access, credentials, certificates, and database permissions.

In every model, report authors reference the configured data source by its `configName`.

## Configure a named data source

***

[Create the data source](/en/reference/products/reporter/create-data-source) through the Reporter API, and set its `configName` to the stable name that templates and filters will use. In a self-hosted deployment, you can also seed it at startup with `DATASOURCE_<NAME>_*` environment variables, where `DATASOURCE_<NAME>_CONFIG_NAME` sets that name.

For example, if the `configName` is `midaz_onboarding`, templates reference `midaz_onboarding` even if the database host or credentials change later.

For PostgreSQL sources that expose more than one schema, derive the schema variable from the `configName`. A `configName` of `external_db` uses:

```env theme={null}
DATASOURCE_EXTERNAL_DB_SCHEMAS=sales,inventory,reporting
```

See [Configure external data sources](/en/products/reporter/using-reporter#configure-external-data-sources) for the connection variables and complete examples.

## Protect the Midaz database

***

Use a dedicated database role that can connect and select only the required tables and schemas. Point Reporter to a read replica when your topology supports one. This keeps report queries away from the primary database, but the replica is not a substitute for read-only credentials: apply both controls.

Rotate the credential through your normal secret-management process. Keep the `configName` stable so existing templates continue to resolve the same data source.

## Verify the connection

***

1. [List data sources](/en/reference/products/reporter/list-data-sources) and confirm that the expected `configName` appears.
2. Copy the data source ID from the response.
3. [Get the data source schema](/en/reference/products/reporter/get-data-source-schema) and confirm that Reporter discovers the expected tables and fields.
4. Create a small template that references one known field, then generate a report to verify the complete query and rendering path.

The connection is ready when the named source is available, its discovered structure is correct, and the test report returns the expected value.

## Troubleshooting

***

### The data source is unavailable

Check network routing, DNS, TLS settings, credentials, database permissions, and replica health. During template validation, Reporter can return a `DATA_SOURCE_UNAVAILABLE` warning instead of blocking template creation. Fix the connection before relying on the report output.

### The source name is ambiguous

Use one descriptive `configName` per database role, such as `midaz_onboarding` and `midaz_transaction`. Avoid generic names such as `database` or `postgres`, especially when different sources contain tables with the same names. Update the template to reference the intended source explicitly.

## Next steps

***

* [Create your first report](/en/products/reporter/reporter-quick-start)
* [Build templates and filters](/en/products/reporter/using-reporter)
* [See Reporter in a complete core banking architecture](/en/products/building-a-complete-core-banking)


# Add a Data Source
Source: https://docs.lerian.studio/en/products/reporter/console/adding-a-data-source

Configure an external database connection when Reporter needs a data source that is not already available in the Lerian Console for report generation.

Use this page to create a Data Source when Reporter needs to read from an external database or from a connection that is not already configured. If the report uses internal Lerian product data, such as Midaz or CRM, the Data Source may already exist.

## Objective

***

Configure an external connection that Templates and Reports can use.

For example, create a Data Source named `production-postgres` that points to an external reporting database, or `compliance-readonly` for a read-only database user used by reporting operators.

## When to use

***

Use this task when:

* the required Data Source is not already available in Reporter
* a new database must feed reports
* an existing report process needs a separate read-only connection
* operators need schemas and fields available in Template Builder or report filters

Before adding one, check whether the required internal Data Source already exists. Creating a duplicate external connection is unnecessary when Reporter already has the source configured.

Do not use this task to fix an existing connection. Use [Edit a Data Source](/en/products/reporter/console/editing-a-data-source) and [Test a Data Source Connection](/en/products/reporter/console/testing-a-data-source).

## Before you start

***

Have these details ready:

* host, port, and database name
* username and password
* schema names, when the database uses schemas
* the SSL mode that your database requires
* a clear connection name, such as `production-postgres` or `compliance-readonly`

> [!WARNING]
>
> Use credentials intended for reporting access. A Data Source gives Reporter access to read data used in Templates and Reports.

## Step by step

***

**1. Open Data Sources**

Go to **Data Sources** and click **Add Data Source**.

**2. Fill in connection details**

In **Add Data Source**, enter **Connection Name**, **Database Type**, **Host**, **Port**, **Database Name**, **Username**, and **Password**.

**3. Configure schemas when needed**

For PostgreSQL, add the schemas that Reporter should inspect. Type a schema name and click **Add**, or press **Enter**. Without schemas, Reporter uses `public`.

**4. Select the SSL mode**

Select **SSL Mode**. The form starts at **Require**.

**5. Add metadata when useful**

Expand **Metadata** to add key-value fields that help operators classify the connection.

**6. Create the Data Source**

Click **Create**. The Console saves the Data Source and tests its connection.

**7. Read the test result**

When the test succeeds, the dialog closes and a message shows the latency. When it fails, the Data Source stays saved and the dialog shows the reason. Click **Edit connection** to fix it, or **Keep anyway**. When the test cannot run, the dialog closes and a message says that the connection could not be checked.

## Field guide

***

| Field | What to enter | Example |
| - | - | - |
| **Connection Name** | Required operator-facing name. Technical field: `configName`. Up to 100 characters: letters, numbers, `_`, and `-`. You cannot use the name of a Data Source that the platform provides. | `production-postgres` |
| **Database Type** | Required database engine: **PostgreSQL** or **MongoDB**. It fills in the default port. Technical field: `type`. | **PostgreSQL** |
| **Host** | Required database server address, not an application URL. Technical field: `host`. | `db.example.com` |
| **Port** | Required database port. Technical field: `port`; valid range is 1 to 65535. | `5432` |
| **Database Name** | Required database name Reporter will query. Technical field: `databaseName`. | `ledger` |
| **Username** | Required database user. Technical field: `username`. | `reporter_readonly` |
| **Password** | Required secret when creating a Data Source. Technical field: `password`. | Stored through the form |
| **Schemas** | Optional schema list for PostgreSQL. Entries are trimmed, lowercased, and deduplicated. | `public`, `pix`, `transactions` |
| **SSL Mode** | Required. Use **Disable**, **Require**, **Verify CA**, or **Verify Full**. Technical field: `sslMode`. | **Verify CA** |
| **Connection Options** | Optional MongoDB URI options, under **Advanced**. Technical field: `options`. | `authSource=admin` |
| **Metadata** key/value fields | Optional operator classification data. Each row needs a key, and a key cannot repeat. Technical field: `metadata`. | `environment = production` |

## Expected result

***

The new external Data Source appears on the **Data Sources** page with the result of its connection test. After a successful test, operators can use its fields in Templates and Reports.

## Common errors and care points

***

> **Using an application URL as Host**
>
> **Host** should be the database server address, such as `db.example.com`, not the URL of an application or admin panel.

> **Skipping schemas**
>
> If the database uses schemas and the required schema is not listed, operators may not see the expected tables and fields.

> **Ignoring SSL requirements**
>
> If the database requires SSL, the connection can fail until **SSL Mode** matches that requirement.

> **Using unclear names**
>
> Names like `db1` are hard to use safely. Prefer names that show environment and purpose, such as `production-compliance-readonly`.

## Next steps

***

* Use [Test a Data Source Connection](/en/products/reporter/console/testing-a-data-source) to test the connection again later.
* Use [Template Builder](/en/products/reporter/console/template-builder) to use fields from the Data Source in a Template.
* Use [Generate a Report](/en/products/reporter/console/generating-a-report) after the Template and Data Source are ready.


# Add a Template
Source: https://docs.lerian.studio/en/products/reporter/console/adding-template

Create a Template in Reporter using Template Builder or by uploading a prepared .tpl file, then map its data sources for regulatory report generation.

Use this page to create the Template that Reporter will use to generate a Report. A Template is the reusable structure of the output file: it defines the layout, fields, conditions, loops, calculations, and final format.

## Objective

***

Add a Template that operators can select when generating Reports.

For example, a monthly tax Template can define a CSV header, one row per transaction, and a total amount at the end of the file. A regulatory XML Template can define the required XML tags and fill them with values from a Data Source.

## When to use

***

Use this task when:

* you set up the first Template for a report whose Data Source already exists
* a new report obligation requires a new output structure
* your team already has a reviewed `.tpl` file and needs to make it available in the Console
* an operator needs to build the Template visually instead of editing `.tpl` code

Do not use this task to fix a Template that already exists. Use [Update a Template](/en/products/reporter/console/updating-a-template) instead.

## Before you start

***

Confirm:

* the Data Source that will feed the Template is available when the Template needs database fields. It may be an internal source already configured for the environment or an external source added from **Data Sources**
* you know the expected output format: CSV, XML, HTML, TXT, or PDF
* the Template will be created in **Template Builder** or uploaded as a `.tpl` file
* the report owner has confirmed the fields that must appear in the output

> [!NOTE]
>
> A Template is the reusable definition that Reporter applies later during report generation. It is not the generated Report itself.

## Option 1: Build in Template Builder

***

Use Template Builder when an operator needs to assemble the Template visually from blocks.

**1. Open Template Builder**

Go to the **Templates** page and click **Template Builder**.

**2. Name the Template**

Use a name operators can recognize later, such as `Monthly tax CSV` or `Daily transaction PDF`. Then enter the **Category**, the report family, such as `cadoc`.

**3. Choose the output format**

Select the format that the generated Report must produce: XML, HTML, CSV, TXT, or PDF.

**4. Add the Template blocks**

Add blocks such as **Text**, **Variable**, **Loop**, **Conditional**, or **Aggregation**. In practice, blocks represent the pieces of the final file: fixed text, database values, repeated rows, conditional sections, or totals.

**5. Connect fields to data**

Use the Data Sources sidebar to select fields from the configured database connection. For example, use a **Variable** block to place `transactions.amount` in the output.

**6. Save the Template**

Click **Save** to validate the blocks and save the generated `.tpl` file.

## Option 2: Upload a `.tpl` file

***

Use upload when a technical team already maintains the Template outside the Console.

**1. Open the upload wizard**

Go to the **Templates** page and click **New Template**.

**2. Upload the file**

In the **File** step, drag the `.tpl` file to **Drag file here**, or click **to select** to browse your computer.

**3. Configure the Template**

In the **Config** step, fill in **Template Name**, **Output Format**, and **Category**.

**4. Review the summary**

In the **Review** step, confirm the file, name, output format, and category. Use the edit buttons if any field is wrong.

**5. Save the Template**

Click **Save Template**.

> [!TIP]
>
> **API equivalent**: [Upload template endpoint](/en/reference/products/reporter/upload-template)

## Field guide

***

### Upload wizard fields

| Field | What to enter | Example |
| - | - | - |
| **Template File (.tpl)** | Required `.tpl` file used as the Template source. It must be larger than 0 bytes and no larger than 1 MiB by default. API field: `template`. | `monthly-tax.tpl` |
| **Template Name** | Required operator-facing name. It maps to `name` in the Console and to `description` in the Reporter API. | `Monthly tax CSV` |
| **Output Format** | Required output type. Use one of `csv`, `xml`, `html`, `txt`, or `pdf`. | `csv` |
| **Category** | Required report family. Pick one already in use or type a new one: letters, numbers, `_`, and `-`, up to 100 characters. The Console stores it in lowercase. | `cadoc` |

### Template Builder fields

| Field | What to enter | Example |
| - | - | - |
| **Template name** | Required name in the builder header. It becomes the saved Template name and generated `.tpl` filename prefix. | `Daily transaction PDF` |
| Block toolbar | Add at least one block before saving. Blocks become the generated `.tpl` code. | **Text** header + **Loop** over transactions + **Aggregation** total |
| Data Sources sidebar | Use configured Data Sources to insert fields into **Variable** blocks. Technical fields include `dataSource`, `table`, and `field`. | `production-postgres.transactions.amount` |

## Expected result

***

After saving, the Template appears on the **Templates** page and can be selected in the **Generate Report** wizard.

## Common errors and care points

***

> **Uploading a file that is not `.tpl`**
>
> Upload only accepts `.tpl` files. If the Template is not final, use **Template Builder** first or prepare the `.tpl` file outside the Console.

> **Choosing the wrong output format**
>
> The output format controls what kind of file operators will download after generating a Report. Confirm the required format before saving.

> **Creating a Template before the Data Source is ready**
>
> Templates can reference fields from Data Sources. Operators may not know which fields are safe to use when the required source is absent or has no test result.

## Next steps

***

* Use [Generate a Report](/en/products/reporter/console/generating-a-report) to create a Report from the Template.
* Use [Update a Template](/en/products/reporter/console/updating-a-template) if the structure, file, name, or output format needs correction.
* Use [Template Builder](/en/products/reporter/console/template-builder) to build another Template visually.


# Deadlines in the Console
Source: https://docs.lerian.studio/en/products/reporter/console/deadlines-overview

Track upcoming and overdue reporting deadlines from the Reporter Overview in Lerian Console: regulatory calendar, delivery status, and notifications.

In [Lerian Console](/en/platform/console/about-lerian-console), **Deadlines** are not a separate menu item. They live inside the [Reporter module](/en/products/reporter/console/reporter-module), on the **Overview** page. This keeps delivery tracking next to the reports and data sources it relates to.

Use this page to understand how reporting deadlines surface visually in the Console. For creating, updating, or delivering deadlines programmatically, see [Managing deadlines](/en/products/reporter/managing-deadlines).

> [!WARNING]
>
> Reporter is only available if you've acquired the Reporter product. [Get in touch with our team](https://lerian.studio/contact) to learn more.

## Where to find deadlines

***

When you open Reporter, you land on **Overview**. Deadlines appear here as dedicated widgets alongside the module's KPIs:

* **Reporter** from the left-side menu opens the module.
* **Overview**, the default landing page, is the home for all deadline tracking.

There is no separate "Deadlines" navigation entry. This dashboard holds all delivery tracking.

## Overview widgets

***

Two widgets on the Overview page show reporting obligations:

* **Upcoming Deadlines**: Lists the reporting reminders with their due dates and current status, so operators can see what comes next.
* **Delivery Calendar**: Shows recurring and one-off reporting deadlines by date.

## What you can see

***

From the Overview, operators can monitor each obligation without leaving the Console:

* **Deadline status**: whether each obligation is **Pending**, **Overdue**, or **Delivered**.
* **Notifications**: messages on the Overview that begin a configured number of days before the due date, so a deadline doesn't slip unnoticed.
* **Delivery state**: the **Delivered** check box of each reminder. After the due date passes, a delivered recurring reminder moves to its next due date.

## Manage reminders

***

* Click **Add Reminder**. In **New Reminder**, enter **Name**, **Type**, **Due Date**, **Frequency**, and **Notify Days Before** (0 to 30). A **Regulatory** reminder also needs a **Template**. When the tenant has several [institutions](/en/products/reporter/console/managing-institutions), it also needs an **Institution**, or **All institutions**. **Semiannual** and **Annual** reminders need at least one month in **Months of Year**.
* Select **Delivered** when you deliver the report. Clear it to revert the delivery.
* Use the menu () of a reminder to **Edit**, **Deactivate**, **Activate**, or **Delete** it. An inactive reminder shows no notifications.

## Console vs API

***

Use the **Console Overview** when an operator needs to track reminders, follow the delivery calendar, and mark deliveries.

Use the **API** when a system needs to manage or deliver deadlines programmatically, for example to sync obligations from another system or automate delivery tracking.

> **[Managing deadlines (API)](/en/products/reporter/managing-deadlines)**
>
> Full request and response reference for creating, listing, updating, deleting, and delivering deadlines.


# Delete a Data Source
Source: https://docs.lerian.studio/en/products/reporter/console/deleting-a-data-source

Remove a Data Source from Reporter when no live Template depends on its database connection.

Use this page to remove a Data Source that should no longer be available for future Templates or Reports.

## Objective

***

Remove a Data Source connection from Reporter.

For example, delete a Data Source when an external reporting database was retired. Delete it when a temporary migration connection is no longer necessary, or when operators have moved to a replacement connection.

## When to use

***

Use this task when:

* you retired the database connection
* no current Template or reporting process should use it
* a replacement Data Source exists, if the process continues
* the connection exists by mistake and should not remain available

You cannot delete a Data Source marked **Provided by the platform** or **Managed by environment**.

Do not delete a Data Source just because a connection test failed. If you still need the connection, edit and test it instead.

## Before you start

***

Confirm:

* no active reporting process depends on the connection
* current Templates do not rely on fields from this Data Source
* operators know which replacement Data Source to use
* the connection does not fail only temporarily because of credentials, network, schema, or SSL settings

> [!CAUTION]
>
> Reporter refuses to delete a Data Source that a live Template still references. Update or delete those Templates first.

## Step by step

***

**1. Open Data Sources**

Go to **Data Sources**.

**2. Find the connection**

Locate the card for the Data Source you want to delete.

**3. Open the delete action**

Click the three vertical dots () on the card and select **Delete**.

**4. Confirm deletion**

In the **Delete data source** dialog, review the connection name and click **Delete**. When Templates still read from the Data Source, the dialog shows **Data source still in use** and lists them instead.

**5. Check the list**

Confirm that the Data Source no longer appears on the **Data Sources** page.

## Field guide

***

| Field or label | What to check | Example |
| - | - | - |
| Connection name | Confirms the Data Source that will be removed. The technical field is `configName`; check that it is the retired connection, not a replacement. | `migration-postgres-temp` |
| Data source ID | Technical UUID used by the API as the `dataSourceId` path parameter. | `018f2f4c-...` |
| **Delete** | Action in the Data Source card menu. It starts the destructive flow and opens the confirmation dialog. | Select **Delete** on `migration-postgres-temp`. |
| **Delete data source** | Final confirmation dialog. After you click **Delete**, the Data Source is removed from the active **Data Sources** list. | Confirm the temporary connection removal. |

## Expected result

***

The Data Source disappears from the active list. Reporter only completes the deletion after no live Template references the connection.

## Common errors and care points

***

> **Deleting a connection still used by Templates**
>
> Reporter blocks the deletion when a live Template references the connection. Update or delete those Templates first.

> **Deleting instead of fixing credentials**
>
> If your operation still needs the connection, edit credentials or SSL settings and run **Test Connection**.

> **Deleting without a replacement**
>
> If the reporting process continues, create and test the replacement Data Source before deleting the old one.

## Next steps

***

* Use [Add a Data Source](/en/products/reporter/console/adding-a-data-source) if you need a replacement connection.
* Use [Test a Data Source Connection](/en/products/reporter/console/testing-a-data-source) to validate replacement connections.
* Use [Managing Data Sources](/en/products/reporter/console/managing-data-sources) to review the remaining active connections.


# Delete a Template
Source: https://docs.lerian.studio/en/products/reporter/console/deleting-a-template

Remove a Template from Reporter when it is no longer needed for any regulatory report generation.

Use this page to remove a Template that you no longer need for future Report generation.

## Objective

***

Delete a retired Template from the **Templates** page.

For example, delete a Template when a new layout replaces the old one. Delete it when the report obligation no longer exists. Delete a Template created by mistake that has no operational use.

## When to use

***

Use this task when:

* the Template is retired.
* operators should no longer select it when generating Reports.
* a replacement Template already exists, if the reporting process continues.
* the Template is incorrect and should not remain available.

Do not delete a Template just because one generated Report was wrong. Update the Template or the Report inputs, then generate a new Report.

## Before you start

***

Confirm:

* no active reporting process depends on this Template.
* operators do not use it for the current reporting cycle.
* a replacement Template exists when you still need the report.
* you downloaded or archived any generated Reports that need external storage.

> [!WARNING]
>
> Deleting a Template is permanent. Reports already generated with that Template remain available on the **Reports** page, but new Reports cannot use the deleted Template. Reporter also deletes the reminders linked to the Template.

## Step by step

***

**1. Open the Templates page**

Go to **Templates**.

**2. Find the Template**

Locate the Template you want to remove. Check its name carefully if multiple Templates have similar names.

**3. Open the delete action**

Click the three dots () in the **Actions** column and select **Delete**.

**4. Confirm deletion**

In the **Confirm Deletion** dialog, review the Template name and confirm the deletion.

## Field guide

***

| Field or label | What to check | Example |
| - | - | - |
| Template name | Confirm this is the retired Template, not the replacement. API field: `description`; Console field: `name`. | `Monthly tax CSV - legacy` |
| Template ID | Technical identifier used by the delete API. The Console selects it when you choose **Delete**. | `018f2f4c-...` |
| **Delete** | Opens the destructive confirmation flow from the row **Actions** menu. | Select **Delete** for the retired Template |
| **Confirm Deletion** | Final confirmation before the Template is removed from future **Generate Report** selection. | Confirm `Monthly tax CSV - legacy` |

## Expected result

***

The Template is removed from the **Templates** page and is no longer available in the **Generate Report** wizard.

## Common errors and care points

***

> **Deleting a Template still used by operators**
>
> You cannot generate future Reports from the deleted Template. Confirm the replacement workflow before deletion.

> **Deleting instead of updating**
>
> Update the Template instead of deleting it if you still need it. Take this path when the layout, output format, or name is wrong.

> **Assuming generated Reports disappear**
>
> Generated Reports remain available on the **Reports** page. Deletion removes the Template from future use.

## Next steps

***

* Use [Add a Template](/en/products/reporter/console/adding-template) if you need a replacement Template.
* Use [Update a Template](/en/products/reporter/console/updating-a-template) to correct the Template instead of removing it.
* Use [Managing Templates](/en/products/reporter/console/managing-templates) to review the active Template list.

> **API equivalent**
>
> [Delete template endpoint](/en/reference/products/reporter/delete-template)


# Download a Report
Source: https://docs.lerian.studio/en/products/reporter/console/downloading-a-report

Download a finished Report from the Console once Reporter has completed generation, ready for submission to regulators or long-term archiving.

Use this page to download a generated Report after Reporter finishes creating the file.

## Objective

***

Save the generated Report file outside the Console. You can then submit, archive, review, or share it through the appropriate internal workflow.

For example, download a `Finished` XML file for regulatory submission or a CSV file for operational reconciliation.

## When to use

***

Use this task when:

* the Report status is `Finished`, or a regulatory filing is `Final` or a `Draft` with every required field filled.
* the operator needs the generated file outside the Console.
* you must store the file, send it through another process, or check it locally.

Do not use download while the Report is still `Processing`. Wait for completion first.

## Before you start

***

Confirm:

* the Report status is `Finished`, or a regulatory filing is `Final` or a `Draft` with every required field filled.
* you chose the intended Template and filters for generation.
* the receiving process accepts the output format.
* you corrected and regenerated the `Error` Reports.

> [!NOTE]
>
> Use preview to check the Report inside the Console. Download is the action that saves the generated file for use outside the Console.

## Step by step

***

**1. Open the Reports page**

Go to **Reports**.

**2. Find the Report**

Locate the Report you need to download. Check its name, Template, generation date, and status.

**3. Confirm the status**

Make sure the status is `Finished`, `Final`, or `Draft` with every required field filled.

**4. Open the action menu**

Click the three dots () in the **Actions** column.

**5. Download the file**

Select **Download Report**.

## Field guide

***

| Field or label | What to check | Example |
| - | - | - |
| Report status | Download after the Report reaches `Finished`. A regulatory filing also offers **Download Report** in `Draft` or `Final`. A `Draft` downloads only when no required field is blank. Technical field: `status`. | `Finished` |
| Template | Check which Template and output format produced the file. Technical fields include `templateId`, `templateDescription`, and `templateOutputFormat`. | `Monthly tax CSV`, `csv` |
| Filters | Review the filters used during generation. | `transactions.created_at between 2026-05-01 and 2026-05-31` |
| **Download Report** | Action that downloads the generated file for the selected `reportId`. | Download report `018f2f4c-...` |

## Expected result

***

The file downloads in the output format configured by the Template, such as CSV, XML, HTML, TXT, or PDF.

## Common errors and care points

***

> **Trying to download a `Processing` Report**
>
> Wait until the status changes to `Finished`. A Report in `Processing` is not ready yet.

> **Downloading a Report generated with the wrong filters**
>
> Download does not change Report content. If the filters were wrong, generate a new Report with corrected inputs.

> **Using preview as the final file**
>
> Preview helps operators inspect the Report in the Console. Use **Download Report** for the final file.

## Next steps

***

* Store or deliver the downloaded file through the required operational process.
* Use [Correct a Report](/en/products/reporter/console/editing-a-report) if the downloaded file has wrong data, layout, or format.
* Use [Generate a Report](/en/products/reporter/console/generating-a-report) to create a corrected file.

> **API equivalent**
>
> [Download report endpoint](/en/reference/products/reporter/download-report)


# Edit a Data Source
Source: https://docs.lerian.studio/en/products/reporter/console/editing-a-data-source

Update an existing Data Source (change credentials, switch the host, or adjust SSL settings) without recreating the connection or reconfiguring reports.

Use this page to update an existing editable Data Source when its database access details change.

## Objective

***

Keep a Data Source usable without deleting and recreating it.

For example, edit a Data Source when an external database password rotates. Edit it when the host changes after an infrastructure migration. Edit it when a new schema must be visible, or when SSL settings change.

## When to use

***

Use this task when:

* credentials changed.
* host, port, or database name changed.
* schema access changed.
* SSL mode or connection options changed.
* metadata needs better operator context.

You cannot edit a Data Source marked **Provided by the platform** or **Managed by environment**.

Delete a retired connection instead of editing it.

## Before you start

***

Confirm what changed:

* credentials: update **Username** or **Password**.
* database location: update **Host**, **Port**, or **Database Name**.
* schema visibility: update the schema list.
* security: update **SSL Mode**.

> [!NOTE]
>
> A Data Source update affects future Report generation. Reports already generated stay unchanged.

## Step by step

***

**1. Open Data Sources**

Go to **Data Sources**.

**2. Find the connection**

Locate the card for the Data Source you need to edit.

**3. Open the edit form**

Click the three vertical dots () on the card and select **Edit**.

**4. Update the fields**

In **Edit Data Source**, change the fields that need correction.

**5. Save changes**

Click **Save Changes**. The Console saves the changes and tests the connection.

**6. Read the test result**

When the test succeeds, the dialog closes. When it fails, the changes stay saved and the dialog shows the reason. Click **Edit connection** to fix it, or **Keep anyway**. When the test cannot run, the dialog closes and a message says that the connection could not be checked.

> [!NOTE]
>
> The **Password** field appears empty for security reasons. Leaving it blank keeps the current password, unless you change **Database Type**, **Host**, **Port**, **Database Name**, **Username**, **SSL Mode**, or **Connection Options**. Then re-enter the password, even when it did not change.

## Field guide

***

| Field | What to change | Example |
| - | - | - |
| **Connection Name** | Required operator-facing name. Technical field: `configName`. Up to 100 characters: letters, numbers, `_`, and `-`. You cannot rename it while Templates read from it. | `production-postgres-readonly` |
| **Database Type** | Database engine used by the connection: **PostgreSQL** or **MongoDB**. | **PostgreSQL** |
| **Host** | Database server address. Changing it changes where Reporter reads future data from. | `db-new.example.com` |
| **Port** | Database network port. Valid range is 1 to 65535. | `5432` |
| **Database Name** | Database Reporter queries through this Data Source. | `ledger_reporting` |
| **Username** | Database user used by Reporter. | `reporter_readonly` |
| **Password (leave blank to keep current)** | Leave blank to keep the current password. Required when a connection setting changes. | New rotated password |
| **Schemas** | Optional schema list for PostgreSQL. Entries are trimmed, lowercased, and deduplicated. | `public`, `pix` |
| **SSL Mode** | SSL behavior. Use **Disable**, **Require**, **Verify CA**, or **Verify Full**. | **Verify Full** |
| **Connection Options** | MongoDB URI options, under **Advanced**. | `authSource=admin` |
| **Metadata** key/value fields | Optional classification data. Each row needs a key, and a key cannot repeat. | `owner = compliance` |

## Expected result

***

The Data Source keeps the updated configuration. After a successful test, operators can rely on it for Templates and Reports.

## Common errors and care points

***

> **Leaving password blank unintentionally**
>
> Leaving **Password** blank keeps the existing password only when no connection setting changes. When one changes, re-enter the password.

> **Changing host without testing**
>
> Host and port changes can point Reporter to a different database. Read the test result that the Console shows after saving.

> **Removing a schema that Templates use**
>
> If a Template or filter depends on fields from a schema, removing that schema can break future generation.

> **Editing when the connection should be retired**
>
> If no reporting process uses the database, delete the Data Source instead of editing it.

## Next steps

***

* Use [Test a Data Source Connection](/en/products/reporter/console/testing-a-data-source) to test the connection again later.
* Use [Generate a Report](/en/products/reporter/console/generating-a-report) only after the connection is healthy.
* Use [Delete a Data Source](/en/products/reporter/console/deleting-a-data-source) when the connection is retired.


# Correct a Report
Source: https://docs.lerian.studio/en/products/reporter/console/editing-a-report

Understand why generated Reports stay unchanged, when a regulatory filing can be corrected, and how to correct the source setup before generating a new Report from the same Reporter template.

A generated Report is a historical file. Reporter does not edit the generated output after generation finishes. A regulatory filing in `Draft` is the exception: open it and use **Correct a figure** before you **Approve** it. A `Final` filing refuses corrections.

## Objective

***

Correct the source setup that produced a wrong Report, then generate a new Report.

For example, if a CSV file has missing rows, review the filters used during generation. If the layout is wrong, update the Template. If values are wrong, test the Data Source and confirm it points to the expected database and schema.

## When to use

***

Use this page when:

* an operator asks why Reporter cannot change a generated Report directly.
* a generated Report has wrong data, layout, or output format.
* an `Error` Report needs investigation before trying again.
* the team needs a corrected file while preserving the original generated Report for history.

Do not use this task to overwrite a generated file. Generate a new Report after correction.

## Before you start

***

Identify what is wrong:

| Problem | Likely source to check |
| - | - |
| File layout is wrong | Template structure or `.tpl` file |
| Output format is wrong | Template **Output Format** |
| Rows are missing | Report filters or Data Source schema |
| Values are wrong | Data Source connection, schema, fields, or source data |
| Generation returned `Error` | Report details, Template, Data Source, filters |

> [!NOTE]
>
> The original Report remains available for audit history. The corrected file becomes a new generated Report.

## Step by step

***

**1. Open the Report details**

Go to **Reports** and open the generated Report details.

**2. Review how it was generated**

Check the Template, filters, output format, status, and any error details.

**3. Fix the source setup**

Update the Template, test or edit the Data Source, or adjust the filters you will use during the next generation.

**4. Generate a new Report**

Use the corrected Template, Data Source, and filters to generate a new Report.

**5. Download the corrected file**

Wait until the new Report reaches `Finished`, then download it.

## Field guide

***

| Field or status | What it helps diagnose | Example |
| - | - | - |
| Template | Whether the correct Template and output format were used. Technical fields include `templateId`, `templateDescription`, and `templateOutputFormat`. | `Monthly tax CSV`, `csv` |
| Filters | Whether the generated Report included the intended data subset. Technical field: `filters`. | `status eq active` |
| Status | Whether the Report finished, is still running, or returned an error. Technical field: `status`. | `Error` |
| Error details | Message returned by Reporter when generation fails. Technical field: `error`. | `connection timeout` |
| Data Source | Whether the Report came from the expected database and schema. Check the filter `database` and the Template field mapping. | `production-postgres` |

## Expected result

***

The incorrect Report stays unchanged. Reporter generates a new corrected Report from the fixed setup.

## Common errors and care points

***

> **Trying to edit the generated file**
>
> Reporter keeps generated Reports as historical outputs. Correct the Template, Data Source, or filters, then generate again.

> **Fixing the Template when the filter was wrong**
>
> Missing rows often come from filters, not from the Template. Review the generation inputs before changing the Template.

> **Regenerating without testing the Data Source**
>
> If values are wrong or schema access changed, test the Data Source before generating a corrected Report.

## Next steps

***

* Use [Update a Template](/en/products/reporter/console/updating-a-template) when layout or output format is wrong.
* Use [Testing a Data Source](/en/products/reporter/console/testing-a-data-source) when values or schema access are suspect.
* Use [Generate a Report](/en/products/reporter/console/generating-a-report) after fixing the source setup.

> **[Create report](/en/reference/products/reporter/create-report)**
>
> Generate the corrected Report.

> **[Check report status](/en/reference/products/reporter/check-report-status)**
>
> Monitor the corrected Report before download.


# Generate a Report
Source: https://docs.lerian.studio/en/products/reporter/console/generating-a-report

Generate a regulatory Report through a four-step wizard that guides you from Template selection to the final compiled output ready for submission.

Use this page to generate a Report from an existing Template. Generation is the moment Reporter applies a Template to data and creates a file that you can monitor, view, and download.

## Objective

***

Create a generated Report for a specific operational need, period, entity, status, or submission.

For example, generate a monthly CSV for May transactions, an XML file for a regulatory submission, or a PDF summary filtered to one customer segment.

## When to use

***

Use this task when:

* the Template is ready.
* the Data Source used by the Template is available. It may be an internal source already configured for the environment or an external source added from **Data Sources**.
* an operator needs to produce a Report file.
* the Report needs optional filters, such as date range, status, type, or entity.
* the Template declares parameters, such as a reference month.

Do not use this task to change the Template structure. Update the Template first, then generate a new Report.

## Before you start

***

Confirm:

* the selected Template is the correct one for the obligation.
* the Template output format matches the file you need to deliver.
* the Data Source used by the Template is available. Test the connection when the report depends on one that may have changed.
* you know which institution the Report is for, when the tenant has several. See [Managing Institutions](/en/products/reporter/console/managing-institutions).
* you know whether the Report should include all data or a filtered subset.
* the filter values are precise enough for the reporting period.

> [!NOTE]
>
> Reporter generates Reports asynchronously. A new Report starts in `Processing` and only becomes available for download when it reaches `Finished`.

## Step by step

***

**1. Open the Reports page**

Go to **Reports** and click **New Report**.

**2. Select the Template**

In the **Template** step, choose the Template that defines the output structure and format. Click **Next**.

**3. Choose the institution, parameters, and filters**

In the **Filters** step, complete the fields that apply:

* **Institution**: appears when the tenant has several institutions. Choose one institution or **All institutions**. With one institution, the step shows it and uses it.
* **Parameters**: appear when the Template declares parameters. Fill in each required parameter. The step fills in the default values that the Template declares.
* **Filters**: optional. Add one or more filters to narrow the data.

Click **Next**.

**4. Review the setup**

In the **Review** step, check the Template, the institution, the parameters, and the filters.

**5. Generate the Report**

Click **Generate Report**. The wizard moves to the **Generate** step and tracks progress while Reporter creates the file.

**6. Monitor the status**

When generation succeeds, the wizard offers **Download** and **View in List** actions. If you close the wizard earlier, the Report appears in the list with `Processing` status. Wait until it reaches `Finished` before you download it.

## Field guide

***

| Field | What to enter | Example |
| - | - | - |
| **Template** | Required Template selected in the **Template** step. The technical value sent to the API is `templateId`. | `Monthly tax CSV` |
| Search templates | Optional UI search. It filters the loaded Template list by name or file name and is not sent in the generation payload. | `tax` |
| **Institution** | Required when the tenant has several institutions. Choose one institution or **All institutions**. The payload uses this value as `institution`. | `Banco Exemplo S.A.` |
| Template parameters | One field for each parameter that the Template declares. The field name is the parameter name. A required parameter needs a value. A month parameter takes `YYYY-MM`, and a date parameter takes `YYYY-MM-DD`. | `2026-05` |
| **Database** | Required only when a filter row is used. Select the Data Source connection; the payload uses this value as `database`. | `production-postgres` |
| **Table** | Required only when a filter row is used. Select a table from the connection schema. | `transactions` |
| **Field** | Required only when a filter row is used. Select the field to compare. | `created_at` |
| **Operator** | Required only when a filter row is used. Use `eq`, `gt`, `gte`, `lt`, `lte`, `between`, `in`, or `nin`. | **Between** / `between` |
| **Values** | Required only when a filter row is used. `between` needs exactly two values; `in` and `nin` accept comma-separated values; other operators use one value. | `2026-05-01, 2026-05-31` |

## Filter examples

***

| Filter | Result |
| - | - |
| `status` **Equal** `active` | Includes only active records. |
| `created_at` **Between** `2026-05-01, 2026-05-31` | Includes records from May 2026. |
| `type` **In** `credit,debit` | Includes either transaction type. |
| `amount` **Greater Than** `1000` | Includes records with amount above 1000. |

## Status and next action

***

| Status | What it means | Operator action |
| - | - | - |
| `Processing` | Reporter is generating the file. | Wait. The list refreshes automatically. |
| `Finished` | The file is ready. | View, preview, or download the Report. |
| `Partial failure` | Some data sections failed. | Open **View Details** to see the failed sections, fix their Data Sources, and generate again. |
| `Error` | Reporter found an error during generation. | Review the message, check Data Source health, and generate again after correction. |

## Expected result

***

A new Report appears on the **Reports** page. When it reaches `Finished`, operators can preview or download the generated file.

## Common errors and care points

***

> **Generating with the wrong Template**
>
> The Template controls layout and output format. If you selected the wrong Template, generate a new Report with the correct Template.

> **Using a Data Source that was not tested**
>
> Failed or outdated connections can cause generation errors. Test the Data Source before generating operational Reports when connection health is uncertain, especially for external databases or recently changed credentials.

> **Using broad filters by mistake**
>
> Empty filters can include all available data. Confirm whether the Report should cover all records or only a specific period, status, or entity.

> **Expecting immediate download**
>
> Download is only available after the Report reaches `Finished`.

## Next steps

***

* Use [Download a Report](/en/products/reporter/console/downloading-a-report) when the status is `Finished`.
* Use [Correct a Report](/en/products/reporter/console/editing-a-report) if the generated file has wrong data, layout, or format.
* Use [Testing a Data Source](/en/products/reporter/console/testing-a-data-source) if generation fails because of connection or schema issues.

> **[Create report](/en/reference/products/reporter/create-report)**
>
> Generate Reports programmatically.

> **[Check report status](/en/reference/products/reporter/check-report-status)**
>
> Poll generation status before download.


# Managing Data Sources
Source: https://docs.lerian.studio/en/products/reporter/console/managing-data-sources

Review, test, and manage the database connections that supply data to Reporter.

Data Sources are connections that Reporter uses to fetch the data needed for report generation. Some Data Sources can already be configured for internal Lerian products, such as Midaz or CRM. Use this page to review those connections, test them, or manage external database connections through the [Lerian Console](/en/platform/console/about-lerian-console).

## What is a Data Source?

***

A Data Source is a connection between Reporter and a data store. To generate reports, Reporter needs access to source data. For internal product data, the connection may already exist. For external databases, operators can add and manage the connection from this page.

Each Data Source includes:

* **Connection name**: a human-readable identifier.
* **Database type**: the database engine used by the connection: PostgreSQL or MongoDB.
* **Access configuration**: host, port, database name, credentials, and SSL mode, when the Data Source is an external database connection.
* **Schemas**: for PostgreSQL connections, you can specify which schemas to access.
* **Metadata**: additional key-value fields for organization.

Operators usually use this page to answer three questions:

* Is the connection available?
* Which schemas, tables, and fields can Reporter read?
* Is this the right Data Source for the Template or Report that you prepare?

## Supported databases

***

| Database | Default port | Schema support |
| - | :-: | :-: |
| PostgreSQL | 5432 | ✅ |
| MongoDB | 27017 | ❌ |

## Accessing the Data Sources page

***

To open the **Data Sources** page, click **Data Sources** from the left-side menu on the **Reporter** page.

You do not need to start here in every Reporter journey. Start here when the needed Data Source is absent. Start here when you must add an external database, or when a report fails because data is unreachable.

The page displays all configured connections, each in a card showing:

* Connection name and database type.
* Connection status (**Connected**, **Disconnected**, **Connecting**, or **Not checked**) and the time of the last check.
* Configured schemas (if any).
* Latency from the last check.
* Host, database, user, and SSL mode.

A Data Source that your Lerian products provide shows **Provided by the platform**. You cannot test, edit, or delete it. You can test a Data Source marked **Managed by environment**, but you cannot edit or delete it.

You can expand each card to view the database schema, including available tables and columns.

### Available actions

From the Data Sources page, you can:

> **[Add a Data Source](/en/products/reporter/console/adding-a-data-source)**
>
> Create a reusable external database connection for Reporter.

> **[Edit a Data Source](/en/products/reporter/console/editing-a-data-source)**
>
> Update credentials, host, schemas, SSL, or metadata.

> **[Test connection](/en/products/reporter/console/testing-a-data-source)**
>
> Confirm Reporter can reach the database and load schema information.

> **[Delete a Data Source](/en/products/reporter/console/deleting-a-data-source)**
>
> Remove retired connections that you no longer use.

> [!TIP]
>
> If a Report fails because data is absent or unreachable, first test the Data Source. Then check whether the expected schema and table appear in the expanded card.


# Managing Institutions
Source: https://docs.lerian.studio/en/products/reporter/console/managing-institutions

Register the institutions your tenant reports for in the Reporter module of the Lerian Console: CNPJ, data scope per Data Source, and proposals read from Midaz.

An **institution** is one regulatory declarant of your tenant. Each institution files under its own CNPJ and reads only the rows that its scope names. Manage institutions on the **Institutions** page of Reporter in the [Lerian Console](/en/platform/console/about-lerian-console).

Reports, regulatory deadlines, and regulatory filings use the institutions that you register here. See [Where institutions apply](#where-institutions-apply).

## Accessing the Institutions page

***

To open the **Institutions** page, click **Institutions** in the left-side menu of the **Reporter** page.

The page lists the institutions in a table with these columns: **Name**, **CNPJ**, **Data Sources**, **Last Modified**, and **Actions**. The **Data Sources** column names each Data Source in the scope of the institution. It shows **None** when the scope is empty.

The menu () of each row has **Edit** and **Delete**.

Each action on the Institutions screen needs the matching `institutions` permission: `get` to see and propose institutions, `post` to create and confirm, `put` to edit, and `delete` to delete.

## Add an institution

***

**1. Open the form**

On the **Institutions** page, click **New Institution**.

**2. Identify the institution**

Enter the **Business name** and the **CNPJ**. The CNPJ can be numeric or alphanumeric, with or without punctuation.

**3. Define the scope**

Click **Add data source** and select a Data Source. Then tell Reporter which of its rows belong to the institution. See [Scope rules](#scope-rules).

**4. Save**

Click **Save**. If Reporter refuses the institution, the form shows its reason and keeps what you typed.

### Scope rules

The scope names the rows of each Data Source that belong to the institution. An institution with no Data Source in its scope reads nothing.

For each Data Source, choose one of these:

* **The whole data source belongs to this institution**: the institution reads every table of the Data Source.
* **Tables**: click **Add table** and enter the table name. For each table, choose one of these:
  * **Shared: every institution reads this table whole**: use it for reference data that every institution needs.
  * **Conditions**: click **Add condition**, type the **Field**, select an **Operator**, and type the **Values**, comma separated. A table with conditions needs at least one condition with the **Equal** or the **In** operator. These two operators claim the rows of the institution.

### Field guide

| Field | What to enter | Example |
| - | - | - |
| **Business name** | Required. The name of the declarant, up to 255 characters. | `Banco Exemplo S.A.` |
| **CNPJ** | Required. The form checks the check digits. | `12.345.678/0001-95` |
| **Data source** | A Data Source registered on the **Data Sources** page. A Data Source appears once in a scope. | `midaz-postgres` |
| **Table** | A table of the Data Source. A table appears once in a Data Source. | `account` |
| **Field** | The column that identifies the rows of the institution. | `organization_id` |
| **Operator** | **Equal**, **In**, **Not In**, **Greater Than**, **Greater or Equal**, **Less Than**, **Less or Equal**, or **Between**. | **Equal** |
| **Values** | One or more values, comma separated. | `00000000-0000-0000-0000-000000000000` |

## Propose institutions from Midaz

***

Reporter can read the organization table of Midaz and propose one institution for each organization that is not registered yet.

**1. Open the proposals panel**

On the **Institutions** page, click **Propose from Midaz**.

**2. Select the Data Sources**

Under **Data sources to read**, select the PostgreSQL Data Sources that read Midaz. The panel lists the PostgreSQL Data Sources that you registered. It does not list Data Sources provided by the platform.

**3. Find the proposals**

Click **Find proposals**. Each proposal shows the name, the CNPJ, and the proposed scope in each Data Source.

**4. Confirm a proposal**

Click **Confirm** on a proposal. The **New Institution** form opens with the proposal filled in. Review it, then click **Save**. When you close the form, the proposals panel opens again.

> [!WARNING]
>
> Midaz does not check the CNPJ check digits. A proposal with an incorrect CNPJ shows a warning. Correct the CNPJ in the form before you save.

## Edit an institution

***

Click the name of the institution, or select **Edit** in the row menu. Change the fields, then click **Save**.

## Delete an institution

***

Select **Delete** in the row menu and confirm. After the deletion, you can register the same CNPJ again at once.

## Where institutions apply

***

| Where | What the Console asks |
| - | - |
| **Reports** > **New Report** | With one institution, the wizard uses it. With several, choose one institution or **All institutions**. With none, the wizard does not ask. |
| **Overview** > **Add Reminder**, type **Regulatory** | The same rule as a report. |
| **Regulatory Filing** > **Activate document** | With one institution, the dialog uses it. With several, choose the institution that files the document. A filing never offers **All institutions**. Register at least one institution before you activate a document. |

When the tenant has several institutions, **Regulatory Filing** also shows these items:

* Each subscription shows the institution it files for, or **No institution set**. Set the institution before you generate a draft.
* **Activate for another institution** appears on an activated document when an institution does not file it yet.
* **Set institution** in the menu of a subscription changes the institution for the next filings. Reports already generated keep their institution.

Subscribing to a document and generating, correcting or adopting its filings needs `regulatory:post`. Mapping its fields and setting its institution need `regulatory:put`. Deactivating a subscription needs `regulatory:delete`. Approving a draft needs `regulatory-approval:post`.

## Next steps

***

* Use [Generate a Report](/en/products/reporter/console/generating-a-report) to generate a Report for an institution.
* Use [Managing Data Sources](/en/products/reporter/console/managing-data-sources) to register the Data Sources that a scope names.

> **API equivalent**
>
> [Create institution endpoint](/en/reference/products/reporter/create-institution) and [Propose institutions endpoint](/en/reference/products/reporter/propose-institutions)


# Managing Reports
Source: https://docs.lerian.studio/en/products/reporter/console/managing-reports

Generate, filter, track status, and download regulatory reports created from your uploaded templates in the Reporter module of the Lerian Console.

After you upload templates, you can view and manage reports through [Lerian Console](/en/platform/console/about-lerian-console). You can generate reports, filter them, track their status, and download the results.

Use the Reports page as the operational queue for generated files. It shows the generated files, whether generation finished, and the next action for the operator.

If the required Template and Data Source already exist, operators can start here to generate the next Report. Use **Data Sources** only when a connection is absent, unhealthy, or needs a test.

## Accessing the Reports page

***

To open the **Reports** page, click **Reports** from the left-side menu on the **Reporter** page.

The page lists reports in two view modes:

* **Table** (default): a list with columns: Name, Report ID, Status, Format, and Completed At.
* **Grid**: a card-based view. Toggle between modes using the button in the top-right area.

### Actions available

> **[Generate a Report](/en/products/reporter/console/generating-a-report)**
>
> Start a new generation from an existing Template.

> **[Download a Report](/en/products/reporter/console/downloading-a-report)**
>
> Save a finished Report for submission or archiving.

> **[Correct a report](/en/products/reporter/console/editing-a-report)**
>
> Learn what to change when a generated Report is wrong.

For reports in `Error` or `Partial failure`, the menu () has these actions:

* **View Details**: opens a panel with error details.
* **Try Again**: opens the generation wizard.

## Filtering reports

***

You can filter reports by date using the filter fields above the list.

> [!TIP]
>
> The list automatically refreshes while there are reports with `Processing` status. You don't need to reload the page.

To clear all filters, click the  icon.

## Report status

***

Each report displays a status badge:

| Status | Definition |
| :- | :- |
| `Processing` | The system is generating the report. |
| `Finished` | The report is ready for viewing and download. |
| `Partial failure` | Some data sections failed. You can view the failed sections and try again. |
| `Error` | Generation failed. You can view error details and try again. |
| `Draft` | A regulatory filing that a person can still correct and approve. |
| `Final` | An approved regulatory filing. It is ready for download and cannot change. |

If the status is `Error` or `Partial failure`, the Console offers no view or download. Open the details first, fix the Template, filters, or Data Source, and generate a new Report.

## Viewing a report

***

When a report reaches the `Finished` status, you can view it directly in the Console:

* Click the report name in the list, or
* Click the three dots () and select **View**.

A `Draft` or `Final` report opens its filing page. Other reports open a preview dialog that shows the report content. The preview adapts to the report's output format:

| Format | Preview behavior |
| :- | :- |
| CSV | Interactive table with headers, row numbers, and column/row count. |
| XML | Syntax-highlighted code with line numbers and a virtual scrollbar for large files. |
| PDF | Embedded PDF viewer rendered in an iframe. |
| HTML | Sandboxed HTML rendered in an iframe. |
| TXT | Plain text displayed in a monospaced block. |

### Preview actions

The preview dialog includes action buttons at the top:

* **Copy**: copies the report content to your clipboard (not available for PDF).
* **Print**: opens the browser print dialog for the report content (not available for PDF).
* **Download Report**: downloads the report file directly from the preview.

> [!NOTE]
>
> For PDF reports, use the embedded viewer controls to navigate pages, zoom, and print.


# Managing Templates
Source: https://docs.lerian.studio/en/products/reporter/console/managing-templates

Manage reusable templates that define the structure and format of every regulatory report Reporter generates from your Midaz and CRM data sources.

Templates are reusable configurations that define the structure and format of generated reports. Manage them from the [Lerian Console](/en/platform/console/about-lerian-console).

Use the Templates page to manage the reusable definitions that operators select when generating Reports. A Template controls the output format, file layout, and the data fields Reporter uses.

In the common internal-product journey, operators often start here. Data Sources for products such as Midaz or CRM may already be configured. The first manual task is to choose, create, or update the Template.

## Accessing the Templates page

***

To open the **Templates** page, click **Templates** from the left-side menu on the **Reporter** page.

The page lists templates in a table. The columns are **Name**, **Template ID**, **Format** (CSV, XML, HTML, TXT, or PDF), **Last Modified**, and **Actions**.

You can filter templates by creation date or output format using the filter fields above the table.

### Creating templates

The Templates page offers two creation modes:

* **Template Builder**: a visual editor that creates a template from blocks.
* **New Template**: uploads a `.tpl` file created externally.

Choose **Template Builder** when the operator needs a guided, visual flow. Choose **New Template** when a technical team already prepared the `.tpl` file outside the Console.

If the Template needs fields from a Data Source, confirm that the source already appears in the builder. Add a new Data Source only when the required external connection is absent.

### Available actions menu

For each template, the following actions are available in the action menu ():

* **Edit**: opens the edit wizard, for every template. The Template Builder creates templates but does not open a saved one.
* **Delete**: permanently removes the template and the reminders linked to it.

### Related pages

> **[Add a Template](/en/products/reporter/console/adding-template)**
>
> Create a Template visually or upload a prepared `.tpl` file.

> **[Update a Template](/en/products/reporter/console/updating-a-template)**
>
> Change the Template used for future Reports.

> **[Delete a Template](/en/products/reporter/console/deleting-a-template)**
>
> Remove a Template that you no longer need for operations.

> **[Template Builder](/en/products/reporter/console/template-builder)**
>
> Build a Template with visual blocks instead of editing `.tpl` code.

> [!NOTE]
>
> Updating or deleting a Template does not change Reports already generated. It only changes what Reporter generates next.


# Regulatory Filing
Source: https://docs.lerian.studio/en/products/reporter/console/regulatory-filing

Activate a regulatory document for an institution, map your tables to its fields, then generate, correct, and approve the filing in the Reporter module of the Lerian Console.

**Regulatory Filing** is the Reporter page where you file regulatory documents. Reporter keeps the contract of each document: the fields that its file needs. You activate a document, map your tables and columns to its fields, and generate a draft. Then you correct the draft if necessary and approve it. The approved draft becomes the filing.

A filing is made for an institution. Register at least one institution on the [Institutions](/en/products/reporter/console/managing-institutions) page before you activate a document.

## Open Regulatory Filing

***

In the left-side menu of the **Reporter** page, click **Regulatory Filing**. The page has two panels:

* **Document catalog**: the documents that this environment can file. Each card shows the title and the version of the document. The card also tells you if the document includes a reference mapping from Lerian. With a reference mapping, you correct it. Without one, you map the fields from the start.
* **Your subscriptions**: the documents that you file. The table shows **Document**, **Adopted version**, **Mapping version**, **Status**, **Readiness**, and **Actions**. **Status** is **Active** or **Inactive**.

When the catalog is empty, no regulatory document is mounted in this environment. An administrator mounts the regulatory catalog on the Reporter service.

## Activate a document

***

**1. Open the dialog**

On a card of the **Document catalog**, click **Activate**. The **Activate document** dialog opens.

**2. Choose the institution**

With one institution, the dialog uses it. With several, choose the institution that files the document.

**3. Choose the version**

Leave **Version** empty to pin the newest published version. To pin a different version, type it.

**4. Activate**

Click **Activate**. The **Document activated** dialog shows what the starting mapping can read now, and what it cannot read.

Activation pins the version. To change it later, use **Adopt another version**. See [Manage a subscription](#manage-a-subscription).

## Map the fields

***

In the menu () of a subscription, select **Open mapping**. The mapping page has two sections:

* **What this mapping reads**: the queries of the mapping. Each query reads one table of one of your Data Sources. To add a query, click **Add query**.
* **What the document asks for**: one row for each field that the regulator declares. For each set, choose the query that fills its rows. Then choose where each field is read from.

| Where the field is read from | What you enter |
| - | - |
| **A column of this set query** | The column of the query that fills the set. |
| **A column matched onto the published rows** | The column. This choice appears when the document publishes rows for the set. |
| **The same value every time** | The value. |
| **A value given when the filing is generated** | The parameter of the document that fills the field. |
| **Filled by a person on the draft** | A value, or a note that tells what is still missing. Reporter refuses a field with no value and no note. |

Click **Save mapping**. If Reporter refuses the mapping, the page shows the reason and keeps your changes.

## Check readiness

***

In the **Readiness** column of an active subscription, click **Check now**. Reporter checks the mapping against your databases as they are now. The result opens under the row.

| Result | What it means |
| - | - |
| **Ready** | Each field that the document needs is filled. |
| **N required fields are missing** | Nothing fills these fields yet. The result lists them. |
| **Will not generate** | The mapping reads a Data Source that nobody registered, a table that your database does not have, or a column that the table does not have. Or the mapping asks for something that Reporter cannot execute. |
| **Partly checked** | A table answered, but it did not tell which columns it has. |
| **Not checked** | A database did not answer, or no query ran against your databases. |

To check again, click **Check again**.

## Generate a draft

***

**1. Open the dialog**

In the menu () of an active subscription, select **Generate a draft**.

**2. Fill in the parameters**

The document sets the parameters that the filing needs. Write a competency month as `YYYY-MM` and a date as `YYYY-MM-DD`. Some documents are filed for specific months. The field tells you which months.

**3. Generate**

Click **Generate**. The **Draft generated** dialog lists the blank fields. A blank field is a field that the mapping could not fill. It is not a generation failure.

**4. Open the filing**

Click **Open the filing**.

The draft is a Report with the status `Draft`. It also shows on the [Reports](/en/products/reporter/console/managing-reports) page.

## Correct and approve the filing

***

The filing page shows the status, the blank fields, the **Corrections**, and the **Provenance**. **Provenance** shows the document, the document version, the mapping version, the generation time, the parameters, and the file checksum (SHA-256).

While a required field is blank, you cannot approve or download the filing. The page lists each blank field.

### Correct a figure

**1. Open the dialog**

On the filing page of a `Draft`, click **Correct a figure**.

**2. Find the figure**

Enter the **Set** and the **Field**. To select a row, click **Add a key** for each key of the row, and enter its **Key** and **Value**. Leave the keys empty for a set with one row.

**3. Enter the correction**

Enter the **Corrected value**. Under **Why (recorded in the audit trail)**, write why the figure changes. The reason is mandatory.

**4. Apply**

Click **Apply correction**.

Reporter builds the file again from the same rows, so no other figure changes. **Corrections** shows each change, who made it, and the reason.

### Approve the draft

**1. Open the dialog**

On the filing page of a `Draft`, click **Approve**. The Console hides **Approve** while a required field is blank.

**2. Confirm**

Click **Approve as the filing**.

The draft becomes the filing, with the status `Final`. A `Final` filing refuses corrections, and its provenance does not change.

## Manage a subscription

***

The menu () of an active subscription also has these items:

* **Set institution**: changes the institution for the next filings. Reports already generated keep their institution. This item appears when the tenant has several institutions.
* **Adopt another version**: changes the version that you file. Leave **Version to adopt** empty to take the newest published version. Reporter refuses a version that does not exist. Filings already produced keep their version. After you adopt a version, the dialog shows what the new version does to your mapping.
* **Deactivate**: stops the filing of the document. The subscription stays in the list as **Inactive**. Nothing is deleted, and reports already generated from it stay readable.

To restore an inactive subscription with its mapping and version, click **Reactivate** on its row. When the document has no active subscription, its catalog card also has **Reactivate**. The card also offers a new subscription. It shows **Start from Lerian's mapping** when the document includes a reference mapping, and **Start from an empty mapping** when it does not. The mapping that you edited stays saved on the deactivated subscription.

## Permissions

***

Opening the **Regulatory Filing** page needs `regulatory:get`. Activating or reactivating a document, generating a draft, correcting a figure, and adopting another version need `regulatory:post`. Mapping its fields and setting its institution need `regulatory:put`. Deactivating a subscription needs `regulatory:delete`. Approving a draft needs `regulatory-approval:post`.

## Next steps

***

* Use [Managing Institutions](/en/products/reporter/console/managing-institutions) to register the institutions that file documents.
* Use [Managing Data Sources](/en/products/reporter/console/managing-data-sources) to register the Data Sources that a mapping reads.
* Use [Managing Reports](/en/products/reporter/console/managing-reports) to find a filing among your Reports.


# Concepts Map
Source: https://docs.lerian.studio/en/products/reporter/console/reporter-concepts-map

Understand how Templates, Reports, Data Sources, and downloads relate in Reporter before using the module in the Lerian Console for regulatory reporting.

The Reporter Module uses a small set of core objects. They connect to each other, but the operator does not always start by creating a Data Source. In some environments, internal Data Sources for Lerian products such as Midaz or CRM are already configured.

## Core flow

***

Reporter has two common entry paths:

* **Internal product data already configured:** `Template → Report → Download`

* **External or missing data connection:** `Data Source → Template → Report → Download`

* The **Template** says *what the report should look like and in which format*.

* The **Data Source** says *where the data comes from*. It may already exist for internal products. For external databases, you add it manually.

* The **Report** is the file that Reporter produces when it runs a Template against the connected data. Filters can narrow the result.

* The **Download** is the operator action that takes the finished file out of the Console.

### What each object means

| Object | What it represents | Why it exists first or later |
| - | - | - |
| `Data Source` | A configured data connection. It can be an internal product connection already created for the environment, or an external database connection such as PostgreSQL or MongoDB. | It exists before generation, but the operator only needs to create one manually when the required connection is not already configured. |
| `Template` | A reusable definition of structure and output format (CSV, XML, HTML, TXT, or PDF), uploaded as a `.tpl` file or built visually with the Template Builder. | It describes *what* the report should look like. It does not execute anything by itself. |
| `Institution` | One regulatory declarant of the tenant, with its CNPJ and the rows of each Data Source that belong to it. | A Report reads for one institution, or for all of them. A regulatory filing is made for one institution. |
| `Parameter` | A value that the Template declares and the operator enters at generation time, such as a reference month. | It sets the period or the option of a single Report run. |
| `Filter` | An optional rule applied at generation time (Database + Table + Field + Operator + Value). | It narrows the data used for a single Report run, without changing the Template. |
| `Report` | The output produced when a Template is run against the data. Has a status: `Processing`, `Finished`, `Partial failure`, or `Error`, or `Draft` and `Final` for a regulatory filing. | It is the actual artifact the operator delivers. |
| `Preview` | The in-Console view of a `Finished` report, adapted to its output format. | It lets the operator validate the result before sending it out. |
| `Download` | The action that takes the finished report file out of the Console in its configured format. | It is the operational endpoint of the whole flow. |
| `Reminder` | An optional delivery deadline tracked from the Overview page (Once, Daily, Weekly, Monthly, Semiannual, Annual). | Used when a Report has a recurring delivery cadence to manage operationally. |

## When a Template becomes a Report

***

A Template by itself is just a definition. It becomes a Report when you click **Generate Report** in the 4-step wizard on the **Reports** page.

At that point:

1. Reporter takes the selected Template, the institution, and the parameters.
2. It applies any filters you configured.
3. It reads from the Data Sources referenced by the Template.
4. It produces a file in the Template's output format and adds it to the Reports list with `Processing` status.
5. When generation finishes, the status moves to `Finished` and the file becomes downloadable.

## When users usually get lost

***

> **Template vs Report**
>
> A Template is a definition. A Report is a generated file. You can generate many Reports from the same Template over time (each with its own filters, run date, and status).

> **Data Source vs Filter**
>
> The Data Source is the connection Reporter uses to read data. A Filter is a per-run narrowing that does not change the Template or the Data Source, only what data the current Report includes.

> **Template Builder vs uploading a `.tpl`**
>
> The Template Builder generates `.tpl` code from blocks you assemble in the Console. Uploading a `.tpl` skips the builder and uses a file prepared externally. Both end up as the same kind of Template, and both open in the same edit wizard.

> **Why a finished Report is not the same as a delivered Report**
>
> When a Report reaches `Finished`, Reporter has produced the file and you can download it. Reminders on the Overview page separately track delivery, such as sending the file to a regulator or archiving it.

> [!TIP]
>
> Pair this page with [Setup path](/en/products/reporter/console/reporter-setup-path) when onboarding new users. One page explains the model. The other explains the order.


# What is Reporter module?
Source: https://docs.lerian.studio/en/products/reporter/console/reporter-module

Configure Data Sources, build Templates, generate Reports, and download the output through a visual interface in the Lerian Console.

**Reporter** is a module inside the [Lerian Console](/en/platform/console/about-lerian-console) for operating report generation from data already available in your environment.

Use it to define the structure of the output, generate a Report, review its status, and download the final file. When the report needs an external database or a connection needs validation, use **Data Sources** to manage that connection. Typical use cases include regulatory filings, internal audit extracts, recurring operational reports, and ad hoc reports for a specific period.

This page explains how to operate the Reporter Module from the Console.

> [!WARNING]
>
> Reporter is only available if you've acquired the Reporter product. [Get in touch with our team](https://lerian.studio/contact) to learn more.

## Who uses this page

***

Use this page if you produce or manage Reports in the Console. That usually means operations, compliance, finance, regulatory, or support teams. These teams turn stored data into a file for review, submission, or archiving.

Developers and integration teams may also use Reporter, but their main reference is the [Reporter API reference](/en/reference/products/reporter/reporter-developer-quick-start). The Console documentation explains the visual workflow. The API reference explains programmatic access.

## Start here first

***

If this is your first time using Reporter, start by understanding which setup path applies. Some environments already include internal Data Sources for Lerian products, such as Midaz or CRM. In that case, the operator can often start from **Templates** and **Reports**. Use **Data Sources** first when you need to add an external database or validate an existing connection.

> **[Setup Path](/en/products/reporter/console/reporter-setup-path)**
>
> Choose the right path: use existing internal Data Sources, or add and test an external Data Source before generating Reports.

> **[Concepts Map](/en/products/reporter/console/reporter-concepts-map)**
>
> Understand how Data Sources, Templates, Reports, previews, and downloads relate.

## What you can operate

***

From the Reporter Module, you can:

* **Manage Data Sources**: Review, test, or register database connections that Reporter can read from during generation. Internal product connections may already exist. Add external databases from this area.
* **Register Institutions**: Record each institution that the tenant reports for, with its CNPJ and the rows that belong to it.
* **Build Templates**: Define the structure and output format of the Report, either by uploading a prepared `.tpl` file or building one visually in Template Builder.
* **Generate Reports**: Run a Template against connected data. Fill in the parameters that the Template declares, and add optional filters such as date range, status, or transaction type.
* **Review generation status**: Track whether a Report is `Processing`, `Finished`, `Partial failure`, or `Error`, and whether a regulatory filing is `Draft` or `Final`.
* **Preview and download output**: Open a finished Report in the Console and download the generated file in its configured format, such as CSV, XML, HTML, TXT, or PDF.
* **Track delivery reminders**: Use the Overview area to follow upcoming and overdue reporting deadlines.
* **File regulatory documents**: In [Regulatory Filing](/en/products/reporter/console/regulatory-filing), activate a document from the catalog for an institution and map your tables to its fields. Then generate, correct, and approve the filing.

## Operational areas

***

The Reporter sidebar follows the common operator workflow: understand the current state, define the output, then generate and download files. Manage Data Sources when you add, test, or change a connection.

> **[Overview](/en/products/reporter/console/reporter-module)**
>
> Monitor the current Reporter workspace: KPIs, delivery reminders, upcoming deadlines, and recent error count.

> **[Data Sources](/en/products/reporter/console/managing-data-sources)**
>
> Review internal connections and configure or test external database connections Reporter uses to fetch data.

> **[Templates](/en/products/reporter/console/managing-templates)**
>
> Create, update, and delete Templates that define the Report layout and output format.

> **[Reports](/en/products/reporter/console/managing-reports)**
>
> Generate Reports, monitor their status, preview finished files, and download the result.

> **[Institutions](/en/products/reporter/console/managing-institutions)**
>
> Register the institutions the tenant reports for, with their CNPJ and data scope.

## Overview area

***

When you open Reporter, you land on **Overview**. Use it as the operating dashboard for the module.

It includes:

* **What is Reporter?** A short description of the module and a link to the documentation.
* **Templates**: total number of registered Templates.
* **Reports Generated**: total number of generated Reports.
* **Data Sources**: total number of configured database connections.
* **Errors**: errors recorded in the last 30 days.
* **Delivery Calendar**: recurring or one-off reporting deadlines shown by date.
* **Upcoming Deadlines**: the next reminders, their due dates, and their status.

Delivery reminders help operators manage reporting routines.

## Main tasks

***

> **[Add a Data Source](/en/products/reporter/console/adding-a-data-source)**
>
> Register an external database connection when the needed Data Source is not already configured.

> **[Test a Data Source Connection](/en/products/reporter/console/testing-a-data-source)**
>
> Confirm that credentials, network access, and SSL settings are correct.

> **[Add a Template](/en/products/reporter/console/adding-template)**
>
> Upload a prepared `.tpl` file or build a Template visually with Template Builder.

> **[Generate a Report](/en/products/reporter/console/generating-a-report)**
>
> Run a Template against your data and produce a downloadable file.

> **[Download a Report](/en/products/reporter/console/downloading-a-report)**
>
> Save the final file from a finished Report generation.

> **[Correct a Report](/en/products/reporter/console/editing-a-report)**
>
> Learn what to change when a generated Report has the wrong data, layout, or format.

## Console vs API

***

Use the **Console** when an operator needs to configure, generate, review, and download Reports through the visual interface.

Use the **API** when a system needs to automate Reporter operations, integrate Reporter into another workflow, or manage Templates, Reports, and Data Source connections programmatically.

The same Reporter concepts apply in both places: Data Sources provide the data, Templates define the output, and Reports are the generated files. The Data Source may be preconfigured for internal Lerian products or manually added for external databases.


# Setup Path
Source: https://docs.lerian.studio/en/products/reporter/console/reporter-setup-path

Follow the minimum setup path for operating Reporter from the Lerian Console: data sources, templates, first report generation, and download verification.

Use this path when you need to make Reporter usable from the Console for the first time. The sequence depends on your data source model. Start with Templates if internal product Data Sources are already configured. If you need an external database, add and test the Data Source first.

## Before you start

***

Read the [Reporter concepts map](/en/products/reporter/console/reporter-concepts-map) if you have not used Reporter before. It explains the operational chain:

* **Data Sources** define where Reporter reads data from.
* **Institutions** define who a Report is for, and which rows each institution reads.
* **Templates** define the structure and output format of the file.
* **Reports** are the files that Reporter generates from a Template. You can monitor, view, and download them.

Before opening the setup screens, decide which report you want to produce first. For example: "monthly tax report in CSV", "daily operational report in PDF", or "regulatory XML file filtered by date range". That decision tells you whether the needed Data Source already exists. It also tells you which Template, output format, and filters you need.

## Prerequisites

***

| Requirement | What must be ready | Where it is used |
| - | - | - |
| Reporter access | Your organization can access Reporter in the Console. | All Reporter pages |
| Console permissions | Your user can manage Data Sources, Templates, and Reports for the organization. | Data Sources, Templates, Reports |
| Data Source model | Whether the report uses an internal Data Source already configured for products such as Midaz or CRM, or an external database that must be added manually. | Setup path |
| Database connection details | Host, port, database name, user, password, and any required network or SSL information. Required only when adding an external Data Source. | Data Sources |
| Source data context | The database, table, fields, and filters that should feed the first report. | Data Sources, Reports |
| Institution details | The CNPJ of each institution that the tenant reports for, and the rows that belong to it. A regulatory filing needs an institution. | Institutions, Reports, Regulatory Filing |
| Template input | Either an existing `.tpl` file or enough report structure to build one in the Template Builder. | Templates, Template Builder |
| Output expectation | The required file format, such as CSV, XML, HTML, TXT, or PDF. | Templates, Reports |
| API automation need | A decision on whether setup will stay manual in the Console or be automated through the API. | API reference |

If one of these items is absent, stop there first. Reporter can only generate useful files when you know the Template, the intended output, and the relevant data connection.

## Minimum setup sequence

***

**1. Confirm access and choose the first report**

Start from the Reporter overview. Confirm that the team knows which report to create first. Use the overview when you need to explain what each Reporter area is for.

Go to [Reporter Module](/en/products/reporter/console/reporter-module) and [Reporter concepts map](/en/products/reporter/console/reporter-concepts-map).

**2. Confirm the Data Source path**

Check whether the needed Data Source already exists. Internal product Data Sources may already be configured for the environment. If the report depends on an external database or a missing connection, add that Data Source. Test it before you build reports.

On the **Data Sources** page, use existing connections when they are already present. Add a new connection only when the required source is not available. The Console tests the connection when you save it.

Use [Adding a Data Source](/en/products/reporter/console/adding-a-data-source) and [Testing a Data Source connection](/en/products/reporter/console/testing-a-data-source).

**3. Register the institutions**

Register each institution that the tenant reports for, with its CNPJ and its scope. A Report reads for one institution or for all of them. A regulatory filing is made for one institution.

Use [Managing Institutions](/en/products/reporter/console/managing-institutions). Use **Propose from Midaz** to start from the organizations that Midaz already holds.

**4. Add or build a Template**

The Template defines the report structure and output format. You can upload an existing `.tpl` file or build the Template visually in the Console.

On the **Templates** page, use [Adding a template](/en/products/reporter/console/adding-template). If the operator needs to assemble the layout from blocks, use the [Template Builder](/en/products/reporter/console/template-builder).

**5. Generate a Report**

On the **Reports** page, create a report from the Template. Select the Template. Choose the institution and fill in the parameters when the wizard asks. Apply filters when needed, review the setup, then generate the file.

Use [Generating a report](/en/products/reporter/console/generating-a-report). This is the point where a Template becomes a Report. Before generation, it is only a reusable definition.

**6. Monitor completion and download the file**

Generated reports start in `Processing`. Wait until the status reaches `Finished`, then view or download the output file.

If the report ends in `Error` or `Partial failure`, inspect the details. Then run it again after you fix the Data Source, Template, or filter inputs. Use [Downloading a report](/en/products/reporter/console/downloading-a-report) when the file is ready.

**7. Track recurring delivery dates when needed**

If the report has a recurring deadline, use the **Overview** page to add the delivery reminder. This keeps upcoming and overdue deliveries visible.

## Common sequencing mistakes

***

> **Creating a Data Source when one already exists**
>
> Some environments already include internal Data Sources for Lerian products such as Midaz or CRM. Check the existing list before adding a duplicate external connection.

> **Using a Data Source that has never been tested**
>
> An external connection may exist, but its credentials and network access still need validation when the report depends on that source. Run **Test Connection** before relying on it.

> **Uploading a Template without knowing the output format**
>
> The Template should match the required file format. Confirm whether the operation needs CSV, XML, HTML, TXT, or PDF before using it to generate reports.

> **Expecting the API reference to replace Console setup**
>
> Operators can complete the first setup in the Console. Use the API reference when you must automate, integrate, or debug the same workflow with engineering support.

## Related links

***

> **[Reporter API reference](/en/reference/products/reporter/reporter-developer-quick-start)**
>
> Use when you must automate or integrate the Reporter workflow through APIs.


# Using the Template Builder
Source: https://docs.lerian.studio/en/products/reporter/console/template-builder

Build report templates visually by assembling blocks instead of writing .tpl code manually.

Use Template Builder to create a Template visually. The builder converts blocks into `.tpl` code, so operators can define report structure without writing the Template file manually.

## Objective

***

Build a Template from visual blocks and save it for future Report generation.

For example, a monthly transaction Template can use fixed text for the header and a **Loop** for each transaction row. It can also use **Variable** blocks for fields such as amount and date, and an **Aggregation** block for the total.

## When to use

***

Use Template Builder when:

* operators need to create a Template without editing `.tpl` code.
* the report structure depends on fields, loops, conditions, or totals from a Data Source.
* the team wants to download the generated `.tpl` file after building it.

Use `.tpl` upload instead when a technical team already created and reviewed the Template outside the Console.

## Before you start

***

Confirm:

* at least one relevant Data Source exists if the Template needs database fields. It can be an internal source already configured for the environment or an external source added from **Data Sources**.
* you tested the Data Source when connection health is uncertain. The **Data Sources** sidebar lists its tables and fields.
* you know the expected output format: XML, HTML, CSV, TXT, or PDF.
* the operator knows the report structure, such as required header, rows, totals, or conditional sections.

> [!NOTE]
>
> Blocks define the output structure. Filters applied during Report generation define which records enter that structure.

## Step by step

***

**1. Open the builder**

Go to the **Templates** page and click **Template Builder**.

**2. Name the Template**

Edit the Template name in the header. Use a name that operators can identify during report generation. Then enter the **Category**, the report family, such as `cadoc`.

**3. Choose the output format**

Select XML, HTML, CSV, TXT, or PDF.

> [!NOTE]
>
> When you select **PDF**, the generated template code uses HTML format. The code is converted to PDF during report generation.

**4. Add blocks to the canvas**

Use the blocks toolbar to add structure. Common blocks are **Text**, **Variable**, **Loop**, **Conditional**, and **Aggregation**.

**5. Connect fields from Data Sources**

Use the Data Sources sidebar to browse schemas, tables, and fields. Click a field to add a **Variable** block for that field.

**6. Review the code or the preview when needed**

Switch from **Visual** to **Code** to inspect a read-only local approximation of the `.tpl` code. Switch to **Preview** to see the Template rendered by Reporter with placeholder values, not real data.

**7. Save the Template**

Click **Save**. The builder validates required block fields, generates `.tpl` code, and saves the Template.

## Field guide

***

### Builder-level fields and controls

| Field or control | What it does | Example |
| - | - | - |
| **Template name** | Required name in the builder header. It maps to `name` and becomes the saved Template label and generated `.tpl` filename prefix. | `Monthly transaction CSV` |
| **Category** | Required report family in the builder header. | `cadoc` |
| **Output format** | Required format. Use `xml`, `html`, `csv`, `txt`, or `pdf`. When `pdf` is selected, code generation uses HTML internally. | `pdf` |
| **Visual** | Block editor mode for assembling the Template. | Use while arranging blocks |
| **Code** | Read-only local approximation of the `.tpl` code, with **Copy code**. | Review generated `.tpl` |
| **Preview** | The Template rendered by Reporter with placeholder values. A PDF Template previews as its HTML stage. | Check where each field lands |
| **Download .tpl file** | Downloads the generated `.tpl` without saving a new Template. | `monthly-transaction-csv.tpl` |
| **Save** | Validates blocks, generates `.tpl` code, and creates the Template. Requires a name, a category, and at least one block. | Save after blocks are valid |

### Block field guide

| Block | Fields to configure | Effect |
| - | - | - |
| **Text** | **Content** (`content`) | Renders fixed text such as CSV headers, XML tags, or HTML fragments. |
| **Variable** | **Data Source**, **Table**, **Field**, **Index (optional)**, **Filters** (`dataSource`, `table`, `field`, `index`, `filters[]`) | Inserts a field value. Inside a parent **Loop**, **Data Source** can be auto-filled from the loop iterator. |
| **Loop** | **Iterator name** and **Iterable source** (`iteratorName`, `iterableSource`) | Repeats child blocks over a collection. Use `dataSource.table` format for the iterable source. |
| **Conditional** | **Condition** and **Include else block** (`condition`, `hasElse`) | Renders child blocks only when the condition is true; optional else content can render when false. |
| **Aggregation** | **Aggregation type**, **Source**, **Field**, optional grouping/order/result fields (`aggregationType`, `source`, `aggregationField`) | Produces totals, counts, averages, min/max, or **Last Item by Group** values from a source collection. |
| **Calculation** | **Expression** (`expression`) | Renders a calculated value. Supported operators shown in the UI include `+`, `-`, `*`, `/`, `**`, and `%`. |
| **Date/Time** | **Format** and **Date source** (`format`, `dateSource`) | Formats a date value, for example `YYYY-MM-DD` from `transaction.createdAt`. |
| **Counter** | **Mode**, **Counter name**, and **Counter names** (`counterMode`, `counterName`, `counterNames[]`) | **Increment** advances one counter. **Display** outputs one or more counters. |
| **Comment** | **Comment** (`commentText`) | Stores an internal Template note and does not appear in the final Report. |
| **Section** | **Section title** (`sectionTitle`) | Groups child blocks to organize larger Templates. |
| **With (Assign)** | **Variable name** and **Assignment expression** (`variableName`, `assignment`) | Creates a reusable variable from an expression for child blocks. |
| **Expression** | **Expression** (`inlineExpression`) | Renders an inline expression such as `item.name\|upper`. |
| **Custom Tag** | **Tag name** and **Tag arguments** (`tagName`, `tagArgs`) | Emits an advanced Template tag such as `include` with arguments like `"header.html"` or `key=value`. |

## Block types

***

| Block | What it represents in practice |
| - | - |
| **Text** | Fixed content that always appears in the output, such as a header or label. |
| **Variable** | A value from a data source field, such as document number, amount, or status. |
| **Loop** | A repeated section, such as one row for each transaction. |
| **Conditional** | Content that appears only when a rule is true, such as `account.status == "active"`. |
| **Aggregation** | A total, count, average, min, max, or last item by group. |
| **Calculation** | A calculated value, such as `value * 1.05`. |
| **Date/Time** | A formatted date or time value. |
| **Counter** | A row number or sequence value. |
| **Comment** | Internal Template note that does not appear in the generated Report. |
| **Section** | A named group of blocks for organizing larger Templates. |
| **With (Assign)** | A reusable variable created from an expression. |
| **Expression** | An inline expression rendered into the output. |
| **Custom Tag** | A custom Template tag when advanced Template syntax is needed. |

## Working with blocks

***

* Click a block type in the toolbar to add it to the canvas.
* Drag blocks to reorder the output.
* Configure each block inline. For example, a **Variable** needs a source and field, while a **Conditional** needs a condition.
* Use **Inline** when the block should render without a line break after it.
* Use **Trim whitespace** to remove extra spaces around block output.
* Use **Duplicate** to copy a configured block.
* Use **Delete** to remove a block from the Template.

Container blocks such as **Loop**, **Conditional**, **Section**, and **With** can hold child blocks. Use them when the output needs repeated or grouped content.

## Expected result

***

After you save, the Template appears on the **Templates** page. You can select it in the **Generate Report** wizard. You can also download the generated `.tpl` file from the builder.

## Common errors and care points

***

> **No Data Sources appear in the sidebar**
>
> The sidebar only shows configured Data Sources. If the expected internal source does not appear, confirm setup with the Reporter administrator. If the report needs an external database, add and test that Data Source before using database fields in the Template.

> **Required block fields are missing**
>
> The builder validates blocks during save. If a block has no source, field, condition, or expression, fix that block before you save.

> **Using filters inside the wrong part of the workflow**
>
> Template blocks define the file structure. You select report filters later, during report generation. They decide which records enter the output.

> **Choosing PDF without understanding the generated code**
>
> PDF output comes from HTML. Build the Template as HTML-compatible content when the final output format is PDF.

## Next steps

***

* Use [Generate a Report](/en/products/reporter/console/generating-a-report) to test the Template with real filters.
* Use [Update a Template](/en/products/reporter/console/updating-a-template) to change the name, output format, category, or `.tpl` file later. The builder does not open a saved Template.
* Use [Add a Template](/en/products/reporter/console/adding-template) if you need to upload a prepared `.tpl` file instead.

> **API equivalent**
>
> Call [Generate template code endpoint](/en/reference/products/reporter/generate-template-code), then upload the generated `.tpl` file with [Upload template endpoint](/en/reference/products/reporter/upload-template).


# Test a Data Source Connection
Source: https://docs.lerian.studio/en/products/reporter/console/testing-a-data-source

Verify that a Data Source's credentials and network settings are correct before relying on it for regulatory report generation in the Reporter module.

Use this page to confirm that Reporter can reach a Data Source. The test does not read the schema. You cannot test a Data Source marked **Provided by the platform**.

## Objective

***

Validate connectivity before operators rely on the Data Source in Templates or Reports.

For example, test after creating `production-postgres`, after a password rotation, or before generating a monthly report that depends on a recently changed schema.

## When to use

***

Use this task:

* when a Data Source shows **Not checked** or **Disconnected**.
* before generating Reports that depend on the connection.
* when no tables appear in the schema browser.
* when Report generation fails because of connection or schema errors.

## Before you start

***

Confirm:

* the Data Source exists on the **Data Sources** page.
* the expected host, port, database name, username, schema, and SSL settings are configured.
* the database should be reachable from Reporter.
* the database user has permission to read the required tables.

> [!NOTE]
>
> A successful test confirms access at that moment. It does not guarantee future Reports will succeed if credentials, network rules, or database permissions change later.

## Step by step

***

**1. Open Data Sources**

Go to **Data Sources**.

**2. Find the connection**

Locate the card for the Data Source you need to test.

**3. Run the test**

Click **Test Connection**.

**4. Wait for the result**

The status changes to **Connecting** while Reporter tests the connection.

**5. Read the result**

On success, the card shows **Connected** and the latency. On failure, the card shows **Disconnected** and the Console shows the reason that Reporter returns.

**6. Check the schema**

Expand the card to see the tables that Reporter can read. When no tables appear, click **Refresh** to read the schema again.

## Field guide

***

### Test action and result fields

| Field or status | What it means | Example |
| - | - | - |
| **Test Connection** | Action on the Data Source card. The test endpoint identifies the selected connection by `dataSourceId`. | Test `production-postgres`. |
| **Connecting** | Local status while the test request is pending. Wait for the final result before editing or generating a Report. | **Connecting** |
| **Connected** (Console display label) | Successful result mapped from the wire value `connected`; the Data Source is usable at that moment. | **Connected** with `Latency: 45ms`. |
| **Disconnected** (Console display label) | Failed result. A failed probe maps the wire value `failed` to this label. Check host, port, credentials, network access, and SSL settings. | **Disconnected** after `authentication failed`. |
| **Not checked** (Console display label) | Reporter has no test result for the Data Source. | **Not checked** with `Never checked`. |
| Latency | `latencyMs`, returned in milliseconds for the probe. It is a signal, not a guarantee of future Report generation speed. | `45` |
| Test message | `message` returned by Reporter, usually most useful on failure. Use it as the first clue for what to fix. | `authentication failed` |

### Schema fields available separately

| Schema item | What it shows | Example |
| - | - | - |
| Tables | `tables[].name` returned by the separate schema operation. These are the tables operators can use in Template Builder and report filters. | `transactions` |
| Fields | `tables[].fields[]` inside each table. These fields can be inserted as Template variables or used as Report filters. | `amount`, `created_at` |
| No schema loaded | Empty `tables` array or schema load error. The connection may work, but table permissions or schema names still need correction. | No tables discovered. |

## Expected result

***

The card shows **Connected**. Expand the card to confirm the tables before using its fields in Template Builder and report filters.

## Common errors and care points

***

> **Connection succeeds but no tables appear**
>
> Check schema names and database permissions. The database user may connect but not have access to the tables needed for reporting.

> **Connection fails after editing credentials**
>
> Reopen the Data Source and confirm username, password, host, port, and SSL settings.

> **Testing once and assuming it stays valid**
>
> Network rules, rotated passwords, and database permissions can change. Re-test when generation errors appear.

## Next steps

***

* Use [Template Builder](/en/products/reporter/console/template-builder) after schemas and fields are visible.
* Use [Generate a Report](/en/products/reporter/console/generating-a-report) after the Data Source is healthy.
* Use [Edit a Data Source](/en/products/reporter/console/editing-a-data-source) if the test fails because settings are wrong.


# Update a Template
Source: https://docs.lerian.studio/en/products/reporter/console/updating-a-template

Update a Template's name, output format, or replace the uploaded .tpl file directly from the Lerian Console, without deleting and recreating the template.

Use this page when a Template should remain available, but something about its name, output format, layout, or source file needs to change.

## Objective

***

Update the reusable Template that future Reports will use.

For example, update a Template when the report owner changes the required CSV columns. Update it when the output format must be XML instead of TXT. Update it when the Template name is too generic for operators to identify safely.

## When to use

***

Use this task when:

* you still need the Template.
* the name or output format is wrong.
* an uploaded `.tpl` file needs a replacement.
* future Reports should use the corrected Template.

Do not use this task to change a Report already generated. Generated Reports are historical files. Correct the source setup and generate a new Report.

## Before you start

***

Every Template opens in the same edit wizard. You can update the name, output format, and category, or replace the `.tpl` file. The Template Builder does not open a saved Template. To change the blocks of a Template that you built, build it again and save it as a new Template, or replace its `.tpl` file.

Confirm that the change applies to future Reports. Reports already generated from the old Template stay unchanged.

> [!WARNING]
>
> Replacing a `.tpl` file affects every future Report generated from this Template. Validate the new file before using it for a reporting cycle.

## Step by step

***

**1. Open the Templates page**

Go to **Templates** and locate the Template you need to update.

**2. Open the edit action**

Click the three dots () in the **Actions** column and select **Edit**.

**3. Edit the Template fields**

In **Edit template**, update the fields that changed: **Template Name**, **Output Format**, **Category**, and **Template File (.tpl)**. If you do not upload a new file, the current file stays.

**4. Save the changes**

Click **Update Template**.

**5. Generate a test Report**

Generate a new Report with the updated Template and confirm that the output matches the expected structure.

## Field guide

***

| Field | What to change | Example |
| - | - | - |
| **Template Name** | Required Console label for operators. It maps to `name` in the Console and to `description` in the Reporter API. | `Monthly tax XML` |
| **Output Format** | File type for future Reports. Use one of `csv`, `xml`, `html`, `txt`, or `pdf`. | `xml` |
| **Category** | Required report family. | `cadoc` |

## Expected result

***

The Template stays on the **Templates** page with the updated configuration. Future Reports generated from it use the new name, output format, and Template structure.

## Common errors and care points

***

> **Expecting old Reports to change**
>
> Updating a Template does not rewrite Reports already generated. Generate a new Report after correcting the Template.

> **Replacing the file without checking output format**
>
> If the `.tpl` file structure and **Output Format** do not match the expected delivery format, operators can generate the wrong file type.

> **Renaming without operational context**
>
> Names like `Template 1` or `New Template` are hard to distinguish during report generation. Use a name that includes the report purpose or period.

## Next steps

***

* Use [Generate a Report](/en/products/reporter/console/generating-a-report) to test the updated Template.
* Use [Correct a Report](/en/products/reporter/console/editing-a-report) if you found the issue in a generated Report.
* Use [Delete a Template](/en/products/reporter/console/deleting-a-template) only if you no longer need the Template.

> **API equivalent**
>
> [Update templates endpoint](/en/reference/products/reporter/update-templates)


# Prepare trial-balance reporting with Midaz and Reporter
Source: https://docs.lerian.studio/en/products/reporter/creating-trial-balance-report

Use Midaz accounting entries and Reporter templates to build a reporting workflow suited to your institution.

## Scope of this guide

This guide describes a reporting integration pattern. It is not a COSIF mapping specification and does not certify an output for BACEN submission. Define, validate, and approve any regulatory mapping in the controls and processes that own it.

## Use the current Midaz accounting model

For new accounting classifications, use the rubric codes in an OperationRoute's `accountingEntries`.

Midaz keeps the legacy `OperationRoute.code` field for backward compatibility and marks it deprecated. It is an optional external reference. Midaz does not reserve it for COSIF, does not assign it regulatory meaning, and does not write it to operations.

When `accounting.validateRoutes` is enabled on the ledger and a matching rubric resolves, Midaz records the resolved rubric code from `accountingEntries` as `routeCode` on the operation. In other conditions, `routeCode` stays empty. Use `routeCode` when you join report data to classifications. Do not use `code` as the authoritative source for a regulatory mapping.

An OperationRoute can hold accounting entries for the transaction-lifecycle actions `direct`, `hold`, `commit`, `cancel`, and `revert`, plus the supplementary keys `overdraft`, `block`, and `unblock`. Each entry can define debit and credit rubrics with a code and description.

## Build the reporting workflow

1. Define your institution's chart of accounts and the classifications required by the report.
2. Configure OperationRoutes and their accounting entries according to those classifications.
3. Configure a Reporter data source and template for the data available in your environment.
4. Generate the report and validate its content through your accounting and regulatory controls.

Reporter renders template-driven reports from configured data sources. Its supported output formats are HTML, PDF, CSV, XML, and TXT. The chosen format does not, by itself, make a report compliant with a regulatory submission requirement.

## Related documentation

* [OperationRoutes API Reference](/en/reference/products/midaz/v2/create-operation-route)
* [Reporter overview](/en/products/reporter/what-is-reporter)
* [Reporter template reference](/en/products/reporter/template-reference)


# How report generation works
Source: https://docs.lerian.studio/en/products/reporter/how-report-generation-works

The path a Reporter report takes: the request, extraction against the configured data sources, the render, the file in object storage, and the download.

Report generation has two halves. The **manager** accepts your request, checks it, and hands it to a queue. The **worker** extracts the data, renders the template, and writes the file. Reporter answers your request as soon as the first half completes, so you poll or listen for the second.

Both halves ship in one binary. A deployment runs the API surface, the worker surface, or both, and a queue carries the work between them.

## The path end to end

***

**1. Request**

You call [Create a report](/en/reference/products/reporter/create-report) with a template identifier and the row filters you want. Reporter validates the request and stores the report as `Processing`.

**2. Extraction**

The worker queries each data source the template names, one section per data source, and keeps only the fields in the template's field map.

**3. Render**

The extracted rows become the context for the template. Reporter renders the document in the template's output format.

**4. Storage**

Reporter writes the rendered file to the configured object storage bucket and records the terminal status of the report.

**5. Download**

You call [Download a report](/en/reference/products/reporter/download-report) and receive the file with its content type and filename.

## What the manager does

***

The manager owns everything that happens before the queue. It runs these checks in order, and any one of them can reject the request outright.

**It applies idempotency.** Send an `X-Idempotency` header to name the request yourself. Without one, Reporter derives the key from the request body. Reporter rejects a repeat of an in-flight request as a duplicate. A repeat of a completed request returns the original report and marks the response with `X-Idempotency-Replayed: true`. The window is 30 seconds.

**It resolves the template.** Reporter loads the field map, the output format, and the description that belongs to the template identifier. An unknown identifier fails here.

**It validates your filters.** Every field you filter on is checked against the live schema of its data source. A wrong field name fails the request instead of producing an empty report.

**It resolves the parameters and the institution.** Reporter applies the defaults that the template declares for its parameters. It refuses a missing required parameter. It then resolves the institution that the report reads for. A tenant with several institutions must name one, or `all`.

**It records the report and queues the work.** The report is stored as `Processing`.

The report keeps its own copy of the output format and the template description. That snapshot makes an old report reproducible after the template moves on.

## What the worker does

***

The worker consumes the command and owns the rest of the path.

A queue can deliver the same command twice. The worker therefore reads the report before it starts a run. If the report already reached a terminal status, the worker leaves it as it is and does not generate it again.

It then loads the template file from object storage and extracts data. Each data source is one section. A section that fails does not stop the others. The worker collects the outcome of every section and only then decides the status of the report.

When every section fails, Reporter records the failure and skips the render. No misleading file reaches the bucket.

The render step turns the surviving sections into the document. When the output format is PDF, Reporter renders HTML first and converts it through a headless browser pool. The finished bytes go to the bucket, the terminal status goes to the report record, and a terminal event goes to the event stream.

## Report states

***

A report that you create through `POST /v1/reports` reaches one of four states.

| State | Meaning | Artifact |
| - | - | - |
| `Processing` | Accepted and queued, or in extraction | Not yet |
| `Finished` | Every section returned data | Ready to download |
| `Partial` | Some sections failed, others returned data | Incomplete |
| `Error` | Every section failed, the request never reached the worker, or the worker stopped sending heartbeats | None |

A regulatory filing never ends in `Partial`. It ends in `Draft` or `Error`, and approval turns a `Draft` into `Final`.

Poll [Check report status](/en/reference/products/reporter/check-report-status) or consume the terminal event. A `Partial` report carries a per-section outcome in its metadata, which names the data sources that did not answer. Fix those data sources, then generate the report again. [Download a report](/en/reference/products/reporter/download-report) serves the artifact of a `Finished` or `Final` report, and of a `Draft` with no required field blank.

## Time limits on the path

***

Each stage carries its own limit, and an operator sets them per deployment.

| Limit | Default | Applies to |
| - | - | - |
| Idempotency window | 30 seconds | Repeat detection on the request |
| Extraction timeout | 300 seconds | One extraction run |
| Extraction concurrency | 4 | Parallel queries inside one run |
| PDF conversion timeout | 90 seconds | One HTML-to-PDF conversion |
| PDF worker pool | 2 | Concurrent conversions per worker |

Volume limits bound the same run: 10 data sources, 20 tables per data source, 50 fields per table, and 256 MiB of extracted result. Each table returns at most 150,000 rows, and each query times out after 300 seconds. See [Environment variables](/en/products/reporter/reporter-environment-variables) for the settings behind each one.

## Where deadlines fit

***

A deadline is a due date with a recurrence rule, and it can name the template that satisfies it. It sits beside the generation path rather than on it.

A deadline starts a report only when an operator turns on the deadline trigger and names the template's category in `DEADLINE_TRIGGER_GENERATE_CATEGORIES`. Otherwise, you generate the report through the request path above, then mark the deadline delivered.

Reporter recomputes a deadline on read. A recurring obligation that carries a delivery mark rolls forward to its next due date on the first read after the current date passes. That roll-forward clears the mark. The notifications operation returns the deadlines inside their alert window when you ask for them. See [Managing deadlines](/en/products/reporter/managing-deadlines).

## Storage and download

***

Rendered files live in one S3-compatible bucket, under the `reports/` prefix. Reporter stores each file under the template identifier and names it after the report, so files stay grouped by the template that produced them.

Download returns the bytes with the content type of the output format and a filename built from the report identifier. The download works after the template is deleted, because the report holds its own format snapshot.

A report is created once and then retained. Its filters, its status, and its file describe exactly the request that produced them.

> [!NOTE]
>
> Reporter keeps rendered files in the bucket. Set retention with a lifecycle policy on the bucket itself.

## Next steps

***

> **[Reporter template engine](/en/products/reporter/reporter-template-engine)**
>
> The field map, the data context, and the two kinds of filter.

> **[Using Reporter](/en/products/reporter/using-reporter)**
>
> Upload a template, generate a report, and download the result.

> **[Managing deadlines](/en/products/reporter/managing-deadlines)**
>
> Track a regulatory obligation and mark it delivered.

> **[Reporter architecture](/en/products/reporter/reporter-architecture)**
>
> One binary, two surfaces, and the stores they share.


# Managing deadlines
Source: https://docs.lerian.studio/en/products/reporter/managing-deadlines

Track when regulatory and business reports are due with Reporter deadlines: create recurring obligations, monitor their status, and mark them delivered.

A **deadline** is Reporter's tracking layer for report deliveries. Templates define *how* a report looks, and report generation produces the *output*. A deadline records *when* a report is due and its delivery state. Each deadline represents a delivery obligation, typically a regulatory filing or a recurring business report. You can optionally link a deadline to the template that fulfills it.

Deadlines sit alongside the [reporting lifecycle](/en/products/reporter/reporter-quick-start#the-reporting-lifecycle) as an operational tracker, so teams can see what's `pending`, `overdue`, or already `delivered`.

## Why deadlines exist

***

Report generation answers *how* and *what*. Deadlines answer *when* and *whether it was met*. Without a tracking layer, a team can produce perfect reports and still miss a filing window. Nothing in the reporting engine itself knows that a report was *due*.

Deadlines solve a delivery-compliance problem. They turn recurring reporting obligations into tracked, dated commitments so that nothing slips silently:

* **Regulatory reporting obligations**: many filings must reach a regulator on a fixed schedule. A deadline records that obligation, its recurrence, and its delivery state, so a missed or late filing is visible before it becomes a compliance incident.
* **Internal SLAs**: recurring business reports often carry internal commitments ("finance receives the monthly close pack by the 5th"). Deadlines make those commitments explicit and measurable.
* **Audit trails for delivery**: each deadline records `deliveredAt` and moves through `pending` → `overdue` → `delivered`. It leaves an auditable history of *when* each obligation was satisfied.

## Who uses deadlines

***

Deadlines are a business and compliance tool layered on top of the reporting engine. Typical users include:

* A **fintech delivering regulatory reports to BACEN** on fixed monthly or annual schedules. It uses deadlines to track and meet each filing window.
* A **treasury or finance team** tracking recurring monthly report deliveries, using the calendar and status view to confirm each routine output went out on time.
* A **compliance officer** monitoring overdue obligations across the organization, filtering by `overdue` status to catch anything at risk before it escalates.

For these teams, deadlines show what's coming up, what's late, and what's done.

## How deadlines fit the Reporter workflow

***

Deadlines wrap around reports and data sources to add a delivery status layer on top of the reporting engine. Data Sources provide the data, Templates define the output, and the reporting lifecycle produces the file. A deadline sits above all of that. It optionally links to the template that fulfills the obligation, watches the due date, and exposes a single status. The status tells the business whether the obligation has been met.

Deadlines never submit a report to a regulator. When an operator turns on the deadline trigger, Reporter publishes `deadline.due` on the day a deadline falls due. It also generates the report, but only for the template categories that the operator lists in `DEADLINE_TRIGGER_GENERATE_CATEGORIES`. In every other case, you generate reports through the normal lifecycle, and the deadline records the delivery status.

## What a deadline tracks

***

Each deadline captures the due date for a report obligation plus the metadata your team needs to manage it:

| Field | Description |
| - | - |
| `name` | Human-readable name of the deadline (for example, *Monthly Regulatory Report*). |
| `description` | Optional longer description of the obligation. |
| `type` | Classification of the deadline, such as `regulatory` or `custom`. |
| `frequency` | How often the deadline recurs, such as `monthly` or `annual`. |
| `dueDate` | When the report is due, in RFC 3339 format. |
| `color` | Hex color used to visually identify the deadline in dashboards. |
| `notifyDaysBefore` | Number of days before the due date when notifications start. |
| `monthsOfYear` | Months (1–12) in which a `semiannual` or `annual` deadline falls. Required for those two frequencies and refused for the others. |
| `templateId` | Optional UUID of the [template](/en/products/reporter/using-reporter) used to fulfill the deadline. The template must have a category. |
| `filters` | Optional row filters, by data source, table, and field, for the report generated for this deadline. A condition can use `period`, such as `previous_month`, which Reporter resolves into a date range when the deadline fires. |
| `active` | Whether the deadline is currently active. |

Reporter also maintains read-only fields on each deadline: `id`, `status` (`pending`, `overdue`, or `delivered`), `deliveredAt`, `templateName`, `createdAt`, and `updatedAt`.

> [!NOTE]
>
> Include an `Authorization: Bearer <token>` header on every deadline request if your environment enables [Access Manager](/en/platform/access-manager).

## Creating a deadline

***

Create a deadline with the [Create a Deadline](/en/reference/products/reporter/create-deadline) endpoint (`POST /v1/deadlines`).

The required fields are `name`, `type`, `frequency`, `dueDate`, and `color`. The remaining fields are optional. Set `templateId` to link the deadline to the template that fulfills it, and `notifyDaysBefore` to control when reminders begin.

```json theme={null}
{
  "name": "Monthly Regulatory Report",
  "description": "Monthly regulatory compliance report",
  "type": "regulatory",
  "frequency": "monthly",
  "dueDate": "2026-03-31T23:59:59Z",
  "color": "#FF5733",
  "notifyDaysBefore": 5,
  "templateId": "00000000-0000-0000-0000-000000000000",
  "active": true
}
```

A successful request returns `201 Created` with the full deadline, including its generated `id` and an initial `status`.

> [!TIP]
>
> API reference: [Create a Deadline](/en/reference/products/reporter/create-deadline)

## Listing deadlines

***

Retrieve deadlines with the [Retrieve Deadlines](/en/reference/products/reporter/retrieve-deadlines) endpoint (`GET /v1/deadlines`). The endpoint paginates results, and you can filter them by status, activity, type, and due-date range.

| Query parameter | Description | Default |
| - | - | - |
| `status` | Filter by `pending`, `overdue`, or `delivered`. | — |
| `active` | Filter by active or inactive deadlines. | — |
| `type` | Filter by deadline type. | — |
| `start_date`, `end_date` | Earliest and latest due date, in `YYYY-MM-DD`, inclusive. | — |
| `limit` | Number of records per page (integer ≥ 1). | `10` |
| `page` | Page number to return (integer ≥ 1). | `1` |

For example, to list overdue deadlines, ten per page:

```
GET /v1/deadlines?status=overdue&limit=10&page=1
```

The response contains an `items` array plus `page`, `limit`, and `total` for pagination.

> [!TIP]
>
> API reference: [Retrieve Deadlines](/en/reference/products/reporter/retrieve-deadlines)

## Updating a deadline

***

Update an existing deadline with the [Update a Deadline](/en/reference/products/reporter/update-deadline) endpoint (`PATCH /v1/deadlines/{id}`). The endpoint changes only the fields in the request body, so you can send a partial payload. For example, push back a due date or deactivate a deadline:

```json theme={null}
{
  "dueDate": "2026-06-30T23:59:59Z",
  "notifyDaysBefore": 10,
  "active": false
}
```

A successful request returns `200 OK` with the updated deadline.

> [!TIP]
>
> API reference: [Update a Deadline](/en/reference/products/reporter/update-deadline)

## Deleting a deadline

***

Remove a deadline you no longer need to track with the [Delete a Deadline](/en/reference/products/reporter/delete-deadline) endpoint (`DELETE /v1/deadlines/{id}`). A successful request returns `204 No Content`.

> [!TIP]
>
> API reference: [Delete a Deadline](/en/reference/products/reporter/delete-deadline)

## Marking a deadline as delivered

***

After you file or send the report behind a deadline, mark the deadline as delivered. Use the [Deliver a Deadline](/en/reference/products/reporter/deliver-deadline) endpoint (`PATCH /v1/deadlines/{id}/deliver`). It moves the deadline's `status` to `delivered` and stamps `deliveredAt`.

```json theme={null}
{
  "delivered": true
}
```

Because `delivered` is a boolean, the same endpoint can also reverse the action. Send `"delivered": false` to reopen a deadline that you marked delivered by mistake. A successful request returns `200 OK` with the updated deadline.

> [!NOTE]
>
> Delivering a deadline only tracks the obligation. It records that the obligation was met. It does not generate or submit the underlying report. Generate the report through the [reporting lifecycle](/en/products/reporter/reporter-quick-start), then mark the deadline delivered to keep your tracker accurate.

> [!TIP]
>
> API reference: [Deliver a Deadline](/en/reference/products/reporter/deliver-deadline)

## How deadlines fit the workflow

***

A typical obligation moves through these states:

**1. Create the deadline**

Register the obligation with its due date, frequency, and optional template.

**2. Track its status**

It shows as `pending` until the due date, then `overdue` if you do not deliver the report in time.

**3. Generate the report**

Produce the report through the normal [reporting lifecycle](/en/products/reporter/reporter-quick-start), using the linked template.

**4. Mark it delivered**

Call the deliver endpoint to set `status` to `delivered` and record `deliveredAt`.

## Next steps

***

> **[Getting started with Reporter](/en/products/reporter/reporter-quick-start)**
>
> Walk through the reporting lifecycle that deadlines track.

> **[Using Reporter](/en/products/reporter/using-reporter)**
>
> Build the templates that fulfill your deadlines.

> **[BACEN templates](/en/products/reporter/reporter-bacen-templates)**
>
> Ready-to-use templates for Brazilian regulatory reporting.

> **[Deadlines API](/en/reference/products/reporter/create-deadline)**
>
> Full request and response reference for every deadline endpoint.


# Reporter architecture
Source: https://docs.lerian.studio/en/products/reporter/reporter-architecture

How Reporter runs: one binary whose RUN_MODE selects the API surface, the worker surface, or both, the queue between them, and the stores they share.

Reporter ships as one binary. `RUN_MODE` selects which surfaces that binary serves: `api`, `worker`, or `all`. The API and the worker are two roles of the same program, not two products. They share one build, one version, and one release.

You choose a topology at deploy time by setting an environment variable.

## Two surfaces, one binary

***

| Surface | `RUN_MODE` | Serves |
| - | - | - |
| API | `api` | Every REST operation on port `4005`, plus `/health`, `/readyz`, and `/version`. |
| Worker | `worker` | No REST surface. Consumes the report queue. A small health server on `HEALTH_PORT` carries `/health` and `/readyz`. |
| Both | `all` | Both surfaces in one process. |

```bash theme={null}
# API surface
RUN_MODE=api
SERVER_ADDRESS=:4005

# Worker surface
RUN_MODE=worker
HEALTH_PORT=4006
```

Run `all` when one process is enough, which is the usual choice for local development and small deployments. Split the roles into two deployables when report generation needs to scale on its own. Rendering a large PDF costs far more than accepting the request that asked for it. Separate deployments let you size each side to its own load.

## The path a report takes

***

**1. The API accepts the request**

A `POST` to `/v1/reports` names a template and its filters. Reporter takes an idempotency lock first. The lock key is the `X-Idempotency` header when you send one, and a hash of the request body when you do not. Reporter rejects a duplicate that is still in flight. A duplicate of a completed request replays the original report and marks the response as a replay.

**2. The API validates and persists**

Reporter loads the template's field map and output format. It then checks the filter fields against the live schema of each data source, and writes the report with status `Processing`.

**3. The API queues the work**

It publishes a command message to the internal RabbitMQ queue and answers `201 Created` with the `Processing` report. The caller has nothing more to do. Rendering has not started.

**4. The worker renders**

The worker consumes the command. It skips the command if the report already reached a terminal status. It loads the template from object storage and extracts the data for each data source. It renders the document and converts it to PDF when the format calls for it. It uploads the artifact.

**5. The worker settles the state**

It writes `Finished`, `Partial`, or `Error`, or `Draft` for a regulatory filing, and emits the matching event. The download operation serves the artifact of a `Finished` or `Final` report, and of a `Draft` with no required field blank.

## The queue between them

***

The API and the worker communicate over one RabbitMQ queue that carries report commands in one direction, with a dead-letter queue behind it. This queue works as private plumbing between the two surfaces of the same binary. It is not an integration point, it carries no contract you should build against, and its exchange, queue, and routing key are all operator-configured.

Business events are a separate channel. Reporter publishes them to their own exchange, which the operator configures and which the deployment's reference value names `reporter.events`. Every emission happens after the database commit and never fails the work that produced it. High-value events go through a durable outbox rather than a direct publish, so a broker outage delays them instead of losing them.

## Data extraction

***

The worker reaches your databases through its embedded extraction engine, with no hand-written queries and no network hop to a separate service.

The engine bounds every run. The defaults allow 10 data sources per report, 20 tables per data source, and 50 fields per table. They also allow four data sources extracted in parallel, and a five-minute deadline for the whole extraction. Failures do not end the run. A report whose sections partly succeed renders from what it has. It settles as `Partial` and records which sections failed.

## Stores and artifacts

***

| Dependency | Role |
| - | - |
| MongoDB | Templates, reports, deadlines, institutions, regulatory subscriptions, and the event outbox. |
| RabbitMQ | The internal report queue and the business-event exchange. |
| Redis or Valkey | Idempotency locks, the schema cache, and tenant lifecycle signals. |
| S3-compatible object storage | Template files and rendered artifacts, in one bucket. |

Object storage is S3-compatible: Reporter speaks the S3 protocol and any service that answers it works as a target. Template sources land under the `templates/` prefix, and rendered artifacts under `reports/`, keyed by template and report identifier with the output format as the extension. Reporter applies no expiry of its own, so retention is a lifecycle policy you set on the bucket.

## Reporter and Midaz

***

Midaz is a **data source** to Reporter, not a runtime dependency. You register a Midaz database the same way as any other PostgreSQL database. Templates address it by the `configName` the operator chose.

Two consequences follow. Reporter starts and serves templates, deadlines, and metrics with no data source configured at all, so a Midaz outage never stops Reporter from running. And the same deployment can report over Midaz, over your own databases, and over both in one template.

Point Reporter at a read replica where one exists. The extraction path only reads, but the query load of a heavy report is real, and a replica keeps it off the ledger's write path.

> [!NOTE]
>
> See [Connecting Reporter to Midaz](/en/products/reporter/connecting-reporter-to-midaz) for the variables, the `configName` convention, and how to confirm the source is visible.

## Health and readiness

***

Both surfaces expose `/health` and `/readyz` before authentication, so probes reach them without a token. The `/health` probe answers 503 until the startup self-probe succeeds. This lets an orchestrator restart a pod that could not reach its dependencies at boot. The `/readyz` probe reports the dependencies that surface actually uses, and its response states which deployment mode the process runs in. The API surface also serves `/version` with the build provenance.

Read the [health and readiness reference](/en/reference/health-and-readiness) for the probe contract shared across Lerian products.

## Next steps

***

> **[Core concepts](/en/products/reporter/reporter-core-concepts)**
>
> Templates, data sources, reports, deadlines, and the report states.

> **[Environment variables](/en/products/reporter/reporter-environment-variables)**
>
> Every setting that shapes a Reporter deployment.


# BACEN regulatory formats
Source: https://docs.lerian.studio/en/products/reporter/reporter-bacen-templates

Use Reporter templates as a rendering tool and validate every regulatory mapping with the applicable authoritative contract.

Reporter renders templates from configured data sources. Subscription-driven regulatory reports validate extracted values against the pinned contract and produce a `Draft`. Approval makes it `Final`. These checks do not certify a filing or establish a submission schedule.

Use the guides below only after you have verified the relevant layout, field semantics, aggregation, identifiers, and validation rules against the applicable authoritative source.

## Available guidance

***

> **[CADOC 4010 and 4016](/en/products/reporter/cadoc-4010-and-4016)**
>
> Validation status and next steps.

> **[CADOC 4111](/en/products/reporter/cadoc-4111)**
>
> Validation status and next steps.

> **[CCS Report](/en/products/reporter/ccs-reports)**
>
> Review the applicable source contract before use.

> [!WARNING]
>
> Do not treat a Reporter template as regulatory evidence. Validate the generated file with the responsible compliance team and the authoritative validator before operational use.


# Reporter core concepts
Source: https://docs.lerian.studio/en/products/reporter/reporter-core-concepts

The Reporter model in one place: templates, data sources, reports, deadlines, institutions, regulatory filings, the report states, and the tenant boundary that separates them.

Reporter has a small model. You upload a **template** that describes a document. An operator configures the **data sources** Reporter may read. You request a **report** against a template, and Reporter renders an artifact you download. A **deadline** tracks when a report is due and whether someone delivered it.

This page defines each noun and the rules that connect them.

## The model at a glance

***

| Concept | Definition |
| - | - |
| Template | A plain-text document definition, uploaded as a file, that declares one output format. |
| Data source | A persisted, read-only database connection that an operator manages through the API or seeds at startup. |
| Report | One rendering of one template, under the filters you asked for. |
| Artifact | The file a finished report produces, held in object storage. |
| Filter | A per-field condition that narrows the rows a report reads. |
| Deadline | A due date and a recurrence rule, optionally bound to a template. |
| Institution | One regulated entity with one CNPJ, and the rows of each data source that belong to it. |
| Regulatory filing | A report of a curated regulatory document that a person corrects and approves. |
| Tenant | The isolation boundary. Every operation resolves exactly one. |

## Templates

***

A template is a plain-text `.tpl` file that you upload as `multipart/form-data`, together with the output format it produces, a short description, and its category. The category is the report family that a consumer routes by. Reporter keeps the file in object storage and its metadata in MongoDB. The template language is Pongo2, so a template mixes literal document text with variables, loops, conditionals, filters, and aggregation tags.

One template declares one output format: `PDF`, `HTML`, `XML`, `TXT`, or `CSV`. PDF renders as HTML first and then converts through a headless-browser worker pool.

A template addresses data by `configName`, the stable name of a data source, and by table: `{{ midaz_onboarding.accounts }}`. When more than one schema is in play, qualify it as `{{ midaz_onboarding:public.accounts }}`.

At upload, Reporter reads the template text and derives the fields it touches, per data source and per table. It then checks every referenced table and field against the live schema of that data source. A data source that is unreachable produces a warning rather than a rejection, so a template still uploads while a database is down.

Read [Template reference](/en/products/reporter/template-reference) for the tags, filters, and expressions the language offers.

## Data sources

***

A data source is a PostgreSQL or MongoDB connection stored in Reporter's registry. The API creates and manages registry entries. A self-hosted deployment can also seed them from `DATASOURCE_*` variables at startup. Data extraction remains read-only by construction: Reporter issues `SELECT` statements and MongoDB finds, and it has no write path into the source database.

Each entry has two identifiers. The `dataSourceId` is the UUID that registry operations use. The `configName` is the stable name that templates and filters use, so keep it stable while hosts and credentials change. Reporter encrypts passwords at rest with `DATASOURCE_CRED_ENC_KEY` and never returns them.

The registry exposes seven operations: list, create, get, partially update, soft-delete, inspect the live schema, and test the connection. Reporter refuses deletion while a live template still references the source.

Read [Connecting Reporter to Midaz](/en/products/reporter/connecting-reporter-to-midaz) for a worked configuration.

## Reports

***

A report request names a template and the filters that narrow the data behind it. Send an empty `filters` object when you need none. Filters nest three levels (data source, then table, then field):

```json theme={null}
{
  "templateId": "0198c0f6-6d4d-7a34-a9ba-2c2b3ad2f1a0",
  "filters": {
    "midaz_onboarding": {
      "accounts": {
        "status": { "in": ["ACTIVE"] },
        "type": { "nin": ["internal"] }
      }
    }
  }
}
```

Eight operators exist: `eq`, `gt`, `gte`, `lt`, `lte`, `between`, `in`, and `nin`.

A report keeps its own copy of the output format and description that the template carried at creation time. That snapshot keeps an artifact downloadable in its original shape after the template moves on.

Reports are create-and-retain. Four operations exist: create one, get it by identifier, list them, and download the artifact of a finished one. A report and its artifact remain in place once created. Retention is a lifecycle policy on the object-storage bucket, set by whoever operates the deployment.

### Report states

Creation is synchronous only until the work reaches the queue. The `POST` operation answers `201 Created` with a report already in `Processing`, and a worker takes it from there.

| State | Meaning |
| - | - |
| `Processing` | Accepted and queued. The worker has not finished. |
| `Finished` | Every data section succeeded and the artifact is stored. |
| `Partial` | Some data sections failed. The report records which ones, by section, so you can fix those data sources and generate the report again. |
| `Error` | Every attempted section failed, the request never reached the worker, or the worker stopped sending heartbeats. |
| `Draft` | A regulatory filing is generated and waits for review. |
| `Final` | A person approved the regulatory draft. |

`Processing` is the only entry state, and nothing returns to it once the worker settles the report. A queue can deliver the same command twice, so the worker reads the report before it starts a run. The worker skips a report that already reached a terminal status, and does not generate it again.

The download operation serves the artifact of a `Finished` or `Final` report, and of a `Draft` with no required field blank. Poll `GET /v1/reports/{id}` until the state settles, or subscribe to the terminal events Reporter emits and skip the polling.

## Deadlines

***

A deadline models an obligation: a due date, a recurrence rule, and optionally the template that satisfies it. Its `type` is `regulatory` or `custom`. Its `frequency` is `once`, `daily`, `weekly`, `monthly`, `semiannual`, or `annual`, and the semiannual and annual rules also carry the months they fall in.

Reporter derives status and never stores it. A deadline is `delivered` once someone marks it so, `overdue` once its due date passes undelivered, and `pending` otherwise. A recurring deadline rolls forward on the first read after its due date passes. It rolls forward only when it carries the delivery mark. That roll-forward clears the delivery mark, so the record returns to `pending` for the next occurrence and one record carries the whole series.

Notification is pull-based. A single operation returns the deadlines inside their alert window, ranked overdue first, then warning, then informational. Reporter sends no mail and calls no endpoint of yours.

Read [Managing deadlines](/en/products/reporter/managing-deadlines) for the full lifecycle.

## Institutions and regulatory filings

***

An institution is one regulated entity of a tenant, identified by its CNPJ. Its scope names the rows that belong to it in each data source. A report reads for one institution, or for `all`.

A regulatory filing starts from a curated document that the deployment carries. The tenant subscribes to the document and maps its fields to tables in a YAML mapping. Each generation produces a `Draft`. A person corrects the draft field by field, and a person with the approval permission turns it `Final`. The filing keeps a provenance record of the document version, the mapping, the parameters, and the SHA-256 of the file. See [Reporter REST API](/en/products/reporter/reporter-rest-api#regulatory-filing) for the operations.

## Tenants

***

The tenant is the isolation boundary in Reporter. Reporter resolves it from the authenticated request itself. The bearer token that authorizes the call carries the tenant in its `tenantId` claim. No API operation takes a tenant from a request header, and no client-supplied value can widen the scope of a call.

Isolation runs the whole depth of the stack. Each tenant gets its own metadata database, its own message-broker virtual host, its own connection pools, and its own event outbox. Resolution is fail-closed. Reporter rejects a request when it cannot resolve the tenant, and nothing falls back to a shared pool.

A self-hosted deployment needs no tenant configuration at all.

## Next steps

***

> **[Architecture](/en/products/reporter/reporter-architecture)**
>
> One binary, two surfaces, and the queue between them.

> **[Quick start](/en/products/reporter/reporter-quick-start)**
>
> Upload a template and generate your first report.

> **[Template reference](/en/products/reporter/template-reference)**
>
> The tags, filters, and expressions available to a template.

> **[Managing deadlines](/en/products/reporter/managing-deadlines)**
>
> Create, track, and deliver a reporting obligation.


# Reporter deployment
Source: https://docs.lerian.studio/en/products/reporter/reporter-deployment

Deploy Reporter: one binary with a run-mode selector, MongoDB, the report command queue, S3-compatible object storage, Redis or Valkey, worker sizing, and report retention through a bucket lifecycle policy.

Reporter ships as a single binary with two surfaces, and `RUN_MODE` selects which surfaces a process serves. The same image runs as the API, as the report worker, or as both. Four dependencies sit behind them.

Reporter reads your databases through an extraction engine that runs inside the worker process. There is no separate extraction service to deploy.

## What you deploy

***

| Component | Role | Scale on |
| - | - | - |
| **API surface** | REST API for templates, reports, deadlines, data sources, institutions, and regulatory filing. Publishes report commands. | Request rate. |
| **Report worker** | Queue consumer. Extracts the data, renders the report, and writes the artifact. | Queue depth. |
| **MongoDB** | Templates, reports, deadlines, and the durable event outbox. | Metadata volume. |
| **RabbitMQ** | The report command queue, and the business event exchange. | Report rate. |
| **Object storage** | Template sources and rendered reports. S3-compatible. | Artifact volume and retention. |
| **Redis or Valkey** | Idempotency locks, schema cache, and tenant lifecycle. | Both surfaces. |

## Run modes

***

`RUN_MODE=api` serves every REST operation, plus `/health`, `/readyz`, and `/version`, on the address in `SERVER_ADDRESS`. `RUN_MODE=worker` consumes the report command queue and serves `/health` and `/readyz` on `HEALTH_PORT`. `RUN_MODE=all` runs both surfaces in one process.

Use `all` for local development. In production, deploy the two surfaces separately, so report generation scales on its own.

```bash theme={null}
# API deployment
RUN_MODE=api
SERVER_ADDRESS=:4005

# Worker deployment
RUN_MODE=worker
HEALTH_PORT=4006
```

## MongoDB

***

Both surfaces use the same MongoDB deployment. The API surface writes templates, reports, and deadlines. The worker updates a report as it completes.

`MONGO_HOST` and `MONGO_NAME` are required at startup when `MULTI_TENANT_ENABLED` is `false`, the default.

## RabbitMQ

***

Two separate concerns share one broker.

### The report command queue

This queue carries work from the API surface to the worker. `RABBITMQ_EXCHANGE`, `RABBITMQ_GENERATE_REPORT_QUEUE`, and `RABBITMQ_GENERATE_REPORT_KEY` name the exchange, the queue, and the routing key. The API surface publishes, so it needs all three plus its broker connection: `RABBITMQ_HOST`, `RABBITMQ_PORT_AMQP`, `RABBITMQ_DEFAULT_USER`, and `RABBITMQ_DEFAULT_PASS`. The worker consumes from the queue and needs that same connection plus `RABBITMQ_GENERATE_REPORT_QUEUE`. The broker objects must exist before either service starts.

The channel is internal to Reporter. To learn that a report finished, subscribe to the business events below, or poll the report.

A worker that fails a message retries it up to five times with backoff, and then rejects it without requeue. Bind a dead-letter exchange to the command queue, so a rejected report lands somewhere you can inspect.

### The events exchange

Business events (`template.*`, `report.*`, `deadline.*`, `regulatory.*`) go to an exchange you name in `RABBITMQ_REPORT_EVENTS_EXCHANGE`. The value is operator-configured. The reference value is `reporter.events`.

Set that exchange, `STREAMING_BROKERS`, and `STREAMING_CLOUDEVENTS_SOURCE` whenever `STREAMING_ENABLED=true`. With streaming off, both surfaces start normally and publish nothing.

## Object storage

***

Reporter uses one S3-compatible bucket, named in `OBJECT_STORAGE_BUCKET`. It holds two kinds of object, each under its own prefix:

* the template source, as `templates/<templateId>.tpl`
* the rendered report, as `reports/<templateId>/<reportId>.<format>`

AWS S3, MinIO, and SeaweedFS all work. Reach SeaweedFS through its S3 gateway. `OBJECT_STORAGE_USE_PATH_STYLE=true` is what MinIO and SeaweedFS expect, and `OBJECT_STORAGE_DISABLE_SSL` stays `false` outside local development.

### Report retention

Reporter keeps report files and regulatory filings forever. It has no delete endpoint and no retention setting, so the bucket grows with your report volume. The only way a file expires is an object-storage lifecycle rule that you configure. **Such a rule also deletes approved regulatory filings, which are the institution's regulatory record.** The saved rows that a regulatory correction re-renders the draft from are also stored under `reports/`, so an expiry rule can make an older draft impossible to correct.

> [!WARNING]
>
> Keep `templates/` out of scope: a rule that covers the whole bucket also removes the templates your reports are rendered from.

## Redis or Valkey

***

`REDIS_HOST` is required on the API surface. Redis backs the idempotency lock on report creation and the datasource schema cache.

Idempotency state lives in Redis, not in process memory, so API replicas share it.

## Data sources

***

Reporter reads reporting data from PostgreSQL and MongoDB data sources in its persisted registry. Create and manage them through the [data-source API](/en/reference/products/reporter/list-data-sources).

An optional `DATASOURCE_{NAME}_*` block seeds a user-managed registry entry at Manager startup. It seeds the entry only when that `configName` is absent. Later API edits and deletions take precedence over the environment.

Both Manager and worker require the same persistent `DATASOURCE_CRED_ENC_KEY` to protect the registry credentials. Keep it unchanged across restarts and deployments so they can continue decrypting stored credentials. Reporter also starts with none configured, and serves templates, deadlines, and metrics.

## Sizing the worker

***

`RABBITMQ_NUMBERS_OF_WORKERS` sets how many report jobs one worker process runs in parallel. For horizontal scale, add worker replicas and drive them from the depth of the command queue.

PDF output renders through a headless-browser pool: `PDF_POOL_WORKERS` concurrent renders, which defaults to 2, each bounded by `PDF_TIMEOUT_SECONDS`, which defaults to 90. Size worker memory against that pool, not only against the rows a report reads. The other output formats do not use it.

Every report also carries extraction limits. They are 10 data sources, 20 tables per data source, and 50 fields per table. They also cover 4 data sources read at a time, a 300-second deadline, and a 256 MiB cap on extracted data. The `ENGINE_*` variables change them. Each table also returns at most 150,000 rows and each query times out after 300 seconds, unless the data source sets its own values.

## Deployment mode and TLS

***

`DEPLOYMENT_MODE` declares the flavor of the deployment: `local`, `byoc`, or `saas`. It tags the `/readyz` response, and in `saas` it enforces TLS.

> [!WARNING]
>
> **SaaS mode requires TLS on every dependency.** Set `DEPLOYMENT_MODE=saas` and a plaintext MongoDB, RabbitMQ, Redis, or object storage URL stops the process. It stops before any connection opens.

Leave `ALLOW_INSECURE_TLS` unset in production. It bypasses those checks, and the local development stack is the only place for it.

## Startup checks

***

Reporter validates its configuration before it serves anything. Each check below stops the process, and the error names every variable at fault.

| Trigger | What the operator sees |
| - | - |
| `SERVER_ADDRESS`, `REDIS_HOST`, any required RabbitMQ connection or command-queue variable, or `DATASOURCE_CRED_ENC_KEY` missing on the API surface | Config validation fails and lists each missing variable. |
| Any of `RABBITMQ_HOST`, `RABBITMQ_PORT_AMQP`, `RABBITMQ_DEFAULT_USER`, `RABBITMQ_DEFAULT_PASS`, `RABBITMQ_GENERATE_REPORT_QUEUE`, or `DATASOURCE_CRED_ENC_KEY` missing on the worker surface | Config validation fails and lists each missing variable. |
| `MONGO_HOST` or `MONGO_NAME` missing while `MULTI_TENANT_ENABLED` is `false` | Config validation names them. |
| `STREAMING_ENABLED=true` without `RABBITMQ_REPORT_EVENTS_EXCHANGE`, `STREAMING_BROKERS`, and `STREAMING_CLOUDEVENTS_SOURCE` (all three are required for a streaming-enabled start) | Startup aborts rather than run with events that go nowhere. |
| `DEPLOYMENT_MODE=saas` with a plaintext dependency URL | Startup aborts before any connection opens. |
| `WORKER_HEARTBEAT_STALE_SEC` below three times `WORKER_HEARTBEAT_INTERVAL_SEC`, an unknown `REPORT_TIMEZONE`, or a `REGULATORY_CATALOG_DIR` whose catalog does not load | Startup aborts. |

> [!NOTE]
>
> **A dependency that is down at boot does not produce a silently broken pod.** `/health` answers 503 until the startup self-probe succeeds. The kubelet then restarts the pod instead of sending it traffic.

## Rolling updates

***

On `SIGTERM`, both surfaces enter a drain. The `/readyz` probe answers 503 from the moment the signal arrives, before the servers begin shutdown. In-flight requests and in-flight messages finish. Kubernetes removes the pod from Service endpoints while it still works.

Set the termination grace period above your longest report render. See the [health and readiness reference](/en/reference/health-and-readiness) for what the probes report during a drain.

## Next steps

***

> **[Environment variables](/en/products/reporter/reporter-environment-variables)**
>
> Every Reporter variable, by category.

> **[BYOC configuration](/en/reference/byoc-configuration)**
>
> The configuration blocks every Lerian product shares.

> **[Health and readiness](/en/reference/health-and-readiness)**
>
> The probe contract and what each response means.

> **[Connect Reporter to Midaz](/en/products/reporter/connecting-reporter-to-midaz)**
>
> Point Reporter at a Midaz database and render your first report.


# Environment variables
Source: https://docs.lerian.studio/en/products/reporter/reporter-environment-variables

Reference the environment variables used to configure Reporter, organized by category: HTTP server, database, storage, authentication, and telemetry.

This reference lists the environment variables used to configure **Reporter**, the service that generates regulatory, compliance, and accounting reports from configurable templates. Reporter ships as a single binary, and `RUN_MODE` selects its active surfaces: the API manager, the report worker, or both. You set these at deploy time, through Helm values, Docker Compose, or your orchestrator's environment. Variables marked as required cause the server to fail on startup if not set.

For the configuration blocks that every Lerian product shares (TLS posture, OpenTelemetry, Access Manager authentication, service discovery, and event streaming), see the [BYOC configuration reference](/en/reference/byoc-configuration). This page focuses on what is distinctive to Reporter.

## Run mode and ports

`RUN_MODE` decides which surfaces the process serves. Run the API and worker as one process (`all`) for small deployments, or split them into separate deployables (`api` and `worker`) to scale report generation independently. See the [health and readiness reference](/en/reference/health-and-readiness) for the probe contract.

| Variable | Description | Default | Required |
| - | - | - | - |
| `RUN_MODE` | Surfaces to run: `api`, `worker`, or `all` | `all` | No |
| `SERVER_PORT` / `SERVER_ADDRESS` | API bind address (`RUN_MODE=api`/`all`), read from `SERVER_ADDRESS`; `SERVER_PORT` is the convention used to build it (`:4005`). Serves `/health`, `/readyz`, `/version`. | — | Yes (`api`/`all`) |
| `HEALTH_PORT` | Worker health port (`RUN_MODE=worker`). Serves `/health`, `/readyz`. | `4006` | No |

## Deployment and TLS

| Variable | Description | Default | Required |
| - | - | - | - |
| `DEPLOYMENT_MODE` | Deployment flavor: `local`, `byoc`, or `saas`. In `saas`, TLS is mandatory for every dependency connection and the server refuses to start without it. In `byoc`, TLS is recommended and warned-on rather than enforced. Also tags the `/readyz` response. | `local` | No |
| `ALLOW_INSECURE_TLS` | Bypass per-connection TLS enforcement on infrastructure DSNs. Leave unset or `false` in production. | `false` | No |
| `ENV_NAME` | Environment name. With `production`, the Manager requires telemetry, Access Manager authentication, explicit HTTPS CORS origins, and real passwords at startup. It also requires TLS to Redis, RabbitMQ, and object storage unless `ALLOW_INSECURE_TLS` is `true`. With `local`, Reporter reads a `.env` file. | `local` | No |

## CORS and proxies

| Variable | Description | Default | Required |
| - | - | - | - |
| `CORS_ALLOWED_ORIGINS` | Allowed CORS origins (CSV, or `*`). Lock to explicit origins in production. | `*` | No |
| `CORS_ALLOWED_METHODS` | Allowed CORS methods | varies | No |
| `CORS_ALLOWED_HEADERS` | Allowed CORS headers | varies | No |
| `TRUSTED_PROXIES` | Trusted proxy CIDRs for `X-Forwarded-For` parsing. Set when running behind a load balancer. | — | No |
| `SWAGGER_ENABLED` | Serve the OpenAPI/Swagger UI | `false` | No |

## API pagination

| Variable | Description | Default | Required |
| - | - | - | - |
| `MAX_PAGINATION_LIMIT` | Largest `limit` a list operation accepts. A request above the ceiling is rejected with a pagination error rather than clamped. | `100` | No |

## Template uploads

| Variable | Description | Default | Required |
| - | - | - | - |
| `MAX_TEMPLATE_FILE_BYTES` | Largest template file, in bytes, that an upload accepts. A larger file is rejected with `RPT-0078`. The server refuses any request body over 4 MiB, whatever this value. | `1048576` (1 MiB) | No |

## Template previews

| Variable | Description | Default | Required |
| - | - | - | - |
| `PREVIEW_MAX_CONCURRENT` | Maximum synchronous template previews the API manager renders at once. When all slots are in use, Reporter rejects a new preview immediately with HTTP `429` and `RPT-0108`; it does not queue it. The value caps concurrent renders and does not cap the request rate. Values below `1` use the default. | `4` | No |

## Report calendar

| Variable | Description | Default | Required |
| - | - | - | - |
| `REPORT_TIMEZONE` | IANA time zone that measures the start and end of every day in report date filters. Set the zone your books close in, such as `America/Sao_Paulo`. Manager and worker must carry the same value. An unknown name stops the startup. The value applies to every tenant of the deployment. | `UTC` | No |

## Database (MongoDB)

Stores report metadata, templates, and run history.

| Variable | Description | Default | Required |
| - | - | - | - |
| `MONGO_URI` | Connection scheme: `mongodb` or `mongodb+srv` | — | Yes |
| `MONGO_HOST` | MongoDB host | — | Yes (`MULTI_TENANT_ENABLED=false`) |
| `MONGO_PORT` | MongoDB port | — | Yes |
| `MONGO_USER` | Database user | — | Yes |
| `MONGO_PASSWORD` | Database password. Sensitive. | — | Yes |
| `MONGO_NAME` | Database name | — | Yes (`MULTI_TENANT_ENABLED=false`) |
| `MONGO_PARAMETERS` | Extra MongoDB URI options, such as `authSource=admin` | — | No |
| `MONGO_MAX_POOL_SIZE` | Maximum connection pool size | `100` | No |
| `MONGO_TLS_CA_CERT` | Base64-encoded PEM CA certificate for TLS (for example AWS DocumentDB) | — | No |

## Message broker (RabbitMQ)

Carries the generate-report command queue between the API and the worker.

| Variable | Description | Default | Required |
| - | - | - | - |
| `RABBITMQ_HOST` | Broker host | — | Yes |
| `RABBITMQ_PORT_AMQP` | AMQP port | — | Yes |
| `RABBITMQ_PORT_HOST` | Management/HTTP port | — | No |
| `RABBITMQ_URI` | Connection scheme: `amqp` or `amqps`. Use `amqps` in production. | — | Yes |
| `RABBITMQ_DEFAULT_USER` | Broker user | — | Yes |
| `RABBITMQ_DEFAULT_PASS` | Broker password. Sensitive. | — | Yes |
| `RABBITMQ_EXCHANGE` | Exchange where the API publishes report-generation commands | — | Yes (`api`/`all`) |
| `RABBITMQ_GENERATE_REPORT_QUEUE` | Queue that carries report-generation commands from the API to the worker | — | Yes (`api`/`worker`/`all`) |
| `RABBITMQ_GENERATE_REPORT_KEY` | Routing key the API uses for report-generation commands | — | Yes (`api`/`all`) |
| `RABBITMQ_NUMBERS_OF_WORKERS` | Worker consumer concurrency | `5` | No |

## Object storage (S3-compatible)

Where rendered reports are stored. Works with any S3-compatible endpoint.

| Variable | Description | Default | Required |
| - | - | - | - |
| `OBJECT_STORAGE_ENDPOINT` | S3-compatible endpoint URL. Leave empty for AWS S3. | — | No |
| `OBJECT_STORAGE_REGION` | Storage region | `us-east-1` | No |
| `OBJECT_STORAGE_BUCKET` | Bucket for rendered reports | `reporter-storage` | No |
| `OBJECT_STORAGE_ACCESS_KEY_ID` | Access key ID. Leave it and the secret key empty to use the AWS default credential chain. Sensitive. | — | No |
| `OBJECT_STORAGE_SECRET_KEY` | Secret access key. Sensitive. | — | No |
| `OBJECT_STORAGE_USE_PATH_STYLE` | Use path-style addressing (needed by some S3-compatible stores) | `false` | No |
| `OBJECT_STORAGE_DISABLE_SSL` | Disable TLS to the storage endpoint. Leave `false` in production. | `false` | No |

## Cache (Redis / Valkey)

| Variable | Description | Default | Required |
| - | - | - | - |
| `REDIS_HOST` | Redis/Valkey host and port | — | Yes |
| `REDIS_PASSWORD` | Authentication password. Sensitive. | — | No |
| `REDIS_DB` | Logical database index | `0` | No |
| `REDIS_PROTOCOL` | RESP protocol version | `3` | No |
| `REDIS_TLS` | Enable TLS for the connection | `false` | No |
| `REDIS_CA_CERT` | Base64-encoded PEM CA certificate for TLS | — | No |
| `REDIS_MASTER_NAME` | Sentinel master name (Sentinel deployments) | — | No |
| `REDIS_USE_GCP_IAM` | Authenticate to GCP Memorystore with IAM instead of a password | `false` | No |

## PDF rendering (worker)

| Variable | Description | Default | Required |
| - | - | - | - |
| `PDF_POOL_WORKERS` | Concurrent PDF render workers | `2` | No |
| `PDF_TIMEOUT_SECONDS` | Per-report PDF render timeout (seconds) | `90` | No |
| `PDF_PAPER_SIZE` | Page size: `A4` or `Letter` | `A4` | No |
| `PDF_DISPLAY_HEADER_FOOTER` | Print a header and a footer on each PDF page | `true` | No |

## Extraction limits (worker)

| Variable | Description | Default | Required |
| - | - | - | - |
| `ENGINE_MAX_DATASOURCES` | Data sources one report can read | `10` | No |
| `ENGINE_MAX_TABLES_PER_DATASOURCE` | Tables or collections per data source | `20` | No |
| `ENGINE_MAX_FIELDS_PER_TABLE` | Fields per table | `50` | No |
| `ENGINE_MAX_CONCURRENCY` | Data sources extracted in parallel | `4` | No |
| `ENGINE_TIMEOUT_SEC` | Timeout of one extraction (seconds) | `300` | No |
| `ENGINE_MAX_RESULT_BYTES` | Largest extraction result. A larger result fails the extraction. | 256 MiB | No |
| `DATASOURCE_DEFAULT_ROW_CEILING` | Rows one table can return, for a data source without its own ceiling. A table that exceeds it fails with `RPT-0161`. | `150000` | No |
| `DATASOURCE_DEFAULT_QUERY_TIMEOUT_SEC` | Timeout of one query (seconds), for a data source without its own value. A query that exceeds it fails with `RPT-0162`. | `300` | No |
| `ENGINE_MAX_DYNAMIC_POOLS` | Data-source connection pools the worker keeps open, across every tenant | `500` | No |
| `ENGINE_POOL_IDLE_TIMEOUT_SEC` | Idle time before a data-source pool closes (seconds) | `7200` | No |

## Stale-report reaper

A worker stamps a heartbeat on each report it generates. The Manager moves a `Processing` report whose heartbeat is stale to `Error` with `RPT-0160`. Manager and worker must carry the same heartbeat values.

| Variable | Description | Default | Required |
| - | - | - | - |
| `REPORT_REAPER_ENABLED` | Run the reaper on the Manager | `true` | No |
| `REPORT_REAPER_INTERVAL_SEC` | Seconds between reaper passes | `60` | No |
| `REPORT_REAPER_BATCH` | Reports one tenant pass ends | `200` | No |
| `WORKER_HEARTBEAT_INTERVAL_SEC` | Seconds between worker heartbeats | `30` | No |
| `WORKER_HEARTBEAT_STALE_SEC` | Age after which a heartbeat is stale (seconds) | `180` | No |

## Deadline trigger (Manager)

| Variable | Description | Default | Required |
| - | - | - | - |
| `DEADLINE_TRIGGER_ENABLED` | Run the sweep that publishes `deadline.due` when a deadline's day arrives | `false` | No |
| `DEADLINE_TRIGGER_INTERVAL_SEC` | Seconds between sweeps | `300` | No |
| `DEADLINE_TRIGGER_GENERATE_CATEGORIES` | Comma-separated template categories for which the sweep also generates the report. Empty generates none. | — | No |
| `DEADLINE_TRIGGER_GENERATION_TIMEOUT_SEC` | Timeout of one scheduled generation (seconds) | `20` | No |
| `DEADLINE_TRIGGER_MAX_CATCH_UP_OCCURRENCES` | Missed occurrences of one deadline that one sweep generates | `7` | No |

## Regulatory catalog

Without a catalog source, the deployment carries no regulatory documents.

| Variable | Description | Default | Required |
| - | - | - | - |
| `REGULATORY_CATALOG_DIR` | Directory where the curated catalog is mounted. Reporter reads it at startup, and a catalog that does not load stops the startup. | — | No |
| `REGULATORY_CATALOG_GITHUB_REPO` | `owner/repo` that publishes the catalog releases. When set, subscriptions fetch from it instead of the directory. | — | No |
| `REGULATORY_CATALOG_GITHUB_TOKEN` | Token for a private catalog repository. Sensitive. | — | No |
| `REGULATORY_CATALOG_GITHUB_URL` | Alternative API root, such as a proxy | — | No |

## Report datasources

Reports read from PostgreSQL and MongoDB datasources in the persisted registry. Create and manage ordinary entries through the [data-source API](/en/reference/products/reporter/list-data-sources). The environment block below is an optional bootstrap path.

`DATASOURCE_{NAME}_CONFIG_NAME` makes an environment seed block exist. Reporter scans for keys that match `DATASOURCE_*_CONFIG_NAME`. The prefix counts as much as the suffix, so a key that only ends in `_CONFIG_NAME` declares nothing. At Manager startup, a complete block seeds its `configName` only when no registry entry, including a soft-deleted one, already uses that name. The value is the name your templates use to address the source.

Within a block, the variables marked required are the ones Reporter needs before it reads the block.

| Variable | Description | Default | Required |
| - | - | - | - |
| `DATASOURCE_{NAME}_CONFIG_NAME` | Name that templates use to address this datasource. Declares the block. | — | Yes |
| `DATASOURCE_{NAME}_TYPE` | Datasource engine: `postgresql` or `mongodb` | — | Yes |
| `DATASOURCE_{NAME}_HOST` | Datasource host | — | Yes |
| `DATASOURCE_{NAME}_PORT` | Datasource port | — | Yes |
| `DATASOURCE_{NAME}_DATABASE` | Database name | — | Yes |
| `DATASOURCE_{NAME}_USER` | Datasource user | — | No |
| `DATASOURCE_{NAME}_PASSWORD` | Datasource password. Sensitive. | — | No |
| `DATASOURCE_CRED_ENC_KEY` | Persistent hex-encoded AES key shared by Manager and worker to encrypt and decrypt registry credentials. Keep it unchanged across restarts and deployments; changing it prevents them from decrypting credentials already stored in the registry. Generate it with `openssl rand -hex 32`. | — | Yes |
| `DATASOURCE_{CONFIG_NAME}_SCHEMAS` | Schemas to expose from the datasource (CSV). This key uses the uppercased `CONFIG_NAME` value, unlike the other keys in the block. | `public` | No |
| `DATASOURCE_{NAME}_SSLMODE` | SSL mode for a PostgreSQL connection | — | No |
| `DATASOURCE_{NAME}_SSLROOTCERT` | Path to the PostgreSQL SSL root certificate | — | No |
| `DATASOURCE_{NAME}_SSL` | Enable TLS on a MongoDB connection | — | No |
| `DATASOURCE_{NAME}_SSLCA` | Path to the MongoDB CA certificate file | — | No |
| `DATASOURCE_{NAME}_SSLCA_BASE64` | Standard Base64 of a PEM CA bundle, on one line. An alternative to the certificate file path. For PostgreSQL, set `SSLMODE` to `verify-ca` or `verify-full`, or leave it empty for `verify-full`. | — | No |
| `DATASOURCE_{NAME}_OPTIONS` | Extra MongoDB URI options | — | No |
| `DATASOURCE_{NAME}_ROW_CEILING` | Rows one table of this data source can return | `DATASOURCE_DEFAULT_ROW_CEILING` | No |
| `DATASOURCE_{NAME}_QUERY_TIMEOUT_SEC` | Timeout of one query on this data source (seconds) | `DATASOURCE_DEFAULT_QUERY_TIMEOUT_SEC` | No |
| `DATASOURCE_CRM_MIDAZ_ORGANIZATION_ID` | Midaz organization ID that scopes the reserved CRM datasource. Required when `DATASOURCE_CRM_CONFIG_NAME=plugin_crm`. | — | No |
| `CRYPTO_HASH_SECRET_KEY_CRM` | Existing CRM hashing key used to read CRM datasource PII. Sensitive; required when CRM fields are read. | — | No |
| `CRYPTO_ENCRYPT_SECRET_KEY_CRM` | Existing CRM encryption key used to read CRM datasource PII. Sensitive; required when CRM fields are read. | — | No |

A complete per-datasource seed block follows. Set the global `DATASOURCE_CRED_ENC_KEY` separately as described above. We recommend using the same name for `CONFIG_NAME` and `{NAME}`, with the environment-variable segment uppercased (for example, `ONBOARDING` for `CONFIG_NAME=onboarding`). That keeps the schema key intuitive, because `SCHEMAS` uses the `CONFIG_NAME` value as its key while every other field uses `{NAME}`:

```bash theme={null}
DATASOURCE_ONBOARDING_CONFIG_NAME=onboarding
DATASOURCE_ONBOARDING_TYPE=postgresql
DATASOURCE_ONBOARDING_HOST=midaz-postgres-replica
DATASOURCE_ONBOARDING_PORT=5702
DATASOURCE_ONBOARDING_DATABASE=onboarding
DATASOURCE_ONBOARDING_USER=reporter
DATASOURCE_ONBOARDING_PASSWORD=<secret>
DATASOURCE_ONBOARDING_SCHEMAS=public
```

A template then addresses that source by its config name, as in `{{ onboarding.accounts }}`. Use the API to add or update an ordinary datasource. An environment block only seeds a previously absent entry. It never overwrites an API-managed entry or restores a soft-deleted one.

### Reserved CRM datasource

`plugin_crm` is the reserved, environment-managed CRM datasource. Do not create it or PATCH it through the ordinary data-source API: Reporter rejects that path with `RPT-0073`. A CRM template must use the exact config name `plugin_crm` and a complete MongoDB block:

```bash theme={null}
DATASOURCE_CRM_CONFIG_NAME=plugin_crm
DATASOURCE_CRM_TYPE=mongodb
DATASOURCE_CRM_HOST=<crm-mongodb-host>
DATASOURCE_CRM_PORT=<crm-mongodb-port>
DATASOURCE_CRM_DATABASE=<crm-database>
DATASOURCE_CRM_USER=<crm-readonly-user>
DATASOURCE_CRM_PASSWORD=<secret>
DATASOURCE_CRM_MIDAZ_ORGANIZATION_ID=<midaz-organization-id>
```

Put `DATASOURCE_CRM_PASSWORD`, `CRYPTO_HASH_SECRET_KEY_CRM`, and `CRYPTO_ENCRYPT_SECRET_KEY_CRM` in your secret store. The CRM crypto values must be the same keys already used by CRM. Do not generate replacement keys for Reporter. Keep `DATASOURCE_CRED_ENC_KEY` stable as well: changing it prevents Reporter from decrypting stored datasource credentials.

Manager uses this block at startup to seed `plugin_crm` and to fill an absent or empty `metadata.midazOrganizationId`. A non-empty persisted organization ID wins and is not overwritten by the environment. If it is wrong, stop and use the supported engineering recovery path. Do not use the ordinary API to change it.

To set these variables with the Reporter chart, see the [Reporter chart README](https://github.com/LerianStudio/helm/tree/main/charts/reporter). For templates that use `plugin_crm`, validate the full path: import or save the template, generate a report, confirm CRM fields decrypt, and confirm its records are scoped to the intended Midaz organization.

## Configuration shared across products

The following blocks are identical across Lerian products. The [BYOC configuration reference](/en/reference/byoc-configuration) documents them in full. They default off.

* **Access Manager authentication**: `PLUGIN_AUTH_ENABLED`, `PLUGIN_AUTH_ADDRESS`. Enable in production.
* **Service discovery**: `SD_*` (Consul, and Reporter also accepts the legacy `SD_ADVERTISE_*` / `CONSUL_ADDR` aliases). Off by default.
* **Event streaming**: `STREAMING_ENABLED`, `STREAMING_BROKERS`, `STREAMING_CLOUDEVENTS_SOURCE`, plus `RABBITMQ_REPORT_EVENTS_EXCHANGE` for the events exchange and `STREAMING_KAFKA_BROKERS` for the optional Kafka copy of `report.finished` and `report.partial`. Off by default.
* **OpenTelemetry**: `ENABLE_TELEMETRY`, `OTEL_*`, `OTEL_INSECURE_EXPORTER`. Telemetry is OTLP push.


# Reporter events
Source: https://docs.lerian.studio/en/products/reporter/reporter-events

Subscribe to Reporter's report, deadline, and regulatory filing events: the streaming manifest operation, the CloudEvents envelope, delivery policies, and what each payload carries.

Reporter publishes a business event whenever a template, a report, a deadline, or a regulatory filing changes state. Subscribe to those events and you learn that a report finished without polling `GET /v1/reports/{id}` for it.

`GET /v1/streaming/events` describes the contract in machine-readable form. This page covers the consumer side: what the manifest tells you, what arrives on the wire, and what each event carries.

## The manifest operation

***

[Streaming events](/en/reference/products/reporter/get-streaming-events) returns the static event catalog. It requires authentication like every other operation. It answers `Cache-Control: no-store`, and it responds whether or not this deployment publishes events. Read it at startup to check that your consumer and Reporter agree on the contract.

The response exposes the application identity and catalog:

| Field | What it carries |
| - | - |
| `version` | Semantic version of the manifest wire format. |
| `publisher` | Who publishes: `serviceName` and `source` are `reporter`, `routePath` is this operation, and `outboxSupported` is `true`, plus the application and library versions. |
| `events` | One entry per event definition, with its key, `eventKey`, resource type, event type, `class`, schema version, description, and default delivery policy. Reporter emits only `fact` events. |
| `routes` | Omitted. Reporter does not publish broker topology through the API. |

## Broker routing

***

The manifest does not disclose a topic or broker topology. Bind your queue to the exchange named by `RABBITMQ_REPORT_EVENTS_EXCHANGE`. Each message uses the event definition key verbatim as its AMQP routing key: `report.finished`, `deadline.delivery_reverted`, underscores included.

When `STREAMING_KAFKA_BROKERS` is set, `report.finished` and `report.partial` also publish to the Kafka topic `lerian.streaming.reporter`, in addition to RabbitMQ.

## The event catalog

***

Seventeen event definitions exist across the two run modes.

| Event | Emitted when | Delivery profile |
| - | - | - |
| `template.created` | A template is uploaded. | Important |
| `template.updated` | A template's file or metadata changes. | Important |
| `template.deleted` | A template is removed, with the count of deadlines that cascaded. | Important |
| `report.requested` | A report created through `POST /v1/reports` or by the deadline trigger is stored as `Processing`, before Reporter queues its generation. | Important |
| `report.finished` | Every data section succeeded and the artifact is stored. | Critical |
| `report.partial` | Some sections failed. An artifact exists. | Critical |
| `report.errored` | The report ended in error. | Critical |
| `deadline.created` | A deadline is created. | Important |
| `deadline.updated` | A deadline changes. | Important |
| `deadline.deleted` | A deadline is removed. | Important |
| `deadline.delivered` | A deadline is marked delivered. | Critical |
| `deadline.delivery_reverted` | A delivery mark is cleared. | Critical |
| `deadline.due` | The deadline trigger announces an occurrence whose day arrived. | Critical |
| `deadline.generation_failed` | The trigger announced an occurrence, and Reporter refused the report it had to generate. | Critical |
| `regulatory.draft_ready` | A regulatory draft and its file are stored and ready for review. | Critical |
| `regulatory.filing_approved` | A person approved a regulatory draft, and it is `Final`. | Critical |
| `regulatory.version_adopted` | A subscription moved to another version of its regulatory document. | Critical |

This channel is publish-only. Reporter emits these events and consumes none of them.

## Delivery

***

Every manifest event has class `fact`. The delivery profile in the table above selects its delivery policy.

| Delivery profile | Direct publish | Outbox | Route DLQ |
| - | - | - | - |
| Important | Yes | Falls back to the outbox when the circuit opens | Not configured |
| Critical | No | Always | Not configured |

An event with the `Critical` delivery profile therefore never publishes straight to the broker. Reporter writes it to the durable Mongo streaming outbox after the business-state commit, and a dispatcher replays it after a broker outage.

The state write and outbox insert are separate operations, not one atomic application transaction. That gap is a failure window: a crash or a failed outbox insert after the state commit loses the event. No reconciliation recovers it. The loss leaves only an error log and a metric. Once the row is in the outbox, the dispatcher retries until delivery.

The policy requests dead-letter handling for routable failures, but the current RabbitMQ routes do not provide an explicit DLQ destination. Such a failure is surfaced and logged, with no forensic dead-letter copy.

Emission happens after the commit and never fails the work. A publication problem does not turn a stored report into an errored one.

> [!WARNING]
>
> Delivery is at-least-once. Deduplicate on `(ce-source, ce-id)`. Template events, `report.requested`, and deadline create, update, and delete events carry a generated identifier. The other events use deterministic identifiers.

## The CloudEvents envelope

***

Messages travel in CloudEvents binary mode, version 1.0. Context attributes ride as message headers.

| Header | Value |
| - | - |
| `ce-specversion` | `1.0` |
| `ce-id` | Opaque producer-defined id; deterministic only for the event classes described above |
| `ce-source` | `reporter` |
| `ce-type` | `studio.lerian.reporter.<resource>.<event>`, for example `studio.lerian.reporter.report.finished` |
| `ce-time` | RFC 3339 emission timestamp |
| `ce-subject` | The identifier of the resource that the event is about |
| `ce-resourcetype` | `report`, `template`, `deadline`, or `regulatory` |
| `ce-eventtype` | `finished`, `created`, `delivery_reverted`, and so on |
| `ce-schemaversion` | `2.0.0` on `report.finished`, `report.partial`, and `report.errored`. `1.0.0` on the other events. |
| `ce-tenantid` | The tenant that owns the change |

Reporter marks messages persistent and always stamps a tenant value.

## What a payload carries

***

Payload keys are `snake_case`, unlike the camelCase REST surface. A `report.finished` body:

```json theme={null}
{
  "report_id": "019826f4-6a9c-7b31-9d40-2f1e8c5a4b77",
  "template_id": "8f2c1a9e-4b30-4c02-9a1b-2d5e6f7a1c33",
  "output_format": "pdf",
  "status": "Finished",
  "artifact_object_key": "org-01abc/reports/8f2c1a9e-4b30-4c02-9a1b-2d5e6f7a1c33/019826f4-6a9c-7b31-9d40-2f1e8c5a4b77.pdf",
  "artifact_content_type": "application/pdf",
  "document_type": "cadoc",
  "completed_at": "2026-07-29T14:22:08Z",
  "duration_ms": 8421,
  "section_count": 3
}
```

`artifact_object_key` is the exact object key reported by storage after the write, not a path that consumers should reconstruct. Use the value verbatim.

If you validate its tenant segment, compare it with the tenant bound to your authenticated subscription, not with another field from the same message. An empty key on `report.finished` or `report.partial` is a contract violation. [Download a report](/en/reference/products/reporter/download-report) remains the supported way to fetch a report in the `Finished` state.

`report.partial` adds `section_failures` and `failed_section_count` alongside the same artifact fields. A resolvable key does not mean that the report is complete. Deliver a template report only from `report.finished`, and a regulatory filing only from `regulatory.filing_approved`. Strictly decode the `status` field instead of using key presence as the discriminator. `regulatory.filing_approved` names the approved file in `artifact_object_key` and carries `artifact_sha256`, `artifact_size_bytes`, `delivery_attempt`, and `approved_by`.

`document_type` carries the category of the template. `report.errored` replaces the artifact fields with `error_code` and `error_summary`, and adds `document_id` and `document_version`, which name the regulatory document when a subscription generated the report. Its lack of an artifact field does not prove that no object was written: storage can succeed before terminal status persistence fails, leaving an object that no event names. Both error fields come from a fixed vocabulary: `report_generation_failed`, `report_generation_timeout`, `report_generation_canceled`, or `report_worker_lost`. Each code has a fixed summary. Raw error text never travels on the wire, so a payload cannot leak a query, a connection string, or tenant data. Branch on `error_code`.

## Enabling event publication

***

Event publication is a deployment choice, set with `STREAMING_ENABLED`. Turn it on and Reporter requires three more settings at startup:

| Setting | Value |
| - | - |
| `RABBITMQ_REPORT_EVENTS_EXCHANGE` | The exchange that carries the events. Operator-configured; the reference value is `reporter.events`. |
| `STREAMING_BROKERS` | Must be present and non-empty. |
| `STREAMING_CLOUDEVENTS_SOURCE` | Must be exactly `reporter`; startup rejects any other value. |

When publication is off, `STREAMING_CLOUDEVENTS_SOURCE` may be unset. If it is set, it must still be exactly `reporter`. Reporter rejects another non-empty value at startup even while publication is off. When publication is on, Reporter also refuses to start if any of the three settings is blank, so a misconfigured deployment fails at startup instead of dropping events quietly.

## Next steps

***

> **[Reporter REST API](/en/products/reporter/reporter-rest-api)**
>
> The 56 operations, authentication, pagination, and errors.

> **[API Reference](/en/reference/introduction)**
>
> The streaming manifest operation, with its full response shape.

> **[Environment variables](/en/products/reporter/reporter-environment-variables)**
>
> Every setting behind the streaming, exchange, and run-mode surfaces.

> **[What is Reporter?](/en/products/reporter/what-is-reporter)**
>
> Templates, reports, deadlines, and where they fit.


# HTML template
Source: https://docs.lerian.studio/en/products/reporter/reporter-html-template

Build an analytical financial report in HTML with Reporter: organization details, per-account breakdowns, and detailed operations lists.

This example shows how to structure an **Analytical Financial Report** focused on account-level transaction analysis, in HTML format. The report includes:

* Organization and Ledger information.
* Per-account breakdown.
* Detailed operation list.

## Template code

***

```html HTML expandable theme={null}
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Analytical Financial Report</title>
  <style>
    body {
      font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
      background-color: #f4f6f9;
      color: #333;
      padding: 40px;
    }

    .container {
      max-width: 900px;
      margin: auto;
      background: #ffffff;
      padding: 30px 40px;
      border-radius: 8px;
      box-shadow: 0 0 10px rgba(0,0,0,0.1);
    }

    h1 {
      text-align: center;
      font-size: 24px;
      color: #004080;
      margin-bottom: 10px;
    }

    .subtitle {
      text-align: center;
      font-size: 14px;
      color: #777;
      margin-bottom: 30px;
    }

    .section-title {
      font-weight: bold;
      font-size: 16px;
      margin-top: 30px;
      margin-bottom: 10px;
      color: #004080;
      border-bottom: 1px solid #ccc;
      padding-bottom: 4px;
    }

    table {
      width: 100%;
      border-collapse: collapse;
      margin-top: 15px;
    }

    th, td {
      padding: 10px;
      text-align: left;
      border: 1px solid #ccc;
    }

    th {
      background-color: #e8f0fe;
      font-weight: bold;
      color: #003366;
    }

    .info p {
      margin: 4px 0;
    }

    .footer {
      margin-top: 40px;
      text-align: center;
      font-size: 12px;
      color: #999;
    }
  </style>
</head>
<body>
  <div class="container">
    <h1>Analytical Financial Report</h1>
    <div class="subtitle">Detailed analysis of movements by linked accounts.</div>

    <div class="info">
      <p><strong>Generation Date:</strong> {% date_time "dd/MM/YYYY HH:mm" %}</p>
      <p><strong>Organization:</strong> {{ midaz_onboarding.organization.0.legal_name }}</p>
      <p><strong>Ledger:</strong> {{ midaz_onboarding.ledger.0.name }}</p>
    </div>

    {% for account in midaz_onboarding.account %}
      {% with balance = filter(midaz_transaction.balance, "account_id", account.id)[0] %}
        <div class="section-title">Account: {{ account.alias }}</div>
        <div class="info">
          <p><strong>ID:</strong> {{ account.id }}</p>
          <p><strong>Currency:</strong> {{ balance.asset_code }}</p>
          <p><strong>Current Balance:</strong> {{ balance.available }}</p>
        </div>

        <table>
          <thead>
            <tr>
              <th>Operation ID</th>
              <th>Type</th>
              <th>Original Amount</th>
              <th>Discount (3%)</th>
              <th>Final Amount</th>
              <th>Description</th>
            </tr>
          </thead>
          <tbody>
            {% for operation in midaz_transaction.operation %}
              {% if operation.account_id == account.id %}
                {% set original_amount = operation.amount %}
                {% set discount_amount = original_amount * 0.03  %}
                {% set final_amount = original_amount - discount_amount %}
                <tr>
                  <td>{{ operation.id }}</td>
                  <td>{{ operation.type }}</td>
                  <td>{{ original_amount|decimal:2 }}</td>
                  <td>{{ discount_amount|decimal:2 }}</td>
                  <td>{{ final_amount|decimal:2 }}</td>
                  <td>{{ operation.description }}</td>
                </tr>
              {% endif %}
            {% endfor %}
          </tbody>
        </table>
      {% endwith %}
    {% endfor %}

    <div class="footer">
      Document generated automatically via Reporter - Lerian · {{ midaz_onboarding.organization.0.legal_document }}
    </div>
  </div>
</body>
</html>
```

## Code breakdown

***

### Organization and Ledger information

```html HTML theme={null}
    <div class="info">
      <p><strong>Generation Date:</strong> {% date_time "dd/MM/YYYY HH:mm" %}</p>
      <p><strong>Organization:</strong> {{ midaz_onboarding.organization.0.legal_name }}</p>
      <p><strong>Ledger:</strong> {{ midaz_onboarding.ledger.0.name }}</p>
    </div>
```

**`<p><strong>Generation Date:</strong> {% date_time "dd/MM/YYYY HH:mm" %}</p>`**

This function applies the date and time at render time, in the `dd/MM/YYYY HH:mm` format.

**`<p><strong>Organization:</strong> {{ midaz_onboarding.organization.0.legal_name }}</p>`**

This line renders the legal name of the first Organization associated with the onboarding data.

* `midaz_onboarding.organization`: the list of Organizations in the system.
* `0`: fetches the first item in the list.
* `legal_name`: fetches the value of the `legal_name` field.

**`<p><strong>Ledger:</strong> {{ midaz_onboarding.ledger.0.name }}</p>`**

This line renders the name of the first Ledger associated with the onboarding data.

* `midaz_onboarding.ledger`: the list of Ledgers in the system.
* `0`: fetches the first item in the list.
* `name`: fetches the value of the `name` field.

### Looping through accounts

```html HTML theme={null}
    {% for account in midaz_onboarding.account %}
      {% with balance = filter(midaz_transaction.balance, "account_id", account.id)[0] %}  
```

**`{% for account in midaz_onboarding.account %}`**

This loop goes through each account in the `midaz_onboarding.account` list.

* This list represents all accounts linked to a customer or associated with an onboarding flow.
* For each iteration, it creates a new scope where `account` refers to one specific item in that list.

**`{% with balance = filter(midaz_transaction.balance, "account_id", account.id)[0] %}`**

Inside the loop, this line:

* Uses the filter function to find a balance from the `midaz_transaction.balance` list where the `account_id` matches the current account's ID.
* The `[0]` takes the first matching balance (assuming there's only one per account).
* The result goes into a temporary variable called `balance`, scoped only within this block.

### Account information

```html HTML theme={null}
        <div class="section-title">Account: {{ account.alias }}</div>
        <div class="info">
          <p><strong>ID:</strong> {{ account.id }}</p>
          <p><strong>Currency:</strong> {{ balance.asset_code }}</p>
          <p><strong>Current Balance:</strong> {{ balance.available }}</p>
        </div>
```

**`<div class="section-title">Account: {{ account.alias }}</div>`**

Shows a section title with the account alias (a friendly or readable name for the account).

**`<p><strong>ID:</strong> {{ account.id }}</p>`**

Shows the unique identifier of the account.

**`<p><strong>Currency:</strong> {{ balance.asset_code }}</p>`**

Shows the currency code (like "BRL" or "USD") associated with the account’s balance.

**`<p><strong>Current Balance:</strong> {{ balance.available }}`**

Shows the current available balance.

### Operations information

```html HTML theme={null}
            {% for operation in midaz_transaction.operation %}
              {% if operation.account_id == account.id %}
                {% set original_amount = operation.amount %}
                {% set discount_amount = original_amount * 0.03  %}
                {% set final_amount = original_amount - discount_amount %}
```

**`{% for operation in midaz_transaction.operation %}`**

This loops through all operations from the `midaz_transaction.operation` list.

**`{% if operation.account_id == account.id %}`**

This line checks whether the current operation relates to the current account in the outer loop (from your earlier block). It proceeds only if:

* The operation's `account_id` matches the `account.id` in focus.

**`{% set original_amount = operation.amount %}`**

This line sets a temporary variable named `original_amount` and gives it the value of the `amount` field in the operation object.

**`{% set discount_amount = original_amount * 0.03 %}`**

This line calculates a 3% discount on the original amount.

* The line saves the result as `discount_amount`.

**`{% set final_amount = original_amount - discount_amount %}`**

This line subtracts the discount from the original amount.

* The line stores the final result in `final_amount`, which you can render later.

### Table columns

```html HTML theme={null}
                <tr>
                  <td>{{ operation.id }}</td>
                  <td>{{ operation.type }}</td>
                  <td>{{ original_amount|decimal:2 }}</td>
                  <td>{{ discount_amount|decimal:2 }}</td>
                  <td>{{ final_amount|decimal:2 }}</td>
                  <td>{{ operation.description }}</td>
                </tr>
```

This block outputs a table row for each operation, including the following information:

**`<td>{{ operation.id }}</td>`**

Unique identifier for the operation.

**`<td>{{ operation.type }}</td>`**

Type of operation, such as `credit` or `debit`.

**`<td>{{ original_amount|decimal:2 }}</td>`**

Shows the original (unadjusted) amount, formatted with 2 decimal places.

**`<td>{{ discount_amount|decimal:2 }}</td>`**

Shows the calculated discount, also with 2 decimal places.

**`<td>{{ final_amount|decimal:2 }}</td>`**

Shows the final amount after applying the 3% discount.

**`<td>{{ operation.description }}</td>`**

Renders the description or label of the operation, such as "Transfer to savings".

### Report footer

```html HTML theme={null}
    <div class="footer">
      Document generated automatically via Reporter - Lerian · {{ midaz_onboarding.organization.0.legal_document }}
    </div>
```

This line renders a footer at the bottom of the document. The footer states that Reporter by Lerian generated the content automatically.

* It also includes the legal document number of the first organization linked to the onboarding data, pulled dynamically using the `{{ midaz_onboarding.organization.0.legal_document }}` placeholder.

## Template output

***

```html HTML expandable theme={null}
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Analytical Financial Report</title>
  <style>
    body {
      font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
      background-color: #f4f6f9;
      color: #333;
      padding: 40px;
    }

    .container {
      max-width: 900px;
      margin: auto;
      background: #ffffff;
      padding: 30px 40px;
      border-radius: 8px;
      box-shadow: 0 0 10px rgba(0,0,0,0.1);
    }

    h1 {
      text-align: center;
      font-size: 24px;
      color: #004080;
      margin-bottom: 10px;
    }

    .subtitle {
      text-align: center;
      font-size: 14px;
      color: #777;
      margin-bottom: 30px;
    }

    .section-title {
      font-weight: bold;
      font-size: 16px;
      margin-top: 30px;
      margin-bottom: 10px;
      color: #004080;
      border-bottom: 1px solid #ccc;
      padding-bottom: 4px;
    }

    table {
      width: 100%;
      border-collapse: collapse;
      margin-top: 15px;
    }

    th, td {
      padding: 10px;
      text-align: left;
      border: 1px solid #ccc;
    }

    th {
      background-color: #e8f0fe;
      font-weight: bold;
      color: #003366;
    }

    .info p {
      margin: 4px 0;
    }

    .footer {
      margin-top: 40px;
      text-align: center;
      font-size: 12px;
      color: #999;
    }
  </style>
</head>
<body>
  <div class="container">
    <h1>Analytical Financial Report</h1>
    <div class="subtitle">Detailed analysis of movements by linked accounts.</div>

    <div class="info">
      <p><strong>Generation Date:</strong> 23/05/2025 14:08</p>
      <p><strong>Organization:</strong> Mante - Pfannerstill</p>
      <p><strong>Ledger:</strong> Rice, Rowe and O'Hara</p>
    </div>    
        <div class="section-title">Account: @external/USD</div>
        <div class="info">
          <p><strong>ID:</strong> 0196d97e-a58d-7814-8eb3-e510b818f6a5</p>
          <p><strong>Currency:</strong> USD</p>
          <p><strong>Current Balance:</strong> 499950</p>
        </div>

        <table>
          <thead>
            <tr>
              <th>Operation ID</th>
              <th>Type</th>
              <th>Original Amount</th>
              <th>Discount (3%)</th>
              <th>Final Amount</th>
              <th>Description</th>
            </tr>
          </thead>
          <tbody>            
                <tr>
                  <td>0196d982-4085-7e1d-b698-3aad306df721</td>
                  <td>CREDIT</td>
                  <td>500000.00</td>
                  <td>15000.00</td>
                  <td>485000.00</td>
                  <td>Duplicated account test</td>
                </tr>
                <tr>
                  <td>0196d983-a2c2-7dce-ad14-78eb36d9f2d1</td>
                  <td>DEBIT</td>
                  <td>20.00</td>
                  <td>0.60</td>
                  <td>19.40</td>
                  <td>Loan payment person1</td>
                </tr>
                <tr>
                  <td>0196d983-a2c2-7e0d-a246-45d5234138e3</td>
                  <td>DEBIT</td>
                  <td>30.00</td>
                  <td>0.90</td>
                  <td>29.10</td>
                  <td>Loan payment person1</td>
                </tr>
          </tbody>
        </table>      
    <div class="footer">
      Document generated automatically via Reporter - Lerian · 123.456.789-0001/00
    </div>
  </div>
</body>
</html>
```

## Rendered output

***

![Example financial report rendered from the HTML template code shown above](https://mintcdn.com/lerian-49cb71fc/uUQdWFdbYtzFLYzd/images/en/docs/html_template.jpg?fit=max\&auto=format\&n=uUQdWFdbYtzFLYzd\&q=85\&s=da9d3540b0a8b7b1122b38f24c2715cc)

Figure 1. An example of a financial report rendered from the HTML code in the example.


# Reporter quick start
Source: https://docs.lerian.studio/en/products/reporter/reporter-quick-start

Upload a minimal Reporter template, generate your first report from live data, and verify the downloaded output. A hands-on setup in under ten minutes.

Use this quick start to generate one report and confirm that your Reporter installation works end to end. For a recurring production workflow, see [Using Reporter](/en/products/reporter/using-reporter).

For complete request and response schemas, use the [Reporter API quick start](/en/reference/products/reporter/reporter-developer-quick-start) and the linked API reference pages.

## Goal

***

You will:

1. Create a minimal `.tpl` template.
2. Upload it as an HTML template.
3. Generate a report without data filters.
4. Track the report until processing ends.
5. Download and verify the finished file.

## Prerequisites

***

You need:

* A running Reporter instance
* An authentication token, if Access Manager is enabled
* `curl`

Set the values used in the examples:

```bash theme={null}
export REPORTER_URL="https://reporter.example.com"
export TOKEN="your-access-token"
```

## Create a minimal template

***

Create `first-report.tpl` with static HTML content:

```html theme={null}
<!doctype html>
<html>
  <body>
    <h1>My first Reporter output</h1>
  </body>
</html>
```

Reporter templates always use the `.tpl` extension. The template content must match the selected output format. Reporter supports HTML, CSV, XML, PDF, and TXT outputs. For PDF output, write the template in HTML and set `outputFormat=PDF`.

For templates that read data, see [Template formats](/en/products/reporter/template-examples).

## Upload the template

***

Upload the file with the four required multipart fields: `template`, `outputFormat`, `description`, and `category`. The category names the report family, in lowercase letters, digits, underscores, and hyphens.

```bash theme={null}
curl --fail-with-body -X POST "$REPORTER_URL/v1/templates" \
  -H "Authorization: Bearer $TOKEN" \
  -F "template=@first-report.tpl" \
  -F "outputFormat=HTML" \
  -F "description=First Reporter output" \
  -F "category=quick_start"
```

Save the returned template `id` as `TEMPLATE_ID`:

```bash theme={null}
export TEMPLATE_ID="returned-template-id"
```

See [Upload template](/en/reference/products/reporter/upload-template) for the complete operation contract.

## Generate the report

***

Create a report with the required `templateId` and `filters` fields. Use an empty object when you do not need filters.

```bash theme={null}
curl --fail-with-body -X POST "$REPORTER_URL/v1/reports" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"templateId\":\"$TEMPLATE_ID\",\"filters\":{}}"
```

Save the returned report `id` as `REPORT_ID`:

```bash theme={null}
export REPORT_ID="returned-report-id"
```

See [Create report](/en/reference/products/reporter/create-report) for filter syntax and the complete operation contract.

## Track processing

***

Check the report until it leaves `Processing`:

```bash theme={null}
curl --fail-with-body \
  -H "Authorization: Bearer $TOKEN" \
  "$REPORTER_URL/v1/reports/$REPORT_ID"
```

The active lifecycle is:

```text theme={null}
Processing -> Finished | Partial | Error
```

| Status | Meaning | What to do |
| - | - | - |
| `Processing` | Reporter is generating the output. | Check again later. |
| `Finished` | Generation completed successfully. | Download the report. |
| `Partial` | Generation completed with incomplete results. | Inspect the report details and application logs. |
| `Error` | Generation failed. | Inspect the error and application logs before retrying. |

See [Check report status](/en/reference/products/reporter/check-report-status) for the response schema.

## Download and verify the output

***

Download only when the report status is `Finished`:

```bash theme={null}
curl --fail-with-body \
  -H "Authorization: Bearer $TOKEN" \
  "$REPORTER_URL/v1/reports/$REPORT_ID/download" \
  -o first-report.html
```

Confirm that the file is not empty and contains the expected heading:

```bash theme={null}
test -s first-report.html
grep -F "My first Reporter output" first-report.html
```

See [Download report](/en/reference/products/reporter/download-report) for response headers and error details.

## Troubleshooting

***

| Problem | Check |
| - | - |
| Template upload is rejected | Include the `.tpl` file, `outputFormat`, `description`, and `category`; confirm that the file content matches the format. |
| Report creation is rejected | Send both `templateId` and `filters`; use `{}` when no filter applies. When the tenant has several institutions, also send `institution`. |
| Report remains in `Processing` | Check Reporter worker and queue health, then inspect application logs. |
| Report ends in `Partial` or `Error` | Inspect the report details, referenced data sources, and application logs before retrying. |
| Download is rejected | Confirm that the report exists and has status `Finished`. |

## Next steps

***

* Follow [Using Reporter](/en/products/reporter/using-reporter) to design a reusable, recurring workflow.
* Learn how to reference configured data in [Template formats](/en/products/reporter/template-examples).
* Review the specialized guidance in [BACEN templates](/en/products/reporter/reporter-bacen-templates) before working with regulatory report structures.
* Use the [Reporter API quick start](/en/reference/products/reporter/reporter-developer-quick-start) for complete API examples.


# Reporter REST API
Source: https://docs.lerian.studio/en/products/reporter/reporter-rest-api

Orient yourself in the Reporter API: the /v1 base path, bearer authentication, the 56 operations grouped by job, idempotency, pagination, and the RFC 9457 error shape.

Reporter serves one HTTP API. Every operation sits under the base path `/v1`, with no product segment ahead of it. A template list is `GET /v1/templates`.

The API carries 56 operations across nine areas: templates, the template builder, reports, data sources, deadlines, institutions, regulatory filing, metrics, and the streaming manifest. All 56 render under the **Reporter** anchor in the [API Reference](/en/reference/introduction). This page covers what the operations share and points you at the reference page for each one.

> [!NOTE]
>
> The OpenAPI documents in this portal are render sources for the reference pages. They are not client contracts, and they are not a basis for SDK generation.

## Authentication

***

Reporter accepts a JWT bearer token. One security scheme applies to every operation:

```http theme={null}
Authorization: Bearer <token>
```

Reporter authorizes each request against the `reporter` application, a resource, and an action. The resource follows the area: `templates`, `reports`, `deadlines`, `data-source`, `institutions`, `regulatory`, `metrics`, or `streaming`. Approving a regulatory draft authorizes against its own resource, `regulatory-approval`. The action is the lower-cased HTTP method, so `POST /v1/reports` authorizes as the `post` action on `reports`. `PLUGIN_AUTH_ENABLED` turns the middleware on, and `PLUGIN_AUTH_ADDRESS` points it at the Access Manager.

Probe routes stay outside authentication so an orchestrator reaches them without a token: `/health`, `/readyz`, and `/version`.

Tenant identity travels inside the token. Reporter resolves the tenant from the JWT `tenantId` claim. None of the operations above take a tenant from a request header, and no client-supplied value overrides it.

## The operations by job

***

### Templates

Nine operations own the template lifecycle: [list](/en/reference/products/reporter/list-templates), [upload](/en/reference/products/reporter/upload-template), [get](/en/reference/products/reporter/retrieve-template-details), [get content](/en/reference/products/reporter/get-template-content), [update](/en/reference/products/reporter/update-templates), [delete](/en/reference/products/reporter/delete-template), and [preview](/en/reference/products/reporter/preview-template), plus [list report families](/en/reference/products/reporter/list-report-families) and [assign a report family](/en/reference/products/reporter/assign-report-family). A template is a plain-text `.tpl` file plus its output format, description, and category. Deleting a template also removes the deadlines that point at it.

### Template builder

Four operations back a visual editor without persisting anything. [List block definitions](/en/reference/products/reporter/list-block-definitions) and [list filter definitions](/en/reference/products/reporter/list-filter-definitions) return the catalog an editor draws from. [Validate blocks](/en/reference/products/reporter/validate-template-blocks) checks a block tree and reports per-block errors. [Generate code](/en/reference/products/reporter/generate-template-code) turns that tree into template source you can then upload.

### Reports

Four operations: [create](/en/reference/products/reporter/create-report), [get](/en/reference/products/reporter/check-report-status), [list](/en/reference/products/reporter/retrieve-reports), and [download](/en/reference/products/reporter/download-report).

The lifecycle is **create-and-retain**. `POST /v1/reports` answers `201` with a report in `Processing` and hands the work to a background worker. The report then reaches `Finished`, `Partial`, or `Error`, and a regulatory filing reaches `Draft` instead of `Finished`. Poll the get operation, or subscribe to the events described in [Events](/en/products/reporter/reporter-events). Download serves a report in `Finished` or `Final`, and a `Draft` only when no required field is blank. The `X-Report-Status` response header names the status you received. Every report you create stays addressable by its identifier for as long as your object-storage retention policy keeps the artifact.

### Data sources

Seven operations manage the persisted registry under `/v1/data-sources` (note the hyphen). You can list or create entries, get, partially update, or soft-delete one by `dataSourceId`, inspect its live schema, and test its connection. Passwords are write-only, encrypted at rest, and absent from every response. A delete is refused while a live template still references the data source. A self-hosted deployment may also seed registry entries from `DATASOURCE_*` variables at startup.

### Institutions

Six operations register the financial institutions a tenant reports for: [list](/en/reference/products/reporter/list-institutions), [create](/en/reference/products/reporter/create-institution), [get](/en/reference/products/reporter/get-institution), [replace](/en/reference/products/reporter/replace-institution), [delete](/en/reference/products/reporter/delete-institution), and [propose from Midaz](/en/reference/products/reporter/propose-institutions). An institution has one CNPJ and a scope that names its rows in each data source. A report request names the institution it reads for. When the tenant has several institutions, a request that names none is refused. Replace requires `If-Match` with the version you read.

### Regulatory filing

Eighteen operations run the filing cycle for the curated regulatory documents that a deployment carries:

* **Catalog**: [list documents](/en/reference/products/reporter/list-regulatory-documents), [get a document](/en/reference/products/reporter/get-regulatory-document), and [get its contract](/en/reference/products/reporter/get-document-contract), which lists every field the file needs.
* **Subscriptions**: [list](/en/reference/products/reporter/list-subscriptions), [create](/en/reference/products/reporter/create-subscription), [get](/en/reference/products/reporter/get-subscription), [deactivate](/en/reference/products/reporter/deactivate-subscription), [reactivate](/en/reference/products/reporter/reactivate-subscription), [adopt another document version](/en/reference/products/reporter/adopt-document-version), and [set the filing institution](/en/reference/products/reporter/set-subscription-institution).
* **Mapping**: [get](/en/reference/products/reporter/get-subscription-mapping) and [replace](/en/reference/products/reporter/replace-subscription-mapping) the YAML mapping from the document's fields to your tables, and [check it against the live databases](/en/reference/products/reporter/check-mapping-readiness).
* **Filings**: [generate a draft](/en/reference/products/reporter/create-regulatory-report), [correct it](/en/reference/products/reporter/correct-regulatory-report), [read the corrections](/en/reference/products/reporter/list-report-corrections), [approve it](/en/reference/products/reporter/approve-regulatory-report), and [read its provenance](/en/reference/products/reporter/get-report-provenance).

Approval is refused while a required field is blank.

### Deadlines

Six operations model a filing obligation with a due date and a recurrence rule: [list](/en/reference/products/reporter/retrieve-deadlines), [create](/en/reference/products/reporter/create-deadline), [update](/en/reference/products/reporter/update-deadline), [delete](/en/reference/products/reporter/delete-deadline), [deliver](/en/reference/products/reporter/deliver-deadline), and [notifications](/en/reference/products/reporter/retrieve-deadline-notifications). Status is derived from the due date and the delivery mark, never sent by a client. Notifications are pull-only: the operation returns the deadlines inside their alert window, sorted overdue first.

### Metrics and streaming

[Metrics](/en/reference/products/reporter/get-metrics) returns deployment counters: templates, reports, data sources, and report errors for the current window against the one before it. `errorPeriodDays` sets that window and defaults to 7. [Streaming events](/en/reference/products/reporter/get-streaming-events) returns the event manifest covered in [Events](/en/products/reporter/reporter-events).

## Content types

***

Template create and update are `multipart/form-data`: a `template` file part, plus `outputFormat`, `description`, and `category`. The regulatory mapping is `application/yaml`. Everything else that carries a body is `application/json`.

Download answers with the bytes and a `Content-Disposition` filename. The media type follows the report's output format: `application/pdf`, `application/xml`, `text/csv`, `text/html`, or `text/plain`.

## Idempotency

***

Template create and report create accept an `X-Idempotency` request header. Send your own key, or omit the header and Reporter derives one from a hash of the request body.

* A request that repeats one still in flight is rejected rather than duplicated.
* A request that repeats one already completed replays the original response and stamps `X-Idempotency-Replayed: true` on it.

## Pagination

***

Template, deadline, data-source, and institution lists use offset pagination with the same two parameters.

| Parameter | Default | Rules |
| - | - | - |
| `page` | `1` | Page number. |
| `limit` | `10` | Items per page. The ceiling is `MAX_PAGINATION_LIMIT`, which defaults to 100. |

A `limit` above the ceiling is rejected with a pagination error rather than clamped.

The report list uses keyset pagination instead: send `limit` without `page`, then follow `nextCursor` or `prevCursor` from the response. A cursor is absent when there is no page in that direction, and the response does not include `page` or `total`. The report list accepts `status`, `template_id`, `created_at`, and `sort_order`. The cursor carries the sort order for the walk. The template list filters on `output_format`, `category`, `has_category`, `description`, `data_source_name`, and `created_at`. The deadline list filters on `status`, `active`, `type`, `start_date`, and `end_date`.

## Errors

***

Every error answers `application/problem+json` and follows [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457), carrying a `title`, a `status`, a `detail`, and a stable domain `code`. Match on the code, never on the prose. The [Reporter error list](/en/reference/products/reporter/reporter-error-list) maps each code to its HTTP status and its fix.

## Reading the spec from a running service

***

`SWAGGER_ENABLED=true` mounts a browsable reference at `/swagger/docs`, with the OpenAPI 3.1 document at `/swagger/openapi.json` and `/swagger/openapi.yaml`. It is off unless you turn it on. Keep it off in production.

## Next steps

***

> **[API Reference](/en/reference/introduction)**
>
> The 56 operations, with full request and response shapes.

> **[API quick start](/en/reference/products/reporter/reporter-developer-quick-start)**
>
> Upload a template, generate a report, and download it with cURL.

> **[Events](/en/products/reporter/reporter-events)**
>
> Subscribe to report and deadline events instead of polling.

> **[What is Reporter?](/en/products/reporter/what-is-reporter)**
>
> Templates, reports, data sources, and where they fit.


# Reporter SDK and embedding
Source: https://docs.lerian.studio/en/products/reporter/reporter-sdk-and-embedding

Integrate Reporter from your own software: the REST surface that carries every operation, the base URL and auth model, a first call, the Go SDK, and the pattern for running Reporter behind a service you already operate.

Reporter's REST API is the complete surface. Templates, reports, data sources, deadlines, institutions, regulatory filing, the template builder, and metrics are all HTTP calls. Nothing exists only inside a client library, and nothing exists only inside the Console.

## Authenticating

***

One scheme protects every operation: a bearer token on the `Authorization` header.

```
Authorization: Bearer <token>
```

Access Manager authorises each call against the resource behind the path and the action. The resource is one of templates, reports, data sources, deadlines, institutions, regulatory, regulatory approval, metrics, or streaming, and the action is the HTTP verb. A token granted read access to reports can list and download them, and gets a `403` on create. Failures answer `application/problem+json`, so parse the problem document rather than the status line alone.

The token also carries the isolation scope of the call. Reporter resolves it from the credential itself, so no operation takes a scoping header from your client and no header widens what a token already permits.

## Base URL

***

The base path is `/v1`, with no product segment in front of it. Every path on this page appends to that:

```
https://reporter.example.com/v1
```

Three content-type rules follow from the surface itself. Template upload and update are `multipart/form-data`, because a template is a `.tpl` file. Report creation is `application/json`. A download streams the rendered bytes with the `Content-Type` of the output format and a `Content-Disposition` filename.

Most list operations take `limit` and `page`, 10 and 1 by default. The report list takes `limit` and a `cursor` from the previous page instead. The largest page is `MAX_PAGINATION_LIMIT`, which each deployment sets and which defaults to 100. A `limit` above that ceiling is rejected, not reduced.

## Your first call

***

**1. Confirm the token and the base URL**

```bash theme={null}
curl -s "https://reporter.example.com/v1/templates" \
  -H "Authorization: Bearer $TOKEN"
```

A `200` with a template list proves both. A `401` means the token. A `404` means the base URL.

**2. Request a report**

```bash theme={null}
curl -s -X POST "https://reporter.example.com/v1/reports" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency: daily-balance-2026-07-28" \
  -d '{
    "templateId": "0196b270-a315-7137-9408-3f16af2685e1",
    "filters": {
      "midaz_onboarding": {
        "account": { "status": { "eq": ["ACTIVE"] } }
      }
    }
  }'
```

The response is `201` with the report in `Processing`. Generation runs asynchronously.

**3. Wait for a terminal state, then download**

```bash theme={null}
curl -s "https://reporter.example.com/v1/reports/$REPORT_ID" \
  -H "Authorization: Bearer $TOKEN"

curl -s "https://reporter.example.com/v1/reports/$REPORT_ID/download" \
  -H "Authorization: Bearer $TOKEN" -o report.pdf
```

Send `X-Idempotency` on every report request, and on template upload for the same reason. Repeat a request that is still in flight and you get an error instead of a second report. Repeat one that already finished and Reporter replays the original report, marking the response `X-Idempotency-Replayed: true`.

A report is created once and kept: create, get, list, download are its four operations. How long a rendered file lives is a lifecycle policy on the storage bucket, not an API call.

## Managing data sources

***

The API manages the persisted data-source registry. Use it to list or create connections, get or partially update one by `dataSourceId`, inspect its live schema, test it, or soft-delete it:

```bash theme={null}
curl -s "https://reporter.example.com/v1/data-sources" \
  -H "Authorization: Bearer $TOKEN"
```

Each entry carries the stable `configName` that templates address. Responses never contain passwords. Fetch one by identifier with `/v1/data-sources/{dataSourceId}` and inspect its live tables or collections with `/v1/data-sources/{dataSourceId}/schema`.

## The Go SDK

***

[`lerian-sdk-golang`](https://github.com/LerianStudio/lerian-sdk-golang) ships a `reporter` package alongside the other Lerian products. It acquires an OAuth2 client-credentials token, refreshes it, and hands back typed results.

Configure it with the same `https://<host>/v1` base URL you use with cURL. Add the client ID, the client secret, the token URL of your authorization server, and a request timeout.

```go theme={null}
report, err := client.Reporter.Reports.Get(ctx, reportID)
if err != nil {
    return err
}

if report.Status == "Finished" {
    data, err := client.Reporter.Reports.Download(ctx, reportID)
    if err != nil {
        return err
    }

    if err := os.WriteFile(reportID, data, 0o600); err != nil {
        return err
    }
}
```

`Download` returns the rendered bytes in the template's output format. Write them to disk, as above, or stream them to your caller.

Use the package to get a report and download its file. Create templates and reports, and call every other operation, over REST. Mixing both in one integration is normal.

## Running Reporter behind your own service

***

Reporter is a service you deploy, not a library you link. To put it behind an application your customers already use, keep the credentials on your side and call Reporter server to server. Four rules keep that boundary clean.

**Never hand a Reporter token to a browser.** Your service authenticates your user and decides whether that user may run this report. It then makes the call with its own token.

**Answer immediately with an identifier.** Report creation returns in `Processing`. Return that identifier to your caller and let your own status endpoint expose progress.

**Learn about completion once.** Poll `GET /v1/reports/{id}` on a modest interval, or subscribe to Reporter's report events and stop polling. See [Reporter events](/en/products/reporter/reporter-events).

**Proxy the download.** The download endpoint streams bytes to an authenticated caller, so your service fetches them and re-serves them under its own auth.

> [!NOTE]
>
> A `Partial` report means some data sections failed while others succeeded, and its metadata names the failing sections. Treat it as a signal about a data source or a filter, and decide in your own service what your users should see.

## Next steps

***

> **[Reporter REST API](/en/products/reporter/reporter-rest-api)**
>
> Every operation, grouped by the job it does.

> **[Reporter events](/en/products/reporter/reporter-events)**
>
> The event contract, and how to subscribe instead of polling.

> **[API quick start](/en/reference/products/reporter/reporter-developer-quick-start)**
>
> Upload a template and generate a report with cURL.

> **[Error list](/en/reference/products/reporter/reporter-error-list)**
>
> Reporter's error codes and what resolves them.


# Reporter template engine
Source: https://docs.lerian.studio/en/products/reporter/reporter-template-engine

How Reporter evaluates a template: the field map it derives, the data context it builds, blocks, template filters, row filters, and the multi-schema data source model.

A Reporter template is a plain-text `.tpl` file. Reporter renders it with a Pongo2 engine, which reads Django-style tags and pipe filters.

[Template reference](/en/products/reporter/template-reference) lists every tag and filter. [Template formats](/en/products/reporter/template-examples) shows a worked file per output format.

## The field map

***

When you upload a template, Reporter analyses the text and derives a **field map**: every data source, every table, and every field the template names.

```json theme={null}
{
  "external_db": {
    "sales__orders": ["id", "total", "created_at"]
  }
}
```

The map is stored with the template metadata and travels with each report request. Extraction reads only what the map lists. A field your template never names is never queried, so a template stays cheap as the underlying tables grow.

Two consequences follow. First, Reporter derives the map when you upload or replace the file, never at render time. A new field reference reaches a report only after you upload the changed template.

Second, Reporter checks the map against the live schema of each data source at upload time. A wrong table name or a wrong field name surfaces there, before any report runs. When a data source cannot answer, Reporter returns warnings and still accepts the template. One unreachable database does not block your work.

## The data context

***

Extraction builds one context for the render. The first level is the data source config name. The second level is the table. Each value is a list of rows.

```json theme={null}
{
  "external_db": {
    "orders": [
      { "id": "018f...", "total": "1200.00", "created_at": "2026-07-01" }
    ]
  }
}
```

Your template addresses that context by the same names it used to declare them:

```django theme={null}
{% for order in external_db.orders %}
  {{ order.id }} — {{ order.total|decimal:2 }}
{% endfor %}
```

Rows come back under the key your template wrote. A bare table name stays bare. A schema-qualified reference becomes `schema__table`, with a double underscore, in both the field map and the render context. Row filters are looser and accept either `schema.table` or `schema__table`.

### Variables

A template reads the context through variables. A loop alias binds one row at a time, and `{% with %}` names part of the context for the block below it. Both aliases are local to the block that declares them.

The analyser follows an alias back to the table behind it. A field you read as `order.total` inside a loop over `external_db.orders` lands in the field map as `total` under that table, so extraction returns it.

## Multi-schema data sources

***

A datasource normally lives in Reporter's persisted registry and is managed through the [data-source API](/en/reference/products/reporter/list-data-sources). An environment block can seed a registry entry at Manager startup only when no active or soft-deleted entry already uses that config name. `CONFIG_NAME` sets the name your templates use, and `SCHEMAS` lists the schemas Reporter discovers on it. Use the same name for the environment-name segment and `CONFIG_NAME`, uppercasing that name in environment-variable keys, as in the block below:

```bash theme={null}
DATASOURCE_EXTERNAL_DB_CONFIG_NAME=external_db
DATASOURCE_EXTERNAL_DB_HOST=external-postgres
DATASOURCE_EXTERNAL_DB_PORT=5432
DATASOURCE_EXTERNAL_DB_USER=db_user
DATASOURCE_EXTERNAL_DB_DATABASE=external_database
DATASOURCE_EXTERNAL_DB_TYPE=postgresql
DATASOURCE_EXTERNAL_DB_SCHEMAS=sales,inventory,reporting
```

Without `SCHEMAS`, Reporter discovers the `public` schema alone. The schema key is `DATASOURCE_{CONFIG_NAME}_SCHEMAS`, whereas the other environment keys use the `{NAME}` segment. See [Environment variables](/en/products/reporter/reporter-environment-variables) for the full bootstrap block.

The engine resolves a bare table name against every discovered schema:

| Owners of the table name | Result |
| - | - |
| Exactly one schema | The engine reads that table. |
| Several schemas, none of them `public` | The engine reports the table as ambiguous and names the candidates. |
| No schema | The engine reports the table as not found. |

Qualify the reference to remove the ambiguity. The qualified form names the source, the schema, and the table:

```django theme={null}
{% for order in external_db:sales.orders %}
  {{ order.id }}
{% endfor %}
```

A qualified reference must match the discovered schema exactly. The engine does not search other schemas for it.

## Blocks

***

A block is the unit the visual template builder works in. Thirteen types exist, in six categories:

| Category | Block types |
| - | - |
| Basic (`basic`) | `text`, `variable`, `comment` |
| Control (`control`) | `loop`, `conditional`, `with` |
| Data (`data`) | `aggregation`, `calculation`, `date_time`, `expression` |
| Layout (`layout`) | `section` |
| Numbering (`dimp`) | `counter` |
| Advanced (`advanced`) | `custom_tag` |

The value in brackets is what the block catalogue returns as the category string. A client that matches on the API response keys on it rather than on the label.

Four of them hold children: `loop`, `conditional`, `section`, and `with`. A conditional also carries alternative branches. Blocks nest up to fifty levels deep.

Blocks are never stored. The builder sends them to Reporter, and Reporter returns Pongo2 source. The template you upload is always the text.

Three operations support that flow:

* [Validate template blocks](/en/reference/products/reporter/validate-template-blocks) checks the structure and reports each problem against the block that caused it.
* [Generate template code](/en/reference/products/reporter/generate-template-code) returns the finished source for an output format.
* [List block definitions](/en/reference/products/reporter/list-block-definitions) returns the catalogue, so a client stays in step with the engine.

## Two kinds of filter

***

Reporter uses the word filter for two different things, and they run at different times.

**Row filters** run during extraction. They live in the report request, not in the template, and they narrow the rows the database returns. The payload nests them three levels deep: data source, then table, then field.

```json theme={null}
{
  "templateId": "018f2a6c-1c2f-7a10-9f1e-2b8c4d5e6f70",
  "filters": {
    "external_db": {
      "orders": {
        "status": { "nin": ["cancelled", "draft"] },
        "created_at": { "gte": ["2026-07-01"], "lte": ["2026-07-31"] }
      }
    }
  }
}
```

Eight operators exist:

| Operator | Meaning | Values |
| - | - | - |
| `eq` | Matches any listed value | One or more |
| `gt` | Above the value | One |
| `gte` | At or above the value | One |
| `lt` | Below the value | One |
| `lte` | At or below the value | One |
| `between` | Inside an inclusive range | Exactly two |
| `in` | Matches any listed value | One or more |
| `nin` | Excludes every listed value | One or more |

Every operator takes an array. Several operators on one field combine, as the date range above shows.

**Template filters** run during the render, after the rows arrive. They shape a value inside the document, and they use pipe syntax: `{{ value|percent_of:total }}`. [List filter definitions](/en/reference/products/reporter/list-filter-definitions) returns the catalogue with an example per filter.

## The render step

***

The engine parses the prepared template once per report and executes it against the context. Two behaviours of that step change how you design a document.

Numeric output loses its trailing zeros, so `1200.00` renders as `1200`. Use the `decimal` filter, as in `{{ total|decimal:2 }}`, when a column needs fixed decimals. Values that carry several dots stay intact, which keeps an accounting code such as `1.1.2.00.000` unchanged.

An XML template can declare the encoding of the stored file. Put the marker on the same line as the XML declaration:

```django theme={null}
{# reporter:output-encoding=utf-16be #}<?xml version="1.0" encoding="UTF-16"?>
```

Reporter then writes the file in UTF-16BE with a byte order mark. PDF output ignores the marker.

## Generation parameters

***

A template can declare the parameters that a report request answers. Each declaration is a template comment:

```django theme={null}
{# reporter:parameter name=dataBase type=month required=true #}
```

A declaration takes the keys `name`, `type`, `required`, `default`, `allowedValues`, `description`, and `appliesTo`. The type is `string`, `integer`, `decimal`, `boolean`, `date` (`YYYY-MM-DD`), or `month` (`YYYY-MM`). A malformed declaration fails the upload.

The report request sends the values in `parameters`, and the template prints one as `{{ system.dataBase }}`. When the template declares parameters, Reporter refuses a request that sends an undeclared one. It also refuses a request that omits a required parameter that has no default.

`appliesTo` binds a `date` or `month` parameter to a date field, written as `<dataSource>.<table>.<field>`. Reporter then adds the end of that period as an `lte` filter on the field. It refuses a request that also sets an upper bound on that field.

## Limits the engine applies

***

> [!NOTE]
>
> Reporter blocks the Pongo2 tags that load or extend another file: `include`, `extends`, `import`, `block`, and `ssi`. A template is a self-contained document. Reporter also blocks `filter`, which applies a filter to a whole block of output.

Block nesting stops at fifty levels, on validation and on code generation alike. Free-form block fields reject template delimiters, so builder input cannot inject a tag. Uploaded templates reject script tags.

## Next steps

***

> **[How report generation works](/en/products/reporter/how-report-generation-works)**
>
> The path from a report request to a file you can download.

> **[Template reference](/en/products/reporter/template-reference)**
>
> Every tag, filter, and operator the syntax accepts.

> **[Template formats](/en/products/reporter/template-examples)**
>
> A worked template per output format.

> **[Reporter core concepts](/en/products/reporter/reporter-core-concepts)**
>
> Templates, data sources, reports, and deadlines in one place.


# TXT template
Source: https://docs.lerian.studio/en/products/reporter/reporter-txt-template

Build a transaction receipt template in plain text with Reporter, in a simple .tpl file that renders into a printable TXT proof of payment.

This page shows how to create a transaction receipt template with Reporter in `.txt` format.

## Template code

***

```text Text expandable theme={null}
##########################################
#            PROOF OF PAYMENT            #
##########################################

Generation Date: {% date_time "dd/MM/YYYY HH:mm" %}
Ledger Name: {{ midaz_onboarding.ledger.0.name }}

{%- for transaction in midaz_transaction.transaction %}
-----------------------------------------
Transaction ID: {{ transaction.id }}
Transaction Date: {{ transaction.created_at }}
Total Amount: {{ transaction.amount }}
Transaction Status: {{transaction.status}}
------------------------------------------

Source Accounts:
{%- for operation in filter(midaz_transaction.operation, "transaction_id", transaction.id) %} 
{%- if operation.type == "DEBIT" %} 
- Alias: {{operation.account_alias }} 
- Debit Amount: {{ operation.amount }} 
{%- endif %}
{%- endfor %}

Target Accounts:
{%- for operation in filter(midaz_transaction.operation, "transaction_id", transaction.id) %} 
{%- if operation.type == "CREDIT" %} 
- Alias: {{operation.account_alias }} 
- Credit Value: {{operation.amount }} 
{%- endif %}
{%- endfor %}

{%- endfor %}
------------------------------------------
Automatically generated document.
```

## Code breakdown

***

\*\* `Generation Date: {% date_time "dd/MM/YYYY HH:mm" %}`\*\*

Renders the current date and time during template processing.

* Uses the format `dd/MM/YYYY HH:mm` (e.g., `26/05/2025 11:45`).

\*\* `Ledger Name: {{ midaz_onboarding.ledger.0.name }}`\*\*

Displays the name of the ledger associated with this report.

* `midaz_onboarding.ledger` is a list, and `[0]` selects the first ledger.
* `.name` fetches the name property, like `"Corporate Ledger"`.

\*\* `{% for transaction in midaz_transaction.transaction %}`\*\*

This loop iterates over each transaction in the `midaz_transaction.transaction` list. For every transaction, the code below will run once to display its information.

### Transaction header block

Each transaction prints the following details:

```txt Text theme={null}
-----------------------------------------
Transaction ID: {{ transaction.id }}
Transaction Date: {{ transaction.created_at }}
Total Amount: {{ transaction.amount }}
Transaction Status: {{ transaction.status }}
------------------------------------------
```

* `transaction.id`: Unique ID of the transaction.
* `transaction.created_at`: Creation timestamp of the transaction.
* `transaction.amount`: The raw amount of the transaction.
* `transaction.status`: Current status, such as `APPROVED`, `PENDING`, or `CANCELED`.

### Source accounts section

```txt Text theme={null}
Source Accounts:
{% for operation in filter(midaz_transaction.operation, "transaction_id", transaction.id) %}
  {% if operation.type == "DEBIT" %}
    - Alias: {{ operation.account_alias }}
    - Debit Amount: {{ operation.amount }}
  {% endif %}
{% endfor %}
```

* Filters the operations list to include only operations linked to the current transaction.
* Further filters it to only show operations with `type == "DEBIT"` (funds leaving an account).
* For each matching debit:
  * Displays the account alias.
  * Displays the debit amount.

### Target accounts section

```txt Text theme={null}
Target Accounts:
{% for operation in filter(midaz_transaction.operation, "transaction_id", transaction.id) %}
  {% if operation.type == "CREDIT" %}
    - Alias: {{ operation.account_alias }}
    - Credit Value: {{ operation.amount }}
  {% endif %}
{% endfor %}
```

* Same logic as the debit block, but filters for `type == "CREDIT"` (funds received).
* For each matching credit:
  * Displays the account alias.
  * Displays the credit amount.

### Footer text

```text Text theme={null}
------------------------------------------
Automatically generated document.
```

* Simple text footer that marks the end of the report.
* Indicates automatic generation of the file, typically for traceability.

## Template output

***

```text Text expandable theme={null}
##########################################
#            PROOF OF PAYMENT            #
##########################################

Generation Date: 23/05/2025 14:08
Ledger Name: Rice, Rowe and O'Hara

-----------------------------------------
Transaction ID: 75906707-8c31-479c-b354-aa805c4cefbc
Transaction Date: 2025-05-22T14:15:22.123Z
Total Amount: 5000
Transaction Status: APPROVED
------------------------------------------

Source Accounts:
- Alias: @external|USD 
- Debit Amount: 1500

Target Accounts:
- Alias: @wallet_12345 
- Credit Value: 1500

------------------------------------------
Automatically generated document.
```


# XML template
Source: https://docs.lerian.studio/en/products/reporter/reporter-xml-template

Build an analytical financial report in XML with Reporter: account-level activity, custom logic like discounts, and per-account summaries.

This page guides you through a full example of an Analytical Financial report in XML. The template breaks down account-level activity, applies custom logic (like discounts), and includes summaries to support analysis and auditing.

**What this report shows:**

* **Organization and Ledger details**.
* **Account-level overview**: balance, currency, and alias.
* **Operation breakdowns**: original amount, discount, final amount, status, description, and type.
* **Summaries per account**: total operations, total value, and average per operation.

## Template code

***

```xml XML expandable theme={null}
<AnalyticalReport>
    <Organization>{{ midaz_onboarding.organization.0.legal_name }} - Tax ID: {{ midaz_onboarding.organization.0.legal_document }}</Organization>
    <GenerationDate>{% date_time "dd/MM/YYYY HH:mm" %}</GenerationDate>
    {%- with ledger = midaz_onboarding.ledger[0] %}
    <Ledger>{{ ledger.name }}</Ledger>

    {%- for account in midaz_onboarding.account %}
    <Account>
        <AccountID>{{ account.id }}</AccountID>
        <Alias>{{ account.alias }}</Alias>
        {%- with balance = filter(midaz_transaction.balance, "account_id", account.id)[0] %}
        <CurrentBalance> {{ balance.available }}</CurrentBalance>
        {%- endwith %}
        {%- for balance in midaz_transaction.balance %}
        {%- if balance.account_id == account.id %}
        <CurrentBalance>{{ balance.available }}</CurrentBalance>
        {%- endif %}
        {%- endfor %}
        <Currency>{{ account.asset_code }}</Currency>
        <Operations>
        {%- for operation in midaz_transaction.operation %}
        {%- if operation.account_id == account.id %}
            {%- set original_amount = operation.amount %}
            {%- set discount_amount = original_amount * 0.03 %}
            {%- set final_amount = original_amount - discount_amount %} 
        <Operation>
                <OperationID>{{ operation.id }}</OperationID>
                <Description>{{ operation.description }}</Description>
                <Type>{{ operation.type }}</Type>
                <Route>{{ operation.route }}</Route>
                <OriginalAmount>{{ original_amount }}</OriginalAmount>
                <DiscountAmount>{{ discount_amount }}</DiscountAmount>
                <FinalAmountWithDiscount>{{ final_amount }}</FinalAmountWithDiscount>
                <Currency>{{ operation.asset_code }}</Currency>
                <Status>{{ operation.status }}</Status>
            </Operation>
        {%- endif %}
        {%- endfor %}
        </Operations>
        <AccountSummary>
            <TotalOperations>{% count_by midaz_transaction.operation if account_id == account.id %}</TotalOperations>
            <SumOfOperations>{% sum_by midaz_transaction.operation by "amount" if account_id == account.id %}</SumOfOperations>
            <AverageOfOperations>{% avg_by midaz_transaction.operation by "amount" if account_id == account.id %}</AverageOfOperations>
        </AccountSummary>
    </Account>
    {%- endfor %}
    {%- endwith %}
</AnalyticalReport>
```

## Code breakdown

***

### Organization and Ledger information

```xml XML theme={null}
<AnalyticalReport>
    <Organization>{{ midaz_onboarding.organization.0.legal_name }} - Tax ID: {{ midaz_onboarding.organization.0.legal_document }}</Organization>
    <GenerationDate>{% date_time "dd/MM/YYYY HH:mm" %}</GenerationDate>
    {%- with ledger = midaz_onboarding.ledger[0] %}
    <Ledger>{{ ledger.name }}</Ledger>
```

**`<Organization>{{ midaz_onboarding.organization.0.legal_name }} - Tax ID: {{ midaz_onboarding.organization.0.legal_document }}</Organization>`**

Displays the organization’s legal name and corresponding *CNPJ* (Brazilian Tax ID).

* `{{ midaz_onboarding.organization.0.legal_name }}`: retrieves the organization's name.
* `{{ midaz_onboarding.organization.0.legal_document }}`: retrieves the *CNPJ*.

**`<GenerationDate>{% date_time "dd/MM/YYYY HH:mm" %}</GenerationDate>`**
This function applies the date and time of the render, in the `dd/MM/YYYY HH:mm` format.

**`{%- with ledger = midaz_onboarding.ledger[0] %}`**

Creates a temporary variable pointing to the first available ledger. This keeps the code cleaner and avoids repetitive references.

* `-`: removes extra spaces in the rendered file.
* `ledger`: the name of the temporary variable.
* `midaz_onboarding.ledger[0].name`: points to the first available ledger.

### Looping through accounts

```xml XML theme={null}
    {%- for account in midaz_onboarding.account %}
    <Account>
        <AccountID>{{ account.id }}</AccountID>
        <Alias>{{ account.alias }}</Alias>
        {%- with balance = filter(midaz_transaction.balance, "account_id", account.id)[0] %}
        <CurrentBalance> {{ balance.available }}</CurrentBalance>
        {%- endwith %}
```

**`{%- for account in midaz_onboarding.account %}` ... `{% endfor %}`**

Loops through all accounts linked to the user. Since most users have more than one account, this allows you to display individual data for each one.

* `midaz_onboarding.account`: the full list of user accounts.
* `{%- for account in midaz_onboarding.account %}`: the loop runs once per account.

**`{%- with balance = filter(midaz_transaction.balance, "account_id", account.id)[0] %}`**

Defines a variable named `balance` that holds the current account’s balance.

* `filter()`: scans through `midaz_transaction.balance` to find the one matching the `account.id`.
* `[0]`: grabs the first match.
* `balance` holds the result.

**`<CurrentBalance> {{ balance.available }}</CurrentBalance>`**

Shows the account’s available balance (`balance.available`).

### Looping without `{%with...%}`

```xml XML theme={null}
        {%- for balance in midaz_transaction.balance %}
        {%- if balance.account_id == account.id %}
        <CurrentBalance>{{ balance.available }}</CurrentBalance>
        {%- endif %}
        {%- endfor %}
```

**`{%- for balance in midaz_transaction.balance %}`**

Loops through all balances to find the one that matches the current account. This is a more explicit alternative to `filter()`.

* `midaz_transaction.balance`: The list of all balances.
* `{%- balance in midaz_transaction.balance %}`: the loop runs once per balance.

**`{% if balance.account_id == account.id %}`**

Filters balances to show only those that match the current account.

* If they match, the balance appears.

### Currency information

```xml XML theme={null}
       <Currency>{{ account.asset_code }}</Currency>
```

Shows the account’s currency (e.g., BRL, USD).

* `account.asset_code`: dynamically injects the currency code.

### Grouping operations

```xml XML theme={null}
        <Operations>
        {%- for operation in midaz_transaction.operation %}
        {%- if operation.account_id == account.id %}
            {%- set original_amount = operation.amount %}
            {%- set discount_amount = original_amount * 0.03 %}
            {%- set final_amount = original_amount - discount_amount %} 
```

### `<Operations>...</Operations>`

Defines the section that lists all operations for an account.

* Keeps the report structured and easy to scan.

**`{%- for operation in midaz_transaction.operation %}`**

Loops through all operations in the transaction, and displays operations that match the current account.

* `operation`: represents the current operation that is part of the current transaction.
* `midaz_transaction.operation`: the list of all operations in the transaction.

**`{%- if operation.account_id == account.id %}`**

Includes only the relevant operations for the current account.

* If the `account_id` of the operation is equal to the current `account.id`, the rest of the block runs.

**`{%- set original_amount = operation.amount %}`**

Defines the original amount and sets it as a variable.

* `original_amount`: the name of the variable.

**`{%- set discount_amount = original_amount * 0.03 %}`**

Defines a variable and calculates a 3% discount on the original amount.

* `discount_amount`: the name of the variable.
* `original_amount * 0.03`: applies a 3% discount on the original amount.

**`{%- set final_amount = original_amount - discount_amount %}`**

Subtracts the discount from the original amount to get the final value.

* `final_amount`: variable that represents the final value.
* `original_amount - discount_amount`: the subtraction operation.

### Operation block

```xml XML theme={null}
        <Operation>
                <OperationID>{{ operation.id }}</OperationID>
                <Description>{{ operation.description }}</Description>
                <Type>{{ operation.type }}</Type>
                <Route>{{ operation.route }}</Route>
                <OriginalAmount>{{ original_amount }}</OriginalAmount>
                <DiscountAmount>{{ discount_amount }}</DiscountAmount>
                <FinalAmountWithDiscount>{{ final_amount }}</FinalAmountWithDiscount>
                <Currency>{{ operation.asset_code }}</Currency>
                <Status>{{ operation.status }}</Status>
        </Operation>
```

Each `<Operation>` contains detailed information about the transaction. These fields help users audit and understand what happened.

**`<OperationID>{{ operation.id }}</OperationID>`**

Unique ID of the operation.

**`<Description>{{ operation.description }}</Description>`**

Short description of the operation.

**`<Type>{{ operation.type }}</Type>`**

Operation type (e.g., credit, debit, adjustment).

**`<Route>{{ operation.route }}</Route>`**

Associated operation route entry.

**`<OriginalAmount>{{ original_amount }}</OriginalAmount>`**

Original amount before any adjustments.

**`<DiscountAmount>{{ discount_amount }}</DiscountAmount>`**

Value of the discount applied.

**`<FinalAmountWithDiscount>{{ final_amount }}</FinalAmountWithDiscount>`**

Final amount after discount.

**`<Currency>{{ operation.asset_code }}</Currency>`**

The currency used for the operation.

**`<Status>{{ operation.status }}</Status>`**

Operation status (e.g., Approved, pending).

### Account summary block

```xml XML theme={null}
<AccountSummary>
            <TotalOperations>{% count_by midaz_transaction.operation if account_id == account.id %}</TotalOperations>
            <SumOfOperations>{% sum_by midaz_transaction.operation by "amount" if account_id == account.id %}</SumOfOperations>
            <AverageOfOperations>{% avg_by midaz_transaction.operation by "amount" if account_id == account.id %}</AverageOfOperations>
        </AccountSummary>
```

**`{% count_by midaz_transaction.operation if account_id == account.id %}`**

Counts the number of operations associated with your account.

* The `count_by` function goes through `midaz_transaction.operation` and adds up how many operations have the same `account_id` as the current account.

**`{% sum_by midaz_transaction.operation by "amount" if account_id == account.id %}`**

Sums up the total value of all operations for this account.

* `sum_by` loops through transactions filtered by `account_id`.
* Sums the `amount` fields.

**`{% avg_by midaz_transaction.operation by "amount" if account_id == account.id %}`**

Calculates the average operation value for this account. Useful for spotting spending patterns or outliers.

* `avg_by` applies the average calculation to the amount values.
* Only considers operations for the current account.

## Template output

***

```xml XML expandable theme={null}
<AnalyticalReport>
	<Organization>Ferry, Stiedemann and Jast - Tax ID: 78425230000190</Organization>
	<GenerationDate>28/04/2025 10:30</GenerationDate>
	<Ledger>O'Connell, Dietrich and Bernhard</Ledger>
	<Account>
		<AccountID>01965efe-5afd-733d-9a64-3d53f73b13c8</AccountID>
		<Alias>@external/BRL</Alias>
		<CurrentBalance>1000</CurrentBalance>
		<CurrentBalance>1000</CurrentBalance>
		<Currency>BRL</Currency>
		<Operations>
			<Operation>
				<OperationID>01965f04-7087-73f1-a802-f8fceedb34ec</OperationID>
				<Description>Initial transfer</Description>
				<Type>DEBIT</Type>
				<Route></Route>
				<OriginalAmount>1000</OriginalAmount>
				<DiscountAmount>30</DiscountAmount>
				<FinalAmountWithDiscount>970</FinalAmountWithDiscount>
				<Currency>BRL</Currency>
				<Status></Status>
			</Operation>
		</Operations>
		<AccountSummary>
			<TotalOperations>1</TotalOperations>
			<SumOfOperations>1000</SumOfOperations>
			<AverageOfOperations>1000</AverageOfOperations>
		</AccountSummary>
	</Account>
	<Account>
		<AccountID>01965eff-0b2d-73cf-bbfe-0dc1ac9032d3</AccountID>
		<Alias>@wallet_46040127</Alias>
		<CurrentBalance> 0</CurrentBalance>
		<CurrentBalance> 0</CurrentBalance>
		<Currency>BRL</Currency>
		<Operations></Operations>
		<AccountSummary>
			<TotalOperations>0</TotalOperations>
			<SumOfOperations>0</SumOfOperations>
			<AverageOfOperations>0</AverageOfOperations>
		</AccountSummary>
	</Account>
	<Account>
		<AccountID>01965f01-aa72-7254-bb4a-fa9c8c9d4009</AccountID>
		<Alias>@account1</Alias>
		<CurrentBalance>300</CurrentBalance>
		<CurrentBalance>300</CurrentBalance>
		<Currency>BRL</Currency>
		<Operations>
			<Operation>
				<OperationID>01965f04-7087-73d2-a167-cb5146bee801</OperationID>
				<Description>External to accounts 1 and 2</Description>
				<Type>CREDIT</Type>
				<Route></Route>
				<OriginalAmount>300</OriginalAmount>
				<DiscountAmount>9</DiscountAmount>
				<FinalAmountWithDiscount>291</FinalAmountWithDiscount>
				<Currency>BRL</Currency>
				<Status></Status>
			</Operation>
		</Operations>
		<AccountSummary>
			<TotalOperations>1</TotalOperations>
			<SumOfOperations>300</SumOfOperations>
			<AverageOfOperations>300</AverageOfOperations>
		</AccountSummary>
	</Account>
	<Account>
		<AccountID>01965f01-ff74-712a-9e2c-d987f15a1d14</AccountID>
		<Alias>@account2</Alias>
		<CurrentBalance>700</CurrentBalance>
		<CurrentBalance>700</CurrentBalance>
		<Currency>BRL</Currency>
		<Operations>
			<Operation>
				<OperationID>01965f04-7087-73b1-aff9-69f59d623d31</OperationID>
				<Description>External to accounts 1 and 2</Description>
				<Type>CREDIT</Type>
				<Route></Route>
				<OriginalAmount>700</OriginalAmount>
				<DiscountAmount>21</DiscountAmount>
				<FinalAmountWithDiscount>679</FinalAmountWithDiscount>
				<Currency>BRL</Currency>
				<Status></Status>
			</Operation>
		</Operations>
		<AccountSummary>
			<TotalOperations>1</TotalOperations>
			<SumOfOperations>700</SumOfOperations>
			<AverageOfOperations>700</AverageOfOperations>
		</AccountSummary>
	</Account>
	<Account>
		<AccountID>01965f02-55fc-7a06-9f95-07e9a9ff4941</AccountID>
		<Alias>@account3</Alias>
		<CurrentBalance> 0</CurrentBalance>
		<CurrentBalance> 0</CurrentBalance>
		<Currency>BRL</Currency>
		<Operations></Operations>
		<AccountSummary>
			<TotalOperations>0</TotalOperations>
			<SumOfOperations>0</SumOfOperations>
			<AverageOfOperations>0</AverageOfOperations>
		</AccountSummary>
	</Account>
</AnalyticalReport>
```


# Template formats
Source: https://docs.lerian.studio/en/products/reporter/template-examples

Design Reporter templates for HTML, XML, CSV, PDF, or TXT outputs, with practical examples to start building reports that fit your use case.

Reporter supports multiple output formats: HTML, XML, CSV, PDF, and plain text.

The examples show how to structure your `.tpl` files for each format. They follow the formatting rules and parse correctly during generation.

> [!CAUTION]
>
> The file content **must** follow the output format you need (HTML, XML, CSV or TXT), but make sure to save it with a `.tpl` extension. For PDF output, author the template as HTML. Reporter converts it during generation.

## Available examples

***

> **[HTML template](/en/products/reporter/reporter-html-template)**
>
> Analytical financial report with account-level transaction analysis.

> **[XML template](/en/products/reporter/reporter-xml-template)**
>
> Analytical financial report in XML with custom logic and summaries.

> **[TXT template](/en/products/reporter/reporter-txt-template)**
>
> Transaction receipt template in plain text format.

Each page includes the full template code, field-by-field explanations, and sample outputs that you can generate through Reporter.

## Tip for rendering a transaction receipt

***

To generate a transaction receipt using Reporter, you can send a request like this to the [Create a Report](/en/reference/products/reporter/create-report) endpoint:

```json JSON theme={null}
{
  "templateId": "0196f99c-4d3e-73bc-b5d3-2a5bb1efbee4",
  "filters": {
    "midaz_transaction": {
      "transaction": {
        "id": {
          "eq": ["0196d983-a2c2-7d5a-a5b7-029fe0dcb710"]
        }
      }
    }
  }
}
```

### What does this filter do?

The `filters` field lets you limit the data used when rendering the template. In this case, you're telling the system to use **only** the transaction with the ID `0196d983-a2c2-7d5a-a5b7-029fe0dcb710`.

The receipt includes that transaction and the operations linked to it.

### What happens next?

After you send the request:

* The API returns the report `id`.
* You can use this ID to check the status of the report.
* When it's ready, the report will be available for download.

### Each receipt generated in isolation

Reporter generates each receipt in isolation, using the filters and templates you define.


# Template reference
Source: https://docs.lerian.studio/en/products/reporter/template-reference

Reference every template tag, filter, and operator available in Reporter: loops, conditionals, placeholders, and built-in formatting helpers.

This page is the reference for the template tags, filters, and operators in Reporter. For an introduction to templates and placeholders, see [What is Reporter](/en/products/reporter/what-is-reporter).

## Building templates

***

### Common blocks

* **Loop**

```
{% for <item> in <list> %}
  ...
{% endfor %}
```

* **Loop with explicit schema**

```
{% for order in external_db:sales.orders %}
  {{ order.id }} - {{ order.total }}
{% endfor %}
```

* **Simple condition**

```
{% if value_a == value_b %}
  ...
{% endif %}
```

* **Temporary scope**

```
{% with <object> as <alias> %}
  ...
{% endwith %}
```

* **Value formatting**

```
{{ field_name | decimal:2 }}   --> renders 123.4 as 123.40
```

### Conditional blocks

| Block | Description | Example |
| - | - | - |
| If | Runs block if condition is true | `{% if condition %}...{% endif %}` |
| If-else | Runs one block if true, another if false | `{% if condition %}...{% else %}...{% endif %}` |
| If-else-if | Allows multiple checks | `{% if a %}...{% elif b %}...{% else %}...{% endif %}` |
| Equal | Checks if two values are equal | `{% if a == b %}` |
| Not equal | Checks if two values are different | `{% if a != b %}` |
| Greater than | Checks if a is greater than b | `{% if a > b %}` |
| Less than | Checks if a is less than b | `{% if a < b %}` |
| Greater than or equal | Checks if a is greater than or equal to b | `{% if a >= b %}` |
| Less than or equal | Checks if a is less than or equal to b | `{% if a <= b %}` |
| And | Returns true if both conditions true | `{% if a and b %}` |
| Or | Returns true if at least one true | `{% if a or b %}` |
| Not | Inverts Boolean result | `{% if not a %}` |

## Tags reference

***

### Aggregation tags

**sum\_by** -- Sums numeric values from a field across all items in a collection.

```
{% sum_by <collection> by <field> %}
{% sum_by <collection> by <field> if <condition> %}
```

**Example:**

```xml theme={null}
<Sum>
  {% sum_by transaction.operation by "amount" if accountAlias != "@external/BRL" %}
</Sum>
```

**count\_by** -- Counts the number of items in a collection.

```
{% count_by <collection> %}
{% count_by <collection> if <condition> %}
```

**Example:**

```xml theme={null}
<Count>
  {% count_by transaction.operation if accountAlias != "@external/BRL" %}
</Count>
```

**avg\_by** -- Calculates the average of numeric values in a field.

```
{% avg_by <collection> by <field> %}
{% avg_by <collection> by <field> if <condition> %}
```

**min\_by** -- Finds the minimum numeric value in a field.

```
{% min_by <collection> by <field> %}
{% min_by <collection> by <field> if <condition> %}
```

**max\_by** -- Finds the maximum numeric value in a field.

```
{% max_by <collection> by <field> %}
{% max_by <collection> by <field> if <condition> %}
```

> [!NOTE]
>
> All aggregation tags use decimal precision to avoid floating-point rounding errors. Missing or non-numeric fields are skipped. Returns `0` if no items match.

### Date and time tag

**date\_time** -- Outputs the current date and time in the Reporter runtime's local time zone, formatted according to the provided format string.

```
{% date_time "<format>" %}
```

**Format codes:**

| Code | Meaning | Example |
| - | - | - |
| `YYYY` | 4-digit year | 2025 |
| `MM` | 2-digit month | 01-12 |
| `dd` | 2-digit day | 01-31 |
| `HH` | 2-digit hour (24h) | 00-23 |
| `mm` | 2-digit minute | 00-59 |
| `ss` | 2-digit second | 00-59 |

**Examples:**

```
{% date_time "YYYY-MM-dd" %}           --> 2025-02-06
{% date_time "dd/MM/YYYY HH:mm:ss" %} --> 06/02/2025 14:30:45
```

### Arithmetic tag

**calc** -- Evaluates mathematical expressions with support for variables from the template context.

```
{% calc <expression> %}
```

**Supported operators:**

| Operator | Description | Precedence |
| - | - | - |
| `**` | Exponentiation | Highest (right-to-left) |
| `*` `/` | Multiplication, division | Middle |
| `+` `-` | Addition, subtraction | Lowest |
| `( )` | Parentheses | Override precedence |

**Examples:**

```
{% calc 100 + 50 %}                                --> 150
{% calc balance.available * 0.5 %}                 --> calculated value
{% calc (balance.available + 1.2) * balance.on_hold - balance.available / 2 %}
```

> [!NOTE]
>
> Variables that cannot be resolved default to `0`. Division by zero produces an error.

### Grouped selection tag

**last\_item\_by\_group** -- Groups items by a field and selects the most recent item per group, ordered by a date field (descending). Optionally filters items first. Useful for regulatory reports that require the latest record per account grouped by category.

```
{% last_item_by_group <collection> group_by "<group_field>" order_by "<date_field>" [if <condition>] as <result_var> %}
```

The result is a list of items -- the latest one per group -- stored in a variable you can iterate over. Each element is the original collection record, so you access its own fields:

```
{% last_item_by_group accounts group_by "cosif_code" order_by "created_at" as latest %}
{% for account in latest %}
  {{ account.cosif_code }}: {{ account.balance }}
{% endfor %}
```

> [!NOTE]
>
> `group_by` accepts a comma-separated list of fields for composite grouping. Maximum collection size: 100,000 items. Results are sorted by the `group_by` value for deterministic output.

### Counter tags

**counter** -- Increments a named counter by 1. Produces no output. Counters are scoped per render.

```
{% counter "<counter_name>" %}
```

**counter\_show** -- Displays the sum of one or more named counters.

```
{% counter_show "<name1>" %}
{% counter_show "<name1>" "<name2>" "<name3>" %}
```

**Example:**

```
{% for tx in ledger.transactions %}
  {% counter tx.type %}
{% endfor %}
Total credits: {% counter_show "credit" %}
Total debits: {% counter_show "debit" %}
Combined: {% counter_show "credit" "debit" %}
```

## Filters reference

***

### percent\_of

Calculates the percentage of a value relative to a total. Returns a formatted string with 2 decimal places.

```
{{ value | percent_of: total }}
```

Example: if `category.amount = "6.00"` and `total.expenses = "20.00"`:

```
{{ category.amount | percent_of: total.expenses }}  --> 30.00%
```

### strip\_zeros

Removes trailing zeros from a numeric value without rounding.

```
{{ number | strip_zeros }}
```

**Examples:**

```
{{ "100.50000" | strip_zeros }}  --> 100.5
{{ "100.00" | strip_zeros }}     --> 100
{{ "99.990" | strip_zeros }}     --> 99.99
```

### decimal

Prints a number with a fixed number of decimal places, from 0 to 18.

```
{{ number | decimal:places }}
```

**Examples:**

```
{{ "100.5" | decimal:2 }}  --> 100.50
{{ 7 | decimal:0 }}        --> 7
```

Only `rjust`, `ljust`, or `center` can follow `decimal` in the same expression. Reporter refuses a template that uses `decimal` inside a `{% %}` tag.

### slice

Extracts a substring using start and end indices (0-based).

```
{{ string | slice:"start:end" }}
```

**Examples:**

```
{{ "hello" | slice:"0:3" }}  --> hel
{{ "12345" | slice:"1:4" }}  --> 234
```

### replace

Replaces all occurrences of a search string with a replacement string. Format: `"search:replacement"`.

```
{{ string | replace:"search:replacement" }}
```

**Examples:**

```
{{ "01310-100" | replace:"-:" }}      --> 01310100   (removes hyphens)
{{ "1234.56" | replace:".:," }}       --> 1234,56    (dot to comma)
{{ "12.345.678/0001-99" | replace:".:" }}  --> 12345678/0001-99
```

### where

Filters an array of objects by field equality. Supports nested fields via dot notation.

```
{{ array | where:"field:value" }}
```

**Examples:**

```
{{ holders | where:"state:SP" }}
{{ holders | where:"address.state:SP" }}
```

Use inside loops:

```
{% for holder in holders|where:"state:SP" %}
  {{ holder.name }}
{% endfor %}
```

### sum (filter)

Sums numeric values from a field across all items in an array. Uses decimal precision.

```
{{ array | sum:"field" }}
```

**Examples:**

```
{{ operations | sum:"amount" }}
{{ items | sum:"price.value" }}
```

### count (filter)

Counts elements in an array where a field matches a value. Supports nested fields.

```
{{ array | count:"field:value" }}
```

**Examples:**

```
{{ operations | count:"nat_oper:6" }}
{{ holders | count:"address.state:SP" }}
```

### add\_day

Adds a `dia` field to each row of a list. The value is the day of the named date field, as a number in `YYYYMMDD` form. Use it to group or compare rows by day.

```
{{ list | add_day:"date_field" }}
```

### add\_signed

Adds a `signed` field to each row of a list. The value is the named amount, negative when the row's `direction` is `debit`. Use it to sum a net balance.

```
{% with ops = midaz_transaction.operation|add_signed:"amount" %}
  {% sum_by ops by "signed" %}
{% endwith %}
```

### filter (function)

Returns the rows of a list whose field equals a value.

```
{% for operation in filter(midaz_transaction.operation, "transaction_id", transaction.id) %}
```

### contains

Checks if one value is partially included in another, ignoring case. Useful when data includes dynamic prefixes or suffixes.

```
{% if contains(source_field, target_field) %}
```

**Example:**

* Source: `0#@external/BRL`
* Target: `@external/BRL`

Returns `true` because `@external/BRL` exists within the source value.

## Operators and filters summary

***

| Name | Type | Description |
| - | - | - |
| `sum_by` | Tag | Sum values by field with optional filter |
| `count_by` | Tag | Count items with optional filter |
| `avg_by` | Tag | Calculate average by field |
| `min_by` | Tag | Find minimum value |
| `max_by` | Tag | Find maximum value |
| `date_time` | Tag | Format current date/time |
| `calc` | Tag | Evaluate arithmetic expressions |
| `last_item_by_group` | Tag | Latest item per group by date |
| `counter` | Tag | Increment a named counter |
| `counter_show` | Tag | Display counter value(s) |
| `percent_of` | Filter | Calculate percentage |
| `strip_zeros` | Filter | Remove trailing zeros |
| `slice` | Filter | Extract substring |
| `replace` | Filter | String replacement |
| `where` | Filter | Filter array by field value |
| `sum` | Filter | Sum array field values |
| `count` | Filter | Count matching items |
| `decimal` | Filter | Print fixed decimal places |
| `add_day` | Filter | Add a numeric day field to each row |
| `add_signed` | Filter | Add a signed amount field to each row |
| `filter` | Function | Rows whose field equals a value |
| `contains` | Function | Partial string match, ignoring case |
| `floatformat` | Filter | Round to decimal places |

## Advanced filtering

***

When generating a report, you can pass filters in the request body to narrow the data. Filters follow a structure of datasource > table > field:

**Single schema (default):**

```json theme={null}
{
  "templateId": "00000000-0000-0000-0000-000000000000",
  "filters": {
    "midaz_onboarding": {
      "account": {
        "id": { "eq": ["123", "456"] },
        "createdAt": { "between": ["2023-01-01", "2023-01-31"] },
        "status": { "in": ["active", "pending"] }
      }
    }
  }
}
```

**Multi-schema (explicit schema.table key):**

```json theme={null}
{
  "templateId": "00000000-0000-0000-0000-000000000000",
  "filters": {
    "external_db": {
      "sales.orders": {
        "total": { "gt": [100] },
        "created_at": { "gte": ["2025-01-01"] }
      },
      "finance.invoices": {
        "status": { "eq": ["paid"] }
      }
    }
  }
}
```

**Supported operators:**

| Operator | Description | Example |
| - | - | - |
| `eq` | Equal to | `{ "eq": ["active", "pending"] }` |
| `gt` | Greater than | `{ "gt": [100] }` |
| `gte` | Greater than or equal to | `{ "gte": ["2025-06-01"] }` |
| `lt` | Less than | `{ "lt": [1000] }` |
| `lte` | Less than or equal to | `{ "lte": ["2025-06-30"] }` |
| `between` | Value falls within a range | `{ "between": [100, 1000] }` |
| `in` | Value is within a list | `{ "in": ["active", "pending"] }` |
| `nin` | Value is not within a list | `{ "nin": ["deleted", "archived"] }` |


# Using Reporter
Source: https://docs.lerian.studio/en/products/reporter/using-reporter

Manage Reporter templates, generate regulatory reports on demand, track their status, and download completed files.

Use this guide for the recurring Reporter workflow: manage a template, generate a report, verify the result, and download the finished file.

## Prerequisites

Before you begin, make sure that:

* Reporter runs and you can authenticate with its API.
* An operator has configured at least one data source for the data your template queries.
* You have a `.tpl` file that matches the intended output format. For PDF output, author the template as HTML. See [Template examples](/en/products/reporter/template-examples) and the [template reference](/en/products/reporter/template-reference).

***

## Manage templates

Reporter uses uploaded `.tpl` files to define report content and layout.

### Upload a template

Call [Upload a template](/en/reference/products/reporter/upload-template) as a multipart request with all four required fields:

* `template`: the `.tpl` file.
* `outputFormat`: the generated file format, such as `HTML`, `PDF`, `XML`, `CSV`, or `TXT`.
* `description`: a human-readable description of the template.
* `category`: the report family, such as `cadoc`. Use lowercase letters, digits, underscores, and hyphens, up to 100 characters.

Reporter returns the template identifier that you use when generating reports.

### Maintain existing templates

Use the template endpoints to:

* [List templates](/en/reference/products/reporter/list-templates).
* [Retrieve template details](/en/reference/products/reporter/retrieve-template-details).
* [Update a template](/en/reference/products/reporter/update-templates).
* [Delete a template](/en/reference/products/reporter/delete-template).

Deleting a template is a soft delete. Reporter excludes it from standard queries but preserves reports already created from it.

***

## Generate a report with filters

Call [Create a report](/en/reference/products/reporter/create-report) with both required fields:

* `templateId`: the identifier returned when you uploaded the template.
* `filters`: the conditions grouped by data source, table, and field.

The following request limits the report to one transaction:

```json theme={null}
{
  "templateId": "0196159b-4f26-7300-b3d9-f4f68a7c85f3",
  "filters": {
    "midaz_transaction": {
      "transaction": {
        "id": {
          "eq": ["0196d983-a2c2-7d5a-a5b7-029fe0dcb710"]
        }
      }
    }
  }
}
```

To generate a report without filtering rows, send an empty object. Don't omit the field:

```json theme={null}
{
  "templateId": "0196159b-4f26-7300-b3d9-f4f68a7c85f3",
  "filters": {}
}
```

Reporter returns the report identifier in the `id` field. Store this value as `REPORT_ID` to check the generation status and retrieve the output.

See [Advanced filtering](/en/products/reporter/template-reference#advanced-filtering) for the supported operators and filter structure.

***

## Discover data source schemas

Inspect the configured data sources before building templates or dynamic filter interfaces:

* [List data sources](/en/reference/products/reporter/list-data-sources) returns a page of registered connections without credentials.
* [Retrieve a data source](/en/reference/products/reporter/retrieve-data-source) returns one connection configuration by `dataSourceId`. Credentials remain hidden.
* [Get a data source schema](/en/reference/products/reporter/get-data-source-schema) introspects the live tables or collections and their typed fields.

The API owns the registry lifecycle: create a data source, partially update it, test the connection, inspect its schema, or soft-delete it. Reporter refuses deletion while a live Template still references the source. A self-hosted deployment can also seed entries from `DATASOURCE_*` variables at startup.

***

## Interpret report statuses and errors

Call [Check report status](/en/reference/products/reporter/check-report-status) with `REPORT_ID`.

| Status | Meaning | What to do |
| - | - | - |
| `Processing` | Reporter is generating the file. | Keep polling with a reasonable interval. |
| `Finished` | Generation completed successfully. | Download the report. |
| `Partial` | Reporter generated only part of the requested output. | Inspect the response details and correct the failed data sections before generating again. |
| `Error` | Generation failed. | Inspect the error details, template, filters, and data source availability. |

Treat `Finished` and `Final` reports, and a `Draft` with no required field blank, as downloadable. A `Partial` result requires investigation even when Reporter produced some data.

***

## Verify and download the report

When the status is `Finished`:

1. Call [Download a report](/en/reference/products/reporter/download-report) with `REPORT_ID`.
2. Confirm that the response has the expected content type and `Content-Disposition` header.
3. Open the file and verify that its data and layout match the template and filters.

***

## Troubleshooting

| Symptom | Check |
| - | - |
| Template upload is rejected | Send `template`, `outputFormat`, `description`, and `category`, and confirm that the file uses the `.tpl` extension. |
| Report creation is rejected | Send both `templateId` and `filters`. Use `"filters": {}` when you don't need row filters. |
| Report remains in `Processing` | Check Worker health, RabbitMQ connectivity, and the referenced data sources. |
| Report ends as `Partial` | Inspect which data sections failed and verify their source, table, field, and filter names. |
| Report ends as `Error` | Check the returned error, template syntax, filter values, data source connectivity, and object storage. |
| Download is rejected | Check the latest status. Downloads are available for `Finished` and `Final` reports, and for a `Draft` with no required field blank. |

***

## Operator configuration

The following deployment settings are for operators. Application users don't need them for the report generation workflow.

### Configure object storage

Reporter stores templates and generated reports in one S3-compatible bucket. It uses the `templates/` and `reports/` prefixes. Reporter supports AWS S3, MinIO, and SeaweedFS.

| Variable | Description | Default |
| - | - | - |
| `OBJECT_STORAGE_ENDPOINT` | S3-compatible endpoint. Leave empty for AWS S3. | -- |
| `OBJECT_STORAGE_REGION` | AWS region. | `us-east-1` |
| `OBJECT_STORAGE_ACCESS_KEY_ID` | Access key. | -- |
| `OBJECT_STORAGE_SECRET_KEY` | Secret key. | -- |
| `OBJECT_STORAGE_USE_PATH_STYLE` | Uses path-style URLs. Commonly required by MinIO and SeaweedFS. | `false` |
| `OBJECT_STORAGE_DISABLE_SSL` | Uses HTTP instead of HTTPS when `OBJECT_STORAGE_ENDPOINT` has no scheme. An explicit `http://` or `https://` scheme takes precedence. | `false` |
| `OBJECT_STORAGE_BUCKET` | Bucket name. | `reporter-storage` |

> **AWS S3**
>
> ```env theme={null}
> OBJECT_STORAGE_ENDPOINT=
> OBJECT_STORAGE_REGION=us-west-2
> OBJECT_STORAGE_ACCESS_KEY_ID=AKIA...
> OBJECT_STORAGE_SECRET_KEY=your-secret-key
> OBJECT_STORAGE_USE_PATH_STYLE=false
> OBJECT_STORAGE_DISABLE_SSL=false
> OBJECT_STORAGE_BUCKET=reporter-prod-bucket
> ```

> [!WARNING]
>
> The MinIO and SeaweedFS examples below use HTTP only for local development. Production deployments require HTTPS and TLS.

> **MinIO (local development)**
>
> ```env theme={null}
> OBJECT_STORAGE_ENDPOINT=http://minio:9000
> OBJECT_STORAGE_REGION=us-east-1
> OBJECT_STORAGE_ACCESS_KEY_ID=minioadmin
> OBJECT_STORAGE_SECRET_KEY=minioadmin
> OBJECT_STORAGE_USE_PATH_STYLE=true
> OBJECT_STORAGE_DISABLE_SSL=true
> OBJECT_STORAGE_BUCKET=reporter-storage
> ```

> **SeaweedFS (local development)**
>
> ```env theme={null}
> OBJECT_STORAGE_ENDPOINT=http://reporter-seaweedfs:8333
> OBJECT_STORAGE_REGION=us-east-1
> OBJECT_STORAGE_ACCESS_KEY_ID=any
> OBJECT_STORAGE_SECRET_KEY=any
> OBJECT_STORAGE_USE_PATH_STYLE=true
> OBJECT_STORAGE_DISABLE_SSL=true
> OBJECT_STORAGE_BUCKET=reporter-storage
> ```

> [!NOTE]
>
> S3 doesn't support per-object TTL. Configure [S3 bucket lifecycle policies](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) if generated reports must expire automatically.

### Configure external data sources

Set `DATASOURCE_CRED_ENC_KEY` to a persistent hexadecimal AES key before Reporter starts. Generate a 32-byte key with `openssl rand -hex 32`. Manager and worker fail startup when the key is absent or malformed. Keep the same key available to every Reporter runtime that reads the registry, because stored passwords are encrypted with it.

Use the API for the normal data-source lifecycle. In a self-hosted deployment, you may also seed PostgreSQL or MongoDB entries at startup with `DATASOURCE_<NAME>_*` variables:

| Variable | Description | Required |
| - | - | - |
| `DATASOURCE_<NAME>_CONFIG_NAME` | Identifier used in templates, such as `midaz_onboarding`. | Yes |
| `DATASOURCE_<NAME>_HOST` | Database host. | Yes |
| `DATASOURCE_<NAME>_PORT` | Database port. | Yes |
| `DATASOURCE_<NAME>_USER` | Database user. | Only when the database requires user authentication |
| `DATASOURCE_<NAME>_PASSWORD` | Database password. | Only when the database requires password authentication |
| `DATASOURCE_<NAME>_DATABASE` | Database name. | Yes |
| `DATASOURCE_<NAME>_TYPE` | `postgresql` or `mongodb`, in lowercase. | Yes |
| `DATASOURCE_<NAME>_SSLMODE` | PostgreSQL SSL mode, such as `disable` or `require`. | PostgreSQL only |
| `DATASOURCE_<NAME>_SSLROOTCERT` | PostgreSQL root certificate path. | PostgreSQL only |
| `DATASOURCE_<NAME>_SSL` | Enables MongoDB SSL. | MongoDB only |
| `DATASOURCE_<NAME>_SSLCA` | MongoDB CA certificate path. | MongoDB only |
| `DATASOURCE_<NAME>_SSLCA_BASE64` | Standard Base64 of a PEM CA bundle, as an alternative to a certificate file path. For PostgreSQL, set `SSLMODE` to `verify-ca` or `verify-full`, or leave it empty for `verify-full`. | No |
| `DATASOURCE_<NAME>_OPTIONS` | Additional MongoDB URI options. | MongoDB only |
| `DATASOURCE_<NAME>_ROW_CEILING` | Rows one table can return. Defaults to `DATASOURCE_DEFAULT_ROW_CEILING`. | No |
| `DATASOURCE_<NAME>_QUERY_TIMEOUT_SEC` | Query timeout in seconds. Defaults to `DATASOURCE_DEFAULT_QUERY_TIMEOUT_SEC`. | No |
| `DATASOURCE_<CONFIG_NAME>_SCHEMAS` | Comma-separated PostgreSQL schemas to expose. The variable prefix derives from `CONFIG_NAME`. | PostgreSQL only |

For a source whose `CONFIG_NAME` is `midaz_onboarding`:

```env theme={null}
DATASOURCE_ONBOARDING_CONFIG_NAME=midaz_onboarding
DATASOURCE_ONBOARDING_HOST=midaz-postgres-replica
DATASOURCE_ONBOARDING_PORT=5702
DATASOURCE_ONBOARDING_USER=midaz
DATASOURCE_ONBOARDING_PASSWORD=CHANGE_ME
DATASOURCE_ONBOARDING_DATABASE=onboarding
DATASOURCE_ONBOARDING_TYPE=postgresql
DATASOURCE_ONBOARDING_SSLMODE=require
```

Reference it in a template by its `CONFIG_NAME`:

```django theme={null}
{% for account in midaz_onboarding.account %}
  {{ account.id }} - {{ account.name }}
{% endfor %}
```

For multiple PostgreSQL schemas, derive the schema variable from `CONFIG_NAME`. For example, `external_db` maps to `DATASOURCE_EXTERNAL_DB_SCHEMAS`:

```env theme={null}
DATASOURCE_EXTERNAL_CONFIG_NAME=external_db
DATASOURCE_EXTERNAL_HOST=external-postgres
DATASOURCE_EXTERNAL_PORT=5432
DATASOURCE_EXTERNAL_USER=db_user
DATASOURCE_EXTERNAL_PASSWORD=CHANGE_ME
DATASOURCE_EXTERNAL_DATABASE=external_database
DATASOURCE_EXTERNAL_TYPE=postgresql
DATASOURCE_EXTERNAL_SSLMODE=require
DATASOURCE_EXTERNAL_DB_SCHEMAS=sales,inventory,reporting
```

Use `database:schema.table` in templates and `schema.table` as the filter table key:

```django theme={null}
{% for order in external_db:sales.orders %}
  {{ order.id }} - {{ order.total }}
{% endfor %}
```

```json theme={null}
{
  "templateId": "00000000-0000-0000-0000-000000000000",
  "filters": {
    "external_db": {
      "sales.orders": {
        "created_at": { "gte": ["2025-01-01"] }
      }
    }
  }
}
```

When the schema variable isn't set, Reporter uses the `public` schema.

Manager and worker connect to a data source on demand, when a request needs it.

***

## Related tasks

* [Get started with Reporter](/en/products/reporter/reporter-quick-start)
* [Connect Reporter to Midaz](/en/products/reporter/connecting-reporter-to-midaz)
* [Build templates](/en/products/reporter/template-reference)
* [Review template examples](/en/products/reporter/template-examples)


# Reporter in Lerian Console
Source: https://docs.lerian.studio/en/products/reporter/using-reporter-in-lerian-console

Manage templates, generate reports, and download results in Reporter through the Lerian Console. No API calls or local tooling required.

Reporter is available as a product module within the [Lerian Console](/en/platform/console/about-lerian-console), the unified web interface for managing all Lerian products.

Through the Console, you can manage templates, generate reports, and download results from a single interface.

> **[Reporter in Lerian Console](/en/products/reporter/console/reporter-module)**
>
> Access the full documentation for using Reporter in the Lerian Console.

## Available actions

***

From the Lerian Console, you can:

* [Manage templates](/en/products/reporter/console/managing-templates): Upload, update, and delete `.tpl` template files
* [Manage reports](/en/products/reporter/console/managing-reports): Generate, track, and download reports


# What is Reporter?
Source: https://docs.lerian.studio/en/products/reporter/what-is-reporter

Turn financial data into repeatable business and operational reports with Reporter: reusable templates, automated rendering, and BACEN-ready output.

Reporter is Lerian's licensed reporting engine. It turns data from your
financial systems into repeatable reports based on plain-text `.tpl` templates.
You define the document structure once, then generate updated outputs whenever
you need them.

Reporter can render HTML, CSV, XML, PDF, and TXT files. Lerian licenses
Reporter to institutions and maintains its source code in a private repository.

## What you can use Reporter for

Reporter gives product, operations, and engineering teams a shared way to
produce consistent documents from changing data. You can use it to:

* Replace recurring manual report assembly with a repeatable process
* Keep document structure separate from the data used to populate it
* Reuse a template across reporting periods and data sets
* Produce several output formats through one reporting workflow
* Store templates and generated files for later retrieval

## Problems Reporter solves

Reporter separates data extraction, document formatting, and delivery. Data
sources provide the values, templates describe the output, and the rendering
workflow produces the final file. This separation helps you update a layout
without rebuilding the data integration, or connect new data without
redesigning every report.

## How Reporter works

Each report follows the same flow:

1. You create or select a `.tpl` template.
2. You request a report with the relevant parameters and filters.
3. Reporter retrieves data from configured PostgreSQL or MongoDB sources.
4. The template engine applies the document logic and renders the output.
5. Reporter stores the generated file and makes it available to the requesting
   system.

![Reporter workflow from a template and configured data sources to a generated report](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/reporter-workflow.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=c1e8c0d4649fd75eecdb139e3ba465b9)

## Core capabilities

* **Template-driven reports:** Define layouts and document logic in reusable
  `.tpl` files.
* **Multiple data sources:** Read report data from PostgreSQL and MongoDB.
* **Flexible document logic:** Build conditional sections, repeated content,
  calculations, and aggregations into templates.
* **Multiple output formats:** Generate HTML, CSV, XML, PDF, or TXT files.
* **Asynchronous processing:** Run report generation outside the request path
  when a workload requires background processing.
* **Durable artifacts:** Keep templates and generated reports in
  S3-compatible object storage.
* **Regulatory filing cycle:** When the deployment carries a curated
  regulatory catalog, subscribe to a document, map its fields to your tables,
  and turn each generated draft into an approved filing with a provenance record.
* **API-based operation:** Create templates, request reports, and retrieve
  results through the Reporter API.

## Architecture and deployment model

Reporter keeps data access, template processing, storage, and API delivery as
separate responsibilities:

* The data layer connects to configured PostgreSQL and MongoDB sources.
* The template layer resolves data and renders the requested format.
* The storage layer uses an S3-compatible service for templates and outputs.
* The API layer exposes reporting resources to applications and operators.

![Reporter architecture with data, template processing, storage, and API layers](https://mintcdn.com/lerian-49cb71fc/L6O4e7zHOgclCLRh/images/en/d2/reporter-layers.svg?fit=max\&auto=format\&n=L6O4e7zHOgclCLRh\&q=85\&s=d75f7a4dba14864f5c374e3f43011a3b)

You deploy Reporter alongside the databases and object storage it needs to
reach. The exact topology depends on your environment and operational model.

Reporter can integrate with [Access Manager](/en/platform/access-manager)
to control access to reporting resources. Whether that integration is enabled,
and which policies apply, depends on your deployment and licensed offering.

## Next steps

> **[Start with Reporter](/en/products/reporter/reporter-quick-start)**
>
> Complete the shortest path from access to a generated report.

> **[Connect Reporter to Midaz](/en/products/reporter/connecting-reporter-to-midaz)**
>
> Understand how Reporter reads data from a Midaz deployment.

> **[Use Reporter](/en/products/reporter/using-reporter)**
>
> Follow task-oriented guidance for templates, data sources, and reports.

> **[Explore template capabilities](/en/products/reporter/template-reference)**
>
> Review the available template tags, filters, and expressions.


# Audit and compliance
Source: https://docs.lerian.studio/en/products/tracer/audit-compliance

Understand how Tracer's immutable, hash-chained audit trail works, and query validation history for compliance reporting.

Auditors, compliance officers, and disputes teams use this layer to answer one question: *"Why did this transaction get this decision?"*

**What changes in your operation:** evidence of a control goes from "let me pull logs from N systems and reconcile timestamps" to "here is the immutable record, cryptographically chained, showing that this transaction got this decision because this specific rule fired at this moment."

**Trade-off:** there is no "delete" or "edit" on audit records, by design. A `TRUNCATE` trigger at the database level blocks bulk deletion. Each record's SHA-256 hash includes the previous record's hash, so removing or re-dating a record breaks the chain everywhere downstream. If you need to remove a record for legal reasons (such as GDPR right-to-be-forgotten on PII), the answer is data minimization upfront, not retroactive editing.

> [!TIP]
>
> **Who is this guide for?** Compliance officers and auditors checking what Tracer guarantees, disputes teams looking up validation history, and developers building reports against the audit endpoints. The retention section assumes zero API knowledge. The query and verify sections assume basic REST.

Tracer maintains an immutable audit trail (A chronological, immutable record of every action and transaction in the system, essential for regulatory compliance and dispute resolution.) of validation decisions. This guide explains how the audit system works and how to query validation history for compliance reporting.

## Audit trail architecture

***

Tracer records `POST /v1/validations` decisions with full context for compliance and investigation.

### What gets recorded

The audit record of a validation contains:

| Data | Description |
| - | - |
| **Request snapshot** | Complete input payload as received |
| **Response snapshot** | Full response including decision and details |
| **Decision** | ALLOW, DENY, or REVIEW |
| **Reason** | Why the decision was made |
| **Evaluated rules** | All rules that were evaluated |
| **Matched rules** | Rules that triggered (if any) |
| **Limit details** | Usage information for checked limits |
| **Processing time** | How long validation took |
| **Timestamp** | When the validation occurred |

> [!NOTE]
>
> Audit events are deduplicated for transaction validations. If you retry a validation request with the same `requestId`, Tracer stores only the first audit event. This ensures the audit trail reflects unique business events, not API retry patterns.

### Immutability and hash chain

Audit records are write-once and cryptographically chained:

* You cannot modify a record after creation.
* A `TRUNCATE` trigger protects the audit table at the database level and blocks bulk deletion.
* Each record stores a SHA-256 hash computed over the record's identity, timestamp, actor, and the previous record's hash, forming an append-only chain. Removing, re-ordering, or re-dating a record makes every later record fail verification.
* A `pg_advisory_xact_lock` serializes hash-chain writes to keep the order stable under concurrent inserts.

You can verify the chain at any time using `GET /v1/audit-events/{id}/verify`, which returns:

```json theme={null}
{
  "isValid": true,
  "totalChecked": 12345,
  "message": "Hash chain integrity verified successfully"
}
```

The check covers the chain from its first record up to and including the record you name. When every hash still matches, `isValid` is `true` and `message` confirms it. When a record no longer matches its stored hash, `isValid` is `false`. The `message` field reports tampering.

On a failed check, `firstInvalidId` carries an internal sequence number for the diverging record. It is not an audit-event id, so it is not a value you can pass to `GET /v1/audit-events/{id}`.

***

## Data retention

***

### Retention periods

| Data type | Retention period | Reason |
| - | - | - |
| **Rules (active/inactive)** | Indefinite | Operational continuity |
| **Rules / Limits (deleted)** | Soft-deleted: row kept indefinitely for audit, excluded from API listings | Compliance trail must outlive operational visibility |
| **Limits** | Indefinite | Operational continuity |

***

## Querying validation history

***

Use the `GET /v1/validations` endpoint to query historical validations.

### Basic query

```http theme={null}
GET /v1/validations
X-API-Key: {api_key}
```

Returns validations in cursor-paginated reverse chronological order.

> [!WARNING]
>
> **A query with no dates covers the last 90 days, not the full retention period**. Tracer applies that default window only when both `start_date` and `end_date` are absent. Send either one, or both, to query an older range. With only `start_date`, the range runs forward from that date with no end. With only `end_date`, the range runs backward from that date with no start.

### Filtered query

```http theme={null}
GET /v1/validations?start_date=2026-01-01T00:00:00Z&end_date=2026-01-31T23:59:59Z&decision=DENY
X-API-Key: {api_key}
```

### Available filters

| Parameter | Type | Description |
| - | - | - |
| `start_date` | RFC3339 | Start of date range (inclusive). Defaults to 90 days ago when neither date is supplied |
| `end_date` | RFC3339 | End of date range (inclusive). Defaults to the end of today when neither date is supplied |
| `decision` | enum | Filter by ALLOW, DENY, or REVIEW |
| `account_id` | UUID | Filter by account |
| `segment_id` | UUID | Filter by segment |
| `portfolio_id` | UUID | Filter by portfolio |
| `transaction_type` | enum | Filter by CARD, WIRE, PIX, CRYPTO |
| `matched_rule_id` | UUID | Filter by rule that matched |
| `exceeded_limit_id` | UUID | Filter by limit that was exceeded |

### Date format requirement

> [!WARNING]
>
> Date parameters must use RFC3339 format with mandatory timezone. Tracer rejects date-only formats.

**Valid:**

```
start_date=2026-01-01T00:00:00Z
start_date=2026-01-01T00:00:00-03:00
```

**Invalid:**

```
start_date=2026-01-01  (rejected - missing time and timezone)
```

### Pagination

Results use cursor-based pagination. The response includes `nextCursor` and `hasMore` fields to navigate through results.

| Parameter | Default | Maximum | Description |
| - | - | - | - |
| `limit` | 100 | 1000 | Results per page |
| `cursor` | - | - | Pagination cursor from previous response |

> [!NOTE]
>
> Cursor pagination keeps `sort_by` and `sort_order` from the original query.

### Sorting

```http theme={null}
GET /v1/validations?sort_by=created_at&sort_order=DESC
```

| Parameter | Options | Default |
| - | - | - |
| `sort_by` | `created_at`, `processing_time_ms` | `created_at` |
| `sort_order` | ASC, DESC | DESC |

***

## Getting validation details

***

Retrieve complete details for a specific validation using `GET /v1/validations/{id}`.

The response contains everything needed to understand a validation decision:

* **Request snapshot**: The complete input payload as received
* **Response snapshot**: Full response including decision and reason
* **Evaluated rules**: All rules that Tracer checked
* **Matched rules**: Rules that triggered (if any)
* **Limit details**: Usage information for checked limits
* **Timestamps**: When the validation occurred and processing time

***

## Querying audit events

***

Beyond validation records, Tracer also exposes a generic audit event log via `GET /v1/audit-events`. This is the only way to see lifecycle changes for rules and limits: who created, updated, activated, deactivated, drafted, or deleted them.

### Event types

| `eventType` | When emitted |
| - | - |
| `TRANSACTION_VALIDATED` | A validation request was processed (also available via `GET /v1/validations`) |
| `RULE_CREATED` / `RULE_UPDATED` | Rule created or modified |
| `RULE_ACTIVATED` / `RULE_DEACTIVATED` | Rule moved into ACTIVE / INACTIVE |
| `RULE_DRAFTED` | Rule moved from INACTIVE back to DRAFT for re-editing |
| `RULE_DELETED` | Rule soft-deleted |
| `LIMIT_CREATED` / `LIMIT_UPDATED` | Limit created or modified |
| `LIMIT_ACTIVATED` / `LIMIT_DEACTIVATED` | Limit moved into ACTIVE / INACTIVE |
| `LIMIT_DRAFTED` | Limit moved from INACTIVE back to DRAFT for re-editing |
| `LIMIT_DELETED` | Limit soft-deleted |
| `RESERVATION_RESERVED` / `RESERVATION_CONFIRMED` / `RESERVATION_RELEASED` / `RESERVATION_EXPIRED` | Two-phase reservation lifecycle on the ledger seam: capacity held, committed, returned on abort, or expired |

### Filters

`GET /v1/audit-events` accepts the same date-range and scope filters as `GET /v1/validations`, plus filters tailored to lifecycle events:

| Parameter | Type | Description |
| - | - | - |
| `start_date` / `end_date` | RFC3339 | Date range (both inclusive). With neither supplied, the query covers the last 90 days |
| `event_type` | enum | `TRANSACTION_VALIDATED`, or a rule, limit, or reservation event type |
| `action` | enum | `VALIDATE`, `CREATE`, `UPDATE`, `DELETE`, `ACTIVATE`, `DEACTIVATE`, `DRAFT`, `RESERVE`, `CONFIRM`, `RELEASE`, `EXPIRE`, `SKIP` |
| `result` | enum | `SUCCESS`, `FAILED` (for CRUD) or `ALLOW`, `DENY`, `REVIEW` (for validations) |
| `resource_type` | enum | `transaction`, `rule`, `limit`, `reservation` |
| `resource_id` | UUID | The affected resource ID |
| `actor_type` / `actor_id` | string | `user`, `api_key`, or `system`, plus the actor ID |
| `account_id` / `segment_id` / `portfolio_id` / `transaction_type` / `matched_rule_id` | UUID/enum | Same scope filters as validations |
| `limit`, `cursor`, `sort_by`, `sort_order` | — | Cursor pagination (default `limit` 100, max 1000; `sort_by` accepts `created_at` or `event_type`) |

### Use cases

* **Who activated this rule?** `GET /v1/audit-events?resource_type=rule&resource_id={ruleId}&action=ACTIVATE`
* **All rule changes last week:** `GET /v1/audit-events?resource_type=rule&start_date=...&end_date=...`
* **All limit deletions in 2026:** `GET /v1/audit-events?resource_type=limit&action=DELETE&start_date=2026-01-01T00:00:00Z`

### Single event detail

Use `GET /v1/audit-events/{id}` to retrieve a specific audit record, including the snapshot of state at the time of the event.

***

## Compliance reporting scenarios

***

Common queries for audit and compliance reporting.

### Scenario 1: Audit investigation

"Why was this transaction denied on January 15th?"

```http theme={null}
GET /v1/validations/{id}
```

The response shows the exact request received, all rules evaluated, which rule or limit caused the denial, and the timestamp.

### Scenario 2: Monthly compliance report

"Show all denied transactions for corporate accounts in January"

```http theme={null}
GET /v1/validations?start_date=2026-01-01T00:00:00Z&end_date=2026-02-01T00:00:00Z&decision=DENY&segment_id=corporate-segment-uuid&limit=1000
```

### Scenario 3: Rule effectiveness analysis

"Which transactions were denied by a specific fraud rule?"

```http theme={null}
GET /v1/validations?matched_rule_id=fraud-rule-uuid&decision=DENY&limit=1000
```

### Scenario 4: Limit usage review

"Which transactions exceeded spending limits this month?"

```http theme={null}
GET /v1/validations?start_date=2026-01-01T00:00:00Z&end_date=2026-02-01T00:00:00Z&exceeded_limit_id=daily-limit-uuid
```

***

## Best practices for compliance

***

Recommendations for maintaining audit readiness.

### Record keeping

* **Store validation IDs** in your transaction records for easy cross-reference
* **Log the requestId** you send to Tracer for correlation
* **Export regularly** if you need records in external audit systems

> [!WARNING]
>
> **Common pitfalls when reading the audit trail:**
>
> * **"I can see the validation but the rule that fired was already deleted."** Deleted rules are soft-deleted. The row stays in the database, but it doesn't appear in `GET /v1/rules`. To investigate, query `GET /v1/audit-events?resource_type=rule&resource_id={ruleId}` for the lifecycle of that rule, including its activations and the eventual delete.
> * **"Two retries of the same `requestId` only produced one audit event."** This is by design (deduplication via `idx_audit_events_validation_dedup`). The audit trail reflects unique business events, not API retry patterns. If your retry produced a different decision, that's worth investigating. Tracer should return the original cached response.
> * **"`/verify` says the chain is broken on a record I haven't touched."** The chain links every record to the previous one, so a tamper or DB corruption anywhere makes everything downstream report invalid. Run `/verify` against progressively earlier records to bracket where the chain first breaks.
> * **"My audit query came back empty for last year."** A query with no `start_date` and no `end_date` covers the last 90 days. Supply the range you want.

### Audit preparation

* **Test queries** before audit season to ensure you can retrieve needed data
* **Verify date ranges** work correctly with your timezone requirements

### Investigation workflow

When investigating a specific transaction:

1. **Find the validation ID** from your transaction logs or Tracer history
2. **Retrieve full details** using GET /v1/validations/
3. **Review the request snapshot** to see the data in the request
4. **Check matched rules** to understand the reason for the decision
5. **Verify limit status** if limits apply

***

## No-match behavior and audit

***

When a validation runs and no rule matches, Tracer returns a configured default decision instead of treating the empty match as an error. This is a **per-request fallback**, not an infrastructure resilience strategy.

The `DEFAULT_DECISION_WHEN_NO_MATCH` environment variable governs the decision (default: `ALLOW`).

| Scenario | Behavior | Audit record |
| - | - | - |
| No rules match | Returns `DEFAULT_DECISION_WHEN_NO_MATCH` (default `ALLOW`) | Recorded with `reason: "No matching rules found"` |
| Evaluation timeout | Returns HTTP 504 with error code `0422` | No validation record; an audit failure event may be emitted |
| Database error during limit check | Returns HTTP 500; the entire validation transaction is rolled back | No validation record persisted |

> [!NOTE]
>
> Set `DEFAULT_DECISION_WHEN_NO_MATCH=DENY`. The service logs a warning at startup if this remains at the default `ALLOW`.

Infrastructure failures (database down, cache stale, timeout) do **not** fall back to ALLOW. They surface as HTTP errors to the client, and the original transaction has no audit record. Operators should monitor `tracer_audit_persist_failures_total` and the `/readyz` endpoint to detect these cases.

***

## Quick reference

***

Key endpoints and retention information.

### Endpoints

| Operation | Method | Endpoint |
| - | - | - |
| List validations | GET | `/v1/validations` |
| Get validation | GET | `/v1/validations/{id}` |
| List audit events | GET | `/v1/audit-events` |
| Get audit event | GET | `/v1/audit-events/{id}` |
| Verify hash chain | GET | `/v1/audit-events/{id}/verify` |

### Retention summary

| Data | Retention |
| - | - |
| Active rules/limits | Indefinite |


# Managing limits
Source: https://docs.lerian.studio/en/products/tracer/console/managing-limits

Create, filter, activate, and edit Tracer spending limits in Lerian Console with period-based caps, scope conditions, and DRAFT to ACTIVE lifecycle controls.

Use the **Limits** page to define spending caps by period and transaction context.

## Accessing the Limits page

***

In the Tracer sidebar, select **Limits**. The page opens as **Transaction Limits** with the helper **What is a Limit?**.

## Available filters

***

| Filter | Options |
| - | - |
| **Search** | Search by name and account ID |
| **Status** | All, Active, Inactive, Draft |
| **Period** | All Periods, Daily, Weekly, Monthly, Custom, Per Transaction |
| **Type** | All Types, PIX, Card, Wire, Crypto |

Items per page is also configurable.

## Limit cards

***

Each card shows:

* Limit name and limit type.
* Max amount and asset.
* Limit status (`ACTIVE`, `INACTIVE`, `DRAFT`).
* Scope badges (when configured).
* Action menu.

## Limit actions

***

| Action | Behavior |
| - | - |
| **Details** | Opens the limit side panel |
| **Activate** | Moves limit to `ACTIVE` |
| **Deactivate** | Moves limit to `INACTIVE` |
| **Move to Draft** | Available for `INACTIVE` limits; returns to `DRAFT` |
| **Delete** | Permanently deletes limit with confirmation |

> [!WARNING]
>
> Deactivate an `ACTIVE` limit before you move it back to `DRAFT`.

## Creating a new limit

***

**Step 1**

Click **New Limit**.

**Step 2**

Fill the side panel:

| Field | Required | Notes |
| - | - | - |
| **Name** | Yes | Limit name |
| **Description** | No | Limit context |
| **Limit Type** | Yes | `DAILY`, `WEEKLY`, `MONTHLY`, `CUSTOM`, `PER_TRANSACTION`. `CUSTOM` reveals **Start Date** and **End Date** fields. |
| **Asset** | Yes | `BRL`, `USD`, `EUR` |
| **Max Amount** | Yes | Numeric max amount |
| **Active Time Window** | No | Reveals **Start Time (UTC)** and **End Time (UTC)**. Tracer skips the limit for transactions outside the window. |
| **Scope** | Yes | Groups of conditions. See [Scope](#scope). |

**Step 3**

Click **Create**.

New limits start in `DRAFT` status.

## Editing a limit

***

Open **Details** to edit. The Console only allows saving changes for `DRAFT` limits and shows **Only draft limits can be edited** otherwise.

You cannot change `Limit Type` and `Asset` on an existing limit.

The Console has no reset time field. To start periods at another time of day, create the limit through the API with `resetTime`. See [Reset time](/en/products/tracer/spending-limits#reset-time).

## Scope

***

A limit needs at least one group. **Add Group** adds a group of conditions. Inside a group, **Add Condition** adds a row with a scope type and a value. Each scope type appears once per group.

| Scope type | Input |
| - | - |
| Account | UUID |
| Merchant | UUID |
| Segment | UUID |
| Portfolio | UUID |
| Transaction type | Selector (`CARD`, `PIX`, `WIRE`, `CRYPTO`) |
| Sub type | Text |

All conditions in a group must match. One matching group is enough, and the Console shows **OR** between groups. Each group saves as one scope object.

For every limit type except `PER_TRANSACTION`, the Console notes that usage counts separately for the accounts, portfolios, segments, and merchants each group names. Transaction type does not split the count.

## Related

***

* [Spending limits](/en/products/tracer/spending-limits) - Conceptual guide
* [Create limit](/en/reference/products/tracer/create-limit) - API reference
* [Update limit](/en/reference/products/tracer/update-limit) - API reference
* [Retrieve limit usage](/en/reference/products/tracer/retrieve-limit-usage) - API reference


# Managing rules
Source: https://docs.lerian.studio/en/products/tracer/console/managing-rules

Create, filter, activate, and edit Tracer decision rules in Lerian Console with CEL expression validation, ALLOW/DENY/REVIEW actions, and scope conditions.

Use the **Rules** page to create and operate Tracer decision rules. A rule combines expression logic, decision action, and optional scope.

## Accessing the Rules page

***

In the Tracer sidebar, select **Rules**. The page opens as **Fraud Detection Rules** with the inline helper **What is a Rule?**.

## Available filters

***

Use the filter bar at the top:

| Filter | Options |
| - | - |
| **Search** | Search by rule name |
| **Status** | All, Active, Inactive, Draft |
| **Decision** | All, Allow, Deny, Review |
| **Transaction Type** | All Types, Card, PIX, Wire, Crypto |

You can also choose items per page.

## Rule cards

***

Each card shows:

* Rule name.
* Rule status (`ACTIVE`, `INACTIVE`, `DRAFT`).
* Rule action (`ALLOW`, `DENY`, `REVIEW`).
* Description (when provided).
* Rule expression.
* Last update date.

## Rule actions

***

The action menu on each card supports:

| Action | Behavior |
| - | - |
| **Details** | Opens the rule side panel |
| **Activate** | Moves rule to `ACTIVE` |
| **Deactivate** | Moves rule to `INACTIVE` |
| **Move to Draft** | Available for `INACTIVE` rules; returns to `DRAFT` |
| **Delete** | Permanently deletes rule with confirmation |

> [!WARNING]
>
> Deactivate an `ACTIVE` rule before you move it back to `DRAFT`.

## Creating a new rule

***

**Step 1**

Click **New Rule**.

**Step 2**

Complete the side panel fields:

| Field | Required | Notes |
| - | - | - |
| **Name** | Yes | Rule name |
| **Description** | No | Rule context |
| **Expression** | Yes | Evaluated with real-time validation |
| **Action** | Yes | `ALLOW`, `DENY`, or `REVIEW` |
| **Scope** | No | Groups of conditions. See [Scope](#scope). |

**Step 3**

Click **Create**.

New rules start in `DRAFT` status.

## Editing a rule

***

Open **Details** to edit. The Console only allows saving changes for `DRAFT` rules. Other statuses show **Only draft rules can be edited**.

## Scope

***

**Add Group** adds a group of conditions. Inside a group, **Add Condition** adds a row with a scope type and a value. Each scope type appears once per group.

| Scope type | Input |
| - | - |
| Account | UUID |
| Merchant | UUID |
| Segment | UUID |
| Portfolio | UUID |
| Transaction type | Selector (`CARD`, `PIX`, `WIRE`, `CRYPTO`) |
| Sub type | Text |

All conditions in a group must match. One matching group is enough, and the Console shows **OR** between groups. Each group saves as one scope object.

A rule with no group applies to all transactions. To save it, select **This rule applies to all transactions**.

## Related

***

* [Rule engine](/en/products/tracer/rule-engine) - Conceptual behavior
* [Create rule](/en/reference/products/tracer/create-rule) - API reference
* [Update rule](/en/reference/products/tracer/update-rule) - API reference


# Managing validations
Source: https://docs.lerian.studio/en/products/tracer/console/managing-validations

Inspect Tracer validation history in Lerian Console with search, date and decision filters, evaluated rules, and detailed transaction decision panels.

The **Validations** page is read-only and focused on investigation. It lists validation decisions produced by Tracer for each evaluated transaction.

> [!NOTE]
>
> You cannot create, edit, or delete validation records from this page.

## Accessing the Validations page

***

In the Tracer sidebar, select **Validations**. The page opens as **Transaction Validations** with the helper **What is a Validation?**.

## Available filters

***

| Filter | Options |
| - | - |
| **Search** | Search by ID, reason, or rule name |
| **Start date** | Start datetime |
| **End date** | End datetime |
| **Decision** | All, Approved, Blocked, Review |
| **Type** | All Types, Card, PIX, Wire, Crypto |

Use **Refresh** to reload the data.

## Main table

***

Each row displays:

* Validation ID.
* Decision label.
* Transaction type.
* Amount and asset.
* Decision reason.
* Validation timestamp.
* View action.

Decision mapping:

| Internal value | Console label |
| - | - |
| `ALLOW` | Approved |
| `DENY` | Blocked |
| `REVIEW` | Review |

## Validation details panel

***

Open a row to see **Transaction Details**:

* Hero header with amount and decision.
* ID and date.
* Transaction type and reason.
* Account ID (when present).
* Evaluated rules with `Matched` and `Passed` markers.
* Processing time in milliseconds.

## Related

***

* [Audit and compliance](/en/products/tracer/audit-compliance) - Conceptual guide
* [Integration guide](/en/products/tracer/integration-guide) - Validation generation flow
* [Retrieve validation](/en/reference/products/tracer/retrieve-validation) - API reference
* [List validations](/en/reference/products/tracer/list-validations) - API reference


# Tracer module overview
Source: https://docs.lerian.studio/en/products/tracer/console/tracer-module

Open the Tracer module in Lerian Console: the dashboard shows what Tracer decided over a period, and the module pages manage rules, limits, and validations.

**Tracer** is available as a product module in Lerian Console for real-time transaction control. In this module, you manage decision rules, spending limits, and validation history from one operational surface.

> [!WARNING]
>
> Tracer is available only if your organization has purchased the product. Need access? [Contact our team](https://lerian.studio/contact).

## Accessing Tracer

***

Open the product launcher in Lerian Console and select **Tracer**.

## Dashboard

***

With Tracer 4.1.0 or later, the module opens on the **Dashboard**. The dashboard shows what Tracer decided over a period. With an earlier Tracer version, the module opens on a cover page with links to **Rules**, **Limits**, and **Validations**.

Select the period at the top: **Last 7 days**, **Last 30 days**, or **Last 90 days**. The default is the last 30 days.

The dashboard shows:

* **Transactions Processed**, **Fraud Rate**, and **Avg Decision Time**.
* **My Operation**: **Approval Rate**, **Blocked Frauds** with the blocked amount of each asset, **Manual Review Rate**, and **Manual Reviews**.
* **Active Rules** and **Active Limits**.
* The **Validations per Day** and **Flagged Traffic by Type** charts.
* The **Busiest Rules** table.

If a dashboard read fails, a notice with a **Retry** button replaces the figures. The period buttons stay available.

With Access Manager, the dashboard needs the read permission on the Tracer dashboard resource.

## Available pages

***

### Rules and limits

> **[Rules](/en/products/tracer/console/managing-rules)**
>
> Manage rule logic, decision action, lifecycle status, and optional scope conditions.

> **[Limits](/en/products/tracer/console/managing-limits)**
>
> Configure period-based spending caps with controlled activation and scope filtering.

### Audit and investigation

> **[Validations](/en/products/tracer/console/managing-validations)**
>
> Inspect validation decisions, reason, transaction type, and evaluated rules in detail.

> **[Tracer Documentation](/en/products/tracer/what-is-tracer)**
>
> Access conceptual guides and API references for Tracer.

## Related

***

* [What is Tracer](/en/products/tracer/what-is-tracer) - Product overview
* [Getting started](/en/products/tracer/getting-started) - Initial setup
* [Integration guide](/en/products/tracer/integration-guide) - Connect Tracer to your systems


# Creating a rule from a policy
Source: https://docs.lerian.studio/en/products/tracer/creating-a-rule-from-a-policy

Turn a written policy sentence into a live Tracer rule: map it to fields, create it as a draft, rehearse it on a test account, activate it, and change or retire it later.

A compliance officer hands over a sentence: *"decline card-not-present purchases above BRL 5,000 from a device we have not seen before."*

This guide turns that sentence into a rule that evaluates the way the policy reads. You rehearse it where it reaches nobody, then put it live.

**What changes in your operation:** the policy stops living in a ticket and starts living in an endpoint. The person who wrote the sentence can read the rule back. The rehearsal runs through real evaluation instead of a spreadsheet. Each change to the rule leaves an audit event behind it.

> [!TIP]
>
> **Who is this guide for?** Risk and fraud analysts authoring rules, and the developers who wire the policy fields into the validation request. Steps 1 and 2 are about the policy. Steps 3 to 8 are API calls.

## Before you start

***

* [ ] Tracer running and reachable, with an API key. See [Getting started](./getting-started.mdx)
* [ ] The CEL (A lightweight expression language for writing business rules, for example, 'if transaction amount > 10000 then REVIEW'. Tracer uses CEL for validation rules.) variables and the scope model. See [Rules engine](./rule-engine.mdx)
* [ ] A test account id you can send validations for, that no customer traffic uses
* [ ] The policy sentence, written down, with whoever wrote it available for one question

All calls below send the API key as `X-API-Key`.

***

## Step 1: Map the sentence onto fields

***

A rule reads what the validation request carries. Take the sentence apart clause by clause and put each one in the column it belongs to.

| Clause in the policy | Where the value comes from | Reads as |
| - | - | - |
| "card ... purchases" | `transactionType`, a Tracer enum | `CARD` |
| "above BRL 5,000" | `amount` and `asset` on the request | `amount`, `asset` |
| "card-not-present" | `subType`, free-form text your integration sets | `subType` |
| "a device we have not seen before" | metadata (Additional key-value information attached to entities like accounts or transactions, such as external IDs, reference numbers, or department codes.), which your integration sets | `metadata.deviceFirstSeen` |

The first two are fields Tracer defines. The last two are fields your integration has to send. Tracer has no opinion about what "card-not-present" or "new device" mean. That is the question to take back to whoever wrote the policy: *which flag in our payload says the device is new?*

> [!NOTE]
>
> `subType` reaches expressions in lower case, so `"card_not_present"` is the form to compare against. If your integration already uses `subType` for something else, carry the entry mode in `metadata` instead and match on that. Both work the same way in an expression.

For the full variable list and the fields each context map carries, see [Rules engine](./rule-engine.mdx#expressions).

***

## Step 2: Split the rule between scope and expression

***

Two things in that table (the transaction type and the account) are things Tracer can filter on before an expression runs. Those belong in the rule's `scopes`. The value comparisons belong in the `expression`.

**Scope**, which decides *whether the rule is considered at all*:

```json theme={null}
"scopes": [{ "transactionType": "CARD" }]
```

**Expression**, which decides *whether the rule fires*:

```cel theme={null}
subType == "card_not_present" && amount > 5000 && metadata.deviceFirstSeen == true
```

Read the expression against the sentence: entry mode, threshold, and the device flag. `amount > 5000` is strictly above, so a transaction of exactly `5000.00` does not fire it. Check that against the policy before you go further, because "above" and "from" are different rules.

A rule that reads a metadata key the request does not carry does not match, and the other rules still run. So the expression above needs no presence test for `deviceFirstSeen`. See [Rules engine](./rule-engine.mdx#expressions).

> [!WARNING]
>
> Do not repeat scope conditions inside the expression. `transactionType == "CARD"` in both places is not wrong. It leaves two places to edit when the policy changes, and the expression is the one that needs a lifecycle round-trip to edit.

***

## Step 3: Create the rule as a draft

***

`POST /v1/rules` creates the rule in `DRAFT`. A draft never reaches evaluation, so nothing you do here reaches traffic.

```bash theme={null}
curl -X POST http://localhost:4020/v1/rules \
  -H "X-API-Key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Deny CNP card purchases above BRL 5,000 from a new device",
    "description": "Compliance policy 2026-14, approved 2026-07-20",
    "expression": "subType == \"card_not_present\" && amount > 5000 && metadata.deviceFirstSeen == true",
    "action": "DENY",
    "scopes": [
      { "transactionType": "CARD", "accountId": "8a1f2c34-5d6e-4a7b-8c9d-0e1f2a3b4c5d" }
    ]
  }'
```

The `accountId` in that scope is your test account. It is what keeps Step 4 off customer traffic. Step 5 takes it out.

A `201` answers with the stored rule:

```json theme={null}
{
  "ruleId": "4d9c2e70-8b1a-4f36-9c07-5e2a1b3d4f68",
  "name": "Deny CNP card purchases above BRL 5,000 from a new device",
  "description": "Compliance policy 2026-14, approved 2026-07-20",
  "expression": "subType == \"card_not_present\" && amount > 5000 && metadata.deviceFirstSeen == true",
  "action": "DENY",
  "scopes": [
    { "transactionType": "CARD", "accountId": "8a1f2c34-5d6e-4a7b-8c9d-0e1f2a3b4c5d" }
  ],
  "status": "DRAFT",
  "createdAt": "2026-07-31T11:04:12.318Z",
  "updatedAt": "2026-07-31T11:04:12.318Z"
}
```

Tracer preserves the name's case and internal whitespace. It trims leading and trailing whitespace before storage. Rule-name uniqueness is case-sensitive within the context derived from the rule's scopes. So `FraudRule` and `fraudrule` are different names, and the same name can coexist in different contexts.

Take the `ruleId` from the response. That is the handle every call below uses. See [Create a rule](/en/reference/products/tracer/create-rule).

The expression compiles on this call, so an expression that cannot run never becomes a draft. A syntax error answers `0340`, an expression that does not return a boolean answers `0341`, and one whose estimated cost is above `CEL_COST_LIMIT` answers `0342`.

***

## Step 4: Rehearse it on an account nobody else uses

***

The scope you set is what keeps the rehearsal contained. The rule reaches evaluation only for transactions on that one test account. Activation puts it in front of exactly the traffic you send it.

**1. Activate the scoped rule**

```bash theme={null}
curl -X POST http://localhost:4020/v1/rules/4d9c2e70-8b1a-4f36-9c07-5e2a1b3d4f68/activate \
  -H "X-API-Key: your-secure-api-key"
```

The response comes back with `status: "ACTIVE"` and an `activatedAt`. See [Activate a rule](/en/reference/products/tracer/activate-rule).

**2. Send a transaction the policy should decline**

```bash theme={null}
TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)

curl -X POST http://localhost:4020/v1/validations \
  -H "X-API-Key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "c1a7f402-6b93-4d5e-8f10-2a4c6e8b0d31",
    "transactionType": "CARD",
    "subType": "card_not_present",
    "amount": "7500.00",
    "asset": "BRL",
    "transactionTimestamp": "'"$TS"'",
    "account": {
      "accountId": "8a1f2c34-5d6e-4a7b-8c9d-0e1f2a3b4c5d",
      "type": "checking",
      "status": "active"
    },
    "metadata": {
      "deviceFirstSeen": true
    }
  }'
```

See [Validate a transaction](/en/reference/products/tracer/validate-transaction).

**3. Read the decision**

```json theme={null}
{
  "validationId": "b7e3d190-4c25-4e8f-9a16-3d5f7b0c2e41",
  "requestId": "c1a7f402-6b93-4d5e-8f10-2a4c6e8b0d31",
  "decision": "DENY",
  "matchedRuleIds": ["4d9c2e70-8b1a-4f36-9c07-5e2a1b3d4f68"],
  "evaluatedRuleIds": ["4d9c2e70-8b1a-4f36-9c07-5e2a1b3d4f68"],
  "reason": "Rule matched with DENY action",
  "totalRulesLoaded": 1,
  "truncated": false,
  "limitUsageDetails": [],
  "processingTimeMs": 6.1,
  "evaluatedAt": "2026-07-31T11:09:44.207Z"
}
```

Your `ruleId` in `matchedRuleIds` means the rehearsal passed.

**4. Send the cases that should not fire**

Change one value at a time and repeat the call with a fresh `requestId`: `"amount": "5000.00"` for the boundary, `"deviceFirstSeen": false` for a known device, `"subType": "purchase"` for a card-present sale. Each should come back without your `ruleId` in `matchedRuleIds`.

> [!WARNING]
>
> Send a new `requestId` for every attempt. The `requestId` is the idempotency key. Repeat one and Tracer answers `200` with the decision it already recorded for that key. The change you just made then looks like it did nothing.

> [!NOTE]
>
> A rehearsal is a real validation. It stores a decision record and writes an audit event, and an `ALLOW` decision consumes the spending limits that cover that account. That is why the test account matters.

If your `ruleId` is not in `matchedRuleIds`, work through it in this order. Is the rule `ACTIVE` (`GET /v1/rules/{id}`)? Does the transaction match the scope you set? Do the values you sent satisfy the expression?

***

## Step 5: Put it live

***

Going live means one edit: drop the test account from the scope so the rule applies to the population the policy names.

**1. Stop evaluating the rehearsal version**

A scope edit does not require `INACTIVE`. Deactivating first makes the switch take effect at a moment you control and records a visible gap in the audit trail. Each instance serves rules from a cache it refreshes on a poll (every 10 seconds by default, `RULE_SYNC_POLL_INTERVAL_SECONDS`). Allow that window for the deactivation to reach every instance. `GET /v1/rules` confirms the stored status, not that every instance has caught up.

```bash theme={null}
curl -X POST http://localhost:4020/v1/rules/4d9c2e70-8b1a-4f36-9c07-5e2a1b3d4f68/deactivate \
  -H "X-API-Key: your-secure-api-key"
```

Status goes to `INACTIVE`. See [Deactivate a rule](/en/reference/products/tracer/deactivate-rule).

**2. Replace the scope**

```bash theme={null}
curl -X PATCH http://localhost:4020/v1/rules/4d9c2e70-8b1a-4f36-9c07-5e2a1b3d4f68 \
  -H "X-API-Key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "scopes": [{ "transactionType": "CARD" }] }'
```

`scopes` replaces the whole array. Send every scope object you want the rule to keep. See [Update a rule](/en/reference/products/tracer/update-rule).

**3. Activate**

```bash theme={null}
curl -X POST http://localhost:4020/v1/rules/4d9c2e70-8b1a-4f36-9c07-5e2a1b3d4f68/activate \
  -H "X-API-Key: your-secure-api-key"
```

Activation reaches the instance that served this call as soon as it commits. When you run several instances behind a load balancer, the others pick the change up on their next rule sync (`RULE_SYNC_POLL_INTERVAL_SECONDS`, default `10`). Deactivation travels the same way. Allow that same window after activation before you treat the rule as enforcing on every instance.

**4. Confirm what is live**

```http theme={null}
GET /v1/rules?status=ACTIVE&transaction_type=CARD&sort_by=updated_at
X-API-Key: {api_key}
```

The listing answers "which rules enforce on card traffic right now". See [List rules](/en/reference/products/tracer/list-rules). For one rule, `GET /v1/rules/{id}` returns the expression and scopes as stored ([Retrieve a rule](/en/reference/products/tracer/retrieve-rule)). Both report the stored state, not what each instance's cache holds.

> [!NOTE]
>
> A validation loads its rule set once, from the cache of the instance that serves it, when the call starts. A rule that activates while a validation is in flight is not part of that decision. Decisions already recorded do not change when rules change afterwards.

***

## Step 6: Know where your rule sits among the others

***

Rules carry no priority field and no ordering to configure. Rules whose scope matches a transaction are evaluated together. The decision comes from the strictest action that fired: a `DENY` rule first, then an exceeded spending limit, then `REVIEW`, then `ALLOW`, then the configured no-match default. The `matchedRuleIds` array carries every rule that matched, whatever action each one holds.

Two consequences for the rule you just wrote:

* **An `ALLOW` rule does not exempt anyone from a `DENY` rule.** If the policy has an exception (VIP customers, a partner merchant), put it inside the `DENY` expression. Add it as one more condition that makes the rule narrower:

  ```cel theme={null}
  subType == "card_not_present" && amount > 5000 && metadata.deviceFirstSeen == true && metadata.customerTier != "vip"
  ```

  The narrowed rule now reads `metadata.customerTier`, and a request that does not carry that key does not match it.

* **Your rule joins the set every matching transaction evaluates.** `MAX_RULES_PER_REQUEST` caps how many rules one validation evaluates. When the set is larger, the response reports `truncated: true`. See [environment variables](./tracer-environment-variables.mdx).

The precedence table and the reasoning behind it are on the [Rules engine](./rule-engine.mdx#evaluation-pattern) page.

***

## Step 7: Change the rule when the policy changes

***

What you do depends on the field, not on how the rule performs.

| What changed | How |
| - | - |
| Anything inside the expression (the threshold, the entry mode, the device flag) | Deactivate, then `POST /v1/rules/{id}/draft`, then `PATCH` the expression, then activate |
| `DENY` becomes `REVIEW` | `PATCH /v1/rules/{id}` with the new `action` |
| Name, description, or scopes | `PATCH /v1/rules/{id}` |

> [!WARNING]
>
> The `expression` accepts an edit only while the rule is `DRAFT`. Sending one to a rule in another status answers `422` with error code `0351`. Deactivating is not enough on its own, because `INACTIVE` is not `DRAFT`. Do not skip `POST /v1/rules/{id}/draft`. See [Draft a rule](/en/reference/products/tracer/draft-rule).

A `PATCH` is stored when it answers, and reaches evaluation on the next rule sync. When the change matters to the minute, deactivate first and activate again after. That sequence also puts a visible gap in the audit trail where the rule did not enforce. A reviewer will look for that gap.

The lifecycle is a closed set of moves: `DRAFT` activates or is deleted. `ACTIVE` deactivates. `INACTIVE` goes back to `DRAFT`, back to `ACTIVE`, or is deleted. `DELETED` is the end. Anything else answers `422` with error code `0349`, including a request to draft a rule that is still `ACTIVE`.

***

## Step 8: Retire or delete the rule

***

**To stop enforcing without losing anything**, deactivate. The rule keeps its expression, its scopes, and its history. It no longer reaches evaluation, and `POST /v1/rules/{id}/activate` brings it back. That is the move for a policy that is suspended, seasonal, or under review.

**To remove it**, delete. Deactivate first, because you cannot delete a rule in `ACTIVE`:

```http theme={null}
DELETE /v1/rules/4d9c2e70-8b1a-4f36-9c07-5e2a1b3d4f68
X-API-Key: {api_key}
```

A `204` answers on success. See [Delete a rule](/en/reference/products/tracer/delete-rule).

What deleting removes:

* The rule stops answering on `GET /v1/rules/{id}`, which returns `404` with error code `0347` afterwards.
* It no longer appears in `GET /v1/rules`, and `DELETED` is not a value the `status` filter accepts.
* `DELETED` is the end of the lifecycle. No endpoint moves a rule out of it. A deleted rule comes back only as a new rule you create again.

What deleting leaves behind:

* The audit trail keeps the rule's lifecycle, and the `RULE_DELETED` event carries the definition (name, description, expression, action, scopes) as it stood at deletion. See [Audit and compliance](./audit-compliance.mdx).
* Decisions the rule produced keep its `ruleId` in `matchedRuleIds`. A denial from six months ago still names it. See [Reviewing a denied transaction](./reviewing-a-denied-transaction.mdx).
* The name becomes available again for a new rule in the same context.

> [!WARNING]
>
> Deactivate, then read the audit trail, then delete. Deactivating is reversible in one call and deleting is not reversible at all, so there is no reason to skip the intermediate state.

***

## Common pitfalls

***

> [!WARNING]
>
> **What usually goes wrong turning a policy into a rule:**
>
> * **"The rule is ACTIVE but matches nothing."** Check the field the policy leans on hardest. A rule reading `metadata.deviceFirstSeen` matches nothing if your integration never sends that key. The rule is correct and the payload is incomplete.
> * **"It fired on a transaction the policy exempts."** An `ALLOW` rule does not override a `DENY`. Put the exemption inside the `DENY` expression (Step 6).
> * **"My second rehearsal returned the first decision."** `requestId` is the idempotency key. Send a new UUID per attempt.
> * **"PATCH rejected my expression with 422."** The rule was not in `DRAFT`. Move it there first (Step 7).
> * **"The name I sent is not the name I get back."** Tracer trims only leading and trailing whitespace. It preserves case and internal whitespace. Reference the rule by `ruleId`.

### Error codes

| Code | Status | What to change |
| - | - | - |
| `0340` | 400 | The expression does not parse as CEL |
| `0341` | 400 | The expression does not return a boolean (`amount > 5000`, not `amount`) |
| `0342` | 422 | The expression's estimated cost is above `CEL_COST_LIMIT` |
| `0347` | 404 | No rule has that `ruleId`, or it was deleted |
| `0349` | 422 | The lifecycle does not allow that move (for example, deleting an `ACTIVE` rule) |
| `0351` | 422 | An expression edit on a rule that is not `DRAFT` |
| `0353` / `0355` / `0357` | 400 | `name`, `expression`, or a valid `action` is missing |
| `0354` / `0356` / `0359` | 400 | `name` above 255, `expression` above 5000, or `description` above 1000 characters |
| `0358` | 400 | A scope object with no field set. Omit `scopes` entirely for a global rule. Never send `{}` |
| `0360` | 400 | More than 100 scope objects on one rule |
| `0441` | 409 | Another rule in the same context already holds that name |
| `0065` | 400 | The id in the path is not a UUID |
| `0082` | 400 | A filter on `GET /v1/rules` carries a value the endpoint does not accept |

The complete list is in the [Tracer error list](/en/reference/products/tracer/tracer-error-list).

***

## Quick reference

***

| Step | Method | Endpoint |
| - | - | - |
| Create as a draft | POST | `/v1/rules` |
| Start evaluating | POST | `/v1/rules/{id}/activate` |
| Rehearse or verify | POST | `/v1/validations` |
| Stop evaluating | POST | `/v1/rules/{id}/deactivate` |
| Reopen for editing | POST | `/v1/rules/{id}/draft` |
| Change fields | PATCH | `/v1/rules/{id}` |
| Read one rule | GET | `/v1/rules/{id}` |
| See what is live | GET | `/v1/rules` |
| Remove | DELETE | `/v1/rules/{id}` |


# Getting started with Tracer
Source: https://docs.lerian.studio/en/products/tracer/getting-started

Set up Tracer with Docker Compose, learn its core validation contexts, and run your first ALLOW, DENY, or REVIEW transaction validation call.

Tracer is the layer your authorization or onboarding system calls before a transaction goes through. It runs your fraud, risk, and limit policies in milliseconds and returns ALLOW, DENY, or REVIEW. The decision then lives in one place instead of scattered across product code.

**What changes in your operation:** decision logic stops living in scattered `if` statements across services. Rule changes ship through an API the same day instead of in the next release. Validation history gives you one place to investigate why a transaction received its decision.

**Trade-off:** you add one HTTP call to the critical path of every transaction. The target is p99 under 80ms. In return, you get a single point for policy and decision history, and you remove duplicated logic from product code.

> [!TIP]
>
> **Who is this guide for?** Developers (junior or senior) integrating Tracer for the first time. If you're evaluating Tracer at a product or strategy level, start with [What is Tracer](./what-is-tracer.mdx). If you already have it running and need API mechanics, jump to the [Tracer API quick start](/en/reference/products/tracer/tracer-api-quick-start).

This guide walks you through setting up Tracer and running your first validation. In a few steps, you'll have a working environment ready to validate transactions in real time.

For step-by-step API instructions with request and response examples, see the [Tracer API quick start](/en/reference/products/tracer/tracer-api-quick-start).

## Why use Tracer

***

* **Real-time validation**: Make ALLOW/DENY/REVIEW decisions in under 80ms (p99)
* **Flexible rules**: Expression-based rule engine for custom business logic
* **Spending control**: Configure limits by account, portfolio, segment, and period
* **Validation history**: Stored decisions for investigation and reporting
* **Product-agnostic**: Supports any transaction type (Card, Wire, Pix, Crypto)

By the end of this guide, you will:

* Understand Tracer architecture and core concepts
* Have a working development environment
* Run your first transaction validation
* Configure a spending limit

***

## What is Tracer

***

Tracer is a transaction validation platform that evaluates rules and limits and returns instant decisions. Your system calls Tracer before it executes a transaction. It then acts on the decision (ALLOW, DENY, or REVIEW) according to your business logic.

### How it works

![How Tracer processes a validation request across its Validation, Rules, and Limits contexts and returns an ALLOW, DENY, or REVIEW decision](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/how-tracer-works.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=27f03ce51f24a3a9e5b85cd6d6f40882)

Figure 1. How Tracer works

In this flow:

* **Rules** evaluate expressions against the transaction context
* **Limits** check spending thresholds for applicable scopes
* **Decision** returns ALLOW, DENY, or REVIEW based on evaluation results

### Core contexts

Tracer has three bounded contexts:

1. **Validation Context** - Orchestrates requests, coordinates evaluation, and stores validation history
2. **Rules Context** - Manages rule definitions and expression evaluation
3. **Limits Context** - Manages spending limits and usage tracking

***

## Prerequisites

***

Before you start, make sure you have:

* [ ] **Docker** and **Docker Compose** installed
* [ ] **Go 1.27+** for local development (the repository's `go.mod` declares the exact toolchain version)
* [ ] **PostgreSQL 17** (the shared Midaz primary, started by the platform infrastructure compose, not by Tracer's own)
* [ ] **API Key** for authentication

### Infrastructure dependencies

Tracer requires the following components:

| Component | Version | Purpose |
| - | - | - |
| PostgreSQL | 17 | Data persistence. Tracer uses its own `tracer` database on the shared Midaz PostgreSQL primary; it does not ship a dedicated instance. |

### Ports

Default ports used by Tracer services:

| Service | Port | Description |
| - | - | - |
| Tracer API | 4020 | Main REST API |
| Reservation seam | 4021 | gRPC service the Midaz ledger calls to reserve limit capacity |
| PostgreSQL | 5701 | Shared Midaz PostgreSQL primary, as exposed by the shipped infrastructure example (`DB_PORT`) |

***

## Step 1: Set up the environment

***

You can run Tracer with Docker Compose or locally for development.

### Option A: Docker Compose (recommended)

> [!NOTE]
>
> Tracer's own Compose file declares only two services: the application and a one-shot migration runner. **PostgreSQL is not one of them**. It comes from the shared platform infrastructure Compose and must be healthy first. The application container starts only after the migration runner applies the schema and exits successfully. The service always boots against an already-migrated database.

> [!NOTE]
>
> In Midaz v4, Tracer ships in the Midaz repository and release. It still runs as its own service. Start from `components/tracer` for local development.

Navigate to the Tracer project directory and start the services:

```bash theme={null}
cd components/tracer

# Setup environment
cp .env.example .env

# Start all services (brings up the shared infrastructure first,
# then the migration runner, then Tracer)
make up
```

### Option B: Local run

For development, you can run Tracer locally:

```bash theme={null}
# Set environment variables
export DB_HOST="localhost"
export DB_NAME="tracer"
export API_KEY="your-secure-api-key"
export API_KEY_ENABLED="true"
export SERVER_PORT="4020"
export LOG_LEVEL="INFO"

# Start the service
go run cmd/app/main.go
```

### Essential environment variables

| Variable | Description | Example |
| - | - | - |
| `DB_HOST` | PostgreSQL host | `localhost` |
| `DB_NAME` | PostgreSQL database name | `tracer` |
| `API_KEY` | API Key for authentication | `your-secure-api-key` |
| `API_KEY_ENABLED` | Enable API Key authentication | `true`, `false` |
| `SERVER_PORT` | API port | `4020` |
| `LOG_LEVEL` | Log level | `INFO`, `DEBUG`, `ERROR` |

***

## Step 2: Authenticate to the API

***

Tracer supports API key and plugin authentication. Plugin authentication takes precedence when you enable both, except on endpoints configured as API-key-only.

| Deployment and authentication configuration | Auth header | When to use |
| - | - | - |
| **Self-hosted, plugin auth enabled** | `Authorization` header with a Bearer token | `PLUGIN_AUTH_ENABLED=true`, unless the endpoint is configured as API-key-only. |
| **Self-hosted, API key auth** | `X-API-Key` header | Plugin auth is disabled, or the endpoint is configured as API-key-only. |
| **Lerian Cloud** | `Authorization` header with a Bearer token | Always. The JWT is issued by [Access Manager](/en/platform/access-manager) and carries the `tenantId` claim. |

The remaining steps use the API key form because most local-development setups run that way. If plugin authentication applies to your request, replace `X-API-Key: your-secure-api-key` with `Authorization: Bearer $JWT` in every example.

### API Key

Include the API Key in the `X-API-Key` header:

```http theme={null}
GET /v1/rules
X-API-Key: your-secure-api-key
```

### Bearer JWT

Include the JWT issued by Access Manager in the `Authorization` header:

```http theme={null}
GET /v1/rules
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

Tracer extracts the `tenantId` claim from the JWT and routes the request to the correct tenant database.

**You never pass the tenant identifier in a header, path, body, or rule scope**. The token is the only source of truth.

### cURL example

```bash theme={null}
# API key: List rules
curl -H "X-API-Key: your-secure-api-key" \
  http://localhost:4020/v1/rules
```

```bash theme={null}
# Bearer JWT: List rules
curl -H "Authorization: Bearer $JWT" \
  https://tracer.sandbox.lerian.net/v1/rules
```

> [!WARNING]
>
> Keep API Keys and JWTs secure. Never expose them in client-side code or public repositories.

> [!WARNING]
>
> API key authentication is **disabled by default** (`API_KEY_ENABLED=false`). The provided `.env.example` keeps it off, so local development works without setup. A production deployment **must** set `API_KEY_ENABLED=true` or `PLUGIN_AUTH_ENABLED=true` before you expose the service.

***

## Step 3: Configure a spending limit

***

Spending limits control transaction amounts by scope and period. Create a limit using `POST /v1/limits`.

### Limit types

| Type | Description | Period counting |
| - | - | - |
| `DAILY` | Maximum amount per day | A new count starts each day at the reset time (00:00 UTC by default) |
| `WEEKLY` | Maximum amount per week | A new count starts each Monday at the reset time (00:00 UTC by default) |
| `MONTHLY` | Maximum amount per month | A new count starts on the 1st of the month at the reset time (00:00 UTC by default) |
| `CUSTOM` | Maximum amount for a custom date range | One count for the whole range |
| `PER_TRANSACTION` | Maximum per single transaction | No count is kept |

For detailed configuration of all limit types including reset times, time windows, and custom periods, see the [Spending limits guide](./spending-limits.mdx).

### Scopes

Apply limits to specific contexts:

* **Segment**: Apply to all accounts in a segment (e.g., corporate customers)
* **Portfolio**: Apply to accounts in a portfolio
* **Account**: Apply to a specific account
* **Transaction type**: Apply only to CARD, WIRE, PIX, or CRYPTO

### Create a limit

```bash theme={null}
curl -X POST http://localhost:4020/v1/limits \
  -H "X-API-Key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Corporate Card Limit",
    "description": "Daily spending limit for corporate card transactions",
    "limitType": "DAILY",
    "maxAmount": "50000.00",
    "asset": "BRL",
    "scopes": [
      {
        "segmentId": "550e8400-e29b-41d4-a716-446655440000",
        "transactionType": "CARD"
      }
    ]
  }'
```

### Activate a limit

```bash theme={null}
curl -X POST http://localhost:4020/v1/limits/{id}/activate \
  -H "X-API-Key: your-secure-api-key"
```

### Limit lifecycle

Limits start in `DRAFT` status and follow the lifecycle `DRAFT` → `ACTIVE` → `INACTIVE`. Inactive limits can return to `DRAFT` for editing, or you can delete them. Activate a limit to start enforcement. For the full lifecycle and transition rules, see the [Spending limits guide](./spending-limits.mdx).

### Monitor usage

Every `POST /v1/validations` response carries `limitUsageDetails`, with one entry per limit Tracer checked. Each entry holds the cap, the amount attempted, and the projected consumption of that cap's current period. That projection includes this transaction. The endpoint `GET /v1/limits/{id}/usage` reports a cumulative total across the limit's counters, for a review of overall consumption.

For detailed configuration options, see the [Spending limits guide](./spending-limits.mdx).

***

## Step 4: Validate your first transaction

***

With limits configured, you're ready to validate a transaction using `POST /v1/validations`.

### Submit a transaction for validation

Send a validation request with the transaction context including:

* Transaction details (type, amount, asset, timestamp)
* Account information
* Optional: segment, portfolio, merchant, and custom metadata (Additional key-value information attached to entities like accounts or transactions, such as external IDs, reference numbers, or department codes.)

```bash theme={null}
TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)

curl -X POST http://localhost:4020/v1/validations \
  -H "X-API-Key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "550e8400-e29b-41d4-a716-446655440104",
    "transactionType": "CARD",
    "subType": "credit",
    "amount": "1500.00",
    "asset": "BRL",
    "transactionTimestamp": "'"$TS"'",
    "account": {
      "accountId": "550e8400-e29b-41d4-a716-446655440100"
    },
    "merchant": {
      "merchantId": "550e8400-e29b-41d4-a716-446655440103",
      "category": "5411",
      "name": "Test Merchant"
    },
    "metadata": {
      "channel": "mobile"
    }
  }'
```

> [!NOTE]
>
> The `transactionTimestamp` must be recent, which is why the example generates it. Tracer rejects a future timestamp with error code `0419` (1-minute clock skew tolerance). Tracer rejects a timestamp older than 24 hours with error code `0421`.

> [!NOTE]
>
> `requestId` is the idempotency key. Send a new UUID for each attempt. If you repeat one, Tracer returns the decision it already recorded for that key. A rule you activated in between will not appear to take effect.

Tracer evaluates the rules and limits that apply to the transaction, then returns one of three decisions:

| Decision | Meaning | Your system should |
| - | - | - |
| `ALLOW` | Transaction approved | Proceed with the transaction |
| `DENY` | Transaction denied (rule matched or limit exceeded) | Block the transaction |
| `REVIEW` | Requires manual review | Queue for human review |

The response names the rules Tracer evaluated, the rules that matched, and the current limit usage. That detail helps with debugging and customer support.

> [!NOTE]
>
> **Why Tracer returns a decision instead of blocking directly.** Tracer is a decisioning layer, not an authorization gateway. The calling system holds the customer relationship and knows the channel. It decides what to do with a DENY. For example, your card-issuing system may honor a `DENY` for a stand-in pre-auth. It may still capture the request for analytics. By returning a decision, Tracer fits into any authorization flow without owning the customer-facing UX.

For complete payload structure and field details, see the [API reference](/en/reference/products/tracer/validate-transaction).

***

## Step 5: Create a validation rule

***

Rules let you define custom business logic that evaluates during validation. Create a rule using the `POST /v1/rules` endpoint with an expression, action, and optional scopes.

For example, to block high-value transactions:

```bash theme={null}
curl -X POST http://localhost:4020/v1/rules \
  -H "X-API-Key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Block high-value card transactions",
    "description": "Deny card transactions above R$ 10,000",
    "expression": "amount > 10000",
    "action": "DENY",
    "scopes": [
      {
        "transactionType": "CARD"
      }
    ]
  }'
```

> [!NOTE]
>
> Tracer preserves the name's case and internal whitespace, trimming only leading and trailing whitespace before storage. Take the `ruleId` from the response and use it in the activate call below.

### Activate a rule

```bash theme={null}
curl -X POST http://localhost:4020/v1/rules/{id}/activate \
  -H "X-API-Key: your-secure-api-key"
```

> [!NOTE]
>
> Activation takes effect right away on the instance that served the activate call. A single-instance setup evaluates the rule on your next validation. When you run several instances behind a load balancer, the others pick the change up on their next rule sync. The interval is `RULE_SYNC_POLL_INTERVAL_SECONDS`, default `10`. Deactivation propagates the same way.

### Rule lifecycle

Rules follow the same lifecycle as limits: `DRAFT` → `ACTIVE` → `INACTIVE`. To start evaluation, activate the rule using `POST /v1/rules/{id}/activate`. You can deactivate and reactivate an active rule as needed.

For detailed information about rule expressions and lifecycle management, see the [Rules engine guide](./rule-engine.mdx).

***

## Observability

***

Tracer exposes endpoints for monitoring and observability.

### Key metrics

Tracer exposes OpenTelemetry-compatible metrics via the OTLP exporter, plus custom application metrics:

* `tracer_auth_failures_total{reason}` - Authentication failures by reason (missing\_api\_key, invalid\_api\_key)
* `tracer_validation_rollback_failures_total` - Usage rollback failures during REVIEW decisions (eventual consistency gaps that self-correct at period boundaries)

Tracer's built-in OpenTelemetry HTTP middleware provides standard HTTP request metrics automatically.

***

## Verification

***

Confirm that everything works correctly.

### Checklist

* [ ] Docker services started and healthy
* [ ] API Key authentication working
* [ ] Spending limit configured
* [ ] Test transaction validated successfully
* [ ] Rule created and activated

***

## Next steps

***

From here, you can explore more advanced features:

* **[Integration guide](./integration-guide.mdx)** - Learn how to integrate your authorization system with Tracer
* **[Rules engine](./rule-engine.mdx)** - Write validation rules in CEL and manage their lifecycle
* **[Spending limits](./spending-limits.mdx)** - Configure and manage spending limits by scope and period
* **[Validation history and compliance](./audit-compliance.mdx)** - Query validation history and use it in your compliance processes

***

## Quick reference

***

The three flows you'll use most:

* **Validate a transaction**: `POST /v1/validations`. See the [Tracer API quick start](/en/reference/products/tracer/tracer-api-quick-start) for the request shape.
* **Manage rules**: `/v1/rules` (CRUD + lifecycle endpoints `/activate`, `/deactivate`, `/draft`). See the [Rules engine guide](./rule-engine.mdx).
* **Manage limits**: `/v1/limits` (CRUD + lifecycle + `/usage`). See the [Spending limits guide](./spending-limits.mdx).

For the full endpoint catalog, request/response schemas, and error codes, see the [API reference](/en/openapi/v3-current/tracer.yaml).

### What your system should do with each decision

| Decision | Tracer recommends | Your system should |
| - | - | - |
| `ALLOW` | Approval | Proceed with the transaction |
| `DENY` | Denial | Block the transaction and inform the user |
| `REVIEW` | Review | Queue for manual review in your system |

> [!NOTE]
>
> Tracer returns decisions as recommendations. Your system must implement the appropriate action for each decision.


# Integration guide
Source: https://docs.lerian.studio/en/products/tracer/integration-guide

Integrate Tracer with your authorization system: send complete payloads, handle ALLOW, DENY, and REVIEW decisions, and stay within an 80ms latency budget.

Integrating Tracer means deciding where in your authorization flow to make the validation call, what data to send, and how to handle the three possible decisions. The pattern is short: your system collects the full transaction context, calls `POST /v1/validations`, acts on ALLOW / DENY / REVIEW, and moves on. Tracer never reaches back into your stack. There are no webhooks or callbacks, and the integration ends with the response.

**What changes in your operation:** decisioning moves from in-process logic to an external call. The call is synchronous (request/response, no webhooks), so it sits on the critical path of the transaction. Done well, it adds under 80ms p99 and gives you a single point for policy and validation history. Done poorly (no timeout, no retry strategy, no fallback), it becomes a single point of failure.

**Trade-off:** you add a network hop. The contract is simple: idempotent by `requestId`, no callbacks, deterministic three-state response. You must think about timeouts, retries, and what to do if Tracer is unreachable. Most of this guide is about that.

> [!TIP]
>
> **Who is this guide for?** Integration engineers writing the request from your system to Tracer, and architects deciding where the call sits in the flow. Risk and fraud analysts who write rules can skip ahead to the [Rules engine guide](./rule-engine.mdx). Compliance can read the [Audit and compliance guide](./audit-compliance.mdx) instead.

This guide covers payload requirements, the integration flow, and practices that keep the validation call inside your latency budget.

Tracer sits outside your ledger: it never calls Midaz. Your application orchestrates the two. It calls Tracer to validate, and submits the transaction to Midaz only if the decision is `ALLOW`. Tracer evaluates your configured policies and limits against the context you send, not account balances. The ledger stays the source of truth for what an account holds.

> [!NOTE]
>
> Midaz can also drive Tracer through an optional per-ledger reservation seam. It remains one-way, Ledger → Tracer. The rest of this guide covers the application-orchestrated HTTP pattern. The seam contract appears below.

## Integration overview

***

Tracer expects calls from authorization systems (payment gateways, workflow orchestrators, or transaction processors) that need real-time validation decisions. The integration follows a simple request-response pattern:

![Request-response integration where an authorization system calls Tracer for a validation decision and only submits the transaction to Midaz when the decision is ALLOW](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/integration-overview-tracer.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=087d44f66ec751efe4bb38be8c964467)

Figure 1. Integration overview with Tracer

Tracer does not fetch external data during validation. Your system must provide all context needed for rule evaluation.

***

## Midaz Ledger reservation seam

***

This opt-in seam belongs to **Ledger HTTP v2**. Ledger HTTP v1 never invokes it. The Tracer public HTTP API is v1-only and has no reservation operations. Ledger calls the gRPC service `lerian.midaz.reservation.v1.ReservationService`. This service is an internal service-to-service transport, not a public API.

Tracer always starts this gRPC listener, on port `4021` by default. To use a different port, set `TRACER_GRPC_PORT` to a listen address in the form `:4021`.

On Ledger, set `TRACER_BASE_URL` to the listener address as `host:port`. When `TRACER_BASE_URL` is unset, Ledger makes no reservation call. Ledger calls Tracer only when the per-ledger `tracer.mode` is `advisory` or `enforce`. An unset or `off` mode skips reservations even when you set `TRACER_BASE_URL`. An honored per-call skip also bypasses the seam.

The seam has five transitions:

| Transition | Ledger action |
| - | - |
| `Reserve` | Hold limit capacity before the transaction commits. |
| `ConfirmByTransaction` | Commit every hold for a transaction. |
| `ReleaseByTransaction` | Return every hold for a transaction. |
| `ConfirmById` | Commit one hold. |
| `ReleaseById` | Return one hold. |

### Deployment order

Deploy Tracer from Midaz v4.2.0 before you deploy the Ledger. While a Ledger from v4.2.0 runs, do not roll Tracer back to an earlier version. An earlier Tracer drops the account type, the metadata and the revert flag of each reserve request.

### Rules on a reserve

On each `Reserve`, Tracer evaluates your active rules first, with the same evaluator as `POST /v1/validations`. Then it reserves limit capacity. On a reserve, the no-match default does not apply. When no rule matches, the reserve continues to the limit check. A reserve for a revert skips rules and still reserves limit capacity.

The reserve request carries the amount, the asset, the ID and type of the first internal source account, the transaction timestamp and scalar metadata values, as strings. It carries no transaction type, segment, portfolio or merchant.

### Outcomes on the Ledger

A reservation denial is a successful response, not a transport error. The `advisory` mode never blocks the transaction. The `enforce` mode rejects the transaction before any balance movement:

| Tracer outcome | Ledger error in `enforce` mode |
| - | - |
| A spending limit is exceeded | `0177` |
| A matched rule returns DENY | `0535` |
| A matched rule returns REVIEW, or a rule cannot be evaluated | `0531` |
| Tracer refuses the reserve request | `0532`, for every `failPosture` |
| Tracer is unavailable | `0178` when `failPosture` is `closed`. With `open`, the transaction proceeds without a reservation. |

With the open posture, the Ledger also proceeds without rule or limit checks when Tracer refuses the Ledger's credentials.

The Ledger can also return `0536` for a reserve. The [Midaz error list](/en/reference/products/midaz/error-list) describes each code.

Confirm and release failures do not block the transaction.

## Payload-Complete Pattern

***

Tracer uses the **Payload-Complete Pattern**. Every request must carry all context required for validation. This design ensures:

| Benefit | Description |
| - | - |
| **Simplicity** | Single request contains everything needed for decision |
| **Reliability** | No dependency on external services during validation |
| **Flexibility** | Your system controls data freshness and enrichment logic |

### Your responsibilities

As the integrating system, you are responsible for:

1. **Enriching the payload** with account, segment, portfolio, and merchant data before calling Tracer
2. **Providing accurate context** for rule and limit evaluation. Tracer cannot fetch missing data
3. **Handling the decision** (ALLOW, DENY, or REVIEW) appropriately in your workflow
4. **Implementing retry logic** if Tracer is temporarily unavailable
5. **Managing review workflows** when Tracer returns `REVIEW`. Tracer does not include case management

> [!WARNING]
>
> Tracer validates what you send. If your payload lacks context (e.g., account status, segment membership), rules that depend on that data cannot evaluate correctly. Always ensure payloads are complete before submission.

### Tracer's responsibilities

Tracer is responsible for:

1. **Evaluating rules** against the provided context
2. **Checking limits** against current usage
3. **Storing validation history** for investigation and reporting
4. **Returning decision** with detailed information

***

## Integration flow

***

Follow these steps to integrate your system with Tracer.

### Step 1: Prepare the transaction context

Before calling Tracer, gather all relevant data from your systems:

![Steps for preparing the transaction context and calling Tracer, from gathering data in your systems to acting on the returned decision](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/integration-flow-tracer.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=d988019ee7d8f486fce76b423b55d941)

Figure 2. Preparing transaction context

### Step 2: Call Tracer API

Send a POST request to `/v1/validations` with the complete transaction context including:

* Transaction details (type, subType, amount, asset, timestamp)
* Account information (required)
* Optional: segment, portfolio, merchant, and custom metadata (Additional key-value information attached to entities like accounts or transactions, such as external IDs, reference numbers, or department codes.)

For complete payload structure and field details, see the [API reference](/en/reference/products/tracer/validate-transaction).

### Step 3: Handle the response

Process the decision returned by Tracer:

| Decision | Action |
| - | - |
| `ALLOW` | Proceed with the transaction |
| `DENY` | Reject the transaction; show reason to user if appropriate |
| `REVIEW` | Queue for manual review in your review system |

The response includes the `validationId` for correlation with validation history, details about which rules matched, and current limit usage information.

### Using metadata

Metadata allows you to pass custom fields that your rules can evaluate. Use this for context like channel, device information, customer tier, or any business-specific attributes.

> [!NOTE]
>
> Metadata keys must be alphanumeric with underscores only, maximum 64 characters. Maximum 50 entries per request.

***

## Request idempotency

***

Validation requests are **idempotent** based on the `requestId` field. If you send the same `requestId` twice, Tracer returns the cached result from the first request instead of reprocessing.

| Response code | Meaning |
| - | - |
| `201 Created` | New validation processed |
| `200 OK` | Duplicate request detected; cached result returned |

The response body is identical in both cases. Your client should handle both status codes as success.

Network timeouts and retries can cause duplicate requests. Without idempotency, a retried request could double-count against limits or create duplicate validation records. The `requestId` ensures exactly-once processing semantics.

**Idempotency contract:**

* Same `requestId` → Same response (guaranteed)
* Different `requestId` → Independent processing (even if transaction data is identical)

> [!WARNING]
>
> Always generate a unique `requestId` (UUID) for each new transaction. Reusing a `requestId` from a previous transaction will return the old result, not process the new transaction.

***

## Authentication

***

Tracer supports two authentication modes. You can use them independently or together.

### API key authentication

The simplest option. Send your API key in the `X-API-Key` header with every request.

| Environment variable | Description |
| - | - |
| `API_KEY_ENABLED` | Enable API key authentication (default: `false`) |
| `API_KEY` | The secret key value |
| `API_KEY_ENABLED_ONLY_VALIDATION` | Use API key only for the `/v1/validations` endpoint (default: `false`) |

### Plugin authentication (Access Manager)

For enterprise deployments, Tracer can delegate authentication to the [Lerian Access Manager](/en/platform/access-manager/auth-plugin). This enables centralized authentication across all Lerian services.

| Environment variable | Description |
| - | - |
| `PLUGIN_AUTH_ENABLED` | Enable plugin authentication (default: `false`) |
| `PLUGIN_AUTH_ADDRESS` | URL of the auth service (default: `http://localhost:4000`) |

### Authentication priority

When you enable both modes, Tracer uses this priority:

1. If `PLUGIN_AUTH_ENABLED=true` and the endpoint has no API-key-only flag → Plugin auth
2. If `API_KEY_ENABLED=true` or the endpoint carries the API-key-only flag → API key auth

Infrastructure endpoints (health checks, version probe, OpenAPI spec) bypass authentication and are not part of the public `/v1/*` API surface documented in this reference.

> [!NOTE]
>
> You can configure the `/v1/validations` endpoint for API-key-only authentication via `API_KEY_ENABLED_ONLY_VALIDATION=true`. This is useful in high-throughput scenarios where plugin auth adds unacceptable latency.

### Authentication on Lerian Cloud

On Lerian Cloud, authentication works like this:

* **Every `/v1/*` request must carry a JWT bearer token** issued by [Access Manager](/en/platform/access-manager): `Authorization: Bearer <jwt>`.
* **`tenantId` comes from the JWT claim**, not from a header, path, body, metadata, or rule scope. There is no `X-Tenant-ID` header. The tenant identifier has no effect anywhere other than the token claim.

A token that **parses but carries no `sub` claim** returns HTTP 401 and error code `0474` up front. The `sub` claim is what the audit writer uses to attribute the action to a principal. Tracer fails loudly rather than recording the change against a generic system actor. Make sure your Access Manager tokens always carry it.

If the service is temporarily at capacity for your tenant, requests return HTTP 503 with error code `0466` and a `Retry-After` header. Back off and retry.

***

## Performance considerations

***

Optimize your integration for low latency and high reliability.

### Timeout budget

Tracer targets a response in under **80ms (p99)**. Configure your client timeout accordingly:

| Configuration | Recommended value |
| - | - |
| Client timeout | 100ms |
| Connection timeout | 50ms |
| Read timeout | 100ms |

### Retry strategy

Implement retry logic for transient failures:

```
On 5xx error or timeout:
  - Wait 10ms
  - Retry once
  - If still failing, apply fallback policy
```

> [!WARNING]
>
> Do not retry on 4xx errors. These indicate invalid requests that will fail again. For retries on 5xx/timeout, reuse the same requestId to take advantage of idempotency.

### Fallback behavior

Decide what happens when Tracer is unavailable:

| Strategy | When to use |
| - | - |
| **Fail-open** | Allow transaction if Tracer is down (prioritize availability) |
| **Fail-closed** | Deny transaction if Tracer is down (prioritize security) |
| **Queue for review** | Queue transaction for manual review |

Your choice depends on your risk tolerance and business requirements.

> [!WARNING]
>
> **Common integration pitfalls:**
>
> * **"My retry created a duplicate validation."** Reuse the same `requestId` across retries. Tracer deduplicates by that field. The second call returns the cached result (HTTP 200) without creating another validation. If you generate a fresh UUID on every retry, you defeat idempotency.
> * **"My client times out after 30 seconds but Tracer keeps processing."** Tracer respects its own deadlines (\~80ms p99 target). If your client gives up on the call, Tracer still spends that work on a response. Set client timeout aggressively (100ms) and trust the retry path.
> * **"Tracer rejects my validation with error code `0421` (timestamp too old) on legitimate transactions."** Default tolerance is 24 hours. Check your server clock and the `transactionTimestamp` you're sending. If you batch-process late, set the timestamp to the actual transaction moment, not the moment you're calling Tracer.
> * **"Test transactions show up in production validation history."** Tracer also records validations from test/staging environments calling the same Tracer instance. Use `metadata.environment` (or similar) to tag and filter test traffic if you share Tracer between environments.

***

## Data freshness

***

Since you control the payload enrichment, data freshness is your responsibility. Tracer trusts the data you provide and cannot detect stale information.

| Data type | Freshness recommendation | Risk if stale |
| - | - | - |
| Account status | Real-time or near real-time | Transactions on suspended accounts may be allowed |
| Segment membership | Can be cached (changes infrequently) | Wrong limits or rules may apply |
| Portfolio assignment | Can be cached (changes infrequently) | Incorrect scope matching |
| Merchant data | Can be cached with periodic refresh | Risk rules may not trigger correctly |

> [!WARNING]
>
> Stale data leads to incorrect decisions. If you suspended an account but your cache shows it as active, Tracer will allow transactions that it should deny. Your enrichment layer is the source of truth for Tracer.

***

## Date and time format

***

All datetime fields must use **RFC3339 format** with mandatory timezone:

**Valid formats:**

```
2026-01-30T10:30:00Z           (UTC)
2026-01-30T10:30:00-03:00      (São Paulo timezone)
2026-01-30T00:00:00+00:00      (UTC explicit)
```

**Invalid formats:**

```
2026-01-30                     (date only - rejected)
2026-01-30T10:30:00            (missing timezone - rejected)
```

***

## Integration checklist

***

Before going to production, verify:

* [ ] Your API Key is in place and secure
* [ ] Each request includes a unique requestId (UUID)
* [ ] Client handles both 201 and 200 responses as success
* [ ] Your client timeout is 100ms
* [ ] Your retry logic covers 5xx errors
* [ ] You chose a fallback behavior
* [ ] Your payload carries all required fields
* [ ] Timestamps use RFC3339 format with timezone
* [ ] Asset codes are 1 to 100 uppercase letters
* [ ] Your system handles each decision (ALLOW/DENY/REVIEW)
* [ ] Your system logs validation IDs for validation-history correlation

***

## Example integration (pseudocode)

***

```python theme={null}
def validate_transaction(transaction):
    # Step 1: Enrich payload
    payload = {
        "requestId": generate_uuid(),
        "transactionType": transaction.type,
        "amount": transaction.amount,
        "asset": transaction.asset.upper(),
        "transactionTimestamp": now_rfc3339(),
        "account": get_account_context(transaction.account_id),
        "segment": get_segment_context(transaction.segment_id),
        "merchant": get_merchant_context(transaction.merchant_id),
        "metadata": transaction.custom_fields
    }

    # Step 2: Call Tracer
    try:
        response = http_post(
            url="https://tracer.example.com/v1/validations",
            headers={"X-API-Key": API_KEY},
            json=payload,
            timeout_ms=100
        )
    except Timeout:
        return apply_fallback_policy()
    except ServerError:
        return retry_once_or_fallback()

    # Step 3: Handle decision
    if response.decision == "ALLOW":
        return proceed_with_transaction()
    elif response.decision == "DENY":
        return reject_transaction(response.reason)
    elif response.decision == "REVIEW":
        return queue_for_manual_review(response.validationId)
```

***

## Next steps

***

* **[Rules engine](./rule-engine.mdx)** - Create rules that evaluate against the context you provide
* **[Spending limits](./spending-limits.mdx)** - Configure limits that apply to your transaction scopes
* **[Validation history and compliance](./audit-compliance.mdx)** - Query validation history and use it in your compliance processes


# Reviewing a denied transaction
Source: https://docs.lerian.studio/en/products/tracer/reviewing-a-denied-transaction

Read a Tracer DENY or REVIEW decision to find the rule or the limit behind it, retrieve the stored record later, and verify its audit event during an audit.

A validation came back `DENY` or `REVIEW` and someone asks why. This guide takes you from the decision Tracer returned to a named rule or a named spending limit. From there it reaches the stored record and the audit trail (A chronological, immutable record of every action and transaction in the system, essential for regulatory compliance and dispute resolution.) entry you can hand an auditor months later.

**What changes in your operation:** the answer to "why was this blocked?" stops being a log search. Each decision arrives with the identifiers of what produced it. The same record answers by id years later, and you can check its audit event against the hash chain.

> [!TIP]
>
> **Who is this guide for?** Developers integrating the validation call, support and disputes teams answering customer questions, and compliance officers preparing evidence. Steps 1 to 4 need only the response you already have. Steps 5 to 8 use the query endpoints.

## Before you start

***

* [ ] Tracer running and reachable, with an API key. See [Getting started](./getting-started.mdx)
* [ ] A `DENY` or `REVIEW` response to work from, or the `validationId` of one
* [ ] Familiarity with what rules and limits do. See the [Rules engine](./rule-engine.mdx) and [Spending limits](./spending-limits.mdx)

All calls below send the API key as `X-API-Key`.

***

## Step 1: Read the decision Tracer returned

***

`POST /v1/validations` answers with the full decision. A new request answers `201`. A repeated `requestId` answers `200` with the decision Tracer already recorded for that key.

```bash theme={null}
TS=$(date -u +%Y-%m-%dT%H:%M:%SZ)

curl -X POST http://localhost:4020/v1/validations \
  -H "X-API-Key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "7c3f1b8e-5a2d-4c6b-9e1f-0a4d8b2c6e30",
    "transactionType": "CARD",
    "subType": "purchase",
    "amount": "1500.00",
    "asset": "BRL",
    "transactionTimestamp": "'"$TS"'",
    "account": {
      "accountId": "550e8400-e29b-41d4-a716-446655440100",
      "type": "checking",
      "status": "active"
    },
    "merchant": {
      "merchantId": "550e8400-e29b-41d4-a716-446655440103",
      "category": "5411",
      "country": "BR",
      "name": "Acme Store"
    },
    "metadata": {
      "channel": "mobile"
    }
  }'
```

A denial produced by a rule looks like this:

```json theme={null}
{
  "validationId": "8f14e45f-ea3b-4c6e-9a1c-2b7d5e0a91c4",
  "requestId": "7c3f1b8e-5a2d-4c6b-9e1f-0a4d8b2c6e30",
  "decision": "DENY",
  "matchedRuleIds": [
    "3c8a5b21-9f4d-4e17-8b6a-1d2e3f405162"
  ],
  "evaluatedRuleIds": [
    "3c8a5b21-9f4d-4e17-8b6a-1d2e3f405162",
    "a6b7c8d9-0e1f-4a2b-9c3d-4e5f60718293"
  ],
  "reason": "Rule matched with DENY action",
  "totalRulesLoaded": 2,
  "truncated": false,
  "limitUsageDetails": [],
  "processingTimeMs": 9.4,
  "evaluatedAt": "2026-07-31T14:05:09.481Z"
}
```

| Field | What it tells you |
| - | - |
| `validationId` | The key to this decision. Everything later in this guide starts from it |
| `decision` | `ALLOW`, `DENY`, or `REVIEW` |
| `reason` | What produced the decision. See [Step 2](#step-2-tell-a-rule-denial-from-a-limit-denial) |
| `matchedRuleIds` | Every rule that matched this transaction, whatever action the rule carries |
| `evaluatedRuleIds` | The rules Tracer evaluated for this transaction |
| `limitUsageDetails` | One entry per spending limit Tracer checked |
| `totalRulesLoaded` / `truncated` | How many rules were loaded, and whether `MAX_RULES_PER_REQUEST` cut the set |
| `processingTimeMs` / `evaluatedAt` | How long the evaluation took, and when it ran |

For the full request and response schema, see [Validate a transaction](/en/reference/products/tracer/validate-transaction).

> [!NOTE]
>
> Store the `validationId` next to your own transaction record. It is the key [Step 5](#step-5-retrieve-the-record-later) takes, and it is also the `resourceId` of the audit event in [Step 7](#step-7-pull-the-audit-event-behind-the-decision).

***

## Step 2: Tell a rule denial from a limit denial

***

Read `reason` first. It names what produced the decision, and it tells you which of the next two steps to take.

| `reason` | What happened | Go to |
| - | - | - |
| `Rule matched with DENY action` | A rule whose action is `DENY` matched | [Step 3](#step-3-name-the-rule) |
| `limit_exceeded` | The amount would push a spending limit past its ceiling | [Step 4](#step-4-name-the-spending-limit) |
| `rule_evaluation_error` | A rule expression failed for this request, so Tracer returned `REVIEW`. `matchedRuleIds` lists the matching `REVIEW` rules, then the rules that failed. A failed rule is absent from `evaluatedRuleIds` | [Step 3](#step-3-name-the-rule) |
| `No matching rules found` | No rule matched, so Tracer applied `DEFAULT_DECISION_WHEN_NO_MATCH` | Review that setting on the [environment variables](./tracer-environment-variables.mdx) page |

On a `REVIEW` from a matched rule, `reason` carries the same text (`Rule matched with REVIEW action`), and Step 3 reads a review the same way it reads a denial.

> [!NOTE]
>
> On a rule denial, `limitUsageDetails` comes back empty because Tracer stops before the limit check, not because no limit applies to the account.

***

## Step 3: Name the rule

***

`matchedRuleIds` lists every rule that matched, whatever action each one carries. A `DENY` rule and an `ALLOW` rule can both appear on the same denial. Retrieve each one and read its `action` to find the rule behind the decision:

```http theme={null}
GET /v1/rules/3c8a5b21-9f4d-4e17-8b6a-1d2e3f405162
X-API-Key: {api_key}
```

The rule carries the `name`, `description`, `expression`, `action`, and `scopes` a colleague needs to see why it fired. See [Retrieve a rule](/en/reference/products/tracer/retrieve-rule).

Compare `matchedRuleIds` with `evaluatedRuleIds` when the question is the opposite one: "why did my rule *not* fire?". For a rule absent from both lists, start with its status and its scope rather than its expression.

> [!TIP]
>
> A rule deleted since the decision no longer answers on `GET /v1/rules/{id}`. Its history, including who deleted it, stays in the audit trail. See [Audit and compliance](./audit-compliance.mdx).

***

## Step 4: Name the spending limit

***

On a `limit_exceeded` denial, `limitUsageDetails` holds one entry per limit Tracer checked, and the entries marked `"exceeded": true` are the ones the amount would push past:

```json theme={null}
{
  "validationId": "8f14e45f-ea3b-4c6e-9a1c-2b7d5e0a91c4",
  "requestId": "7c3f1b8e-5a2d-4c6b-9e1f-0a4d8b2c6e30",
  "decision": "DENY",
  "matchedRuleIds": [],
  "evaluatedRuleIds": [
    "a6b7c8d9-0e1f-4a2b-9c3d-4e5f60718293"
  ],
  "reason": "limit_exceeded",
  "totalRulesLoaded": 2,
  "truncated": false,
  "limitUsageDetails": [
    {
      "limitId": "b2d4f6a8-1c3e-4507-9b8d-6f0a2c4e6810",
      "limitAmount": "50000",
      "scope": "(segment:2f1c9b7e-40a5-4d18-9c6b-3e7f5a0d1b24,transactionType:CARD)",
      "period": "DAILY",
      "currentUsage": "51500",
      "attemptedAmount": "1500",
      "exceeded": true
    },
    {
      "limitId": "d4f6a8b2-3e5c-4709-8b6d-0a2c4e681012",
      "limitAmount": "400000",
      "scope": "(account:550e8400-e29b-41d4-a716-446655440100)",
      "period": "MONTHLY",
      "currentUsage": "128400",
      "attemptedAmount": "1500",
      "exceeded": false
    }
  ],
  "processingTimeMs": 14.2,
  "evaluatedAt": "2026-07-31T14:05:09.481Z"
}
```

Read the exceeded entry as the arithmetic of the denial: `attemptedAmount` against `limitAmount`. The `currentUsage` field reports what that limit's current period and matched scope would hold with this transaction included. In the entry above, a `1500` purchase would take a `50000` daily cap to `51500`.

A `PER_TRANSACTION` limit keeps no count, so its entry reports `currentUsage` as `0` and `attemptedAmount` against `limitAmount` is the whole comparison.

`GET /v1/limits/{limitId}` gives the limit's current name and configuration. See [Retrieve a limit](/en/reference/products/tracer/retrieve-limit). The decision record keeps the ceiling, period, and scope that applied when Tracer made the decision. A limit changed since then does not change what the record says.

For how each period counts and how consumption accumulates, see [Spending limits](./spending-limits.mdx).

***

## Step 5: Retrieve the record later

***

Tracer stores every decision under its `validationId`:

```http theme={null}
GET /v1/validations/8f14e45f-ea3b-4c6e-9a1c-2b7d5e0a91c4
X-API-Key: {api_key}
```

The record answers with the transaction context Tracer evaluated (`transactionType`, `amount`, `asset`, `transactionTimestamp`, `account`, and the optional `segment`, `portfolio`, `merchant`, and `metadata`), plus the same `decision`, `reason`, `matchedRuleIds`, `evaluatedRuleIds`, and `limitUsageDetails` the original response carried, and a `createdAt`. See [Retrieve a validation](/en/reference/products/tracer/retrieve-validation).

Read out this record in a dispute. It holds the input and the outcome in one document. It does not change when rules or limits change afterwards.

***

## Step 6: Find records when you do not have the id

***

`GET /v1/validations` lists stored decisions, newest first, with cursor pagination:

```http theme={null}
GET /v1/validations?decision=DENY&account_id=550e8400-e29b-41d4-a716-446655440100&start_date=2026-07-01T00:00:00Z&end_date=2026-07-31T23:59:59Z
X-API-Key: {api_key}
```

> [!WARNING]
>
> **A query with no dates covers the last 90 days, not the full retention period.** Tracer applies that default window only when both `start_date` and `end_date` are absent. Send either one, or both, to reach an older range.

Two filters answer the questions this guide exists for:

* `matched_rule_id={ruleId}`: every stored decision this rule matched
* `exceeded_limit_id={limitId}`: every stored decision this limit stopped

Each result is a summary: `validationId`, `decision`, `reason`, `amount`, `asset`, `transactionType`, `accountId`, `matchedRuleIds`, `exceededLimitIds`, `processingTimeMs`, and `createdAt`. Take the `validationId` of the one you want and retrieve it with Step 5 for the full record. See [List validations](/en/reference/products/tracer/list-validations) for every filter and the pagination fields.

***

## Step 7: Pull the audit event behind the decision

***

The audit trail records the decision under the `validationId` as the event's `resourceId`:

```http theme={null}
GET /v1/audit-events?resource_type=transaction&resource_id=8f14e45f-ea3b-4c6e-9a1c-2b7d5e0a91c4
X-API-Key: {api_key}
```

```json theme={null}
{
  "auditEvents": [
    {
      "hash": "a3f1e2b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2",
      "previousHash": "b4e2f3a5c6d7e8f9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3",
      "eventId": "1d0a6f52-7b3c-4e8d-9a01-5c2b6e7f8091",
      "eventType": "TRANSACTION_VALIDATED",
      "createdAt": "2026-07-31T14:05:09.492Z",
      "action": "VALIDATE",
      "result": "DENY",
      "resourceId": "8f14e45f-ea3b-4c6e-9a1c-2b7d5e0a91c4",
      "resourceType": "transaction",
      "actor": {
        "actorType": "api_key",
        "id": "tracer-default",
        "name": "",
        "ipAddress": "203.0.113.42"
      },
      "context": {
        "request": {
          "requestId": "7c3f1b8e-5a2d-4c6b-9e1f-0a4d8b2c6e30",
          "transactionType": "CARD",
          "amount": "1500",
          "asset": "BRL"
        },
        "response": {
          "decision": "DENY",
          "reason": "Rule matched with DENY action",
          "matchedRuleIds": [
            "3c8a5b21-9f4d-4e17-8b6a-1d2e3f405162"
          ],
          "evaluatedRuleIds": [
            "3c8a5b21-9f4d-4e17-8b6a-1d2e3f405162",
            "a6b7c8d9-0e1f-4a2b-9c3d-4e5f60718293"
          ],
          "totalRulesLoaded": 2,
          "truncated": false,
          "limitUsageDetails": [],
          "processingTimeMs": 9.4
        }
      }
    }
  ],
  "hasMore": false
}
```

What the audit event adds to the validation record:

| Field | Why it matters in a review |
| - | - |
| `actor` | Who made the call: the identity behind the request, and the client IP |
| `result` | The decision, indexed for filtering, so `result=DENY` scopes a query |
| `context.request` | The request snapshot recorded with the decision |
| `context.response` | The decision, reason, and rule identifiers as they were returned |
| `eventId` | The key for [Step 8](#step-8-verify-the-audit-event-in-an-audit) and for [Retrieve an audit event](/en/reference/products/tracer/retrieve-audit-event) |

> [!WARNING]
>
> The 90-day default window applies here too: `GET /v1/audit-events` with neither `start_date` nor `end_date` covers the last 90 days. Send the range you want when the decision is older than that.

The same endpoint carries the lifecycle of rules and limits: who created, activated, or deleted them. See [List audit events](/en/reference/products/tracer/list-audit-events) for the filters, and [Audit and compliance](./audit-compliance.mdx) for the event types and retention periods.

***

## Step 8: Verify the audit event in an audit

***

Pass the `eventId` to the verification endpoint:

```http theme={null}
GET /v1/audit-events/1d0a6f52-7b3c-4e8d-9a01-5c2b6e7f8091/verify
X-API-Key: {api_key}
```

```json theme={null}
{
  "isValid": true,
  "totalChecked": 12345,
  "message": "Hash chain integrity verified successfully"
}
```

`isValid: true` establishes that every record from the first one through the one you named still matches the hash stored with it. Each also links to the hash of the record before it. Within that span, no record was removed, re-ordered, or re-dated. `totalChecked` reports how many records the check covered.

On a failed check, `isValid` is `false`, `message` reports tampering, and `firstInvalidId` carries an internal sequence number for the diverging record. That number is not an audit-event id, so it is not a value to pass to `GET /v1/audit-events/{id}`.

See [Verify an audit event](/en/reference/products/tracer/verify-audit-event).

> [!NOTE]
>
> Hand over the two together: the retrieved event from Step 7 is the content of the decision, and the verification result is the evidence that the chain holding it is intact. The verification call reports on the chain. It does not return the record.

***

## Common pitfalls

***

> [!WARNING]
>
> **What usually goes wrong in a review:**
>
> * **"My query for last year came back empty."** A query with no `start_date` and no `end_date` covers the last 90 days. Send the range you want.
> * **"`matchedRuleIds` has three entries and only one denied."** The array holds every rule that matched, whatever action it carries. Retrieve each rule and read its `action` (Step 3).
> * **"`limitUsageDetails` is empty on a denial."** The decision came from a rule, not a limit. Read `reason` (Step 2).
> * **"`currentUsage` is higher than what the customer actually spent."** It already includes the attempted amount, so it is a projection. On an exceeded limit the counter stays the same, so the stored consumption does not include this transaction.
> * **"The rule that fired no longer exists."** Deleted rules stop answering on `GET /v1/rules/{id}`. Query their lifecycle through `GET /v1/audit-events?resource_type=rule&resource_id={ruleId}`.

### Error codes

| Code | Status | What to change |
| - | - | - |
| `0065` | 400 | The id in the path is not a UUID |
| `0432` | 404 | No stored validation has that `validationId` |
| `0381` | 404 | No audit event has that `eventId` |
| `0077` | 400 | A date is not RFC3339 with a timezone. Send `2026-07-01T00:00:00Z`, not `2026-07-01` |
| `0083` | 400 | `end_date` falls before `start_date` |
| `0431` | 400 | A filter on `GET /v1/validations` carries a value the endpoint does not accept |
| `0080` / `0331` | 400 | `limit` is above 1000, or is not positive |
| `0334` | 400 | `cursor` was sent together with `sort_by` or `sort_order`. The cursor already carries them |

The complete list is in the [Tracer error list](/en/reference/products/tracer/tracer-error-list).

***

## Quick reference

***

| Step | Method | Endpoint |
| - | - | - |
| Validate a transaction | POST | `/v1/validations` |
| Find stored decisions | GET | `/v1/validations` |
| Retrieve one decision | GET | `/v1/validations/{id}` |
| Name a rule | GET | `/v1/rules/{id}` |
| Name a limit | GET | `/v1/limits/{id}` |
| Find audit events | GET | `/v1/audit-events` |
| Retrieve one audit event | GET | `/v1/audit-events/{id}` |
| Verify the hash chain | GET | `/v1/audit-events/{id}/verify` |


# Rules engine
Source: https://docs.lerian.studio/en/products/tracer/rule-engine

Write CEL expressions in the Tracer rules engine to shape ALLOW, DENY, and REVIEW decisions in real time, and manage the DRAFT to ACTIVE lifecycle.

The rules engine is what risk and fraud teams use to change how Tracer approves or blocks transactions, without touching application code.

**What changes in your operation:** rule changes ship through an API endpoint, not through a release. An analyst can publish a new rule in the morning and see it evaluating real transactions within seconds. Tracer records every match, so you can trace a denied customer call six months later back to the exact rule that fired.

**Trade-off:** you have to think in CEL (Common Expression Language) instead of Go, Python, or Java. The learning curve is short (most rules are one line), but the team writing them is no longer your application developers. The upside is no deploys, full audit, and the people closest to the policy own the policy.

> [!TIP]
>
> **This guide is for** risk and fraud analysts who will write rules, developers integrating the validation call, and compliance officers reading the audit trail. The CEL examples get technical further down, but the lifecycle and decision logic are useful for anyone evaluating the product.

The **Tracer rules engine** evaluates validation logic written in CEL (Common Expression Language) (A lightweight expression language for writing business rules, for example, 'if transaction amount > 10000 then REVIEW'. Tracer uses CEL for validation rules.), a type-safe expression language from Google. Tracer compiles expressions at rule creation and runs them during every transaction validation. You change behavior by updating rules through the API, without redeploying code.

## Why use the rules engine

***

* **Flexibility**: Create and modify rules without code deploys
* **Execution model**: Tracer evaluates compiled expressions during validation
* **Type safety**: Expression syntax validated at rule creation
* **No short-circuit**: Tracer evaluates matching rules together, so the audit trail records the rules that triggered, regardless of the winning category
* **Scope-based**: Apply rules to specific segments, accounts, or transaction types

By the end of this guide, you will:

* Understand rule engine concepts and evaluation flow
* Create and test expression-based rules
* Manage the rule lifecycle (DRAFT, ACTIVE, INACTIVE, DELETED)
* Apply best practices for rule management

***

## What is the rules engine

***

The rules engine is the Tracer component responsible for evaluating expressions during transaction validation. It enables fraud analysts and risk managers to configure business logic that executes in real time, without requiring code deployments or engineering support.

### How it works

![How the rules engine evaluates configured expressions against the transaction context during validation and returns a decision](https://mintcdn.com/lerian-49cb71fc/svQbQMf9Iz90q0Cc/images/en/d2/how-rules-works.svg?fit=max\&auto=format\&n=svQbQMf9Iz90q0Cc\&q=85\&s=1ad8112b778cb2db149856477f7718a1)

Figure 1. Rules engine evaluation flow

In this flow:

* **Load rules** fetches active rules from cache
* **Evaluate expressions** runs the CEL expression of each rule whose scope matches the transaction
* **Collect matches** gathers all rules that matched and determines the decision

### Evaluation pattern

**Decision precedence** (highest to lowest):

1. **DENY**: any matching `DENY` rule wins outright.
2. **Limit exceeded**: if no DENY rule matched but the transaction exceeds any applicable limit, the decision is DENY. Rule precedence applies first, and limits come in only when no DENY rule matched.
3. **REVIEW**: if no DENY rule matched and the transaction exceeded no limit, any matching `REVIEW` rule wins. A rule whose expression fails for the request also gives REVIEW, with the reason `rule_evaluation_error`.
4. **ALLOW**: if only `ALLOW` rules matched, the decision is ALLOW.
5. **Default**: if no rule matched at all, a validation returns the configured `DEFAULT_DECISION_WHEN_NO_MATCH` (`ALLOW` unless explicitly set to `DENY`). Tracer accepts only `ALLOW` and `DENY`. `REVIEW` is deliberately not a valid no-match default, and any other value fails the service at boot.

When the Midaz ledger reserves a transaction, Tracer runs the same rules with a smaller input. See [Rules on a reserve](/en/products/tracer/integration-guide#rules-on-a-reserve).

> [!NOTE]
>
> **Why DENY beats REVIEW beats ALLOW.** Precedence never changes and you cannot configure it, on purpose. It removes the "which DENY rule wins?" ambiguity at runtime and makes audit trivial. The response always identifies the strictest action that fired. The cost is that you can't write "ALLOW rules that override DENYs". If you need that pattern, the right answer is to make the DENY rule more specific instead.

> [!NOTE]
>
> Tracer returns decisions. It does not block transactions directly. Your system receives the decision and must take the appropriate action (e.g., blocking, allowing, or queuing for review).

***

## Core concepts

***

Before creating rules, understand the foundational elements.

### Rules

A rule is a unit of business logic composed of:

* **Expression** - A type-safe expression that evaluates to true or false
* **Action** - What decision to return when the expression is true
* **Scopes** - Which transactions the rule applies to
* **Status** - The rule's lifecycle state

### Expressions

You write expressions in **CEL (Common Expression Language)**, a type-safe language that evaluates transaction context and returns a boolean value (true or false). CEL provides compile-time validation, so syntax errors surface when you create the rule, not when Tracer processes transactions.

Example expressions:

```
amount > 10000
```

```
segment.segmentId == "high-risk-segment-uuid" && amount > 5000
```

```
merchant["category"] == "7995"
```

(`merchant.category` is the 4-digit ISO 18245 MCC code. `"7995"` is the MCC for betting/casino. Tracer accepts both `merchant.category` and `merchant["category"]`. The production examples use bracket notation by convention. If you need to match on a string label like `"gambling"`, store it in `metadata` and match on that instead.)

Expressions read the validation request through ten variables. For the field types and formats behind each one, see the [ValidationRequest schema](/en/reference/products/tracer/validate-transaction) in the API reference.

| Variable | Type | What you typically match on |
| - | - | - |
| `amount` | number | The transaction value, in the same units you send in the request: `"1500.00"` reaches an expression as `1500`. Safe range is `±2^53`. |
| `transactionType` | string | One of `CARD`, `WIRE`, `PIX`, `CRYPTO`. |
| `subType` | string | Free-form, lower case (e.g., `"international"`, `"debit"`). Empty string when not provided. |
| `asset` | string | 1 to 100 uppercase letters (e.g., `"BRL"`). |
| `transactionTimestamp` | int | Transaction time in Unix nanoseconds. Divide by `1000000000` for seconds. |
| `account` | map | `accountId`, `type`, `status`, `metadata`. |
| `segment` | map | `segmentId`, `name`, `metadata`. |
| `portfolio` | map | `portfolioId`, `name`, `metadata`. |
| `merchant` | map | `merchantId`, `name`, `category`, `country`, `metadata`. |
| `metadata` | map | Custom fields your integration passes in the request payload. |

Field values worth knowing before you write a condition:

* `account.status` and `account.type` are free text, up to 50 and 256 characters. Your expression receives them as you send them.
* `merchant.category` takes a 4-digit ISO 18245 MCC code. `merchant.country` takes an ISO 3166-1 alpha-2 code.
* Those four fields are optional on the request. A field the request omits reaches your expression as an empty string, so a condition that tests it for a specific value is false.
* `segment.segmentId`, `portfolio.portfolioId`, `account.accountId`, and `merchant.merchantId` are UUID strings.

> [!NOTE]
>
> `segmentId` and `portfolioId` live on the top-level `segment` and `portfolio` variables, not on `account`. To match by segment, write `segment.segmentId == "..."`, not `account.segmentId == "..."`.
>
> When presence itself is the condition you want, write `size(segment) > 0` or `"risk_score" in metadata`.

> [!NOTE]
>
> Tracer bounds expression cost with `CEL_COST_LIMIT` (default `10000`). The check runs at compile time (on create, on expression update, and again on activate), not only at activation. Tracer rejects an expression whose worst-case estimated cost exceeds the limit, the first time you submit it, with error code `0342` (cost limit exceeded). Syntax errors surface as `0340`, type errors (including an expression that does not return a boolean) as `0341`, and a failure to estimate cost at all as `0345`.

### Expression examples by use case

Here are practical examples by business scenario:

#### Amount-based rules

```cel theme={null}
// Block transactions above a threshold
amount > 10000

// Block high-value international transfers
transactionType == "WIRE" && subType == "international" && amount > 50000

// Review large cryptocurrency transactions
transactionType == "CRYPTO" && amount > 5000
```

#### Merchant-based rules

```cel theme={null}
// Block gambling merchants
merchant.category == "7995"

// Block high-risk merchant categories
merchant.category in ["7995", "5967", "5966"]

// Review transactions from new merchant countries
merchant.country != "BR" && amount > 1000
```

#### Account-based rules

```cel theme={null}
// Block suspended accounts
account.status == "suspended"

// Review transactions from newly created accounts
metadata.accountAgeDays < 30 && amount > 500

// Block closed accounts
account.status == "closed"
```

#### Combined conditions

```cel theme={null}
// High-value transaction from high-risk segment
segment.segmentId == "high-risk-segment-uuid" && amount > 5000

// International Pix above threshold
transactionType == "PIX" && subType == "international" && amount > 10000

// Large card transaction to foreign merchant
transactionType == "CARD" && merchant.country != "BR" && amount > 3000
```

#### Time-based rules

```cel theme={null}
// Review late-night card transactions above BRL 5,000
transactionType == "CARD" && amount > 5000 && timestamp(transactionTimestamp / 1000000000).getHours("UTC") >= 22

// Review weekend transactions above BRL 10,000
timestamp(transactionTimestamp / 1000000000).getDayOfWeek("UTC") in [0, 6] && amount > 10000
```

#### Using metadata

```cel theme={null}
// Block transactions from untrusted devices
metadata.deviceTrust == "untrusted"

// Review first-time purchases above threshold
metadata.isFirstPurchase == true && amount > 1000

// Block transactions outside business hours (using metadata)
metadata.isBusinessHours == false && amount > 5000

// VIP customers bypass certain restrictions
metadata.customerTier == "vip" && amount < 50000
```

> [!NOTE]
>
> Your integration provides metadata fields. Design your payload to include the context your rules need.

### Actions

Actions determine the decision when an expression evaluates to true:

| Action | Description |
| - | - |
| `ALLOW` | Allow the transaction |
| `DENY` | Deny the transaction |
| `REVIEW` | Route to manual review |

### Scopes

Scopes define which transactions a rule applies to. A rule with no `scopes` is **global** and evaluates against every transaction. A rule with one or more scope objects evaluates only when the transaction matches at least one of them (OR semantics across scope objects).

Within a single scope object, the supported fields are:

* `segmentId` - Match transactions from a specific segment
* `portfolioId` - Match transactions from a specific portfolio
* `accountId` - Match transactions from a specific account
* `merchantId` - Match transactions to a specific merchant
* `transactionType` - Match specific transaction types (CARD, WIRE, PIX, CRYPTO)
* `subType` - Match specific subtypes (debit, credit, instant, etc.)

**Matching semantics:**

* **Within one scope object:** fields combine with AND. A field you leave out works as a wildcard (matches any value). You must set at least one field. Tracer rejects empty scope objects (`{}`) with error code `0358`.
* **Across multiple scope objects on the same rule:** they combine with OR. The rule matches if any scope object matches the transaction.

For example, a rule with two scopes (one targeting `transactionType: CARD` and another targeting `transactionType: PIX`) runs for both card and Pix transactions. A single scope with both `segmentId` AND `accountId` requires the transaction to match the segment AND the account.

***

## Rule lifecycle

***

Rules progress through a defined lifecycle to ensure safe deployment.

![Lifecycle of rules and limits in Tracer, showing the status transitions a definition moves through from creation to active enforcement](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/rules-limits-lifecycle-tracer.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=0e9996cc0609ad9f3b8d0ee10feb3a56)

Figure 2. Rules lifecycle and status transitions

### States

| State | Description |
| - | - |
| `DRAFT` | Not evaluated; expression can be modified freely |
| `ACTIVE` | Evaluated during validations; expression is immutable |
| `INACTIVE` | Not evaluated; preserved for audit trail; can be reactivated. The expression is still immutable in this state. To edit it, move the rule back to DRAFT via `POST /v1/rules/{id}/draft`. |
| `DELETED` | Soft-deleted; not returned by listings and cannot be recovered through the API, but the row is preserved in the database for audit trail. |

### Transitions

| Transition | From | To | Description |
| - | - | - | - |
| `activate` | DRAFT, INACTIVE | ACTIVE | Start evaluation (validates expression) |
| `deactivate` | ACTIVE | INACTIVE | Stop evaluation |
| `draft` | INACTIVE | DRAFT | Re-edit a previously deactivated rule before reactivating |
| `delete` | DRAFT, INACTIVE | DELETED | Permanent removal (cannot delete ACTIVE rules) |

> [!NOTE]
>
> You must deactivate active rules before deletion. This prevents accidental removal of rules that Tracer still evaluates.

***

## Create a rule

***

Create rules using `POST /v1/rules`. Tracer creates rules in `DRAFT` status by default.

A rule requires:

* **name**: A descriptive name, unique within its context. The rule's scopes decide the context (the lowest `segmentId` across them), and rules with no scope share a single global context. So the same rule name can coexist across two different segments, but not twice inside one. Comparison is case-sensitive and preserves internal whitespace, and Tracer trims leading and trailing whitespace before storage. A collision returns `409 Conflict` with error code `0441`. Reference the rule by the `ruleId` in the response.
* **expression**: A CEL expression that evaluates to true or false
* **action**: The decision to return when the expression matches (ALLOW, DENY, or REVIEW)
* **scopes** (optional): Limit which transactions the rule applies to

For complete payload structure and field details, see the [API reference](/en/reference/products/tracer/create-rule).

***

## Activate and deactivate rules

***

After creating a rule, activate it to start evaluation. Deactivate rules to stop evaluation without deleting them.

| Operation | Endpoint | Description |
| - | - | - |
| Activate | `POST /v1/rules/{id}/activate` | Start evaluating this rule |
| Deactivate | `POST /v1/rules/{id}/deactivate` | Stop evaluating (preserves for audit) |

> [!NOTE]
>
> Deactivating a rule preserves it for audit purposes. Use delete only when you want to permanently remove a rule.

***

## List and query rules

***

Query rules for management and auditing using `GET /v1/rules`.

### Query parameters

| Parameter | Type | Description |
| - | - | - |
| `name` | string | Filter by name (case-insensitive partial match) |
| `status` | string | Filter by status (DRAFT, ACTIVE, INACTIVE). `DELETED` is not a valid filter value. |
| `action` | string | Filter by action (ALLOW, DENY, REVIEW) |
| `account_id` | UUID | Filter by scope: account ID |
| `segment_id` | UUID | Filter by scope: segment ID |
| `portfolio_id` | UUID | Filter by scope: portfolio ID |
| `merchant_id` | UUID | Filter by scope: merchant ID |
| `transaction_type` | string | Filter by scope: transaction type (CARD, WIRE, PIX, CRYPTO) |
| `sub_type` | string | Filter by scope: subtype (e.g., debit, credit) |
| `limit` | integer | Items per page (default: 10, max: 100) |
| `cursor` | string | Pagination cursor from previous response |
| `sort_by` | string | Sort field: `created_at`, `updated_at`, `name`, `status` (default: `created_at`) |
| `sort_order` | string | Sort direction: `ASC`, `DESC` (default: `DESC`) |

### Get a specific rule

Use `GET /v1/rules/{id}` to retrieve the full rule definition including expression and scopes.

***

## Update a rule

***

> [!WARNING]
>
> The `expression` field is immutable in ACTIVE and INACTIVE states. Deactivating a rule is not enough. To edit an expression, move the rule from ACTIVE → INACTIVE (`POST /v1/rules/{id}/deactivate`), then from INACTIVE → DRAFT (`POST /v1/rules/{id}/draft`). Only DRAFT rules accept expression updates. Once edited, reactivate with `POST /v1/rules/{id}/activate`.

***

## Delete a rule

***

Delete rules you no longer need. You can delete only DRAFT and INACTIVE rules. Deactivate ACTIVE rules first.

```http theme={null}
DELETE /v1/rules/{id}
X-API-Key: {api_key}
```

> [!WARNING]
>
> Deletion is permanent. You cannot recover deleted rules, and they do not appear in any listings.

***

## Best practices

***

Follow these practices for effective, maintainable rules.

### Naming

* **Use descriptive names** - The name should clearly state what the rule does
* **Include context** - Mention the scenario or transaction type
* **Avoid abbreviations** - Prefer clarity over brevity

| Less clear | More clear |
| - | - |
| `Rule 1` | `Block night transactions above BRL 5,000` |
| `Block high` | `Deny high-value weekend transactions` |
| `Pix rule` | `Review Pix transfers to new recipients` |

### Expression design

* **Keep expressions simple** - Complex logic is harder to maintain
* **Use scopes for filtering** - Don't repeat scope conditions in expressions
* **Test edge cases** - Consider boundary values and null fields

### Lifecycle management

* **Start in DRAFT** - Test before activating
* **Return to DRAFT before editing the expression** - The expression is immutable in ACTIVE and INACTIVE. Move the rule to DRAFT via `POST /v1/rules/{id}/draft` to edit, then reactivate
* **Archive unused rules** - Keep audit trail intact
* **Delete only when certain** - Deletion is permanent

### Monitoring

* **Review matched rules** - Check which rules trigger
* **Monitor DENY rates** - High deny rates may indicate overly aggressive rules
* **Audit regularly** - Ensure rules still align with business requirements

> [!WARNING]
>
> **Common pitfalls when working with rules:**
>
> * **"I edited the expression but the change didn't take effect."** The expression is immutable in ACTIVE and INACTIVE states. Move the rule back to DRAFT via `POST /v1/rules/{id}/draft`, edit, then reactivate. INACTIVE alone is not enough.
> * **"My rule is ACTIVE but another Tracer instance isn't evaluating it yet."** Activation takes effect right away on the instance that served the activate call. When you run several instances behind a load balancer, the others pick the change up on their next rule sync (`RULE_SYNC_POLL_INTERVAL_SECONDS`, default `10`). Deactivation propagates the same way. Plan integration tests around that gap when the calls can land on different instances.
> * **"I want to delete an ACTIVE rule."** You can't. Call `POST /v1/rules/{id}/deactivate` first, then `DELETE /v1/rules/{id}`. This forces a visible step where the rule stops affecting traffic before it disappears from listings.
> * **"My empty scope `{}` gets rejected with error code `0358`."** Every scope object must have at least one field set. To run a rule globally (against every transaction), omit the `scopes` array entirely. Don't pass `{}`.

***

## Quick reference

***

Key endpoints, actions, and status information.

### Endpoints

| Operation | Method | Endpoint |
| - | - | - |
| Create rule | POST | `/v1/rules` |
| List rules | GET | `/v1/rules` |
| Get rule | GET | `/v1/rules/{id}` |
| Update rule | PATCH | `/v1/rules/{id}` |
| Delete rule | DELETE | `/v1/rules/{id}` |
| Activate rule | POST | `/v1/rules/{id}/activate` |
| Deactivate rule | POST | `/v1/rules/{id}/deactivate` |
| Draft rule | POST | `/v1/rules/{id}/draft` |

### Statuses

| Status | Evaluated | Editable | Can delete |
| - | - | - | - |
| `DRAFT` | No | Yes | Yes |
| `ACTIVE` | Yes | Partial (expression immutable) | No (deactivate first) |
| `INACTIVE` | No | Partial (expression immutable; return to DRAFT first) | Yes |
| `DELETED` | No | No | N/A |


# Setting up a spending limit
Source: https://docs.lerian.studio/en/products/tracer/setting-up-a-spending-limit

Cap what an account, a portfolio, or a segment can spend in a period with Tracer, activate the cap, and read how much of it is left from the validation decision.

A product or risk decision has landed as a sentence: "no more than R\$ 20,000 per account per month." This guide turns that sentence into a live cap, and shows where to read how much of it a customer has left.

**What changes in your operation:** the ceiling moves from a constant compiled into a service to a stored definition you create, activate, raise, and stop. Every decision that touches it reports what it consumed.

> [!TIP]
>
> **This guide is for** product and risk teams setting the ceiling, and developers wiring `POST /v1/validations` into the payment path. Steps 1 and 2 are decisions to make before any call. Steps 3 to 6 are the calls.

## Before you start

***

* [ ] Tracer running and reachable, with an API key. See [Getting started](./getting-started.mdx)
* [ ] The id of the account, portfolio, or segment the cap applies to
* [ ] The asset code for the transactions you want capped
* [ ] Familiarity with limit types, time windows, and custom periods. See [Spending limits](./spending-limits.mdx)

All calls below send the API key as `X-API-Key` and run against `http://localhost:4020`.

***

## Step 1: Decide what the cap is addressed to

***

A limit carries a list of scope objects, and each object names what the limit applies to. These fields are available inside one object:

| Field | Applies the limit to |
| - | - |
| `accountId` | Transactions on one account |
| `portfolioId` | Transactions on one portfolio |
| `segmentId` | Transactions on one segment |
| `merchantId` | Transactions to one merchant |
| `transactionType` | One of `CARD`, `WIRE`, `PIX`, `CRYPTO` |
| `subType` | One transaction subtype, such as `purchase` (matched without regard to case) |

Fields inside one object combine with AND. A field you leave out is a wildcard. Across objects the list combines with OR, so a limit with two objects applies when either one matches.

The id you name decides the answer to "R\$ 20,000 per account":

**One account, its own budget**

```json theme={null}
"scopes": [
  { "accountId": "550e8400-e29b-41d4-a716-446655440100" }
]
```

The cap applies to that account. It counts that account's spending and no one else's. For a per-account ceiling across a book of customers, each account gets its own limit.

**One segment, one shared budget**

```json theme={null}
"scopes": [
  { "segmentId": "2f1c9b7e-40a5-4d18-9c6b-3e7f5a0d1b24" }
]
```

The cap applies to the segment as a whole. Every account in that segment draws down the same R\$ 20,000 (the first customers to spend consume it for the rest).

**Narrowed to one rail**

```json theme={null}
"scopes": [
  {
    "accountId": "550e8400-e29b-41d4-a716-446655440100",
    "transactionType": "PIX"
  }
]
```

The cap counts only that account's Pix transactions. Its card and wire traffic passes without touching this limit.

> [!NOTE]
>
> A limit also carries an `asset`, and Tracer checks a limit against a transaction only when the two match. Tracer does not check a limit created in `BRL` against a `USD` transaction. A book that settles in two currencies needs a limit for each.

A limit must carry at least one scope object, and each object must set at least one field. Tracer rejects an empty list or an empty object. See [What goes wrong](#what-goes-wrong).

***

## Step 2: Choose the period

***

`limitType` decides both the size of the ceiling's window and when a new count starts. Tracer offers five:

| `limitType` | The count covers | A new count starts |
| - | - | - |
| `DAILY` | One day, UTC | Each day at the reset time (00:00 UTC by default) |
| `WEEKLY` | One week, UTC | Each Monday at the reset time (00:00 UTC by default) |
| `MONTHLY` | One month, UTC | On the 1st at the reset time (00:00 UTC by default) |
| `CUSTOM` | A date range you set | Not at all. One count spans the whole range |
| `PER_TRANSACTION` | A single transaction | No count is kept; each transaction is measured on its own |

"per month" is `MONTHLY`.

> [!WARNING]
>
> **The boundary is UTC, not local time.** A São Paulo customer spending at 21:30 on 31 July is at 00:30 UTC on 1 August. Without `resetTime`, that amount lands in the August count, not July's.

To move the boundary, set `resetTime` in `HH:MM` UTC when you create a `DAILY`, `WEEKLY`, or `MONTHLY` limit. For example, `"03:00"` starts each period at midnight in São Paulo (UTC-3). You cannot change `resetTime` after creation. See [Reset time](./spending-limits.mdx#reset-time).

`CUSTOM` takes `customStartDate` and `customEndDate` and is the shape for a campaign or a promotion. Those two fields belong to `CUSTOM`. Tracer rejects them on the other four types. To restrict a cap to certain hours of the day instead, see [time windows](./spending-limits.mdx#time-windows).

***

## Step 3: Create the limit

***

`POST /v1/limits` stores the definition. Tracer creates it in `DRAFT` and does not check it against transactions yet.

```bash theme={null}
curl -X POST http://localhost:4020/v1/limits \
  -H "X-API-Key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly Account Spending Cap",
    "description": "Caps total monthly outflow for one account",
    "limitType": "MONTHLY",
    "maxAmount": "20000.00",
    "asset": "BRL",
    "scopes": [
      { "accountId": "550e8400-e29b-41d4-a716-446655440100" }
    ]
  }'
```

A successful call answers `201`. The body carries the stored limit. Two fields matter now:

| Field | What to do with it |
| - | - |
| `limitId` | The id every later call in this guide takes. Keep it |
| `status` | `DRAFT`, so Tracer does not check the limit yet. [Step 4](#step-4-activate-it) changes that |

> [!NOTE]
>
> **Names are unique across limits, and the character set is narrow.** `name` accepts ASCII letters and digits, spaces, and `-`, `_`, `.`, `(`, `)`. Tracer rejects an accent, or a dash typed as an em dash, with `0371`. Tracer rejects a name another live limit already holds, with `0442`. Deleting a limit frees its name again.

For the full payload and every optional field, see [Create a limit](/en/reference/products/tracer/create-limit).

***

## Step 4: Activate it

***

Tracer does not check a `DRAFT` limit. Activation is what puts it in the path:

```bash theme={null}
curl -X POST http://localhost:4020/v1/limits/{limitId}/activate \
  -H "X-API-Key: your-secure-api-key"
```

The response carries the limit with `status` set to `ACTIVE`. From here, Tracer checks `POST /v1/validations` whose transaction matches the scope and asset against this limit.

> [!NOTE]
>
> **Activating mid-month does not import the month's history.** Tracer counts a transaction against a limit at the moment it decides on it. Spending that happened while the limit was `DRAFT` is not in the count. A cap activated on the 20th governs what happens from the 20th onward.

See [Activate a limit](/en/reference/products/tracer/activate-limit).

***

## Step 5: Read how much is left

***

Every `POST /v1/validations` response carries `limitUsageDetails`, with one entry per limit Tracer checked:

```json theme={null}
{
  "limitId": "b2d4f6a8-1c3e-4507-9b8d-6f0a2c4e6810",
  "limitAmount": "20000",
  "scope": "(account:550e8400-e29b-41d4-a716-446655440100)",
  "period": "MONTHLY",
  "currentUsage": "20000",
  "attemptedAmount": "1500",
  "exceeded": false
}
```

| Field | What it reports |
| - | - |
| `limitAmount` | The ceiling that was checked |
| `currentUsage` | Projected consumption of that limit's current period and matched scope if this transaction is allowed |
| `attemptedAmount` | The amount measured against the ceiling |
| `period` | The limit's type (`MONTHLY` here) |
| `scope` | The limit's scope as text, each object in parentheses, several objects joined by `OR` |
| `exceeded` | Whether the amount would push this cap past its ceiling |

In the entry above, a R\$ 1,500 purchase took an 18,500 month to exactly 20,000 and spent the cap. Tracer denies the next transaction on that account until August.

When a transaction exceeds a limit, the decision is `DENY` and `reason` is `limit_exceeded`. Tracer does not add to the count the amount that would have crossed the ceiling. A limit produces a denial, not a flag for review. To go from such a denial back to the limit that caused it, see [Reviewing a denied transaction](./reviewing-a-denied-transaction.mdx).

### The other reading

`GET /v1/limits/{limitId}/usage` answers with a total for the limit rather than for one period. It adds up the usage counters recorded against it, across the periods and scopes it has accumulated. Use it to review how much a limit has absorbed overall, not to answer how much a customer has left this month.

See [Retrieve a limit usage snapshot](/en/reference/products/tracer/retrieve-limit-usage).

***

## Step 6: Change it, pause it, remove it

***

**1. Raise or lower the ceiling**

```bash theme={null}
curl -X PATCH http://localhost:4020/v1/limits/{limitId} \
  -H "X-API-Key: your-secure-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "maxAmount": "30000.00" }'
```

`name`, `description`, `maxAmount`, and `scopes` are editable, and so are the time-window and custom-period fields. `limitType`, `asset`, and `resetTime` are not. Tracer rejects a request that sends any of them with `0380`, and a different period, asset, or reset time means a new limit. Tracer rejects an empty body with `0183`. See [Update a limit](/en/reference/products/tracer/update-limit).

Changing the ceiling does not clear the running count. Lower it below what the current period already consumed, and Tracer denies the account until the next period starts.

**2. Stop enforcing it**

```bash theme={null}
curl -X POST http://localhost:4020/v1/limits/{limitId}/deactivate \
  -H "X-API-Key: your-secure-api-key"
```

The limit moves to `INACTIVE` and Tracer stops checking it. It keeps its definition and its place in the audit trail (A chronological, immutable record of every action and transaction in the system, essential for regulatory compliance and dispute resolution.), and `POST /v1/limits/{limitId}/activate` puts it back in the path. See [Deactivate a limit](/en/reference/products/tracer/deactivate-limit).

**3. Take it back to draft**

```bash theme={null}
curl -X POST http://localhost:4020/v1/limits/{limitId}/draft \
  -H "X-API-Key: your-secure-api-key"
```

Moves an `INACTIVE` limit back to `DRAFT`. See [Return a limit to draft](/en/reference/products/tracer/draft-limit).

**4. Remove it**

```bash theme={null}
curl -X DELETE http://localhost:4020/v1/limits/{limitId} \
  -H "X-API-Key: your-secure-api-key"
```

Answers `204`. You have to deactivate a limit that is currently `ACTIVE` first. Tracer rejects the deletion with `0363`, which is what keeps a live ceiling from disappearing by accident. See [Delete a limit](/en/reference/products/tracer/delete-limit).

### Find the limits you already have

`GET /v1/limits` lists them, and filters by the same scope fields you set in Step 1:

```http theme={null}
GET /v1/limits?status=ACTIVE&account_id=550e8400-e29b-41d4-a716-446655440100&limit_type=MONTHLY
X-API-Key: {api_key}
```

`name`, `status`, `limit_type`, `account_id`, `segment_id`, `portfolio_id`, `merchant_id`, `transaction_type`, and `sub_type` all filter. Results are cursor-paginated. See [List limits](/en/reference/products/tracer/list-limits), and [Retrieve a limit](/en/reference/products/tracer/retrieve-limit) for one by id.

***

## What goes wrong

***

> [!WARNING]
>
> **What usually goes wrong when you set up a cap:**
>
> * **"The customer overspent and nothing stopped them."** Check `status` first. Tracer does not check a limit in `DRAFT` or `INACTIVE`. Then check that the limit's `asset` matches the transaction's, and that the scope names the id the transaction actually carried.
> * **"The segment cap ran out on day two."** A segment-scoped limit is one budget for the whole segment, not one per account in it. A per-account ceiling means a limit addressed to each account.
> * **"The month rolled over a few hours early."** Without `resetTime`, periods start at 00:00 UTC. Spending after 21:00 in UTC-3 belongs to the next UTC day, and on the last day of the month, to the next month. Create the limit with a `resetTime` to move the boundary.
> * **"I raised the limit and the account is still denied."** Raising the ceiling does not clear the count. Confirm the new `maxAmount` is above what the period already consumed.
> * **"`GET /v1/limits/{id}/usage` reports more than the customer spent this month."** That endpoint totals the counters recorded for the limit, across periods and scopes. For the current period, read `limitUsageDetails` on the validation response.

### Error codes

| Code | Status | What to change |
| - | - | - |
| `0009` | 400 | A field failed validation. `detail` names it, for example `scopes must have at least 1 item(s)`, `scope at index 0 must have at least one field set`, or `maxAmount must be greater than or equal to 0` |
| `0065` | 400 | The id in the path is not a UUID |
| `0183` | 400 | The `PATCH` body carried no editable field |
| `0362` | 404 | No limit has that id |
| `0363` | 422 | The transition is not allowed (deleting an `ACTIVE` limit, for instance) |
| `0366` | 400 | `asset` carries a character that is not a letter |
| `0371` | 400 | `name` carries a character the field does not accept |
| `0380` | 422 | The request tried to change `limitType`, `asset`, or `resetTime` |
| `0440` | 400 | `resetTime` is not in `HH:MM` format |
| `0442` | 409 | Another live limit already holds that name |
| `0537` | 400 | `resetTime` was set on a `CUSTOM` or `PER_TRANSACTION` limit |
| `0538` | 400 | `resetTime` falls inside the limit's time window |

The complete list is in the [Tracer error list](/en/reference/products/tracer/tracer-error-list).

***

## Quick reference

***

| Step | Method | Endpoint |
| - | - | - |
| Create a limit | POST | `/v1/limits` |
| Activate it | POST | `/v1/limits/{id}/activate` |
| Read consumption with the decision | POST | `/v1/validations` |
| Read the limit's cumulative total | GET | `/v1/limits/{id}/usage` |
| Change the ceiling | PATCH | `/v1/limits/{id}` |
| Stop enforcing it | POST | `/v1/limits/{id}/deactivate` |
| Take it back to draft | POST | `/v1/limits/{id}/draft` |
| Remove it | DELETE | `/v1/limits/{id}` |
| Find limits | GET | `/v1/limits` · `/v1/limits/{id}` |


# Spending limits
Source: https://docs.lerian.studio/en/products/tracer/spending-limits

Configure Tracer spending limits by account, portfolio, or segment with daily, weekly, monthly, and custom periods, time windows, and lifecycle controls.

Spending limits are how product and risk teams cap exposure per customer, per segment, or per portfolio without writing code. Common use cases: a daily ceiling on card spending for retail customers, a monthly cap on a specific MCC, a campaign-window limit for a marketing promotion.

**What changes in your operation:** spending caps no longer live as constants hardcoded in config files or scattered across services. They become versioned data with a clear lifecycle (DRAFT → ACTIVE → INACTIVE). Each new period starts counting from zero, and they're audit-trailed every time a transaction would have pushed past one.

**Trade-off:** counters need to stay consistent across replicas and races. Tracer handles that transactionally. If Tracer denies a transaction or sends it to REVIEW, the counter rolls back. You give up "local clever logic in each service" and gain a single, consistent number.

> [!TIP]
>
> This guide is for product managers configuring caps, risk teams reviewing exposure, compliance auditing what Tracer denied, and developers integrating the validation call. The Limit types section assumes no API knowledge. The lifecycle and PATCH sections assume basic REST.

**Spending limits** in Tracer let you control transaction amounts by scope (account, portfolio, segment) and period (daily, weekly, monthly, custom, or per-transaction). Tracer evaluates limits in real-time alongside rules, in the same `POST /v1/validations` call.

## Why use spending limits

***

* **Customer protection**: Detect overspending and return DENY decisions for unauthorized large transactions
* **Risk management**: Monitor exposure per account, segment, or portfolio
* **Flexible scoping**: Apply limits at different granularity levels
* **Period counting**: Daily, weekly, and monthly limits start a new count at each period boundary
* **Time windows**: Restrict limit enforcement to specific hours of the day
* **Custom periods**: Define date-bound limits for campaigns, promotions, or compliance requirements

By the end of this guide, you will:

* Understand limit types, time windows, and scoping options
* Create and configure spending limits with period-based controls
* Monitor limit usage in real-time
* Manage the limit lifecycle

***

## Core concepts

***

Understand the building blocks of spending limits.

### Limit types

Tracer supports five types of spending limits:

| Type | Description | Period counting |
| - | - | - |
| `DAILY` | Maximum amount per day | A new count starts each day at the reset time (00:00 UTC by default) |
| `WEEKLY` | Maximum amount per week | A new count starts each Monday at the reset time (00:00 UTC by default) |
| `MONTHLY` | Maximum amount per month | A new count starts on the 1st of the month at the reset time (00:00 UTC by default) |
| `CUSTOM` | Maximum amount within a user-defined date range | One count for the whole range; from `customEndDate` onward Tracer stops checking the limit |
| `PER_TRANSACTION` | Maximum amount per single transaction | No count is kept; each transaction is checked on its own |

### Reset time

`resetTime` moves the start of each `DAILY`, `WEEKLY`, and `MONTHLY` period to another time of day, in `HH:MM` format (24-hour, UTC). Without it, each period starts at 00:00 UTC. Set it when you create the limit. You cannot change it later.

Tracer rejects `resetTime` on a `CUSTOM` or `PER_TRANSACTION` limit with error code `0537`. When the limit has a time window, `resetTime` must not fall inside the window. It can equal `activeTimeStart` or `activeTimeEnd`. A reset time inside the window returns error code `0538`.

### Time windows

Time windows restrict when Tracer enforces a limit during the day. When a transaction occurs outside the configured time window, Tracer skips the limit and does not enforce it. The transaction proceeds without counting against that limit.

* **Format**: `HH:MM` (24-hour, UTC)
* **Both fields required**: If you set `activeTimeStart`, you must also set `activeTimeEnd` (and vice versa)
* **Half-open interval**: Start is inclusive, end is exclusive `[start, end)`
* **Overnight windows supported**: Setting `activeTimeStart: "20:00"` and `activeTimeEnd: "06:00"` creates a window from 8 PM to 6 AM UTC

> [!NOTE]
>
> You can apply time windows to any limit type (DAILY, WEEKLY, MONTHLY, CUSTOM, or PER\_TRANSACTION). Without a time window, the limit is active 24/7.

**Example: Pix compliance**

A financial institution needs to enforce lower Pix transfer limits during nighttime hours. The Pix nighttime window runs from 20:00 to 06:00 in Brasília time (UTC-3), which is 23:00 to 09:00 UTC:

* `limitType`: `DAILY`
* `maxAmount`: `"1000.00"`
* `activeTimeStart`: `"23:00"`
* `activeTimeEnd`: `"09:00"`
* `resetTime`: `"09:00"`
* Scope: Pix transactions

Tracer checks transactions between 23:00 and 09:00 UTC against the R\$ 1,000 limit. This limit does not affect transactions outside this window.

`resetTime: "09:00"` starts each daily count when the window closes. Without it, the count resets at 00:00 UTC (21:00 in Brasília), in the middle of the window. A customer can then spend the full R\$ 1,000 before 21:00 Brasília time and again after it.

> [!WARNING]
>
> Upgrade every Tracer pod to Midaz v4.2.0 or later before you create a limit with `resetTime`. A pod on an earlier version accepts the request but drops the field. Until every pod runs v4.2.0, an earlier pod still resets the count at 00:00 UTC.

### Custom periods

Custom periods define a date range during which a limit is active. This is useful for campaigns, promotions, seasonal events, or compliance requirements with specific date boundaries.

* **Required fields**: `customStartDate` and `customEndDate` (only for `CUSTOM` type)
* **Half-open interval**: Start is inclusive, end is exclusive `[start, end)`
* **Maximum duration**: 5 years
* **Cannot be in the past**: The `customEndDate` must not be entirely before the current date

> [!WARNING]
>
> The `customStartDate` and `customEndDate` fields are required for `CUSTOM` limits and forbidden for other limit types.

**Example: Black Friday campaign**

A retailer wants to set a special spending limit for the Black Friday period:

* `limitType`: `CUSTOM`
* `maxAmount`: `"100000.00"`
* `customStartDate`: `"2026-11-25T00:00:00Z"`
* `customEndDate`: `"2026-11-30T00:00:00Z"`
* Scope: CARD transactions in the retail segment

Usage accumulates across the whole window in a single count. From `customEndDate` onward, Tracer stops checking the limit.

### Combining time windows and custom periods

You can use time windows and custom periods together on `CUSTOM` limits. Tracer then checks a transaction against the limit only when it falls within both the custom period and the time window.

For example, take a `CUSTOM` limit with `customStartDate` Nov 25 to `customEndDate` Nov 30 and a time window of `09:00` to `18:00`. Tracer enforces that limit only during business hours within the Black Friday period.

### Scopes

Scopes define which transactions a limit applies to. Unlike rules, every limit must have at least one scope object. Limits cannot be global.

Within a single scope object, the supported fields are:

* `segmentId` - Apply to transactions from a specific segment
* `portfolioId` - Apply to transactions from a specific portfolio
* `accountId` - Apply to transactions from a specific account
* `merchantId` - Apply to transactions to a specific merchant
* `transactionType` - Apply to specific transaction types (CARD, WIRE, PIX, CRYPTO)
* `subType` - Apply to a specific transaction subtype (e.g., `debit`, `credit`)

**Matching semantics:**

* **Within one scope object:** fields combine with AND. A field you leave out works as a wildcard (matches any value). You must set at least one field. Tracer rejects empty scope objects (`{}`) with error code `0009`.
* **Across multiple scope objects on the same limit:** they combine with OR. The limit applies if any scope object matches the transaction.

**No hierarchy between limits.** A transaction can match multiple limits, for example an account-level and a segment-level limit. Tracer then checks all applicable limits independently in a single transaction. If the transaction exceeds any applicable limit, Tracer denies it.

### Usage tracking

For `DAILY`, `WEEKLY`, `MONTHLY`, and `CUSTOM` limits, Tracer keeps one usage counter per limit, per matched scope, per period. The validation decision reports that counter. See [Read consumption](#read-consumption).

For `DAILY`, `WEEKLY`, and `MONTHLY` counters, `expiresAt` is 90 days after the period reset. For `CUSTOM` counters, it is 90 days after `customEndDate`. Expired counters are eligible for cleanup. Physical deletion requires an enabled cleanup worker that runs successfully.

***

## How limits work

***

Tracer evaluates limits during validation requests.

### Limit check flow

![How Tracer checks all applicable spending limits during a validation request and updates their usage counters](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/how-limits-works.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=edfe5fa47c5158e9f86f97d7dcc9326b)

Figure 1. How spending limits work

1. **Find limits** - Query all active limits matching the transaction scope
2. **Check time window** - If the limit has a time window configured, verify the current server time falls within `activeTimeStart`/`activeTimeEnd`. If outside, Tracer skips the limit (it does not use the client-supplied `transactionTimestamp` here)
3. **Check custom period** - If the limit is `CUSTOM`, verify the current server time falls within `customStartDate`/`customEndDate`. If outside, Tracer skips the limit (again, it does not use `transactionTimestamp`)
4. **Calculate projected usage** - Add transaction amount to current usage
5. **Compare threshold** - Check if projected usage exceeds limit amount
6. **Return result** - If the transaction exceeds any applicable limit, or any DENY rule matches, Tracer returns a DENY decision (your system should then block the transaction)

> [!NOTE]
>
> Limit checks and counter increments are transactional. If Tracer denies a transaction (by limits or rules) or flags it for review, it rolls back all counter increments atomically. This prevents limit leakage from partial operations.

> [!NOTE]
>
> When Tracer skips a limit during evaluation, `limitUsageDetails[i]` includes `skipped: true` and a `skipReason` field with one of two values:
>
> * `"outside_time_window"`: current server time is outside the limit's `activeTimeStart`/`activeTimeEnd` window
> * `"outside_custom_period"`: current server time is outside the limit's `customStartDate`/`customEndDate` range
>
> Tracer reports skipped limits for transparency, but they do not participate in the DENY decision, and their counters do not increment. The window check uses server time, not the client-supplied `transactionTimestamp`, to prevent timestamp-manipulation attacks.

> [!NOTE]
>
> **Why server time instead of `transactionTimestamp`.** The client can set `transactionTimestamp` to whatever they want. That includes a value crafted to fall inside an active window when the real transaction would fall outside it. If Tracer trusted the client clock for time-window enforcement, anyone with access to the payload could bypass off-hours limits. Pinning the window check to Tracer's own clock removes that attack surface. The downside is that small clock drift between Tracer pods can cause edge-case skips around the window boundary.

### Example scenario

A corporate segment has a daily limit of R\$ 50,000 (`"50000.00"`) for CARD transactions.

If current usage is R$ 45,000 and a new transaction of R$ 8,000 arrives:

* Projected usage: R$ 45,000 + R$ 8,000 = R\$ 53,000
* Limit: R\$ 50,000
* Result: Tracer returns DENY decision (your system should block the transaction)

***

## Create a limit

***

Create limits using `POST /v1/limits`. Tracer creates limits in `DRAFT` status by default.

A limit requires:

* **name**: A descriptive name (e.g., "Daily Corporate Card Limit")
* **limitType**: DAILY, WEEKLY, MONTHLY, CUSTOM, or PER\_TRANSACTION
* **maxAmount**: Maximum amount as a decimal value (e.g., `"50000.00"`). It cannot be negative. `"0"` is accepted and denies every transaction in the limit's scope, which blocks an account without deactivating the limit
* **asset**: Asset code of 1 to 100 uppercase letters (e.g., BRL, USD)
* **scopes**: At least one scope to define which transactions it applies to

Optional fields:

* **activeTimeStart**: Start of the daily time window in `HH:MM` format (e.g., `"09:00"`)
* **activeTimeEnd**: End of the daily time window in `HH:MM` format (e.g., `"17:00"`)
* **customStartDate**: Start date for `CUSTOM` limits (ISO 8601 timestamp, required for CUSTOM)
* **customEndDate**: End date for `CUSTOM` limits (ISO 8601 timestamp, required for CUSTOM)
* **resetTime**: Start of each `DAILY`, `WEEKLY`, or `MONTHLY` period in `HH:MM` format (e.g., `"09:00"`)

> [!NOTE]
>
> Limit names must be globally unique across all non-deleted limits, unlike rule names, which are unique only within their scope context. Tracer enforces uniqueness on the name exactly as stored, after it trims leading and trailing whitespace. The comparison is case-sensitive and does not collapse whitespace inside the name, so `Daily Card Limit` and `daily card limit` are two distinct, both-acceptable limits. Deleting a limit frees its name for reuse. A collision returns `409 Conflict` with error code `0442`.

For complete payload structure and field details, see the [API reference](/en/reference/products/tracer/create-limit).

***

## List and query limits

***

Query limits for management and auditing using `GET /v1/limits`.

### Query parameters

| Parameter | Type | Description |
| - | - | - |
| `name` | string | Filter by name (case-insensitive partial match) |
| `status` | string | Filter by status (DRAFT, ACTIVE, INACTIVE) |
| `limit_type` | string | Filter by limit type (DAILY, WEEKLY, MONTHLY, CUSTOM, PER\_TRANSACTION) |
| `account_id` | string | Filter by scope: account ID |
| `segment_id` | string | Filter by scope: segment ID |
| `portfolio_id` | string | Filter by scope: portfolio ID |
| `merchant_id` | string | Filter by scope: merchant ID |
| `transaction_type` | string | Filter by scope: transaction type (CARD, WIRE, PIX, CRYPTO) |
| `sub_type` | string | Filter by scope: subtype (e.g., debit, credit) |
| `limit` | integer | Items per page (default: 10, max: 100) |
| `cursor` | string | Pagination cursor |
| `sort_by` | string | Sort field: `created_at`, `updated_at`, `name`, `max_amount` |
| `sort_order` | string | Sort direction: `ASC`, `DESC` (default: DESC) |

### Get a specific limit

Use `GET /v1/limits/{id}` to retrieve the full limit definition including scopes and current status.

***

## Read consumption

***

### From the decision

Every successful `POST /v1/validations` response, `201` or `200`, carries `limitUsageDetails`. Each entry reports:

* **limitId** and **limitAmount**: which cap Tracer checked, and its ceiling
* **currentUsage**: the projected consumption of that cap's current period and matched scope if Tracer allows this transaction
* **attemptedAmount**: the amount checked against the cap
* **exceeded**: whether the attempted amount would push this cap past its ceiling. Tracer evaluates every cap, so more than one entry can carry `exceeded: true`, and any of them produces the DENY

### From the limit

`GET /v1/limits/{id}/usage` reports a cumulative total. Its `currentUsage` adds up the usage counters recorded for the limit, across periods and scopes. Use it to review a limit's overall consumption rather than to answer how much a customer has left in the current period.

On a long-running limit, this total covers only the periods still retained, not the limit's full lifetime.

***

## Update a limit

***

Update limits using `PATCH /v1/limits/{id}`. The `limitType`, `asset`, and `resetTime` fields are immutable. You cannot change them after creation.

> [!WARNING]
>
> Changing the limit amount does not clear the current count. If you reduce a limit below what the current period already consumed, Tracer denies subsequent transactions until the next period starts.

***

## Limit lifecycle

***

Limits follow the same lifecycle as rules:

![Lifecycle of rules and limits in Tracer, showing the status transitions a definition moves through from creation to active enforcement](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/rules-limits-lifecycle-tracer.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=0e9996cc0609ad9f3b8d0ee10feb3a56)

Figure 2. Spending limits lifecycle

### States

| State | Description |
| - | - |
| `DRAFT` | Limit created but not active; can be modified freely |
| `ACTIVE` | Limit is checked during validations |
| `INACTIVE` | Limit is not checked; preserved for audit trail (A chronological, immutable record of every action and transaction in the system, essential for regulatory compliance and dispute resolution.); can be reactivated |

### Transitions

| Operation | From | To | Description |
| - | - | - | - |
| Create | - | DRAFT | Limits are created in DRAFT status by default |
| Activate | DRAFT, INACTIVE | ACTIVE | Start checking this limit |
| Deactivate | ACTIVE | INACTIVE | Stop checking this limit |
| Draft | INACTIVE | DRAFT | Return to draft for editing |

***

## Best practices

***

Recommendations for effective limit management.

### Naming

* **Be descriptive** - Include the scope and type in the name
* **Use consistent patterns** - e.g., "Daily   Limit"

| Less clear | More clear |
| - | - |
| `Limit 1` | `Daily Corporate Card Limit` |
| `VIP limit` | `Monthly VIP Pix Limit` |
| `BF promo` | `Custom Black Friday Card Limit` |

### Scope design

* **Start broad, refine as needed** - Begin with segment-level limits, add account-level for exceptions
* **Avoid overlapping scopes** - Multiple limits on the same scope can cause confusion
* **Use transaction types** - Different payment methods may need different limits

### Time window design

* **Use for regulatory compliance** - BACEN nighttime Pix limits are a common use case
* **Consider timezone impact** - Time windows use UTC. Account for your users' local timezone offset
* **Combine with custom periods** - Use time windows inside custom periods for precise campaign controls

### Monitoring

* **Review denied transactions** - High denial rates may indicate limits are too restrictive
* **Adjust seasonally** - Consider temporary limit increases during high-spending periods or use `CUSTOM` limits for specific date ranges

> [!WARNING]
>
> **Common pitfalls when working with limits:**
>
> * **"My customer is reporting overspend. They should have hit the limit."** Check whether the limit is `ACTIVE`. Tracer does not evaluate a limit in DRAFT or INACTIVE state. Also confirm the limit's scope actually matches the transaction (segment, transaction type, etc.).
> * **"My PATCH lowered the limit but transactions are still denied."** Lowering the limit does not clear the count. If the current period already consumed more than the new ceiling, Tracer denies subsequent transactions until the next period starts.
> * **"I tried to delete an ACTIVE limit and it was rejected."** The deletion comes back `422` with code `0363`. Send `POST /v1/limits/{id}/deactivate` first, then `DELETE /v1/limits/{id}`. This is intentional: it prevents accidentally removing a live enforcement.
> * **"`GET /v1/limits/{id}/usage` reports more than the customer spent this period."** That endpoint totals the usage counters recorded for the limit, across periods and scopes. For the current period, read `limitUsageDetails` on the validation response.

***

## Quick reference

***

Key endpoints and configuration options.

### Endpoints

| Operation | Method | Endpoint |
| - | - | - |
| Create limit | POST | `/v1/limits` |
| List limits | GET | `/v1/limits` |
| Get limit | GET | `/v1/limits/{id}` |
| Update limit | PATCH | `/v1/limits/{id}` |
| Activate limit | POST | `/v1/limits/{id}/activate` |
| Deactivate limit | POST | `/v1/limits/{id}/deactivate` |
| Draft limit | POST | `/v1/limits/{id}/draft` |
| Delete limit | DELETE | `/v1/limits/{id}` |
| Get usage | GET | `/v1/limits/{id}/usage` |

For limit type definitions (DAILY, WEEKLY, MONTHLY, CUSTOM, PER\_TRANSACTION), see [Limit types](#limit-types) earlier in this guide. The same guide covers the optional time-window and custom-period fields and the full scope-field list. The [API reference](/en/reference/products/tracer/create-limit) has schema-level details.


# Environment variables
Source: https://docs.lerian.studio/en/products/tracer/tracer-environment-variables

Reference for Tracer environment variables covering ports, TLS, PostgreSQL, authentication, RI permission declaration, background workers, CEL cost limits, and reservation gRPC.

This reference lists the environment variables used to configure **Tracer**, the real-time spending-control and transaction-risk service. You set these at deploy time, through Helm values, Docker Compose, or your orchestrator's environment. Variables marked as required cause the server to fail on startup if not set.

For the configuration blocks that every Lerian product shares, see the [BYOC configuration reference](/en/reference/byoc-configuration). Those blocks cover TLS posture, OpenTelemetry, Access Manager authentication, service discovery, and event streaming. This page focuses on what is distinctive to Tracer.

## Ports and health endpoints

See the [health and readiness reference](/en/reference/health-and-readiness) for the probe contract.

| Surface | Port variable | Default | Endpoints |
| - | - | - | - |
| REST + health | `SERVER_PORT` / `SERVER_ADDRESS` | `4020` | `/health`, `/readyz`, `/version`, `/metrics` |
| Reservation gRPC seam | `TRACER_GRPC_PORT` | `:4021` | gRPC reserve / confirm / release |

## Deployment and TLS

| Variable | Description | Default | Required |
| - | - | - | - |
| `DEPLOYMENT_MODE` | Deployment flavor: `local`, `byoc`, or `saas`. In `saas`, TLS on the PostgreSQL connection is validated at boot and the server refuses to start without it. In `byoc` and `local`, that boot-time check is skipped, but per-connection TLS enforcement still applies unless `ALLOW_INSECURE_TLS=true`. Also tags the `/readyz` response. | `local` | No |
| `ALLOW_INSECURE_TLS` | Bypass per-connection TLS enforcement on infrastructure DSNs. Leave unset or `false` in production. | `false` | No |

## Application

| Variable | Description | Default | Required |
| - | - | - | - |
| `LOG_LEVEL` | Log verbosity: `debug`, `info`, `warn`, or `error` | `debug` | No |
| `CEL_COST_LIMIT` | Maximum evaluation cost for a single CEL rule expression | `10000` | No |
| `OPENAPI_DOCS_ENABLED` | Serve the OpenAPI 3.1 spec and interactive Scalar docs at `/v1/openapi.{json,yaml}` and `/v1/docs` | `false` | No |

## Rule evaluation

| Variable | Description | Default | Required |
| - | - | - | - |
| `DEFAULT_DECISION_WHEN_NO_MATCH` | Decision a validation returns when no rule matches. Only `ALLOW` (fail-open) and `DENY` are accepted. Tracer deliberately rejects `REVIEW`, and any other value fails the service at boot. Leaving it unset keeps `ALLOW` and logs a startup warning. | `ALLOW` | No |
| `MAX_RULES_PER_REQUEST` | Ceiling on how many active rules are evaluated in a single validation. When more rules apply, the excess is truncated (a warning is logged) and the response reports `totalRulesLoaded` with `truncated: true`. Must be positive and at most `100000`; an invalid value fails the service at boot. | `1000` | No |

## Authentication and request handling

| Variable | Description | Default | Required |
| - | - | - | - |
| `API_KEY_ENABLED` | Enforce API-key authentication | `false` | No |
| `API_KEY` | API key for request authentication. Sensitive. Use at least 32 characters in production. | — | Yes (if `API_KEY_ENABLED=true`) |
| `API_KEY_ENABLED_ONLY_VALIDATION` | Validate-only mode: check keys without hard-enforcing them | `false` | No |
| `API_KEY_LABEL` | Audit actor identifier recorded for the API-key principal | `tracer-default` | No |
| `CORS_ALLOWED_ORIGINS` | Allowed CORS origins (CSV). When unset or empty, cross-origin requests are not allowed; set an explicit allow-list in production. The explicit value `*` is rejected at boot when `API_KEY_ENABLED=true`. | unset (no cross-origin requests allowed) | No |
| `TRUSTED_PROXY_CIDRS` | Trusted proxy CIDRs for `X-Forwarded-For` parsing. Set when running behind a load balancer. | unset (uses peer IP) | No |

## RI permission declaration

| Variable | Description | Default | Required |
| - | - | - | - |
| `IDP_DECLARATION_ENABLED` | Publish Tracer's permission declaration to the identity service at boot. This integration is optional and fail-open: a publish or configuration failure logs a warning and Tracer continues serving. | `false` | No |
| `IDP_HOST` | Absolute URL of the identity service (distinct from the Access Manager address in `PLUGIN_AUTH_ADDRESS`). When declaration is enabled in `saas`, an explicit `http://` URL makes boot fail; use `https://`. | — | No (needed to publish) |
| `IDP_M2M_CLIENT_ID` | Client ID used for the declaration's machine-to-machine token. | — | No (needed to publish) |
| `IDP_M2M_CLIENT_SECRET` | Secret used for the declaration's machine-to-machine token. Sensitive. | — | No (needed to publish) |

## Database (PostgreSQL)

Tracer stores rules and usage counters in its own `tracer` database on the shared Midaz PostgreSQL primary. A dedicated migration-runner image applies the schema migration before the application starts. The service boots against an already-migrated schema and does not run migrations in-process.

> [!WARNING]
>
> Plan a maintenance window for the upgrade to Midaz v4.2.0. Its migration `000025` widens the asset column of the validation history table. PostgreSQL rewrites that table and rebuilds its indexes under an exclusive lock, so validation reads and writes wait until it ends. The duration grows with the number of stored validations.
>
> Each migration waits at most 5 seconds for the lock and fails with SQLSTATE `55P03` when traffic holds it. Run it again in a quieter window. A second run is safe.

| Variable | Description | Default | Required |
| - | - | - | - |
| `DB_HOST` | PostgreSQL host | — | Yes |
| `DB_PORT` | PostgreSQL port | — | Yes |
| `DB_USER` | Database user | — | Yes |
| `DB_PASSWORD` | Database password. Sensitive. | — | Yes |
| `DB_NAME` | Database name | — | Yes |
| `DB_SSL_MODE` | libpq SSL mode: `disable`, `require`, `verify-ca`, or `verify-full`. Use `require` or stronger in production. | `disable` | No |

## Background workers

| Variable | Description | Default | Required |
| - | - | - | - |
| `CLEANUP_WORKER_ENABLED` | Run the expired usage-counter cleanup worker | `false` | No |
| `CLEANUP_INTERVAL_HOURS` | Cleanup interval (hours). The retention window itself is fixed at 90 days and is not configurable. | `24` | No |
| `RULE_SYNC_POLL_INTERVAL_SECONDS` | Rule-cache sync poll interval (seconds) | `10` | No |
| `RULE_SYNC_STALENESS_THRESHOLD_SECONDS` | Rule-cache staleness threshold (seconds) | `50` | No |
| `RULE_SYNC_OVERLAP_BUFFER_SECONDS` | Rule-cache sync overlap buffer (seconds) | `2` | No |

## Reservations

| Variable | Description | Default | Required |
| - | - | - | - |
| `RESERVATION_REAPER_ENABLED` | Run the worker that expires reservations past their lifetime and returns their held capacity | `true` | No |
| `RESERVATION_REAPER_INTERVAL_SECONDS` | Reservation reaper sweep interval (seconds). Must be from `1` to `3600`; an invalid value fails the service at boot. | `30` | No |
| `RESERVATION_LONG_LIVED_TTL_HOURS` | Lifetime recorded on a reservation that the ledger holds for a pending transaction (hours). Must be positive and at most `8760`; an invalid value fails the service at boot. Reservations for direct transactions carry a fixed lifetime this variable does not change. | `720` | No |

## Readiness and draining

| Variable | Description | Default | Required |
| - | - | - | - |
| `READYZ_DRAIN_GRACE_SECONDS` | Window during which `/readyz` returns 503 after SIGTERM, so Kubernetes de-registers the pod before shutdown | `12` | No |
| `READYZ_CACHE_STALENESS_THRESHOLD_SECONDS` | Rule-cache age at which `/readyz` reports `degraded` | `300` | No |

## Reservation gRPC seam

Server side of the seam the Midaz ledger calls to reserve spending limits.

Tracer always opens the reservation port, `:4021` by default. Protect it with Access Manager authentication (`PLUGIN_AUTH_ENABLED`), an API key (`API_KEY_ENABLED`), mutual TLS (`TRACER_TLS_MODE=mtls`) or your service mesh. Tracer starts without any of these, and any workload that reaches the port can reserve and release limit capacity.

| Variable | Description | Default | Required |
| - | - | - | - |
| `TRACER_GRPC_PORT` | gRPC listen address for the reservation seam | `:4021` | No |
| `TRACER_TLS_MODE` | Seam transport mode: `mtls`, `server`, `mesh`, or empty | empty | No |
| `TRACER_TLS_CERT_FILE` | Server certificate PEM path | — | Yes (if `TRACER_TLS_MODE` is `mtls` or `server`) |
| `TRACER_TLS_KEY_FILE` | Server private-key PEM path. Sensitive. | — | Yes (if `TRACER_TLS_MODE` is `mtls` or `server`) |
| `TRACER_TLS_CLIENT_CA_FILE` | Client CA certificate PEM path | — | Yes (if `TRACER_TLS_MODE=mtls`) |
| `TRACER_TLS_CLIENT_ALLOWED_NAMES` | Comma-separated client certificate names for `mtls` mode | — | No |
| `TRACER_SEAM_ALLOWED_CLIENTS` | Comma-separated Access Manager application client IDs for the seam, read when `PLUGIN_AUTH_ENABLED=true` | — | Yes (if `PLUGIN_AUTH_ENABLED=true`, outside `DEPLOYMENT_MODE=local`) |
| `AUTH_M2M_INVERSION_ENABLED` | Set it to `true` when `PLUGIN_AUTH_ENABLED=true`. Otherwise Access Manager authorizes application tokens under one shared role, and only `TRACER_SEAM_ALLOWED_CLIENTS` limits which applications can reserve. | `false` | No |
| `AUTH_CACHE_TTL` | Cache lifetime for Access Manager decisions, as a Go duration such as `60s` | unset (no cache) | Yes (if `PLUGIN_AUTH_ENABLED=true` with `DEPLOYMENT_MODE=saas`) |
| `AUTH_BREAKER_ENABLED` | Circuit breaker on Access Manager calls | unset (off) | No |
| `AUTH_JWT_VERIFY_CERT` | PEM public keys or certificates for token signatures | — | No |

## Configuration shared across products

The following blocks are identical across Lerian products. The [BYOC configuration reference](/en/reference/byoc-configuration) documents them in full. They default off.

* **Access Manager authentication**: `PLUGIN_AUTH_ENABLED`, `PLUGIN_AUTH_ADDRESS`. Enable in production. With service discovery on (see **Service discovery** below), Tracer resolves the Access Manager host through Consul. It falls back to `PLUGIN_AUTH_ADDRESS` if resolution fails.
* **Service discovery**: `SD_*` (Consul). Off by default. When `SD_ENABLED=true`, Tracer registers itself as `midaz-tracer` (advertising the HTTP port from `SERVER_ADDRESS`, default `4020`) and resolves Access Manager through Consul. If that resolution fails, it falls back to the static `PLUGIN_AUTH_ADDRESS`. Discovery requires `SD_EXTERNAL_ADDRESS` or `SD_INTERNAL_ADDRESS`. Tracer is the server on the reservation gRPC seam and does not advertise it.
* **Event streaming**: `STREAMING_*`. Off by default.
* **OpenTelemetry**: `ENABLE_TELEMETRY`, `OTEL_*`. Tracer also exposes a Prometheus `/metrics` endpoint.


# Tracer in Lerian Console
Source: https://docs.lerian.studio/en/products/tracer/using-tracer-in-lerian-console

Find how to access the Tracer module in Lerian Console to operate decision rules, spending limits, and validation history from one web interface.

Tracer is available as a product module within the [Lerian Console](/en/platform/console/about-lerian-console), the unified web interface for managing all Lerian products.

Through the Console, you can operate:

* Decision results over a period (`Dashboard`)
* Decision rules (`Rules`)
* Transaction caps (`Limits`)
* Validation history (`Validations`)

> [!WARNING]
>
> To access Tracer in the Lerian Console, you need to acquire the product. Contact your account manager for more information.

> **[Tracer module overview](/en/products/tracer/console/tracer-module)**
>
> Access the full documentation for using Tracer in the Lerian Console.

## Available actions

***

From the Lerian Console, you can:

* [Dashboard](/en/products/tracer/console/tracer-module#dashboard): See what Tracer decided over a period
* [Rules](/en/products/tracer/console/managing-rules): Create and manage transaction rules
* [Limits](/en/products/tracer/console/managing-limits): Configure and monitor spending limits
* [Validations](/en/products/tracer/console/managing-validations): Inspect validation history and details


# What is Tracer?
Source: https://docs.lerian.studio/en/products/tracer/what-is-tracer

Validate transactions in real time with Tracer: enforce spending limits, detect unauthorized activity, and decide allow/deny under 100ms.

**Tracer** is Lerian's platform for real-time transaction validation and spending controls. It helps financial institutions enforce spending policies, detect unauthorized transactions, and maintain audit-ready compliance records. Tracer does this in real time, before a transaction executes.

In Midaz v4, Tracer ships in the Midaz repository and release. It remains a separate runtime and deployment from the Ledger service. The Midaz chart installs it as an optional component: see the [Midaz chart README](https://github.com/LerianStudio/helm/tree/main/charts/midaz).

## Tracer in a complete core banking

***

Tracer is one of the pieces of a Lerian core banking, its real-time control layer. A ledger records what happened. Tracer decides what's allowed to happen first. In that flow, before your application records a transaction in Midaz, it calls Tracer to check the move against your rules and spending limits. Your application submits to the ledger only if the decision is `ALLOW`, so unauthorized or over-limit movements never reach the ledger.

Tracer stays separate from the ledger. It never initiates a call to Midaz and never reads balances. It evaluates the context it receives, records validation history, and manages reservation state. By default your application orchestrates the two, submitting to the ledger only on `ALLOW`.

Midaz can also call Tracer directly through an optional per-ledger [reservation seam](/en/products/tracer/integration-guide#midaz-ledger-reservation-seam), which is off by default. In that seam the Ledger HTTP v2 transaction path asks Tracer to evaluate your rules and hold limit capacity before it commits a transaction. Then it confirms or releases the hold. Tracer's public HTTP API remains `/v1`. The seam is not a public Tracer v2 API.

Only the Ledger HTTP v2 transaction path invokes the seam. Ledger HTTP v1 never does. In both flows, calls go toward Tracer. Tracer does not call back into Midaz.

For where this sits in the bigger picture, see [Building a complete core banking](/en/products/building-a-complete-core-banking).

## Why use Tracer?

***

Financial institutions need to control how money moves: enforcing spending caps, blocking unauthorized transactions, and producing audit trails for regulators. Doing this manually or through batch processes creates delays, errors, and compliance gaps.

Tracer solves this by evaluating every transaction in real time against your policies. It provides two capabilities:

* **Validation rules**: Business rules that evaluate transaction context and return instant decisions, without requiring code deployments. You define rules as expressions, so analysts and compliance teams can use them without writing code.
* **Dynamic spending limits**: Configurable limits per transaction, per account, per portfolio, per segment, or per merchant, with real-time usage tracking and automatic period resets.

### Solving control and compliance challenges

Tracer helps institutions evaluate spending policies, identify unauthorized transactions, and satisfy audit requirements.

## Key capabilities

***

* Real-time validation with response times under 80ms (p99)
* Expression-based rule engine using CEL (Common Expression Language) (A lightweight expression language for writing business rules, for example, 'if transaction amount > 10000 then REVIEW'. Tracer uses CEL for validation rules.) for type-safe, analyst-friendly rules
* Product-agnostic design supporting multiple transaction types:
  * Card transactions (debit, credit, prepaid)
  * Wire transfers (domestic, international, ACH)
  * Pix (instant, scheduled)
  * Cryptocurrency (bitcoin, ethereum, stablecoin)
* Dynamic spending limits:
  * Per transaction, account, portfolio, segment, or merchant
  * Daily, weekly, monthly, custom, or per-transaction periods
* Real-time limit usage tracking with automatic period resets
* Hash-chained audit trail
* Configurable no-match default (`DEFAULT_DECISION_WHEN_NO_MATCH`): when no rule matches a validation request, Tracer returns the configured default (ALLOW for fail-open, DENY for fail-closed). Infrastructure failures surface as HTTP errors. The calling system decides the fallback behavior.

## How it works

***

Tracer has four core contexts:

1. **Validation Context** - Orchestrates validation requests, coordinates rule and limit evaluation, and records the audit trail.
2. **Rules Context** - Manages rule definitions, compiles expressions, and evaluates rules against transaction context.
3. **Limits Context** - Manages spending limit configurations, tracks usage counters, and enforces thresholds.
4. **Audit Context** - Keeps the immutable event log and verifies its hash chain.

**Your system must act on the validation decision** (e.g., blocking the transaction, showing an error to the user, or queuing for review).

### Who does what

Tracer sits between several teams. Each team owns a different part of the loop:

| Actor | What they do | Touches |
| - | - | - |
| **Risk / fraud analyst** | Writes and tunes rules ("deny Pix over R\$ 50k from new accounts") | `POST /v1/rules`, `/v1/rules/{id}/activate`, audit trail review |
| **Product / risk manager** | Configures spending limits per segment, portfolio, account | `POST /v1/limits`, lifecycle endpoints, usage monitoring |
| **Integration engineer** | Builds the call from the authorization system into Tracer | `POST /v1/validations`, retry / timeout / fallback handling |
| **Authorization system** | Sends every transaction for validation, acts on ALLOW / DENY / REVIEW | Hits `POST /v1/validations` on the critical path |
| **Midaz ledger** (optional seam) | When the per-ledger reservation seam is enabled, has Tracer evaluate rules and hold limit capacity before committing, then settles the hold | The gRPC `Reserve` call, then the confirm / release transitions |
| **Tracer** | Evaluates rules and limits, records the result, returns the decision | Runs internally and never calls back |
| **Compliance / audit** | Queries the trail, verifies hash chain integrity | `GET /v1/validations`, `/v1/audit-events`, `/v1/audit-events/{id}/verify` |
| **SRE / platform** | Monitors latency, capacity, readiness | Watches `/readyz`, OTel metrics, error rates |

A typical request flows: **authorization system → Tracer (evaluate rules + check limits → decision) → audit log → response back to authorization system**. Risk and product teams set up rule and limit definitions beforehand. Compliance reads the audit log later. Tracer never reaches back into your stack. There are no webhooks or callbacks.

> [!NOTE]
>
> Monetary values (transaction `amount`, spending limit `maxAmount`, and usage counters) use decimal strings, for example `"1500.00"` or `"50000.00"`.

## When to use Tracer

***

Tracer fits into any workflow where you need to control how money moves through your institution.

* **Spending governance**: Evaluate transactions against internal or customer-level spending policies
* **Transaction validation**: Evaluate custom business rules and return decisions before transaction execution
* **Regulatory compliance**: Produce audit-ready logs and ensure traceability
* **Customer protection**: Detect overspending and return decisions that your system can act on

## Scope and design principles

***

Tracer is a transaction validation engine, and complete fraud management is outside its scope. It is a specialized component optimized for low-latency decisions (\< 100ms) that validates pre-enriched payloads against configurable rules and limits.

### What Tracer focuses on

* **Rule-based validation**: Deterministic, expression-based logic using CEL
* **Spending limits**: Real-time enforcement with automatic period reset
* **Audit trail**: Immutable records
* **Low-latency decisions**: Synchronous API responses under 80ms (p99)

### What Tracer does not include

| Capability | Reason | Alternative |
| - | - | - |
| **Machine learning scoring** | ML inference adds latency incompatible with sub-100ms target | Integrate external ML services upstream and pass scores via metadata |
| **Data enrichment** | External calls during validation break latency guarantees | Enrich payloads in your integration before calling Tracer |
| **Manual review workflows** | Case management is outside core validation scope | Build review queues in your system and use `REVIEW` decision as trigger |
| **User interface** | API-first design enables flexible integration | Build custom UIs or use third-party tools |
| **Payment execution** | Tracer returns validation decisions; it does not move funds | Execute or block payments in the upstream system based on the decision |

> [!TIP]
>
> These boundaries keep Tracer fast and predictable: it returns instant transaction decisions with audit trails.

## Integration

***

Your authorization system sends validation requests with complete transaction context, and Tracer responds with a decision, typically in under 35ms.

With this **Payload-Complete Pattern**, all the context Tracer needs arrives in a single request. There are no external calls during validation, and latency stays predictable.

> [!NOTE]
>
> On Lerian Cloud, Tracer scopes every request to your tenant from your token. See [Access Manager](/en/platform/access-manager) for the auth flow.

Like all Lerian products, Tracer ships with native [Access Manager](/en/platform/access-manager) integration. When enabled, Access Manager handles authentication and authorization for Tracer's APIs. This is an optional feature available under the **Enterprise model**.

## Next steps

***

> **[Explore the Tracer API](/en/reference/products/tracer/tracer-api-quick-start)**
>
> Browse endpoints for validation rules, spending limits, and audit trails.

> **[Getting started](/en/products/tracer/getting-started)**
>
> Set up Tracer and configure your first authorization rule.


# What is Access Manager?
Source: https://docs.lerian.studio/en/platform/access-manager

Access Manager controls human and machine access across Lerian products using Auth, Identity, and product-level authorization for fine-grained permissions.

**Access Manager** handles authentication and authorization for Lerian products. Authentication answers who makes a request. Authorization answers what they are allowed to do.

**Access Manager** is Lerian's access-control layer for our products and plugins. Instead of wiring identity and permissions into every product, you can manage them in one place: who your users are, which tokens they carry, and what those tokens can reach. When a product configures route-level enforcement and its Auth client is enabled, Auth evaluates the requested resource and action before the product handler runs. In the products that read `AUTH_REQUIRED`, set `AUTH_REQUIRED=true` when requests must be refused if the Auth client is disabled or misconfigured. [Product-level enforcement](/en/platform/access-manager/product-level-enforcement) lists these products.

Two services do the work, and protected products plug into them at the route level:

* **Auth** runs the live side of access: issuing and refreshing tokens, validating sessions, checking permissions, handling logout and user info, and running MFA challenges.
* **Identity** holds the data behind those decisions: users, groups, applications, communication providers, application-provider links, and MFA configuration.

On a protected route whose product Auth client is enabled and configured, the product sends the subject, resource, and action to Auth before business logic runs. A back-office operator in a group like `midaz-viewer-group` can read Midaz data but can't change it. A service integration receives access according to its effective M2M subject. By default, non-user tokens use `admin/<product>-editor-role`.

## Why use Access Manager?

***

Use Access Manager when you want native, fine-grained access control across Lerian products, instead of stitching something together product by product.

It lets you:

* manage human users and the product groups that define their access
* create machine-to-machine applications for service integrations
* enforce permissions down to the resource and action, like `reports:get`, `templates:post`, or `accounts:patch`
* apply one access-control model across every Lerian product you run
* keep product APIs protected behind bearer tokens and route-level checks.

How it fits your stack depends on how you deploy it:

* In **SaaS deployments**, it's the platform access layer. JWT claims carry the authenticated subject and tenant context the platform relies on.
* In **BYOC deployments**, you may already run your own identity provider. Access Manager can still add Lerian-native authorization and application credentials wherever you need that control.

> [!TIP]
>
> Access Manager is available as an optional feature under the **Enterprise model**. If you'd like to learn more or evaluate it for your use case, [get in touch with our team](https://lerian.studio/contact).

## Technical specs

***

What you get out of the box:

* REST APIs for [Auth](/en/reference/platform/access-manager/am-auth-apis) and [Identity](/en/reference/platform/access-manager/am-identity-apis) operations.
* Lerian Console settings for supported visual user and application management.
* Product-level authorization enforcement for protected HTTP APIs.
* Per-product Auth client configuration for route-level authorization enforcement.
* OAuth2/OIDC token flows for password and client credentials access.
* MFA support for user authentication flows.
* Valkey-backed caching for token, permission, and MFA-related operations.
* RBAC aligned with product resources, actions, groups, and machine-to-machine applications.

## Bootstrap and operation

***

Access Manager has two distinct lifecycle layers:

| Layer | What it is used for |
| - | - |
| Bootstrap | Initial environment setup, including base organizations, built-in roles, groups, applications, and permission sets. |
| Operation | Day-to-day management of users, group assignments, applications, providers, MFA, and access reviews. |

Bootstrap is what seeds a brand-new environment. Once that environment starts, it's no longer where you make changes. For the operator-level walkthrough of getting Auth and Identity up and ready before any product enforces access, see [Installing Access Manager](/en/platform/access-manager/installing-access-manager).

From there on, manage access through the Identity APIs or Lerian Console. Console covers the everyday user and application work: creating users, assigning groups, updating passwords, and creating machine-to-machine applications. The Identity APIs give you the full operational surface, including providers, application-provider links, and MFA.

Ship changes to built-in resources, actions, roles, and permission sets through controlled platform updates, like migrations or an idempotent reconciler. Don't edit bootstrap seed data to change access in a running environment.

## Tenant behavior on Lerian Cloud

***

On Lerian Cloud, the tenant is part of the caller's identity. Clients never send tenant ownership in payloads, query parameters, or headers.

That shapes behavior in three places:

* **Identity management**: user, group, and application APIs return only records in the caller's tenant organization.
* **Authentication**: password and refresh-token flows keep token handling scoped to the tenant carried by the user context.
* **Authorization**: permission checks evaluate only the groups, roles, and application permissions that belong to the resolved tenant.

Single-tenant deployments skip all of this and fall back to the configured default organization.

> [!WARNING]
>
> Don't reuse a token from one tenant to manage users, applications, or permissions in another. Access Manager scopes those operations to the authenticated context.

## Use cases

***

Access Manager fits scenarios such as:

* Teams that want built-in authentication and authorization across Lerian products.
* Organizations without an existing IAM solution.
* Teams that already run an identity provider but still need product-level authorization.
* Integrations that depend on secure machine-to-machine access.
* Multi-product deployments that need one consistent access model for users, services, and tenants.

> [!TIP]
>
> [Explore the Access Manager API](/en/reference/platform/access-manager/am-api-introduction). Browse endpoints for users, groups, applications, and permissions.


# Enabling Access Manager
Source: https://docs.lerian.studio/en/platform/access-manager/enabling-access-manager

Activate Access Manager across Lerian products by setting the Auth environment variables in each `.env` so your services start enforcing access.

[Installing Access Manager](/en/platform/access-manager/installing-access-manager) isn't enough on its own. To start enforcing access, turn it on in each product. Set the Auth variables in the `.env` file of any Lerian product or plugin where you want it active.

> [!NOTE]
>
> Enabling Access Manager only turns on authorization enforcement in a product or plugin. You manage access data separately through Access Manager. This includes users, groups, applications, providers, roles, and permissions.

Every protected product must enable enforcement and point to Auth. The address variable is not the same in every repository, so use the variable expected by the product you configure:

```text Text theme={null}
# Most products and plugins
PLUGIN_AUTH_ENABLED=true
PLUGIN_AUTH_ADDRESS=http://plugin-auth:4000
```

```text Text theme={null}
# Midaz Ledger and Pix via JD
PLUGIN_AUTH_ENABLED=true
PLUGIN_AUTH_HOST=http://plugin-auth:4000
```

> [!CAUTION]
>
> After you enable Access Manager, protected API requests must include an `Authorization` header with a valid Bearer access token.
>
> Without this header, protected requests will be rejected, even for endpoints that were previously accessible without authentication.
>
> [**Learn how to generate and use access tokens.**](/en/platform/access-manager/using-access-manager)

## Where to update

***

You'll find the relevant `.env` files in these locations:

* **Midaz**
  * `/midaz/components/ledger` uses `PLUGIN_AUTH_HOST`.
  * `/midaz/components/tracer` uses `PLUGIN_AUTH_ADDRESS`
* **Other products and plugins**
  * Use the `.env` file in the product or plugin root, or in the component directory when the repository is split into components.
  * Reporter and Bank Transfer use `PLUGIN_AUTH_ADDRESS`.
  * Pix Indirect BTG uses `PLUGIN_AUTH_ADDRESS`.
  * Pix via JD uses `PLUGIN_AUTH_HOST`.

> [!TIP]
>
> If you can't see the files, adjust your system settings to show hidden files. `.env` files are often hidden by default.

## Rebuild after changes

***

After updating a `.env` file, rebuild and restart from the root of the repository that owns that file. Lifecycle commands differ by repository: in the Midaz repository root, run `make rebuild-up`, because its `make up` target starts services without rebuilding them. For other products and plugins, use the lifecycle command documented for that product.

## Deployment lifecycle

***

Access Manager setup has two phases:

* **Bootstrap** seeds a new environment with the base organization, roles, groups, applications, and permission sets required by the platform.
* **Operation** starts after the environment is up. From that point on, manage access through the Identity APIs or Lerian Console.

Use the operational APIs for user access, group assignment, application credentials, providers, and MFA. Don't change a running environment by editing bootstrap seed files.

> [!WARNING]
>
> Bootstrap applies its seed data only during initial environment setup. Changes to built-in resources, actions, roles, groups, applications, or permission sets in an existing environment must be delivered through controlled platform updates. Examples include migrations and an idempotent reconciler.


# Manage the IP allowlist via API
Source: https://docs.lerian.studio/en/platform/access-manager/features/ip-allowlist/api

Read and replace your workspace's IP allowlist with two Identity API operations, and handle the errors the operations can return.

Two operations on the Identity API manage the [IP allowlist](/en/platform/access-manager/features/ip-allowlist/overview): one reads it, one replaces it. Use them when you manage security settings from your own tooling instead of the Console.

The API reference documents both operations: [Get Organization IP Allowlist](/en/reference/platform/access-manager/get-organization-ip-allowlist) and [Set Organization IP Allowlist](/en/reference/platform/access-manager/set-organization-ip-allowlist).

## The two operations

***

| Operation | What it does | Permission |
| - | - | - |
| `GET /v1/security/ip-allowlist` | Returns the stored entries and the surfaces where the list applies. | `security` / `get` |
| `PUT /v1/security/ip-allowlist` | Replaces the whole list and, optionally, the surfaces. | `security` / `put` |

Both operations live on the Identity API base URL and need a bearer token. The platform resolves your workspace from the token. There is no organization identifier in the path or in the body.

## The body

***

The request body of `PUT` and the response body of both operations have these fields:

```json JSON theme={null}
{
  "entries": ["203.0.113.0/24", "198.51.100.7"],
  "scopes": ["console", "api"]
}
```

| Field | Required | Meaning |
| - | - | - |
| `entries` | Yes | The full list of addresses and CIDR ranges. What you send replaces what is stored. |
| `scopes` | No | Where the list applies: `console`, `api`, or both. |
| `labeledEntries` | Response only | The stored entries in the same order, each with its `description`. |

Rules that apply to the fields:

* `entries` is a full replacement. To add one address, send the current list plus the new address.
* In a request, you can send an entry as an address string or as an object with `cidr` and `description`. You can mix the two forms.
* The platform stores a string entry with an empty description. To keep a description, send that entry as an object again.
* An entry broader than `/24` for IPv4 or `/48` for IPv6 is rejected with `400`, and nothing changes.
* The response echoes the entries as the platform stored them. A single address comes back with its prefix: `198.51.100.7` becomes `198.51.100.7/32`.
* `entries: []` deactivates the list. The operation returns `200`.
* An empty stored list serializes as `[]`, never as `null`.
* When you omit `scopes`, the stored scopes stay as they are.
* `scopes: []` keeps the entries but stops enforcement everywhere.
* When you omit `entries`, the operation returns `400` with code `IDE-0001` and nothing changes.

## Examples

***

Replace the placeholders with your Identity API base URL and a bearer token that holds the `security` permission.

```bash Read the list theme={null}
IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
IDENTITY_BEARER_TOKEN="paste-your-access-token-here"

curl -sS "${IDENTITY_BASE_URL}/v1/security/ip-allowlist" \
  -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}"
```

```bash Activate for Console access theme={null}
IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
IDENTITY_BEARER_TOKEN="paste-your-access-token-here"

curl -sS -X PUT "${IDENTITY_BASE_URL}/v1/security/ip-allowlist" \
  -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": ["203.0.113.0/24", "198.51.100.7"],
    "scopes": ["console"]
  }'
```

```bash Add API access theme={null}
IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
IDENTITY_BEARER_TOKEN="paste-your-access-token-here"

curl -sS -X PUT "${IDENTITY_BASE_URL}/v1/security/ip-allowlist" \
  -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": ["203.0.113.0/24", "198.51.100.7", "192.0.2.10"],
    "scopes": ["console", "api"]
  }'
```

```bash Deactivate theme={null}
IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
IDENTITY_BEARER_TOKEN="paste-your-access-token-here"

curl -sS -X PUT "${IDENTITY_BASE_URL}/v1/security/ip-allowlist" \
  -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "entries": [] }'
```

A successful `PUT` returns `200` with the stored list:

```json Response theme={null}
{
  "entries": ["203.0.113.0/24", "198.51.100.7/32"],
  "scopes": ["console"],
  "labeledEntries": [
    { "cidr": "203.0.113.0/24", "description": "" },
    { "cidr": "198.51.100.7/32", "description": "" }
  ]
}
```

## Recommended order

***

**1. Register the addresses with only the console scope**

Send the full list with `"scopes": ["console"]`. Include the address you call from.

**2. Make sure you can still sign in**

Sign in to the Console from a listed address. Then try from an unlisted address and expect a refusal.

**3. List every integration's outgoing address**

Collect the address each ERP, webhook sender, scheduled job, and application calls from. Add each one to `entries`.

**4. Add the api scope**

Send the full list again with `"scopes": ["console", "api"]`. Watch your integrations for `403` responses.

## Errors

***

Every error uses the Access Manager envelope with the fields `code`, `title`, and `message`.

| Status | `code` | `title` | `message` |
| - | - | - | - |
| 400 | `IDE-0001` | Missing Fields in Request | Your request is missing one or more required fields. |
| 400 | `IDE-0035` | IP Allowlist Too Large | The IP allowlist is too large: the combined, comma-separated entries must not exceed `{value}` characters. Please remove some entries and try again. |
| 400 | `IDE-0036` | Invalid IP Allowlist Entry | The IP allowlist entry `{value}` is not a valid IP address or CIDR block. Please correct it and try again. |
| 400 | `IDE-0037` | Invalid IP Allowlist Scope | The IP allowlist enforcement scope `{value}` is not supported. Please use console, api, or both, and try again. |
| 401 | `IDE-0008` | Token Missing | A valid token must be provided in the request header. Please include a token and try again. |
| 401 | `IDE-0009` | Invalid Token | The provided token is expired, invalid or malformed. Please provide a valid token and try again. |
| 403 | `AUT-0021` | IP Not Allowed | Access from your network is not allowed for this workspace. Contact your administrator. |

The stored entries, separated by commas, must fit in 200 characters. Descriptions do not count.

> [!WARNING]
>
> Inspect the `code` field, not only the status. A `403` with code `AUT-0021` can come back from any protected endpoint, including these two, when your own address is outside an active list. In that case the list did not change and you must call from a listed address.

## Related pages

***

> **[IP allowlist](/en/platform/access-manager/features/ip-allowlist/overview)**
>
> What the feature protects, how it decides, and what it does not cover.

> **[Access Manager error list](/en/reference/platform/access-manager/access-manager-error-list)**
>
> Every Auth and Identity error code, with title and message.


# Manage the IP allowlist in the Console
Source: https://docs.lerian.studio/en/platform/access-manager/features/ip-allowlist/console

Add trusted addresses, choose whether the list applies to Console access, API access, or both, and deactivate it from the Security page of Lerian Console.

This guide shows how to manage the [IP allowlist](/en/platform/access-manager/features/ip-allowlist/overview) from the Console. You add addresses, choose where the list applies, and deactivate it when you no longer need it.

## Before you start

***

You need the `security` permission with the `get` action to open the page and the `put` action to change the list. Lerian's default administrator role has both. Without `get`, the page shows "You are not authorized to access this page."

Know the address you connect from. The Console shows it to you in several dialogs and in the **Add my IP** button. If you connect through a VPN or a corporate proxy, the address you see is the address of that VPN or proxy.

## Open the IP allowlist tab

***

**1. Open Settings**

Click the gear icon () in the top navigation bar.

**2. Select Security**

Select **Security** in the Settings sidebar. The page title is "Security".

**3. Select the IP allowlist tab**

The page opens on the **Single Sign-On** tab. Select the **IP allowlist** tab. You can also open the path `/settings/security?tab=ip-allowlist` directly.

![The Security page in the Console, open on the IP allowlist tab. The amber banner reads "IP allowlist inactive" and the empty-state box reads "No IP addresses registered. While the list is empty, access is not restricted." The "Add my IP" and "Add IP" buttons sit above the box.](https://mintcdn.com/lerian-49cb71fc/kktgwl8ajkkMHFzZ/images/en/console/security-ip-allowlist-empty.png?fit=max\&auto=format\&n=kktgwl8ajkkMHFzZ\&q=85\&s=bc6b84025d249245cd3429fb75bf570a)

Figure 1. The IP allowlist tab with an empty list

## Read the page

***

The tab subtitle reads "Restrict platform access to a list of trusted IP addresses."

A status banner tells you whether the platform enforces the list now:

| Banner | Color | Description shown |
| - | - | - |
| IP allowlist inactive | Amber | "Access is not restricted. Add an IP address to activate the allowlist." |
| IP allowlist inactive | Amber | "The list is saved but enforced nowhere — access is not restricted. Choose where it applies below." |
| IP allowlist active | Green | "Only the IP addresses below can sign in and use the console. API access is not restricted." |
| IP allowlist active | Green | "Only the IP addresses below can reach the API with your credentials. Console access is not restricted." |
| IP allowlist active | Green | "Only the IP addresses below can sign in to the console or reach the API with your credentials." |

Three buttons sit above the list:

* **Add my IP** adds the address you connect from. When the Console cannot determine it, it disables the button and shows the tooltip "Your IP address could not be determined."
* **Add IP** opens a side sheet where you type an address or a range.
* **Deactivate** appears only when the list has at least one entry.

## Add an address

***

**1. Open the side sheet**

Click **Add IP**. The side sheet "Add IP address" opens with the description "Add an IP address or CIDR range to the allowlist."

**2. Type the address or range**

Fill in **IP address or CIDR range**. The placeholder shows the accepted forms, such as `203.0.113.5` or `203.0.113.0/24`.

Optionally, fill in **Description** with a label of up to 255 characters, for example "São Paulo office". The description is only a label and does not change access.

To add your own address instead, click **Add my IP** inside the sheet. When the Console knows your address, the button shows it in parentheses. The entry keeps the description you typed.

**3. Save**

Click **Save**. The Console validates the entry before it saves it.

The Console rejects two kinds of input:

* A value that is not an address or a CIDR range shows "Enter a valid IP address or CIDR range".
* A value already on the list shows "This entry is already in the list." `203.0.113.5` and `203.0.113.5/32` count as the same entry.

### When you add the first entry

When you add the first entry, the Console asks you to confirm with the dialog "Activate the IP allowlist?". The text reads:

> Once activated, only requests from your listed IP addresses are accepted on the surfaces ticked under "Where this list is applied". Your current IP is `{ip}`.

Click **Activate** to continue or **I changed my mind** to go back.

### When your own address is not on the list

The list can apply to **Console access** and not cover the address you connect from. If your address is not a private network address, the Console adds it to the list before it saves. It then shows the notice "We also added your current IP (`{entry}`)". The notice explains why and how to delete the entry later.

If the list has no room for your address, the Console opens the dialog "We could not add your current IP to this list" instead.

### When your address is a private network address

You can connect from a private network address that a list for **Console access** does not cover. In that case, the Console asks you first. The dialog "We see your access coming from `{ip}`, a private network address" explains that the address may belong to your VPN or a proxy.

Click **Include it anyway** to add it, or **Continue without including it** to leave it out.

## Choose where the list applies

***

The section "Where this list is applied:" appears below the table once the list has at least one entry. It holds two checkboxes:

* **Console access**: "only the addresses above can sign in and use the console".
* **API access**: "only the addresses above can use the API with your credentials".

The Console saves each change as soon as you tick or untick a checkbox.

### Apply the list to API access

When you tick **API access**, the Console asks you to confirm. The dialog "Your integrations have to be on the list above" opens. It names the systems that call the API with your credentials: webhooks, ERPs, scheduled jobs, application tokens. It asks you to review the list before you confirm.

Click **Apply to API access** to confirm.

> [!WARNING]
>
> Do not tick **API access** until every integration's outgoing address is on the list.

### Untick both checkboxes

If you untick both checkboxes, the list stays saved but does nothing. The banner turns amber. The note below the checkboxes reads "The list is saved but enforced nowhere — access is not restricted."

## Delete an entry

***

**1. Find the entry**

Find the row in the table. The "IP address / CIDR" column shows the entry, and the "Description" column shows its label. The footer reads "Showing N IP entries."

**2. Click the trash icon**

Click the trash icon ("Delete") on the row. The dialog "Remove this entry?" opens.

**3. Confirm**

Read the text "Once removed, requests from this IP range will no longer be allowed." Click **Yes, remove it**.

The deletion can leave your own address outside a list for **Console access**. In that case, the Console then opens the dialog "Your IP is not in this list". It warns that you may lose access to this workspace if you save.

Click **Save anyway** only if you control another address on the list.

Deleting the last entry deactivates the list, so the Console shows the deactivation dialog instead.

## Deactivate the list

***

Deactivation clears every entry and allows access from any address again.

**1. Click Deactivate**

Click **Deactivate** above the table.

**2. Confirm**

The dialog "Deactivate the IP allowlist?" reads "This clears every entry and allows access from any IP address again." Click **Yes, deactivate**.

![The dialog "Deactivate the IP allowlist?" over the Security page. The body reads "This clears every entry and allows access from any IP address again." The buttons read "I changed my mind" and "Yes, deactivate".](https://mintcdn.com/lerian-49cb71fc/kktgwl8ajkkMHFzZ/images/en/console/security-ip-allowlist-deactivate-dialog.png?fit=max\&auto=format\&n=kktgwl8ajkkMHFzZ\&q=85\&s=fa5b71ef7f692b72f8488e7c23e6111b)

Figure 2. The deactivation dialog

> [!TIP]
>
> To pause the list without losing the entries, untick both checkboxes instead. The entries stay saved and you can apply them again later.

## Messages the Console shows

***

After a successful change, the Console shows "IP allowlist updated". When the platform refuses a change, the Console shows the refusal in a notification. The [API errors](/en/platform/access-manager/features/ip-allowlist/api#errors) list the causes.

## Related pages

***

> **[IP allowlist](/en/platform/access-manager/features/ip-allowlist/overview)**
>
> What the feature protects, how it decides, and what it does not cover.

> **[Manage the list via API](/en/platform/access-manager/features/ip-allowlist/api)**
>
> Read and replace the list with two Identity API operations.


# Deployment requirements (BYOC)
Source: https://docs.lerian.studio/en/platform/access-manager/features/ip-allowlist/deployment

Configure the trusted proxies so the IP allowlist enforces in your own BYOC deployment.

The [IP allowlist](/en/platform/access-manager/features/ip-allowlist/overview) compares the caller's network address with the list. Behind a load balancer or an ingress, the address the service sees is the proxy's, not the caller's. This page tells a BYOC operator what to configure so the platform learns the real address.

> [!NOTE]
>
> This page applies to BYOC deployments only. On Lerian Cloud, Lerian operates this configuration for you. You only manage the list itself.

For the architecture view, read [Tenant IP allowlist](/en/platform/access-manager/product-level-enforcement#tenant-ip-allowlist).

## Trusted proxies

***

Set `TRUSTED_PROXIES` on these Lerian services, not only on the Access Manager:

* The Access Manager **Auth** and **Identity** services.
* The products Midaz, Reporter, Lender, and Streaming Hub.
* The rails Pix via JD, Pix Lerian, and Bank Transfer.

Each of these services resolves the caller's address on its own and forwards it to the Access Manager Auth service. A service without the variable forwards no address. If the service calls Auth from a network in `PLATFORM_INTERNAL_CIDRS`, Auth allows the request without checking the address. When `PLATFORM_INTERNAL_CIDRS` is set and the service calls Auth from outside it, Auth checks the service's own address against the list. On the Access Manager itself, the variable decides whether the allowlist enforces at all, as the table below shows.

The value is a comma-separated list of CIDR ranges. List only the proxies that connect directly to that service.

```text Example theme={null}
TRUSTED_PROXIES=10.0.0.0/16,10.1.0.0/16
```

Rules the platform applies to the value:

* CIDR ranges only. A bare address without a prefix is rejected.
* Very broad ranges are rejected: broader than `/8` for IPv4 or `/48` for IPv6. `0.0.0.0/0` never works.
* On the Access Manager, a malformed value stops the service at startup.

What happens when the value is absent:

| Where it is unset | Effect |
| - | - |
| Access Manager Auth | The allowlist does not enforce. A metric and a log line signal the untrusted-proxy condition. |
| A listed product or rail, such as Midaz | The service forwards no caller address. If the service calls Auth from a network in `PLATFORM_INTERNAL_CIDRS`, Auth allows the request without checking the address. When `PLATFORM_INTERNAL_CIDRS` is set and the service calls Auth from outside it, Auth checks the service's own address against the list. |

When Auth has `TRUSTED_PROXIES` set and `PLATFORM_INTERNAL_CIDRS` unset, it trusts no forwarded address. It then refuses product requests that an active list applies to.

## Validate the deployment

***

Run this check once after you set the variables, from a workspace whose list you control.

**1. Activate a list with your own address**

Send the list through the [Identity API](/en/platform/access-manager/features/ip-allowlist/api) with `"scopes": ["console", "api"]`. Include the address you connect from and the address your test client calls from.

**2. Sign in from a listed address**

Sign in from that address. The sign-in must succeed.

**3. Sign in from an unlisted address**

Sign in from another network, such as a mobile connection. Expect a refusal.

**4. Call a Midaz endpoint from both addresses**

Call any protected Midaz endpoint from the listed address, then from the unlisted one. Expect `200` and then `403` with code `AUT-0021`.

If the platform accepts a request from the unlisted address, it does not learn the real address. Check `TRUSTED_PROXIES` on the service that answered and `PLATFORM_INTERNAL_CIDRS` on Auth and Identity.

## Related pages

***

> **[Tenant IP allowlist architecture](/en/platform/access-manager/product-level-enforcement#tenant-ip-allowlist)**
>
> How Auth, Identity, and each product share the check.

> **[Manage the list in the Console](/en/platform/access-manager/features/ip-allowlist/console)**
>
> The administrator's guide to the Security page.


# IP allowlist
Source: https://docs.lerian.studio/en/platform/access-manager/features/ip-allowlist/overview

Restrict access to your Lerian workspace to a list of trusted network addresses, for people who sign in and for systems that call the API.

The IP allowlist is a list of network addresses that your workspace trusts.

The list belongs to the whole workspace, not to one person or one application.

## What the allowlist protects

***

The allowlist has two switches. You can turn on one, the other, or both.

| Switch | What it restricts | Who it affects |
| - | - | - |
| **Console access** | People who sign in to the Console with a user account. | Your team: administrators, analysts, operators. |
| **API access** | Systems that call the Lerian APIs with your workspace's credentials. | Your integrations: ERPs, webhooks, scheduled jobs, application tokens. |

> [!WARNING]
>
> Do not turn on **API access** before you list every address your integrations call from. Those addresses are usually not the same ones your team uses to reach the Console.

## How the platform decides

***

A request to a protected route goes through this check, in this order:

1. A request arrives at the platform with your workspace's credentials.
2. The platform works out the network address the request came from. Behind your load balancer, it reads the address your proxy forwards. On BYOC, see [Deployment requirements](/en/platform/access-manager/features/ip-allowlist/deployment). On Lerian Cloud, Lerian handles this for you.
3. The platform checks whether the list is active for that kind of access, Console or API, and whether the address is on the list.

## What a refused person or system sees

***

See the [Access Manager error list](/en/reference/platform/access-manager/access-manager-error-list).

## What you can register

***

An entry is a single address or a range of addresses, in IPv4 or IPv6.

| You type | The platform stores | Why |
| - | - | - |
| `203.0.113.5` | `203.0.113.5/32` | A single IPv4 address is a range of one. |
| `2001:db8::7` | `2001:db8::7/128` | A single IPv6 address is a range of one. |
| `203.0.113.0/24` | `203.0.113.0/24` | A CIDR range stays as you typed it. |
| `203.0.113.77/24` | `203.0.113.0/24` | The platform normalizes the range to its network address. |

Rules that apply to the list:

* Use CIDR notation for ranges. The platform does not accept "from-to" ranges such as `203.0.113.1-203.0.113.50`.
* The platform merges duplicates. `203.0.113.5` and `203.0.113.5/32` are the same entry.
* The platform rejects a range broader than `/24` for IPv4 or `/48` for IPv6.
* The stored entries, separated by commas, must fit in 200 characters. Prefer ranges over long lists of single addresses.
* An entry can have a description, such as the name of the office. The description is text for your administrators. It does not change the access decision.

## The three states of the list

***

| State | What it means | Does the platform check addresses? |
| - | - | - |
| **Empty** | No entries. | No. |
| **Saved, not applied** | Entries exist, but no switch is on. | No. The list is stored and does nothing. |

The Console shows the current state in a banner at the top of the IP allowlist tab.

## Safety behaviors in the Console

***

The Console helps you avoid locking yourself out.

* Before the first entry activates the list, the Console asks you to confirm.
* If the list applies to Console access and does not cover your own address, the Console adds your address or asks you before it saves.
* An **Add my IP** button adds the address you connect from.
* The Console asks for a separate confirmation before it applies the list to API access.

Read the step-by-step guide in [Manage the IP allowlist in the Console](/en/platform/access-manager/features/ip-allowlist/console).

## What the allowlist does not cover

***

* **Lerian's own platform services keep working.** Requests that carry a platform-internal token bypass the list, so your workspace does not stop by accident.
* **There is no administrator exemption.** Keep at least one address you control on the list.
* **Break-glass.** If every administrator is locked out, contact Lerian support to restore access.

## Next steps

***

> **[Manage the list in the Console](/en/platform/access-manager/features/ip-allowlist/console)**
>
> Add addresses, choose where the list applies, and deactivate it.

> **[Manage the list via API](/en/platform/access-manager/features/ip-allowlist/api)**
>
> Read and replace the list with two Identity API operations, with examples.

> **[Deployment requirements](/en/platform/access-manager/features/ip-allowlist/deployment)**
>
> What a BYOC operator configures so the platform learns the caller's real address.

> **[Error list](/en/reference/platform/access-manager/access-manager-error-list)**
>
> Every code the allowlist can return, with title and message.


# Manage MFA via API
Source: https://docs.lerian.studio/en/platform/access-manager/features/mfa/api

Enroll and manage MFA methods with Identity, then complete MFA challenges with Auth.

MFA uses two Access Manager APIs:

* Identity enrolls methods and manages the user's MFA settings.
* Auth completes the second verification step during sign-in.

Read [Multi-factor authentication](/en/platform/access-manager/features/mfa/overview) before you integrate these operations.

## Account enrollment operations

***

The Identity API exposes these self-service operations:

| Operation | Purpose |
| - | - |
| `POST /v1/users/{id}/mfa/setup` | Start setup for `app` or `email`. |
| `POST /v1/users/{id}/mfa/verify` | Verify the setup passcode. |
| `POST /v1/users/{id}/mfa/enable` | Enable the verified method. |
| `GET /v1/users/{id}/mfa` | Read the current MFA status and enabled methods. |
| `PATCH /v1/users/{id}/mfa/preferred` | Select the preferred enabled method. |
| `DELETE /v1/users/{id}/mfa` | Disable all methods. |
| `DELETE /v1/users/{id}/mfa/{mfaType}` | Disable one method. |
| `POST /v1/users/{id}/mfa/recovery-codes` | Generate a new set of recovery codes. The previous set stops working. |

The standard operations are self-service. The bearer-token subject must match `{id}`.

### Start setup

Send the method in the request body:

```json Request theme={null}
{
  "mfaType": "app"
}
```

This feature supports `app` and `email`.

Authenticator-app setup returns a secret, a QR-code URL, and recovery codes. Email setup returns recovery codes and sends a passcode to the user's saved email address.

### Verify setup

Submit the 6–8-character setup passcode and the method. Authenticator-app verification also needs the secret returned by setup.

```json Request theme={null}
{
  "mfaType": "app",
  "passcode": "123456",
  "secret": "setup-secret"
}
```

### Enable the method

After verification, enable the method with one recovery code from the setup response. Authenticator-app enablement also needs the setup secret.

```json Request theme={null}
{
  "mfaType": "app",
  "secret": "setup-secret",
  "recoveryCode": "recovery-code"
}
```

> [!WARNING]
>
> Treat setup secrets and recovery codes as credentials. Do not log them or store them in source control.

### Turn off MFA or remove a method

To turn off MFA, send the code that the [Disable MFA](/en/reference/platform/access-manager/disable-mfa) reference describes. To remove the authenticator app or the email method, send a code from that method.

To get the code by email, call `POST /v1/users/{id}/mfa/disable/challenge`. Only the user can request it, and only when the email method is on. The code is valid for 10 minutes and allows 5 wrong attempts. A user can request 3 codes in 15 minutes.

### Administrator operations

An administrator manages the methods of another user with two more operations. `{id}` is the target user. The bearer token needs the `mfa-admin` permission with the `post` action to enable a method and the `delete` action to remove one.

| Operation | Purpose |
| - | - |
| [`POST /v1/users/{id}/mfa/admin/enable`](/en/reference/platform/access-manager/admin-enable-mfa) | Enable `email` for the target user without setup or verification. The response contains the recovery codes of the target user. |
| [`DELETE /v1/users/{id}/mfa/admin/{mfaType}`](/en/reference/platform/access-manager/admin-disable-mfa) | Remove one method (`app`, `email`, or a legacy `sms` enrollment) from the target user. The operation takes no code. |

## Login operations

***

The first factor uses [Request Access Token](/en/reference/platform/access-manager/request-access-token). When MFA is required, the operation returns an MFA challenge response instead of access tokens.

The response includes:

* `mfaRequired: true`.
* a short-lived `mfaToken`.
* the enabled methods.
* the preferred method.

### Request email delivery

Use [Initiate MFA Challenge](/en/reference/platform/access-manager/initiate-mfa-challenge) for email.

```json Request theme={null}
{
  "mfaToken": "short-lived-mfa-token",
  "mfaType": "email"
}
```

Do not request delivery for `app`. The authenticator app generates the passcode locally.

### Verify the second factor

Use [Verify MFA Login](/en/reference/platform/access-manager/verify-mfa-login). Send either `passcode` or `recoveryCode`, not both.

```json Passcode theme={null}
{
  "mfaToken": "short-lived-mfa-token",
  "mfaType": "app",
  "passcode": "123456"
}
```

```json Recovery code theme={null}
{
  "mfaToken": "short-lived-mfa-token",
  "mfaType": "app",
  "recoveryCode": "unused-recovery-code"
}
```

A successful verification returns the standard access-token response. A recovery code is consumed after one successful use.

## Error handling

***

Important login errors include:

| Code | Meaning |
| - | - |
| `AUT-0016` | The passcode is invalid. |
| `AUT-0017` | The MFA session expired. Restart sign-in. |
| `AUT-0018` | The verification limit was exceeded. |
| `AUT-0020` | The MFA token is invalid. |

Identity can also reject an unsupported method, missing setup secret, missing email destination, or unverified setup.

See the [Access Manager error list](/en/reference/platform/access-manager/access-manager-error-list) for the full error envelope and current codes.

## Related pages

***

> **[Complete MFA in the Console](/en/platform/access-manager/features/mfa/console)**
>
> The user workflow for verification during sign-in.

> **[Identity APIs](/en/reference/platform/access-manager/am-identity-apis)**
>
> The generated reference for account-management operations.


# Complete MFA and remove a method in the Console
Source: https://docs.lerian.studio/en/platform/access-manager/features/mfa/console

Complete MFA at Console sign-in with a passcode or a recovery code, and remove an enrolled method.

Lerian Console completes the second verification step for users who already have [multi-factor authentication](/en/platform/access-manager/features/mfa/overview) enabled.

Account enrollment and method management are available under Settings › Security and through the [Identity API](/en/platform/access-manager/features/mfa/api).

## Before you start

***

You need:

* an active user account with authenticator-app or email MFA enabled.
* access to the selected method or an unused recovery code.

## Complete the second verification step

***

After the password or SSO step succeeds, the Console opens the MFA verification page.

**1. Select a method**

Use the preferred method or select another enabled method.

**2. Get the passcode**

For an authenticator app, open the app and read the current code.
At sign-in, the Console sends the email code automatically.

**3. Enter the passcode**

Enter the six-digit passcode and continue.

## Use a recovery code

***

Select the recovery-code option when an enrolled method is unavailable. Enter one unused recovery code.

> [!WARNING]
>
> A recovery code works once. Store the remaining codes securely after sign-in.

## Recover from a failed verification

***

| Situation | Action |
| - | - |
| The passcode is invalid | Get the current passcode and try again before the submission limit is reached. The verification limit applies per user, not per sign-in session. |
| The email does not arrive | Wait for the resend cooldown, then request one new code. |
| The MFA session expires | Restart the complete sign-in flow, including the first factor. |
| No enrolled method is available | Use an unused recovery code. If none is available, contact an administrator and follow your organization's account-recovery procedure. |

## Remove a method

***

In **Settings** › **Security**, open the **MFA** tab and select **Remove** next to the method.

To remove the authenticator app, enter its current code. To remove the email method, enter the code that the Console sends by email when the dialog opens.

## Related pages

***

> **[Multi-factor authentication](/en/platform/access-manager/features/mfa/overview)**
>
> How MFA enrollment, verification, and recovery work.

> **[Manage MFA via API](/en/platform/access-manager/features/mfa/api)**
>
> Enroll methods, select a preference, and manage recovery codes.

> **[MFA deployment requirements](/en/platform/access-manager/features/mfa/deployment)**
>
> Configure Auth for MFA sign-in.


# MFA deployment requirements (BYOC)
Source: https://docs.lerian.studio/en/platform/access-manager/features/mfa/deployment

Configure MFA session protection, challenge limits, and email delivery in a BYOC deployment.

This page tells a BYOC operator what to configure before users enable [multi-factor authentication](/en/platform/access-manager/features/mfa/overview).

> [!NOTE]
>
> This page applies to BYOC deployments only. On Lerian Cloud, Lerian operates this configuration for you.

## Protect MFA sessions

***

Set `MFA_SECRET` in the Auth process environment.

Auth uses this secret to sign short-lived MFA-session tokens. These tokens connect the verified first sign-in factor to the MFA challenge.

Set `MFA_ENABLED=true` in the Auth process environment to make Auth check `MFA_SECRET` at startup. If the secret is empty, Auth starts and logs an error. The MFA routes then return `503` with code `AUT-0028` until you set the secret and restart Auth. This startup check does not enable or disable MFA for individual users. `MFA_ENABLED=false` does not bypass their MFA requirement.

> [!WARNING]
>
> Configure `MFA_SECRET` before users enable MFA. If the value is empty, Auth cannot create the MFA token required to continue an MFA-enabled sign-in.

Inject the value from a secret store. Do not commit it to a values file.

## Configure session and attempt limits

***

The Auth deployment supports these variables:

| Variable | Default | Purpose |
| - | - | - |
| `MFA_SESSION_TTL_SEC` | `300` | Lifetime of the short MFA sign-in session, in seconds. |
| `MFA_MAX_ATTEMPTS` | `5` | Maximum verification attempts allowed per user within the counter window. |
| `MFA_MAX_RESEND_ATTEMPTS` | `3` | Maximum email challenge sends allowed per user and email method within the counter window. |

Short session times reduce the period in which a stolen MFA token is useful. Verification requests count only after input, token, session, organization, and IP checks pass. The per-user verification counter expires after `MFA_SESSION_TTL_SEC` without another counted request. Each counted request refreshes that expiry.

The resend counter is per user and method, with a window of `MFA_SESSION_TTL_SEC` from its first reservation. Failed sends release their reservation. Successful verification clears both counters. Restarting sign-in does not reset them. Attempt and resend limits reduce repeated passcode guessing and message delivery abuse.

## Configure email delivery

***

Email MFA needs:

* an email communication provider in Identity.
* a link between the provider and the application that sends MFA messages.
* an email address on the user account.

Use the provider and application-provider operations described in [Identity APIs](/en/reference/platform/access-manager/am-identity-apis).

## Validate the deployment

***

**1. Enable an authenticator app for a test user**

Complete setup and store the issued recovery codes.

**2. Sign out and sign in again**

Make sure Auth returns the MFA step after the first factor.

**3. Verify a valid passcode**

Enter the current authenticator passcode. Expect the normal user session.

**4. Verify expiration**

Start sign-in again and wait longer than `MFA_SESSION_TTL_SEC`. Expect the MFA session to expire.

**5. Test configured delivery methods**

Enable email for the test user. Request a challenge and make sure the message arrives at the saved address.

**6. Test a recovery code**

Sign in with one recovery code, then make sure the same code cannot be used again.

Do not run limit tests against a production user. Repeated invalid attempts can temporarily block MFA verification for that user.

## Related pages

***

> **[Complete MFA in the Console](/en/platform/access-manager/features/mfa/console)**
>
> Test passcode and recovery-code verification during sign-in.

> **[Manage MFA via API](/en/platform/access-manager/features/mfa/api)**
>
> Integrate account enrollment and login verification.


# Multi-factor authentication
Source: https://docs.lerian.studio/en/platform/access-manager/features/mfa/overview

Add a second verification step to user sign-in with an authenticator app or email.

Multi-factor authentication (MFA) requires a user to prove their identity twice. The user first signs in with a password or single sign-on. Access Manager then asks for a passcode or recovery code before it issues access tokens.

MFA applies to user accounts. It does not apply to machine-to-machine applications that use client credentials.

## Supported methods

***

| Method | How the user gets the passcode | Additional requirement |
| - | - | - |
| **Authenticator app** | A TOTP application generates a six-digit passcode on the user's device. | The user scans the setup QR code or enters its secret. |
| **Email** | Access Manager sends a six-digit passcode to the user's saved email address. | The deployment needs an email communication provider. |

A user can enable more than one method and select one as the preferred method. The preferred method appears first during sign-in, but the user can select another enabled method.

## How MFA sign-in works

***

1. The user signs in with a password or [single sign-on](/en/platform/access-manager/features/sso/overview).
2. Auth validates the first factor.
3. If MFA is enabled for the user, Auth returns a short-lived MFA token instead of access tokens.
4. The user selects one of the enabled methods.
5. For email, Auth sends a challenge code. An authenticator app generates its code locally.
6. The user submits a six-digit passcode or one recovery code.
7. Auth verifies the second factor and returns the access tokens.

The MFA token expires after the deployment's configured session time. Auth also limits verification and resend attempts.

> [!WARNING]
>
> Do not treat an MFA token as an access token. It grants access only to the MFA challenge and verification operations.

## Setup and recovery codes

***

A user must set up and verify a method before enabling it. The setup differs by method:

* An authenticator app setup returns a QR-code URL and a secret.
* Email setup sends a verification code to the saved email address.

Access Manager issues recovery codes during MFA enrollment. Each recovery code works once. The user can use one when the preferred method is unavailable.

> [!WARNING]
>
> Store recovery codes when Access Manager issues them. You cannot retrieve the same codes later. Generating a new set invalidates the previous set.

The public Identity API can disable all MFA methods for an account. This operation also removes the account's recovery codes. To turn off MFA, send the code that the [Disable MFA](/en/reference/platform/access-manager/disable-mfa) reference describes.

## Self-service actions

***

Users can enroll and manage their own MFA methods in the Console, under Settings › Security, or through the Identity API. In the Console, a user can enable an authenticator app or email, remove a method, choose the default method, and generate recovery codes. The Console guide covers MFA at sign-in and removing a method. Self-service API operations require the authenticated subject to match the user ID in the request path.

## Failure and recovery behavior

***

| Situation | Result |
| - | - |
| The passcode is invalid | An invalid passcode evaluated after the preliminary checks counts toward the per-user verification limit. |
| The MFA session expires | The user must restart sign-in. |
| The resend limit is reached | Auth stops sending new email challenges for that user until the email-method counter expires or successful MFA verification clears it. |
| A recovery code succeeds | Access Manager consumes the code so it cannot be used again. |
| The user loses every method and recovery code | Contact an administrator and follow your organization's account-recovery procedure. |

## Next steps

***

> **[Complete MFA in the Console](/en/platform/access-manager/features/mfa/console)**
>
> Verify a passcode or use a recovery code during sign-in.

> **[Manage MFA via API](/en/platform/access-manager/features/mfa/api)**
>
> Use the Auth and Identity operations for enrollment and sign-in.

> **[MFA deployment requirements](/en/platform/access-manager/features/mfa/deployment)**
>
> Configure MFA session protection, limits, and delivery providers.

> **[Single sign-on](/en/platform/access-manager/features/sso/overview)**
>
> Use an external identity provider as the first sign-in factor.


# Manage partners via API
Source: https://docs.lerian.studio/en/platform/access-manager/features/partners/api

Create, read, change, and delete partners with the Identity API, read the product scope catalogs, create partner applications, and handle the error codes.

The Identity API manages [partners](/en/platform/access-manager/features/partners/overview) and their applications. Use it when you manage partners from your own tooling instead of the Console.

## Before you start

***

To manage partners, a user needs the `partners` permissions of `plugin-identity`: `get` to read partners and scope catalogs, `post` to create a partner, `patch` to change one and `delete` to delete one. Managing its applications needs the `applications` permissions `get`, `post` and `delete`.

## The operations

***

| Operation | What it does | Reference |
| - | - | - |
| `GET /v1/partners` | Lists your partners, one page at a time, with `applicationsCount` for each one. | [List partners](/en/reference/platform/access-manager/list-partners) |
| `POST /v1/partners` | Creates a partner. It returns `201` with the new partner and its `id`. It creates no application. | [Create a partner](/en/reference/platform/access-manager/create-a-partner) |
| `GET /v1/partners/{id}` | Returns one partner. | [Retrieve a partner](/en/reference/platform/access-manager/retrieve-a-partner) |
| `PATCH /v1/partners/{id}` | Changes a partner: its name, its permissions, its scope, its validity window, its IP allowlist, or its state. | [Update a partner](/en/reference/platform/access-manager/update-a-partner) |
| `DELETE /v1/partners/{id}` | Deletes a partner without applications. It returns `204`. | [Delete a partner](/en/reference/platform/access-manager/delete-a-partner) |
| `GET /v1/partners/ceiling` | Returns the most you can give a partner in the product that the `product` query parameter names. | [Retrieve the partner ceiling of a product](/en/reference/platform/access-manager/retrieve-the-partner-ceiling-of-a-product) |
| `GET /v1/scope-catalog` | Lists the scope catalogs that products published, with `partners` for each one. | [List scope catalogs](/en/reference/platform/access-manager/list-scope-catalogs) |
| `GET /v1/scope-catalog/{product}` | Returns the scope catalog of one product. A product without a catalog returns `404` with `IDE-1053`. | [Retrieve a product's scope catalog](/en/reference/platform/access-manager/retrieve-a-product-s-scope-catalog) |

To learn which dimensions a product accepts in `scope`, read its scope catalog. Each dimension has a `name`, and the flags `required` and `multi`.

## The partner fields

***

| Field | Required on create | Meaning |
| - | - | - |
| `displayName` | Yes | The partner's name, 1 to 128 characters. It is unique in your tenant, and the comparison ignores case. |
| `permissions` | Yes | One or more entries, each with its own `product`, `resources`, and `actions`. Each entry needs at least one resource and one action. |
| `scope` | No | One entry per restriction: `product`, `field`, and `values`. `field` is the `name` of a dimension in the product's scope catalog. |
| `ipAllowlist` | No | The partner's own IP allowlist. Each entry has a `cidr` and an optional `description` of up to 255 characters. |
| `validFrom` | No | The start of the validity window, as an RFC 3339 instant. Absent means no start date. |
| `validUntil` | No | The end of the validity window, as an RFC 3339 instant. Absent means no end date. |
| `state` | Not accepted | `active` or `suspended`. Every new partner is `active`. You change it with `PATCH`. |

The response also carries `id`, `applicationsCount`, `createdAt`, and `updatedAt`.

Rules that apply to the fields:

* `product` is the product slug that the product's scope catalog carries, such as `plugin-br-pix-jd`.
* Write `actions` as lowercase HTTP verbs: `get`, `post`, `put`, `patch`, `delete`.
* `resources` × `actions` is a full cross product. To give different actions on different resources, send more than one entry for the same product.
* Access Manager refuses the wildcard `*` in `resources`, `actions`, and `values`. List the items.
* A product in `scope` must also be in `permissions`.
* A dimension that the catalog marks as `required` needs a scope entry on every partner with permissions on that product. A dimension without `multi` takes one value only.
* Access Manager does not check that the `values` exist in the product. Use the identifiers that the product's own API returns.
* `state` is `active` or `suspended`, never `expired`. After `validUntil`, a read still returns the stored state.
* After the partner's `validUntil` date, Access Manager refuses new tokens for it.

## The IP allowlist field

***

`ipAllowlist` has three meanings on `PATCH`:

| You send | What happens |
| - | - |
| The field omitted | The stored list stays as it is. |
| `null` | The partner's own list is deleted. The partner goes back to your tenant's list. |
| A list of entries | These entries replace the partner's own list. |
| `[]` | Refused with `IDE-1048`. |

On `POST`, omit the field or send `null` to use your tenant's list.

When a partner has its own IP list, that list replaces the tenant's IP list for the partner's requests.

`validFrom` and `validUntil` work in a similar way on `PATCH`. Omit a bound to keep it, send an instant to set it, or send `null` to remove it.

## Examples

***

Replace the placeholders with your Identity API base URL, your bearer token, and identifiers from your own deployment.

```bash Create a partner theme={null}
IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
IDENTITY_BEARER_TOKEN="paste-your-access-token-here"

curl -sS -X POST "${IDENTITY_BASE_URL}/v1/partners" \
  -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Partner A",
    "permissions": [
      { "product": "plugin-br-pix-jd", "resources": ["entries"], "actions": ["get", "post"] }
    ],
    "scope": [
      { "product": "plugin-br-pix-jd", "field": "participantId", "values": ["12345678"] }
    ],
    "ipAllowlist": [
      { "cidr": "203.0.113.10", "description": "Partner A gateway" }
    ]
  }'
```

```bash Create its application theme={null}
IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
IDENTITY_BEARER_TOKEN="paste-your-access-token-here"
PARTNER_ID="paste-the-partner-id-here"

curl -sS -X POST "${IDENTITY_BASE_URL}/v1/applications" \
  -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "plugin-br-pix-jd",
    "description": "Partner A access to Pix JD",
    "partnerId": "'"${PARTNER_ID}"'"
  }'
```

```bash Suspend it theme={null}
IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
IDENTITY_BEARER_TOKEN="paste-your-access-token-here"
PARTNER_ID="paste-the-partner-id-here"

curl -sS -X PATCH "${IDENTITY_BASE_URL}/v1/partners/${PARTNER_ID}" \
  -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "state": "suspended" }'
```

```bash Go back to the tenant's IP list theme={null}
IDENTITY_BASE_URL="https://identity.<your-domain>"   # your Identity API base URL
IDENTITY_BEARER_TOKEN="paste-your-access-token-here"
PARTNER_ID="paste-the-partner-id-here"

curl -sS -X PATCH "${IDENTITY_BASE_URL}/v1/partners/${PARTNER_ID}" \
  -H "Authorization: Bearer ${IDENTITY_BEARER_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "ipAllowlist": null }'
```

## Create the partner's applications

***

A partner calls a product with an application that belongs to it. After you create the partner:

1. Create an application with [Create an Application](/en/reference/platform/access-manager/create-an-application). Send the partner's `id` in `partnerId`, and the product slug in `target`, such as `plugin-br-pix-jd`.
2. The Identity API returns the client secret only in the response that creates the application. Store it then. If you lose the secret, delete the application and create a new one.
3. Send the client ID and the secret to the partner through a secure channel.
4. Repeat steps 1 to 3 for each product the partner calls. Create one application per product.

To list the applications of one partner, send its `id` in the `partnerId` query parameter of [List Applications](/en/reference/platform/access-manager/list-applications). If `partnerId` does not name a partner of your tenant, both operations return `404` with `IDE-1046`.

## Change, suspend, or delete a partner

***

* On `PATCH`, send only the fields you change. A `permissions` or a `scope` list replaces the stored list as a whole. Read the partner first, then send the complete new list.
* To suspend a partner, send `"state": "suspended"`. To reactivate it, send `"state": "active"`.
* Suspending a partner in Access Manager stops its access, including the tokens it already holds. Reactivating the partner inside its validity window restores access with the same credentials.
* You cannot delete a partner that still has applications. The response is `409` with `IDE-1049`, and its `errors` list names each blocking application with its client ID. Delete those applications first.
* Deleting an application stops its tokens from working.

## Error codes

***

Errors in the partner operations:

| Code | Status | Title | When |
| - | - | - | - |
| `IDE-0001` | 400 | Missing Fields in Request | A required field is missing, or the scope has no entry for a dimension the product requires. |
| `IDE-0036` | 400 | Invalid IP Allowlist Entry | An `ipAllowlist` entry is not a valid address or CIDR range. |
| `IDE-1040` | 409 | Partner Display Name Already Exists | Another partner of your tenant has the same `displayName`. |
| `IDE-1042` | 400 | Unknown Scope Field | A scope `field` is not in the product's scope catalog, or the product has no scope catalog. |
| `IDE-1043` | 400 | Permission Above Product Ceiling | A permission is above what the product's editor role holds in your tenant. |
| `IDE-1044` | 400 | Scope Without Permissions | A product is in `scope` but not in `permissions`. |
| `IDE-1045` | 400 | Invalid Validity Window | `validUntil` is not later than `validFrom`. |
| `IDE-1046` | 404 | Partner Not Found | No partner with this `id` exists in your tenant. |
| `IDE-1047` | 400 | Wildcard Not Allowed | `*` is in `resources`, `actions`, or `values`. |
| `IDE-1048` | 400 | Empty IP Allowlist | `ipAllowlist` is an empty array. |
| `IDE-1049` | 409 | Partner Has Applications | The partner still has applications, so it cannot be deleted. |
| `IDE-1050` | 400 | Duplicate IP Allowlist Entry | The same network appears twice in `ipAllowlist`. |
| `IDE-1052` | 400 | Partner Rejected | The identity provider refused the partner for another reason. The message repeats that reason. |
| `IDE-1053` | 404 | Scope Catalog Not Found | The product has not published a scope catalog. |
| `IDE-1054` | 400 | Product Not Ready For Partners | A permission names a product that has not published its scope catalog. |
| `IDE-1055` | 400 | Product Not Opted In To Partners | A permission names a product whose scope catalog does not accept partners. |
| `IDE-1056` | 400 | Partner Write Exceeds Its Scope | A write permission acts at tenant level, or at a level wider than the partner's scope. |
| `IDE-1057` | 400 | Partner Read Rejected | The identity provider refused the ceiling read, for example for an unknown product. |

For every other code, see the [Access Manager error list](/en/reference/platform/access-manager/access-manager-error-list).


# Manage partners in the Console
Source: https://docs.lerian.studio/en/platform/access-manager/features/partners/console

Create a partner step by step, create its applications, change what it can reach, suspend it, and delete it from Settings in Lerian Console.

This guide shows how to manage [partners](/en/platform/access-manager/features/partners/overview) from the Console. You create the partner, create its applications, and change or end its access later.

## Before you start

***

To manage partners, a user needs the `partners` permissions of `plugin-identity`: `get` to see Partners in Settings, `post` to create a partner, `patch` to change one and `delete` to delete one. Managing its applications needs the `applications` permissions `get`, `post` and `delete`.

Creating a partner, changing its permissions or scope, and creating its applications need Access Manager 3.11.0 or later. With an earlier version, the Console shows "Requires Access Manager 3.11.0 or later" in place of those controls.

Collect this information before you start:

* The products the partner needs, and what it may do in each one.
* The identifiers of the items the partner may reach, for each dimension you restrict. Copy them from the product's own API or Console. The Console does not check that they exist.
* The network addresses the partner calls from, if you want to restrict them.
* The start and end dates of its access, if it has a time limit.

## Open the Partners page

***

**1. Open Settings**

Click the gear icon () in the top navigation bar.

**2. Select Partners**

Select **Partners**. The subtitle reads "Give each customer its own credentials and limit what it can reach."

The **Give partners access** card on the Console home page opens the same page.

The list shows each partner's **Name**, **Status**, **Validity window**, **Applications**, and **Creation Date**. The status is **Active**, **Suspended**, **Expired**, or **Not yet valid**. The Console shows **Expired** and **Not yet valid** from the validity window. With no partners yet, the page reads "You haven't registered any partners yet".

## Create a partner

***

Click **New partner**. A wizard opens with five steps: **Details**, **Products**, **Scope**, **Permissions**, and **Review**. The **Next** button opens only when the current step is complete. The **Back** button keeps what you entered.

**1. Details**

Type the partner's **Name**. It must be unique in your tenant.

Under **Validity window**, fill in **Valid from** and **Valid until** if the access has a time limit. Leave **Valid from** empty to start now. Leave **Valid until** empty so it never expires. After the partner's **Valid until** date, Access Manager refuses new tokens for it.

Under **Where it calls from**, choose one option:

* **Use your organization's IP list**: the partner uses your tenant's IP allowlist.
* **Give it its own list**: type each **IP address or CIDR range** and an optional **Description**. Click **Add IP** for each new line.

When a partner has its own IP list, that list replaces the tenant's IP list for the partner's requests.

**2. Products**

Choose the products the partner can use. The list shows only what your tenant can give.

A product that does not accept partners is unavailable, with one of these messages:

* "This product isn't ready for partners yet." The product has not published its scope catalog.
* "This product hasn't enabled partner access yet." The product's scope catalog does not accept partners.

**3. Scope**

Say where the partner can act on each product. A restriction that the product requires is already open, with **(Required)** after its name.

To add an optional restriction, check **Restrict by** followed by the name of the restriction. Type one identifier, or several identifiers separated by commas.

**4. Permissions**

Check the resources and the actions the partner can use on each product. To give a different set of actions on other resources, click **Add another line on** followed by the product name.

The Console offers only what your tenant can give. It shows a reason next to each entry that it cannot save:

* **Not allowed**: the product's editor role in your tenant does not hold this permission.
* **Outside the scope**: the write acts at a level wider than the partner's scope.
* **Granted twice**: another line already grants the same action on the same resource.

**5. Review**

Read the summary under "Check what this partner can and can't do". The **Only inside** part lists the restrictions. The **It can** part lists the actions on each resource. The **It can't** part lists what stays outside.

Click **Save**. The Console creates the partner with no applications and opens its **Overview** tab.

If Access Manager refuses the partner, the Console shows "The Access Manager refused this change". It also shows the reason and the error code, and opens the step that holds the field to fix.

## Create the partner's applications

***

A partner calls a product with an application that belongs to it. Create one application per product.

**1. Open the Applications tab**

In the partner list, click the partner. Select the **Applications** tab.

**2. Create the application**

Click **New Application**. In the **New application** side sheet, choose the **Product**. The list shows only the products that the partner has permissions on. Fill in **Description** and click **Create application**.

**3. Save the credentials**

The dialog "Save the credentials" shows the **Client ID** and the **Client secret**. The Console shows the client secret only when you create the application. Store it then. Click **I've saved them** to close the dialog.

Partner applications do not appear in **Settings → Applications**. They appear only on the partner's **Applications** tab.

## Change a partner

***

Open the partner from the list. The detail page has five tabs:

| Tab | What you do there |
| - | - |
| **Overview** | Rename the partner, change its **Validity window**, suspend or reactivate it, and delete it. |
| **Permissions** | Add or remove products, resources, and actions. |
| **Scope** | Add, change, or remove restrictions. Click **Add restriction** and choose the item under **Restrict by**. |
| **IPs** | Give the partner its own list, change it, or go back to **Use your organization's list**. |
| **Applications** | Create and delete the partner's applications. |

Saving on **Permissions** or **Scope** replaces the permissions and the scope together.

## Suspend or reactivate a partner

***

On the **Overview** tab, click **Suspend** and confirm. This deletes nothing.

To end the suspension, click **Reactivate** and confirm.

Suspending a partner in Access Manager stops its access, including the tokens it already holds. Reactivating the partner inside its validity window restores access with the same credentials.

## Delete a partner

***

You can delete only a partner without applications.

**1. Delete its applications**

On the **Applications** tab, delete each application of the partner. Deleting an application stops its tokens from working.

**2. Delete the partner**

On the **Overview** tab, under **Delete partner**, click **Delete** and confirm with **Yes, delete it**. Access Manager also deletes its permissions, scope, and IP list. You cannot undo this.

If the partner still has applications, the Console lists them and offers **Go to Applications**.

## Partners that use your tenant's IP list

***

When some partners have no IP list of their own, **Settings → Security** shows a notice on the **IP allowlist** tab. The notice says how many partners use your tenant's list, and its button lists them.


# Partners
Source: https://docs.lerian.studio/en/platform/access-manager/features/partners/overview

Give each of your own customers its own applications, and choose what it can do, where, from which addresses, and for how long.

A partner is one of your own customers that calls your Lerian platform from its own systems. Access Manager gives each partner its own applications. You decide what the partner can do and in which part of a product's data. You also decide its network addresses and its validity window.

## The building blocks

***

A partner is a record of your tenant. The rows after it describe what you set for a partner.

| Concept | What it is |
| - | - |
| **Partner** | A record in your tenant that represents one of your own customers. A partner is not a tenant. |
| **Partner application** | An application that belongs to one partner. A partner can have several applications. |
| **Permissions** | What the partner can do: a product, its resources, and the actions on them. |
| **Scope** | Where the partner can do it: one restriction per dimension of the product's scope catalog, with the values you choose. |
| **Scope catalog** | The list of dimensions that a product publishes for partners, such as a participant identifier. |
| **Ceiling** | The most you can give a partner in one product: the permissions of that product's editor role in your tenant. |
| **Partner IP allowlist** | A list of network addresses that belongs to one partner. |
| **Validity window and state** | The start and end of the partner's access (`validFrom` and `validUntil`), and its state: `active` or `suspended`. |

## Products that accept partners

***

You can give a partner permissions only on a product that accepts partners. A product accepts partners when it publishes a scope catalog with the partner opt-in.

To see which products accept partners in your deployment, read the scope catalogs with [List scope catalogs](/en/reference/platform/access-manager/list-scope-catalogs). A product accepts partners when its entry has `partners: true`. A product without an entry has not published a scope catalog.

In the Console, the **Products** step of the partner wizard shows the products that do not accept partners as unavailable.

## What you need to know

***

* Each product sets its own dimensions in its scope catalog. The catalog says if a dimension is required, and if it takes more than one value.
* When a product marks a dimension as required, a partner with permissions on that product needs a scope entry for it.
* Access Manager does not check that scope values exist in the product. It stores the values you enter. Copy them from the product's own API or Console.
* You cannot delete a partner that has applications. Delete its applications first.
* Access Manager refuses a permission above the ceiling with `IDE-1043`. The Console marks it as **Not allowed**.

## Next steps

***

> **[Manage partners in the Console](/en/platform/access-manager/features/partners/console)**
>
> Create a partner step by step, create its applications, suspend it, or delete it.

> **[Manage partners via API](/en/platform/access-manager/features/partners/api)**
>
> The partner operations, their fields, examples, and error codes.

> **[IP allowlist](/en/platform/access-manager/features/ip-allowlist/overview)**
>
> Your tenant's list of trusted network addresses.

> **[Error list](/en/reference/platform/access-manager/access-manager-error-list)**


# Configure SSO in the Console
Source: https://docs.lerian.studio/en/platform/access-manager/features/sso/console

Test, save, review, reconfigure, and remove a tenant's single sign-on provider in Lerian Console.

This guide shows how to configure [single sign-on](/en/platform/access-manager/features/sso/overview) from the Security page of Lerian Console.

## Before you start

***

You need permission to read Security settings and identity providers. You also need permission to configure or remove an application provider.

Create an OAuth or OpenID Connect application in your identity provider. Keep its client ID and client secret available.

## Open the Single Sign-On tab

***

**1. Open Settings**

Click the gear icon () in the top navigation bar.

**2. Select Security**

Select **Security** in the Settings sidebar.

**3. Select Single Sign-On**

The page opens on the **Single Sign-On** tab. You can also open `/settings/security?tab=sso` directly.

The page shows the active provider when one is configured. It also shows the authorized redirect URI that you must register with the provider.

## Register the callback URL

***

Copy the authorized redirect URI from the Console and add it to the provider application. The Console derives the value from the current browser origin. Confirm that this is the canonical Console URL that your users open. The path ends with:

```text theme={null}
/signin/sso/callback
```

The scheme, host, and path must match exactly. Use HTTPS outside local development.

## Configure a provider

***

**1. Open the configuration form**

Click **Configure SSO**. If a provider exists, click **Reconfigure** instead.

**2. Select the provider type**

Select Google, Microsoft Entra ID, Okta, or Custom (OIDC).

**3. Enter the credentials**

Enter the client ID and client secret. You must enter the complete secret on every save or reconfiguration.

**4. Enter the provider-specific settings**

For Okta, enter the Okta domain. For Custom OpenID Connect, enter the issuer URL and optional scopes.

**5. Test the connection**

Run the connection test before you save.

**6. Review the checks**

Fix each failed check. Review the discovered authorization, token, and user-info endpoints.

**7. Save the provider**

Register the callback URL and resolve every required preflight failure before you save. The Console does not block saving when preflight has not passed.

The connection test checks the candidate configuration without changing the active provider.

## Provider-specific settings

***

### Google and Microsoft Entra ID

Enter the client ID and client secret from the provider application. Register the callback URL shown by the Console.

### Okta

Enter the client ID, client secret, and Okta organization domain. Register the callback URL manually in Okta. The Console does not present the callback probe as a reliable Okta check.

### Custom OpenID Connect

Enter an absolute issuer URL. Access Manager uses OpenID Connect discovery to resolve the authorization, token, and user-info endpoints.

Scopes are optional. Enter them as a space-separated list, such as `openid profile email`.

## Review the active provider

***

The provider summary shows its type, display name, and masked client ID. The callback URL appears in the configuration form. Custom OpenID Connect endpoints appear during configuration when they apply. The client secret is write-only and never appears after you save it.

To change the provider, open the reconfiguration form and enter the full credentials again.

## Remove the provider

***

Removing the provider stops new SSO sign-ins for the tenant. Existing sessions continue until they expire or are revoked through the relevant session controls.

> [!WARNING]
>
> Make sure an administrator can still use an allowed sign-in method before you remove the provider.

## Test user sign-in

***

**1. Open a private browser session**

Use a private session so an existing provider session does not hide the login flow.

**2. Enter a tenant email address**

Enter an email address whose domain belongs to the configured tenant.

**3. Continue with the provider**

Select the provider if password login is also available.

**4. Complete provider authentication**

Sign in at the identity provider and return to the Console callback.

**5. Complete MFA if required**

Finish the second verification step for users who have MFA enabled.

## Related pages

***

> **[Single sign-on](/en/platform/access-manager/features/sso/overview)**
>
> Provider support and tenant resolution.

> **[SSO deployment requirements](/en/platform/access-manager/features/sso/deployment)**
>
> Configure the callback and browser-reachable Auth route.


# SSO deployment requirements (BYOC)
Source: https://docs.lerian.studio/en/platform/access-manager/features/sso/deployment

Configure the Console callback, browser-reachable Auth route, Identity route, and tenant resolution for SSO in BYOC.

This page tells a BYOC operator what to configure before an administrator enables [single sign-on](/en/platform/access-manager/features/sso/overview).

> [!NOTE]
>
> This page applies to BYOC deployments only. On Lerian Cloud, Lerian operates this configuration for you.

## Set one callback URL

***

Set `PLUGIN_AUTH_SSO_CALLBACK_URL` on both the Auth and Identity services. Use the exact public Console callback URL:

```text theme={null}
https://console.example.com/signin/sso/callback
```

Auth sends this URL to the identity provider. Identity includes it in the allowed redirect configuration.

> [!WARNING]
>
> Use the same absolute URL in Auth, Identity, the Console, and the identity-provider application. A scheme, host, or path mismatch makes the authorization-code exchange fail.

## Configure Console routes

***

The Console needs these routes:

| Variable | Purpose |
| - | - |
| `PLUGIN_AUTH_BASE_PATH` | Server-to-server Auth API base URL, including `/v1`. |
| `PLUGIN_AUTH_PUBLIC_BASE_PATH` | Browser-reachable Auth API base URL, including `/v1`. |
| `PLUGIN_IDENTITY_BASE_PATH` | Server-to-server Identity API base URL, including `/v1`. |

Set `PLUGIN_AUTH_PUBLIC_BASE_PATH` to an HTTPS address that the user's browser can reach. The browser follows the redirect from the SSO start operation directly.

To set these variables with the Product Console chart, see the [Product Console chart README](https://github.com/LerianStudio/helm/tree/main/charts/product-console).

The public and server-to-server Auth URLs can point to the same address. Use an internal address for server-to-server calls and the public address for browser redirects.

## Configure tenant resolution

***

Before SSO starts, Auth must know which Caradhras organization the user belongs to. Each tenant is one organization. Choose one of the two setups below.

### Fixed organization (recommended)

Set `PLUGIN_AUTH_SSO_STATIC_ORGANIZATION` in Auth to the name of the Caradhras organization your users belong to. This is normally the value of `AUTHORIZER_ORGANIZATION_NAME`, which defaults to `lerian`.

Auth then uses that organization for every SSO request and does not compare the email domain with the organization. This setup needs no change to Caradhras data and works for users of any email domain.

### Without a fixed organization

If you do not set `PLUGIN_AUTH_SSO_STATIC_ORGANIZATION`, SSO uses the organization fields:

* Set `domain` on the organization to your users' email domain, such as `example.com`. Without it, Auth refuses every SSO login.
* Set `domainHome` to `true` if people without an account must be able to sign in with SSO for the first time. Without it, the Console offers these people password login only.

An organization holds one `domain`, so only users of that email domain can sign in with SSO. If your users have more than one email domain, use the fixed organization instead.

### Set the organization fields

You can set `domain` and `domainHome` on the organization's edit page in the Caradhras web UI, or with the Caradhras API operation `POST /api/update-organization`. The Console has no input for them.

To use the API, send the request from a host that can reach Caradhras at the address in `AUTHORIZER_ADDRESS`, the address that Auth and Identity use. Authenticate with HTTP Basic and the client ID and secret that Access Manager uses for Caradhras, `AUTHORIZER_CLIENT_ID` and `AUTHORIZER_CLIENT_SECRET`. A Caradhras global administrator can also make the call. By default, a tenant administrator cannot.

This example makes the `acme` organization the home of the `example.com` domain:

```bash theme={null}
AUTHORIZER_ADDRESS="paste-the-AUTHORIZER_ADDRESS-value-here"
AUTHORIZER_CLIENT_ID="paste-the-AUTHORIZER_CLIENT_ID-value-here"
AUTHORIZER_CLIENT_SECRET="paste-the-AUTHORIZER_CLIENT_SECRET-value-here"

curl -X POST "$AUTHORIZER_ADDRESS/api/update-organization?id=admin/acme" \
  -u "$AUTHORIZER_CLIENT_ID:$AUTHORIZER_CLIENT_SECRET" \
  --json '{"owner":"admin","name":"acme","domain":"example.com","domainHome":true}'
```

Keys that you leave out of the body keep their stored values. A key that you send replaces the stored value, even when it is empty or `false`. Send `owner` and `name` with the organization's current values, because a different `name` renames the organization. Leave out `domainHome` for an organization that is not the home of its domain.

To check the result, list the organizations of a domain:

```bash theme={null}
curl "$AUTHORIZER_ADDRESS/api/get-organizations?owner=admin&field=domain&value=example.com" \
  -u "$AUTHORIZER_CLIENT_ID:$AUTHORIZER_CLIENT_SECRET"
```

### Refuse users from other domains (optional)

Caradhras can also compare the email domain with the organization's `domain` when it creates a user, including a first-time SSO user, and when an administrator changes a user's email. The `emailDomainPolicy` setting controls this check:

| Value | Effect |
| - | - |
| `off` | Caradhras does not check the email domain. |
| `warn` | Default. Caradhras logs the mismatch and saves the user. |
| `enforce` | Caradhras refuses the user with `CRDH-2009`. |

The check applies only to organizations that have a `domain`. To set it with the Access Manager chart, see the [Access Manager chart README](https://github.com/LerianStudio/helm/tree/main/charts/plugin-access-manager).

## Expose Auth to the browser

***

The browser must reach the Auth SSO start route over HTTPS. Expose Auth at a public address and allow the Console origin according to your deployment's cross-origin policy.

Identity can remain on a server-to-server route when administrators manage it only through the Console.

## Configure the identity provider

***

In the provider application:

1. Register the exact Console callback URL.
2. Allow the OpenID Connect scopes required to return the user's identity and email.
3. Issue a client ID and client secret for the tenant.
4. Make the issuer and endpoints reachable from the Access Manager services.

For a Custom OpenID Connect provider, use an issuer that publishes valid discovery metadata. API integrations can instead supply the complete authorization, token, and user-info endpoint set.

## Validate the deployment

***

**1. Open the Single Sign-On tab**

Make sure the Console can read the current provider state from Identity.

**2. Run provider preflight**

Test the candidate configuration without saving it. Fix every required failure.

**3. Register the callback URL**

Compare the provider registration with `PLUGIN_AUTH_SSO_CALLBACK_URL` character by character.

**4. Save the provider**

Keep password login available during the first test.

**5. Test from a private browser session**

Enter a tenant email, complete provider sign-in, and make sure the browser returns to the Console.

**6. Test tenant isolation**

Try an email that does not belong to the tenant. Make sure Auth does not complete the login or reveal tenant details.

**7. Test MFA continuation**

Sign in with an MFA-enabled user and make sure the Console opens the MFA verification step after SSO.

## Related pages

***

> **[Configure SSO in the Console](/en/platform/access-manager/features/sso/console)**
>
> Test and save the provider configuration.


# Single sign-on
Source: https://docs.lerian.studio/en/platform/access-manager/features/sso/overview

Let users sign in to a Lerian workspace through Google, Microsoft Entra ID, Okta, or another OpenID Connect provider.

Single sign-on (SSO) lets an external identity provider authenticate users for a Lerian workspace. Access Manager resolves the user's tenant, redirects the browser to the provider, and exchanges the provider's authorization code for Lerian access tokens.

SSO applies to user sign-in. Machine-to-machine applications continue to use client credentials.

## Supported providers

***

| Provider | Configuration |
| - | - |
| **Google** | OAuth client ID, client secret, and the Lerian callback URL. |
| **Microsoft Entra ID** | OAuth client ID, client secret, and the Lerian callback URL. The API identifies this provider as `AzureAD`. |
| **Okta** | OAuth client ID, client secret, Okta domain, and the Lerian callback URL. |
| **Custom OpenID Connect** | Client ID, client secret, optional scopes, the Lerian callback URL, and either an issuer URL or explicit provider endpoints. |

Access Manager supports one active SSO provider per tenant. Configuring another provider replaces the current configuration.

> [!NOTE]
>
> This SSO contract uses OAuth 2.0 and OpenID Connect. It does not configure a SAML provider.

## How sign-in works

***

1. The Console asks for the user's email address.
2. Auth resolves the tenant from the email address, as described in [Tenant resolution](#tenant-resolution). It then returns the available sign-in method.
3. The Console creates an S256 PKCE challenge.
4. Auth redirects the browser to the configured identity provider.
5. The provider authenticates the user and returns an authorization code to the Console callback URL.
6. The Console sends the code, state, and PKCE verifier to Auth.
7. Auth verifies the flow and the returned email identity.
8. Auth returns Lerian access tokens or continues to [MFA verification](/en/platform/access-manager/features/mfa/overview).

Auth verifies that the email returned by the provider belongs to the same tenant that started the flow. It refuses the login when the email is absent or resolves to another tenant.

## Tenant resolution

***

Each tenant is a Caradhras organization. SSO uses two fields of that organization:

* `domain` is the email domain of the tenant's users, such as `example.com`. Auth refuses the SSO login when the user's email domain differs from the tenant's `domain`.
* `domainHome` marks the one organization where people of that domain get their account when they sign in with SSO for the first time. Each domain has at most one home organization.

A person with accounts in several tenants signs in to their default tenant. If the person has no default tenant, Auth selects one.

On Lerian Cloud, Lerian sets these fields for you. In a BYOC deployment, set them as described in [SSO deployment requirements](/en/platform/access-manager/features/sso/deployment).

A BYOC deployment can use one fixed organization instead, set with `PLUGIN_AUTH_SSO_STATIC_ORGANIZATION`. Auth then does not compare the email domain with the organization.

Discovery does not reveal tenant identifiers. An unknown email receives the same general response as a tenant without SSO.

## Configuration validation

***

Run preflight validation before saving a provider. Preflight does not change the tenant configuration.

It checks:

* required fields.
* OpenID Connect discovery when the provider uses an issuer URL.
* explicit endpoint validation when the API supplies authorization, token, and user-info URLs.
* client credentials.
* the callback URL.
* the resolved authorization, token, and user-info endpoints.

Okta cannot always confirm the callback registration through preflight. Register the callback URL in Okta before you enable the provider.

## Next steps

***

> **[Configure SSO in the Console](/en/platform/access-manager/features/sso/console)**
>
> Test, save, review, and remove the tenant's provider.

> **[SSO deployment requirements](/en/platform/access-manager/features/sso/deployment)**
>
> Configure callback URLs, public Auth routing, and tenant resolution.

> **[Multi-factor authentication](/en/platform/access-manager/features/mfa/overview)**
>
> Add a second verification step after SSO.


# Installing Access Manager
Source: https://docs.lerian.studio/en/platform/access-manager/installing-access-manager

Prepare your environment, deploy the Auth and Identity services, and get Access Manager ready before any Lerian product enforces access.

Installing Access Manager means getting the **Auth** and **Identity** services running, connected to their dependencies, and ready to answer access decisions. This step has to happen before any Lerian product can enforce authentication or permissions.

This guide is for operators who install Access Manager. To install or upgrade the services, see the [Access Manager chart README](https://github.com/LerianStudio/helm/tree/main/charts/plugin-access-manager).

## Prerequisites

***

You can plan an installation without deep Kubernetes knowledge. Use the list below as a checklist before you start.

### License

Access Manager is an Enterprise feature and requires a valid Lerian license configuration. The services apply license checks through HTTP middleware, so validate the license before enabling protected products. See the [License documentation](/en/start-here/evaluate-and-deploy/lerians-license) for details. If you don't have a license yet, [get in touch with our team](https://lerian.studio/contact).

### Deployment model

Decide how you're going to run Access Manager. The choice shapes tenant resolution, Caradhras configuration, and a few operational defaults later on.

* **SaaS** - Lerian runs the platform. You manage users, groups, and applications through Lerian Console or the Identity APIs.
* **BYOC** - You run Access Manager against a configured default organization and Caradhras identity backend.

If you're not sure which model applies, confirm with your Lerian contact before installing.

### Auth service

Auth is the runtime side of Access Manager. It issues and refreshes tokens, validates sessions, checks permissions, handles logout and user info, and runs MFA challenges. Auth needs to be reachable from every protected Lerian product over the network.

### Identity service

Identity is the data side of Access Manager: users, groups, applications, communication providers, application-provider links, and MFA configuration. Identity is the management surface. Both Identity and Auth connect to the configured Caradhras backend: Identity manages identity data through it, while Auth uses its own connection for tokens, MFA, and authorization decisions.

### Identity backend

Access Manager uses a configured Caradhras backend for identity storage. Caradhras persists its identity data in the configured PostgreSQL database. PostgreSQL backs Caradhras and does not replace it. For a BYOC deployment, configure that Caradhras backend for your environment.

### Data and cache services

* A **PostgreSQL** instance as the backing database for Caradhras-managed identity data.
* A **Valkey** cache for token, permission, and MFA-related operations.

Provision both and make them reachable before Auth and Identity start. Sizing and high-availability decisions depend on your deployment model.

### Product connectivity

Plan the network paths now so you're not debugging them later:

* Protected products must reach Auth over the network.
* Administrators (and any back-office tooling) must reach Identity to manage users, groups, applications, and providers.
* Do not expose either service publicly without the appropriate ingress controls.

### Environment and bootstrap data

A fresh environment seeds base access data, including its organization, built-in roles, groups, applications, and permission sets, once at startup. This is the **bootstrap** layer. After the environment is up, day-to-day changes happen through the Identity APIs or Lerian Console, not by editing bootstrap data.

> [!WARNING]
>
> Bootstrap applies its seed data only during initial environment setup. Changes to built-in resources, actions, roles, groups, applications, or permission sets in an existing environment must be delivered through controlled platform updates, such as migrations or an idempotent reconciler.

## Installation flow

***

Follow these steps in order. Each one builds on the previous one.

**1. Choose your deployment model**

Pick SaaS or BYOC and confirm any model-specific decisions with your Lerian contact: Caradhras configuration and licensing scope. Write this down because every later step refers back to it.

**2. Prepare dependencies**

Provision the supporting infrastructure so Auth and Identity have everything they need at startup:

* a valid Lerian license configured for the environment.
* a PostgreSQL instance to back Caradhras-managed identity data.
* a Valkey cache for tokens, permissions, and MFA.
* the configured Caradhras identity backend.
* network paths between Access Manager, its dependencies, and the products that will eventually enforce access.

Don't move on until each dependency is reachable from where Access Manager will run.

**3. Deploy Auth and Identity**

Install the Access Manager services into your environment. See the [Access Manager chart README](https://github.com/LerianStudio/helm/tree/main/charts/plugin-access-manager).

**4. Bootstrap base access data**

First startup seeds the base organization, built-in roles, groups, applications, and permission sets that the platform relies on. Let bootstrap finish before pointing any product at the services.

From this point on, treat bootstrap data as read-only. Manage everyday access through the Identity APIs or Lerian Console.

**5. Validate the services**

Confirm that the installation is healthy before any product depends on it:

* Auth and Identity report healthy and are reachable from the products that will use them.
* PostgreSQL (Caradhras's backing database) and Valkey are connected and responsive.
* The Caradhras identity backend is configured and reachable.
* A test token request succeeds against Auth, and a basic Identity call (for example, [List Groups](/en/reference/platform/access-manager/list-groups)) succeeds for the selected deployment mode.

If anything in this list fails, fix it here. Don't enable products on top of an unhealthy install.

**6. Enable protected products**

After you validate the installation, turn enforcement on inside each Lerian product or plugin by setting the Auth variables in its `.env`. The full per-product configuration lives in [Enabling Access Manager](/en/platform/access-manager/enabling-access-manager).

**7. Use Access Manager**

With installation done and products enforcing access, move on to day-to-day operation: requesting tokens, managing users, groups, and applications, configuring MFA, and calling protected APIs. Start with [Using Access Manager](/en/platform/access-manager/using-access-manager) for the API workflow, or [Access Manager via Lerian Console](/en/platform/access-manager/using-access-manager-with-midaz-console) for the visual flow.

> [!TIP]
>
> Auth and Identity should be deployed, healthy, and validated before you flip any product into enforcement mode.

## Next steps

***

* [Enabling Access Manager](/en/platform/access-manager/enabling-access-manager) - turn on enforcement in each Lerian product.
* [Using Access Manager](/en/platform/access-manager/using-access-manager) - request tokens, manage users and applications, configure MFA.
* [Access Manager chart README](https://github.com/LerianStudio/helm/tree/main/charts/plugin-access-manager) - installation and upgrade.
* [How Access Manager works](/en/platform/access-manager/am-components) - a closer look at Auth, Identity, and product-level enforcement.


# Using Access Manager
Source: https://docs.lerian.studio/en/platform/access-manager/using-access-manager

Use the Access Manager APIs to configure human access, machine-to-machine credentials, MFA challenges, and token-based authentication in your environment.

Access Manager is how you decide who reaches your Lerian products and how systems prove who they are before they call a protected API. This guide walks through that setup with the APIs.

If you'd rather work visually for the common user and application tasks, use [Access Manager via Lerian Console](/en/platform/access-manager/using-access-manager-with-midaz-console) instead.

## Before you start

***

First, make sure each product's route-level Auth client is enabled and configured with an Auth address. Protected routes then expect an `Authorization` header carrying a valid bearer token.

```text theme={null}
Authorization: Bearer <access_token>
```

> [!WARNING]
>
> A product with its Auth client enabled and configured rejects requests without a valid bearer token on its protected routes. This applies even if the endpoint was previously reachable without authentication.

On Lerian Cloud, that token also carries your tenant context, so you never pass tenant identifiers in payloads or headers yourself.

With the Identity APIs, the token is also your tenant boundary. List endpoints return only the users, groups, and applications in your tenant. Create, update, and delete operations stay inside it.

## Human access

***

Follow this flow when a person needs to access Lerian products.

**1. Inspect available groups**

Use [List Groups](/en/reference/platform/access-manager/list-groups) to see the groups available in your environment.

On Lerian Cloud, the list covers only your tenant. Use the returned group IDs as-is when you create or update users.

**2. Review the permission surface**

Some products use HTTP-method-style actions, while others use semantic actions such as `read`, `write`, `create`, or `process`. Use the permissions returned by the API instead of deriving permission names from endpoint paths.

**3. Create the user**

Use [Create a User](/en/reference/platform/access-manager/create-user) and assign the correct groups during creation.

Group assignment defines what the user can access. For example, assigning a read-only Midaz group lets the user inspect Midaz resources without changing them.

**4. Request a user token**

Use [Request an Access Token](/en/reference/platform/access-manager/request-access-token) with the `password` grant type.

Use the returned access token as the bearer token when the user calls protected APIs.

**5. Refresh the token when needed**

Use [Refresh the Access Token](/en/reference/platform/access-manager/refresh-token) to exchange a valid refresh token for a new access token.

### User management endpoints

Use these endpoints to maintain human access over time:

* [List Users](/en/reference/platform/access-manager/list-users): list users.
* [Retrieve User Details](/en/reference/platform/access-manager/retrieve-user-details): inspect a user.
* [Update a User](/en/reference/platform/access-manager/update-user): update user information and group assignments.
* [Delete a User](/en/reference/platform/access-manager/delete-user): remove user access.
* [Reset a User Password](/en/reference/platform/access-manager/reset-user-password): reset a user's password through an administrative flow.
* [Update a User Password](/en/reference/platform/access-manager/update-user-password): update a user's password with the current password and the new one.

## Machine-to-machine access

***

When a service, job, or integration needs to call Lerian APIs without a human in the loop, give it its own application.

**1. Create an application**

Use [Create an Application](/en/reference/platform/access-manager/create-an-application) to create credentials for the integration.

Each integration should have its own application. This makes credential rotation and access review easier. The response includes the `clientId` and `clientSecret` used by Auth in the `client_credentials` flow. Store the secret at once: later reads of the application do not return it.

**2. Review or manage the application**

Use [List Applications](/en/reference/platform/access-manager/list-applications), [Retrieve Application Details](/en/reference/platform/access-manager/retrieve-application-details), or [Delete Application](/en/reference/platform/access-manager/delete-application) when you need to review or remove machine-to-machine access.

Identity hides internal applications from the list. On Lerian Cloud, it only returns applications of your tenant.

**3. Request an application token**

Use [Request an Access Token](/en/reference/platform/access-manager/request-access-token) with the `client_credentials` grant type.

Use the returned access token as the bearer token for the integration's API calls.

### Application catalog

Identity accepts only application names from its catalog when it creates or deletes machine-to-machine applications. [List Available Applications](/en/reference/platform/access-manager/list-available-applications) returns the catalog, with the name and display name of each application.

## Provider setup

***

Use an email provider when an application needs email delivery for MFA. Browser SSO uses a separate OAuth-provider and SSO-policy configuration. See the [Identity service](/en/platform/access-manager/identity-plugin).

1. Create or review a provider with the [Providers API](/en/reference/platform/access-manager/list-providers).
2. Link the provider to the application with [Link Provider to Application](/en/reference/platform/access-manager/link-provider-to-application).
3. If the application has multiple linked providers, use [Set Default Application Provider](/en/reference/platform/access-manager/set-default-application-provider) to select the default provider.

Use the application-provider endpoints when you need to list, update, unlink, or reorder provider links for an application.

## MFA setup

***

Use MFA for users who need an additional login verification step.

**1. Start setup**

Use [Initiate MFA Setup](/en/reference/platform/access-manager/initiate-mfa-setup) on the signed-in user's own account and selected MFA method.

**2. Verify setup**

Use [Verify MFA Passcode](/en/reference/platform/access-manager/verify-mfa-passcode) to confirm the method.

**3. Enable MFA**

Use [Enable MFA](/en/reference/platform/access-manager/enable-mfa) after setup verification.

**4. Manage MFA over time**

Use [Get MFA Status](/en/reference/platform/access-manager/get-mfa-status), [Set Preferred MFA Method](/en/reference/platform/access-manager/set-preferred-mfa-method), or [Disable MFA](/en/reference/platform/access-manager/disable-mfa) as the user's access requirements change.

During login, users with MFA enabled may need to complete [Initiate MFA Challenge](/en/reference/platform/access-manager/initiate-mfa-challenge) with the MFA token and selected method, then [Verify MFA Login](/en/reference/platform/access-manager/verify-mfa-login), before receiving usable access tokens. Administrative MFA changes use separate administrative operations.

## User information and session control

***

Once a user is active, a few endpoints help inspect and control that session. [Retrieve User Information](/en/reference/platform/access-manager/retrieve-user-information) returns their OIDC-compatible profile, and [Retrieve User Permissions](/en/reference/platform/access-manager/retrieve-user-permissions) shows the resources and actions they can reach. To end a session, call [End User Session](/en/reference/platform/access-manager/end-user-session) with the `id_token_hint` form field from that session. This endpoint does not select another user by ID.

## Permission checks

***

Protected products call Auth with the resource and action they need to enforce. Use [Validate User Permission](/en/reference/platform/access-manager/validate-user-permission) when an integration needs to check an access decision explicitly.

```json theme={null}
{
  "resource": "reports",
  "action": "get"
}
```

The response tells you whether the authenticated subject is authorized for that resource-action pair.

## Tenant access rules on Lerian Cloud

***

On Lerian Cloud, Access Manager resolves your tenant from your token or application. For password grants and SSO, Auth finds the tenant from the user's email address. A person with accounts in several tenants signs in to their default tenant. If the person has no default tenant, Auth selects one. Use [List Own Tenants](/en/reference/platform/access-manager/list-own-tenants) and [Set Own Default Tenant](/en/reference/platform/access-manager/set-own-default-tenant) to see the tenants and change the default.

Identity accepts a new user, or a change to the email of a user, only when the email domain matches the `domain` field of your organization. It refuses the request with `IDE-0034` when the domain is different or when that field is empty.

So don't add tenant IDs to Identity or Auth payloads unless an endpoint explicitly documents that field. After authentication, bearer-token claims scope normal Identity management and permission calls. Password and client-credentials grants resolve tenant context before a bearer token exists.


# Platform services
Source: https://docs.lerian.studio/en/platform/platform-introduction

Console, Access Manager, Streaming Hub, Multi-tenancy, and Observability: the services that serve every Lerian product, what each one owns, and what you keep.

Console, Access Manager, Streaming Hub, Multi-tenancy, and Observability are platform services. They are not products themselves.

In BYOC you deploy them into your own cloud or data center alongside the products. In Lerian Cloud, Lerian operates them for you.

## The five services

***

> **[Lerian Console](/en/platform/console/about-lerian-console)**
>
> One web interface for the products that ship a Console module.

> **[Access Manager](/en/platform/access-manager)**
>
> Authentication and authorization for protected Lerian products: tokens, users, groups, applications, and MFA.

> **[Streaming Hub](/en/platform/streaming-hub/what-is-streaming-hub)**
>
> Delivers platform events to destinations you own: webhook, pull cursor, SQS, RabbitMQ, and EventBridge. It consumes the internal stream and never produces onto it.

> **[Multi-tenancy](/en/platform/multi-tenancy)**
>
> One deployment serves independent tenants. Each product derives tenant context according to its own authentication contract.

> **[Observability](/en/platform/observability)**
>
> Products export traces, metrics, and logs over OpenTelemetry to a collector.

## How the services sit around the products

***

```mermaid theme={null}
flowchart LR
  App["Your applications and operators"]
  Console["Lerian Console"]
  AM["Access Manager<br/>Auth and Identity"]
  Products["Lerian products"]
  Hub["Streaming Hub"]
  Sinks["Your webhook, queue, or cursor"]
  Otel["Your collector and telemetry backend"]
  IdP["Your identity provider (optional)"]
  App -->|"presents a token"| Products
  Products -->|"authorizes subject and action"| AM
  Console -->|"manages users and applications"| AM
  Console -->|"operates the modules"| Products
  Products -.->|"publish events"| Hub
  Hub -.->|"delivers, at least once"| Sinks
  Products -.->|"OTLP traces, metrics, logs"| Otel
  IdP -.->|"as an upstream provider"| AM
  classDef lerian fill:#fff8e1,stroke:#f4b400,color:#1f1f1f;
  classDef yours fill:#e8f0fe,stroke:#4285f4,color:#1f1f1f;
  classDef ext fill:#f1f3f4,stroke:#9aa0a6,color:#1f1f1f;
  class Console,AM,Products,Hub lerian;
  class App,Sinks,Otel,IdP yours;
```

The diagram shows five interactions.

1. Your application sends a bearer token to a product route that Access Manager protects. The product asks Access Manager whether that subject may perform the route's action, then admits or rejects it.
2. Lerian Console reads and writes access data through Access Manager, and operates each product module.
3. Streaming Hub matches events on the internal stream against your subscriptions and delivers each match.
4. Products push traces, metrics, and logs over OTLP to the collector address you set.
5. Your identity provider, when you run one, plugs into Access Manager as an upstream provider.

## Services and products

***

| Service | Midaz | Matcher | Flowker | Lender | Reporter | Streaming Hub | Brazil rails |
| - | - | - | - | - | - | - | - |
| Access Manager | protected routes | bearer token on protected routes | protected routes | protected routes, public jurisdiction reads | resource and action per route | the control plane | bearer token on protected routes, default differs per rail |
| Console | Midaz Module, with the plugins the Plugins screen shows | module | module | | module | module | Pix Indirect (BTG), Payments, and, when enabled, Bank Transfer (TED JD) |
| Streaming Hub | fact topics | | workflow trigger | fact topics | report completion facts | — | per rail |
| Multi-tenancy | organizations, ledgers, accounts, transactions | reconciliation resources | per-tenant database connections | tenant from the validated identity | data sources and reports | subscriptions isolated by tenant | per rail |
| Observability | OTLP export | | OTLP export | telemetry toggle and endpoint | OTLP push | OTLP export | OTLP export |

## What you bring and what Lerian ships

***

You bring:

* Cloud infrastructure and Kubernetes clusters.
* Database administration and backups.
* Network security, container patching, and secrets management.
* Your monitoring pipelines and the collector that receives telemetry.
* The destinations Streaming Hub delivers to.
* Your identity provider. It connects to Access Manager as an upstream provider and does not replace the identity backend.

Lerian ships:

* Helm charts for supported products and infrastructure components, through an OCI-compatible registry.
* Terraform examples for the base infrastructure Midaz needs on AWS, GCP, or Azure.
* Lifecycle Management for Enterprise BYOC: an agent in your cluster, through which Lerian installs and upgrades products.
* Access Manager and Lerian Console, as Enterprise features.

The Midaz chart lets you disable a bundled Valkey, PostgreSQL, MongoDB, or RabbitMQ and use an external service instead.

## Adopt one service at a time

***

**1. Access Manager**

Get the Auth and Identity services running with Caradhras, PostgreSQL, and Valkey. Then turn enforcement on per product. Install first, validate, then enable.

**2. Lerian Console**

Point the Console at Access Manager. Its user and application screens read and write that data.

**3. Streaming Hub**

Deploy the dedicated `streaming-hub-helm` chart, separate from any product chart. Its API routes require an Access Manager token.

**4. Observability**

Deploy a collector in your Kubernetes cluster. Then configure the product workloads that support it to send telemetry to it.

Multi-tenancy is not a step in that order. Lerian Cloud provides it.

## Deploy and operate

***

> **[Helm charts](https://github.com/LerianStudio/helm)**
>
> Install and upgrade the published charts.

> **[Lifecycle Management](/en/platform/lifecycle-management)**
>
> Lerian installs and upgrades products in your cluster through an agent that you install.

> **[Licensing](/en/platform/licensing/license-manager)**
>
> How a Lerian product validates its license key, and what each result allows.

> **[Terraform examples](/en/products/midaz/midaz-terraform-foundation)**
>
> Create the network, DNS, database, and Kubernetes base Midaz needs on AWS, GCP, or Azure.

## Build with Narya

***

Narya runs coding agents behind one HTTP API. One long-lived host on your machine owns the sessions, the store and the model connections. Lerian ships a terminal client and a one-shot command on top of it, and you can write your own client against the same contract.

> **[Narya](/en/platform/narya/what-is-narya)**
>
> What Narya is, how you run it, and how it fits a pipeline.

> **[The host API](/en/platform/narya/the-host-api)**
>
> One contract for every client: socket, event stream, envelopes.

## Where to go next

***

[Deployment models](/en/start-here/evaluate-and-deploy/deployment-models) · [Multi-tenancy](/en/platform/multi-tenancy) · [What is Access Manager?](/en/platform/access-manager) · [What is Lerian Console?](/en/platform/console/about-lerian-console) · [Streaming Hub quick start](/en/platform/streaming-hub/streaming-hub-quick-start)


# Compliance
Source: https://docs.lerian.studio/en/products/flowker/compliance

How Flowker supports regulatory compliance with validation before the ledger write and a step-level record of every workflow execution.

Flowker helps compliance teams answer two questions: was the transaction validated before it reached the ledger, and what did each step of that validation do?

## Validation before the ledger

***

Flowker runs a workflow's nodes by following its graph connections, and it has no join node that waits for parallel branches to converge. To place checks before the node that writes to the ledger, build a linear validation chain, and:

* The ledger write runs only after each earlier check in that chain returns a result
* To stop before the write, configure no outgoing edge whose `sourceHandle` matches the conditional's failing outcome. If the failing branch must run notification or audit nodes, ensure that branch has no path to the ledger-write node. Flowker follows only the edge whose `sourceHandle` matches the evaluated outcome. If no edge matches, that branch ends.
* You do not depend on post-write validation and the corrections it forces
* The execution record shows the sequence: the checks that ran, their verdicts, then the write

This is a preventive design. You place the checks ahead of the write, and Flowker preserves that order in the linear chain. Do not use a fan-out and later merge as a synchronization barrier: a node after the merge can run before another branch finishes.

## Execution records

***

Each workflow execution keeps a step-level record of what ran. For every step, the record holds the step name and number, when it ran, and its status. It also holds how long the step took, the output it returned, and the error message if it failed.

* Use [List executions](/en/reference/products/flowker/list-executions) to find executions. Filter by workflow and by status, then page through the results with a cursor.
* Use [Get execution results](/en/reference/products/flowker/get-execution-results) to see an execution's step details after it reaches a terminal status (`completed` or `failed`). It returns an in-progress error for `pending` or `running` executions.

## What's next

***

> **[Security](/en/products/flowker/security)**
>
> Learn about Flowker's authentication model, encryption, and resilience features.

> **[Executions API](/en/reference/products/flowker/list-executions)**
>
> Query execution history and step-level results through the API.


# Configuring a webhook trigger
Source: https://docs.lerian.studio/en/products/flowker/configuring-a-webhook-trigger

Start a Flowker workflow from an inbound HTTP call. Choose the payload contract, decide how the webhook answers, and confirm the route serves your caller.

A webhook trigger is the entry point of a workflow that starts from an inbound HTTP call. You declare a path and a method on the trigger node. When you activate the workflow, Flowker serves that path. Each fresh accepted call starts a workflow execution. A repeat with the same `Idempotency-Key` returns the existing execution instead.

The optional `input_contract` decides which payloads Flowker accepts and how it decodes them. Set it explicitly for new nodes: it fixes the payload format for the whole route. Older nodes that omit it remain valid. Flowker derives `xsd` when they carry an XSD schema and XML format. Otherwise Flowker treats them as `open` with JSON as the default format.

## Before you start

***

* A workflow in `draft` status. An active workflow is locked, so add the trigger before you activate it. See [Step 4: Run the workflow](/en/products/flowker/integration-guide#step-4-run-the-workflow) for the create-and-activate path.
* Grant the `execute` permission on the `webhooks` resource to every system you let call the path. See [Securing a webhook](/en/products/flowker/integration-guide#securing-a-webhook).
* For the `xsd` contract: an XSD document in the registry. Upload it with [Upload an XSD schema](/en/reference/products/flowker/upload-xsd-schema) and keep the id it returns.
* For the `openapi` contract: an OpenAPI document in the registry ([Upload an OpenAPI schema](/en/reference/products/flowker/upload-openapi-schema), covered end to end in [Connecting your own API](/en/products/flowker/connecting-your-own-api)). You also need the path and the method of the operation whose request body describes your payload. [Derive an operation schema](/en/reference/products/flowker/derive-openapi-operation-schema) shows you that request body.
* For a Streaming Hub webhook subscription: set its `endpoint` to [Trigger a Webhook from Streaming Hub](/en/reference/products/flowker/trigger-webhook-from-streaming-hub). That route starts the same workflow and checks the Hub signature instead of a bearer token. The deployment must turn it on, and the subscription's signing secret must match the one the deployment holds for your tenant.

## Step 1: Read the trigger contract from the catalog

***

Triggers are built in. You discover them in the catalog, and you never create one.

**1. List the built-in triggers**

[List catalog triggers](/en/reference/products/flowker/list-catalog-triggers) returns each trigger with its `id`, `name` and `version`. The webhook trigger's id is `webhook`.

```bash theme={null}
curl -s https://your-flowker-host/v1/catalog/triggers \
  -H "Authorization: Bearer <token>" | jq .
```

**2. Read the webhook trigger's schema**

[Get a catalog trigger](/en/reference/products/flowker/get-catalog-trigger) returns the same fields plus `schema`, the JSON Schema Flowker validates your trigger node against. Read it when you want the field list from the running instance.

```bash theme={null}
curl -s https://your-flowker-host/v1/catalog/triggers/webhook \
  -H "Authorization: Bearer <token>" | jq -r '.schema' | jq .
```

## Step 2: Choose the input contract

***

| Mode | What the route accepts | What Flowker does with the payload | Fields the mode requires |
| - | - | - | - |
| `open` | JSON or XML, as you declare in `format` | Decodes the body and runs no contract validation. | `format`: `"json"` or `"xml"` |
| `xsd` | XML | With XSD validation configured, validates the document against the XSD schema you referenced. Without it, Flowker decodes well-formed XML but skips XSD validation. | `xsd_schema_id` |
| `openapi` | JSON | Validates the payload against exactly one operation of the OpenAPI document you referenced, and rejects a payload that does not conform. | `openapi_schema_id`, `operation_path`, `operation_method` |

The mode fixes the route's payload format. An `xsd` route is XML and an `openapi` route is JSON. An `open` route uses the `format` you declare. Omit `format` on `xsd` and `openapi`. A value other than `"xml"` on `xsd`, or other than `"json"` on `openapi`, fails the save with `FLK-0934`.

Choose `open` when the caller's payload has no published contract, or when you want the workflow itself to decide what is acceptable. When a partner sends XML that an XSD document defines, choose `xsd`. Choose `openapi` when a partner sends JSON and you hold the OpenAPI document that describes it.

> [!NOTE]
>
> An `openapi` route never accepts an unchecked payload: when Flowker cannot reach a verdict, it rejects the call with `FLK-0720`, and the workflow never sees that payload. When XSD validation is configured, an `xsd` route reaches its verdict. A document that does not conform is rejected with `XML_VALIDATION_FAILED`. Flowker rejects a verdict it cannot trust with `FLK-0720`.

## Step 3: Decide how the webhook answers

***

| `response_mode` | What the caller receives |
| - | - |
| `async` (default) | For a fresh, non-terminal execution, HTTP `202` with the execution receipt as soon as it starts. The workflow continues in the background, and the caller reads the outcome from [Get execution results](/en/reference/products/flowker/get-execution-results). If the resolved execution is already terminal, including an `Idempotency-Key` replay, Flowker returns the receipt with HTTP `200` and replay metadata. |
| `sync` | Flowker holds the connection until the execution reaches a terminal state, for up to 15 seconds, then returns the outcome. If the window closes first, the caller receives the same `202` receipt plus a `Location` header pointing at the results endpoint. |

On a `sync` route, `response_view` shapes the body:

| `response_view` | Body |
| - | - |
| `full` (default) | The complete execution-results envelope: `executionId`, `workflowId`, `status`, `stepResults`, `finalOutput` when available, `startedAt`, optional `completedAt` and `inputData`, plus idempotency replay metadata when applicable. |
| `final_output` | For a completed execution, only the final business-output map (`{}` when absent). For a failed execution, a failure object with `status: "failed"` and, when available, `errorMessage` and `errorClass`. |
| `receipt` | The lean receipt: `executionId`, `workflowId`, `status` and `startedAt`. |
| `passthrough` | The shape the terminal step implies: a relayed provider response, or a terminal `set_output` node's own output. When the execution failed, its last step captured no provider response, and no `set_output` node that ran set a `responseStatusCode`, the response is the `full` envelope at HTTP `200`. |

`response_view` is inert on an `async` route. For the full `passthrough` rules and for the `responseStatusCode` override, see [Synchronous response mode](/en/products/flowker/integration-guide#synchronous-response-mode).

> [!TIP]
>
> Pick `async` when the caller only needs to know the event arrived. Pick `sync` when the caller needs the answer in the same call (a partner that expects a decision on the same connection, for example).

## Step 4: Write the trigger node

***

The webhook trigger is a node with `type: "trigger"` and these fields in its `data`:

| Field | When you set it | Value |
| - | - | - |
| `triggerType` | Always | `"webhook"`. |
| `path` | Always | The path to serve, such as `"payments/received"`. It carries as many segments as you need. |
| `method` | Always | The method the route answers: `GET`, `POST`, `PUT`, `PATCH` or `DELETE`, in upper case. |
| `input_contract` | Optional | `"open"`, `"xsd"` or `"openapi"`. Set it explicitly for new nodes. When omitted, the legacy rules apply. |
| `format` | With `open` | Required with `open`: `"json"` or `"xml"`. Omit it with `xsd` and `openapi`. |
| `xsd_schema_id` | With `xsd` | The id [Upload an XSD schema](/en/reference/products/flowker/upload-xsd-schema) returned. |
| `openapi_schema_id` | With `openapi` | The id [Upload an OpenAPI schema](/en/reference/products/flowker/upload-openapi-schema) returned. |
| `operation_path` | With `openapi` | The operation path as the OpenAPI document writes it, such as `"/orders"`. Flowker matches it exactly. |
| `operation_method` | With `openapi` | The operation's method: `GET`, `POST`, `PUT`, `PATCH` or `DELETE`. |
| `response_mode` | Optional | `"async"` (default) or `"sync"`. |
| `response_view` | Optional | `"full"` (default), `"final_output"`, `"receipt"` or `"passthrough"`. |
| `accepted_headers` | Optional | Up to 50 extra request-header names to persist in `_webhook.headers`, in every contract mode. Names must be unique case-insensitively; each must be a non-blank HTTP header name, at most 256 characters. The fixed denylist rejects `Authorization`, `Proxy-Authorization`, `Cookie`, `Set-Cookie`, `X-API-Key`, `X-Auth-Token` and `X-Webhook-Signature`; it does not detect credentials in other headers. Never allowlist another secret-bearing name such as `X-Amz-Security-Token`. |

The trigger configuration is a closed contract. A save fails with `FLK-0934` when the webhook trigger:

* omits `path` or `method`
* misses a field its selected `input_contract` mode requires
* names another mode's schema id or operation field
* carries a key or value the schema rejects

An `accepted_headers` name that is not a valid header name, repeats another name or is on the denylist fails with `FLK-0957` instead.

```json open JSON theme={null}
{
  "id": "trigger-1",
  "type": "trigger",
  "name": "Payment received",
  "position": { "x": 0, "y": 0 },
  "data": {
    "triggerType": "webhook",
    "path": "payments/received",
    "method": "POST",
    "input_contract": "open",
    "format": "json"
  }
}
```

```json open XML theme={null}
{
  "id": "trigger-1",
  "type": "trigger",
  "name": "Statement received",
  "position": { "x": 0, "y": 0 },
  "data": {
    "triggerType": "webhook",
    "path": "statements/received",
    "method": "POST",
    "input_contract": "open",
    "format": "xml"
  }
}
```

```json xsd theme={null}
{
  "id": "trigger-1",
  "type": "trigger",
  "name": "STR0008 received",
  "position": { "x": 0, "y": 0 },
  "data": {
    "triggerType": "webhook",
    "path": "spb/str0008",
    "method": "POST",
    "input_contract": "xsd",
    "xsd_schema_id": "0f9a1c3e-5b7d-4c2a-9e18-6d4b2f7a1c05"
  }
}
```

```json openapi theme={null}
{
  "id": "trigger-1",
  "type": "trigger",
  "name": "Order paid",
  "position": { "x": 0, "y": 0 },
  "data": {
    "triggerType": "webhook",
    "path": "orders/paid",
    "method": "POST",
    "input_contract": "openapi",
    "openapi_schema_id": "3c7e9b21-84af-4d6c-b0f1-2a5c8e93d7b4",
    "operation_path": "/orders",
    "operation_method": "POST"
  }
}
```

```json sync response theme={null}
{
  "id": "trigger-1",
  "type": "trigger",
  "name": "Authorize payment",
  "position": { "x": 0, "y": 0 },
  "data": {
    "triggerType": "webhook",
    "path": "payments/authorize",
    "method": "POST",
    "input_contract": "open",
    "format": "json",
    "response_mode": "sync",
    "response_view": "passthrough"
  }
}
```

Flowker registers the path with a leading slash and without a trailing one, so `payments/received`, `/payments/received` and `payments/received/` all register the same route.

## Step 5: Activate the workflow

***

**1. Create the workflow**

Send the node with the rest of your workflow to [Create a workflow](/en/reference/products/flowker/create-workflow). The workflow lands in `draft` status, and Flowker validates the trigger configuration here. A contract error answers `FLK-0934`.

**2. Activate it**

Call [Activate a workflow](/en/reference/products/flowker/activate-workflow). Activation registers the path and the method. It also resolves what the contract references. A missing XSD schema answers `FLK-0930` and a missing OpenAPI schema `FLK-0931`. An operation the document does not declare answers `FLK-0932`, and an operation with no request body answers `FLK-0933`.

```bash theme={null}
curl -s -X POST https://your-flowker-host/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/activate \
  -H "Authorization: Bearer <token>" | jq .
```

One active workflow owns a path and method pair within your tenant. Activating a second workflow on the same pair answers `FLK-0360`. [Deactivating a workflow](/en/reference/products/flowker/deactivate-workflow) releases its routes, so you can hand a path to a new version.

## Step 6: Call the route and confirm it works

***

Send the call the way your caller will:

```bash theme={null}
curl -i -X POST https://your-flowker-host/v1/webhooks/payments/received \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b" \
  -d '{ "transactionId": "txn-123", "amount": 1500.00 }'
```

A fresh `async` route whose execution is not terminal answers `202` with the receipt:

```json theme={null}
{
  "executionId": "019c96a0-10ce-75fc-a273-dc799079a99c",
  "workflowId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
  "status": "running",
  "startedAt": "2026-03-18T14:35:00Z"
}
```

A `sync` route answers with the execution's outcome, in the shape its `response_view` selects. The status it carries depends on the view and on how the execution ended. [Synchronous response mode](/en/products/flowker/integration-guide#synchronous-response-mode) holds those rules.

Three signals tell you the route worked:

* A response that started an execution carries `X-Webhook-Workflow-ID` and `X-Webhook-Execution-ID`, so you can tie a call to the workflow it reached and the execution it started.
* [Get execution results](/en/reference/products/flowker/get-execution-results) reports the step results and the final output for that `executionId`.
* The execution's input carries a `_webhook` object with the method, the path and the caller's address. Use it to confirm the workflow saw the call it should. See [Webhook metadata](/en/products/flowker/integration-guide#webhook-metadata).

A repeat delivery with the same `Idempotency-Key` returns the original execution instead of starting another one. On an `async` route, a terminal replay returns an HTTP `200` receipt with `idempotencyReplayed: true` and the original status. On a `sync` route, the status and body follow `response_view` and any terminal `responseStatusCode`: `full` and `receipt` include replay metadata, while `final_output` and a direct `passthrough` response do not guarantee it. Send a new key to run the workflow again.

The five verbs each have their own reference page: [POST](/en/reference/products/flowker/trigger-webhook), [GET](/en/reference/products/flowker/trigger-webhook-get), [PUT](/en/reference/products/flowker/trigger-webhook-put), [PATCH](/en/reference/products/flowker/trigger-webhook-patch) and [DELETE](/en/reference/products/flowker/trigger-webhook-delete).

## When a call fails

***

| Code | When it happens | What to do |
| - | - | - |
| `FLK-0934` | You save the workflow. | Compare the trigger `data` against the field table in [Step 4](#step-4-write-the-trigger-node). Check this code first when a webhook trigger does not save. |
| `FLK-0930` … `FLK-0933` | You activate the workflow. | Confirm the schema id, and for `openapi` confirm the operation path and method exist in the document and that the operation declares a request body. |
| `FLK-0360` | You activate the workflow. | Another active workflow owns that path and method. Choose another path, or deactivate the other workflow. |
| `FLK-0361` | The caller sends a request. | No route answers that path and method. Confirm the workflow is active, and that the caller uses the method the trigger declares. |
| `FLK-0501` | The caller sends a request. | The workflow resolved but is not active. Activate it. |
| `FLK-0001` | The caller sends a request. | The body of a JSON route is not valid JSON. |
| `XML_MALFORMED` | The caller sends a request. | The body of an XML route is not well-formed XML. XML routes answer with this value in the `<error><code>` element; no `FLK-` code is returned for it. |
| `XML_VALIDATION_FAILED` | The caller sends a request. | The body of an `xsd` route is well-formed XML but does not conform to the XSD document. The `<error>` document names the failing line and column. |
| `FLK-0935` | The caller sends a request. | The JSON body of an `openapi` route does not conform to the pinned operation's request body. The message identifies the first failing JSON Pointer and includes the validation detail when available. |
| `FLK-0720` | The caller sends a request. | Flowker could not validate the payload, so it rejected the call. Confirm the referenced schema exists in the registry. If it does and the call still fails, contact Lerian support. |
| `FLK-0363` | The caller sends a request. | The body is over 1 MB. Send less in one call. |

After Flowker resolves a route, JSON-route errors return `code`, `title` and `message`, while XML-route errors return an `<error>` document. The `FLK-0363` body-size check runs before route resolution, so it returns the JSON error envelope for every request. See the [Flowker error list](/en/reference/products/flowker/flowker-error-list) for every code and both shapes.

## What's next

***

> **[Integration guide](/en/products/flowker/integration-guide)**
>
> Connect the workflow to external services, and read the full synchronous-response rules.

> **[Workflow design guide](/en/products/flowker/workflow-design-guide)**
>
> Build the rest of the graph the trigger enters.


# Connecting your own API
Source: https://docs.lerian.studio/en/products/flowker/connecting-your-own-api

Upload your service's OpenAPI document to Flowker and call its operations from a workflow node. Register the document, point a provider configuration at it, and address one operation per node.

Flowker ships connectors for the services in its catalog. The service you want to call can also be your own: an internal API, a partner API, anything with a published OpenAPI document. You upload that document, and a workflow node calls its operations directly.

You do this once per document. Upload it, create one provider configuration that points at it, then address one operation from each node that calls the service.

## Before you begin

***

* Your service's OpenAPI 3.x document as a file, at most 8 MiB, declaring at least one operation.
* The credentials your service requires, and the authentication method it expects. See [Authentication](/en/products/flowker/integration-guide#authentication) for the methods Flowker supports.
* A workflow in `draft` status to edit. An active workflow is locked. Deactivate it first, then move the inactive workflow to `draft` before editing and activating it again.

> [!TIP]
>
> The Lerian Console covers the same path. In **Providers → + New Provider → Add your own API**, you select an uploaded document and set the base URL and the authentication. See [Adding a provider](/en/products/flowker/console/adding-a-provider).

## Step 1: Upload the OpenAPI document

***

**1. Send the file**

Call [Upload an OpenAPI schema](/en/reference/products/flowker/upload-openapi-schema) as `multipart/form-data` with three parts: the `file`, a `name`, and a `version`.

```bash theme={null}
curl -X POST https://your-flowker-host/v1/openapi-schemas \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@acme-kyc.json" \
  -F "name=acme-kyc" \
  -F "version=v1.0.0"
```

**2. Keep the id**

The `201` response describes what Flowker read out of the file. Its `id` is the value every later step references.

| Field | What it tells you |
| - | - |
| `id` | The document's identifier. A provider configuration and a webhook trigger point at it. |
| `name`, `version` | The pair you sent. |
| `title` | The `info.title` of the document. |
| `openapiVersion` | The `openapi` version the document declares. |
| `operationCount` | How many path-and-method operations the document declares. |
| `contentHash`, `byteSize` | The stored file's digest and size. |
| `createdBy`, `createdAt` | Who uploaded it and when. |

### What a stored document is keyed by

`name` and `version` are yours to choose, up to 255 characters each. The pair is unique in your tenant: uploading the same `name` and `version` again answers `FLK-0812`. The `id` Flowker returns is a fresh UUID for each upload. Everything else references that id, never the name or the version.

Flowker parses the file before it stores it. A file that is not an OpenAPI 3.x document, or one that declares no operation, answers `FLK-0900`. A file over 8 MiB answers `FLK-0901`.

Your uploaded documents are yours alone. A document is only visible to the tenant that uploaded it, and an id from another tenant never resolves.

## Step 2: Read the operations you can call

***

**1. List what you have stored**

[List OpenAPI schemas](/en/reference/products/flowker/list-openapi-schemas) returns your documents as metadata only, without their content. It is paginated: `limit`, `cursor`, `sortBy` and `sortOrder`, and the response carries `nextCursor` and `hasMore`.

**2. Read one document's operations**

[Get an OpenAPI schema](/en/reference/products/flowker/get-openapi-schema) returns the same metadata plus `content` (the stored file) and `operations`, one entry per operation the document declares.

| Field | What it tells you |
| - | - |
| `path` | The operation path, exactly as the document writes it, such as `/v1/checks`. |
| `method` | The operation's HTTP method. |
| `operationId` | The document's `operationId`, when it declares one. |
| `hasRequest` | Whether the operation declares a JSON request body. |
| `hasResponse` | Whether the operation declares a JSON success response. |

Copy the `path` and the `method` of the operation you want. Step 4 puts them on the node.

**3. Read one operation's field names**

[Derive an operation schema](/en/reference/products/flowker/derive-openapi-operation-schema) takes a `path` and a `method` and returns `inputSchema` for the operation's `application/json` request body and `outputSchema` for its first 2xx `application/json` response. Either field is absent when the document declares no such schema. For a non-JSON request body, use `hasBody`, `bodyRequired`, and `bodyContentType`. It also returns `params`, one entry per parameter the operation declares, each with its `name`, its `in` location and whether it is `required`.

Those are the field names you write as mapping targets and sources in Step 4. Both query parameters are required, and `method` is case-insensitive and must be one of `GET`, `PUT`, `POST`, `DELETE`, `OPTIONS`, `HEAD`, `PATCH` or `TRACE`. A missing `path` or an unrecognised `method` answers `FLK-0304`. A path and method the document does not declare answers `FLK-0902`.

## Step 3: Point a provider configuration at the document

***

Call [Create a provider configuration](/en/reference/products/flowker/create-provider-configuration) with `kind` set to `external_openapi`. That kind references your uploaded document instead of a catalog provider.

| Field | Required | Description |
| - | - | - |
| `kind` | Yes | `"external_openapi"`. You choose the kind when you create the configuration, and it stays the kind the configuration was created with. |
| `providerId` | No | Omit it. This connection targets your own document, not a catalog provider. A read of the configuration then returns the reserved id `external.openapi`. |
| `name` | Yes | A name for this connection, 1–100 characters. |
| `config.openapi_schema_id` | Yes | The `id` from [Step 1](#step-1-upload-the-openapi-document). It must name a document in your tenant. |
| `config.base_url` | No | The scheme, host and path prefix Flowker sends requests to. Omit it to use the first usable `servers` entry of the document. |
| `config.auth` | No | A `{ type, config }` authentication block, in the same shape every provider configuration uses. See [Authentication](/en/products/flowker/integration-guide#authentication) for each type and its fields. Omit it for a service that needs no authentication. |
| `config.headers` | No | Static HTTP headers for every request through this connection. It must be an object of valid, non-blank header names and string values; names must not collide case-insensitively. Values can use template references resolved at request time. |
| `allowedHosts` | No | The hosts this configuration is allowed to call. Omit it, or send an empty list, to accept any public host. |
| `allowedPrivateHosts` | No | Named private hosts this configuration is allowed to reach. Cloud metadata and link-local addresses stay blocked. |
| `schemaBindings` | No | The stored documents this configuration binds to. See [Bind the document](#bind-the-document). |
| `description` | No | Free text, up to 500 characters. |
| `metadata` | No | Your own key-value pairs. |

> [!WARNING]
>
> `config.headers` is stored with the provider configuration and can be returned by configuration reads. Never place API keys, tokens, cookies, or other secrets there. Put credentials in `config.auth`.

### Where the credential goes

A read never returns the credential the authentication type declares.

To rotate a secret later, send the new value in an update. To keep the current one, omit the field or send it blank while `auth.type` stays the same. See [Authentication](/en/products/flowker/integration-guide#authentication).

### Where the host allow-lists are set

Both allow-lists belong to this create call, and to [Update a provider configuration](/en/reference/products/flowker/update-provider-configuration) afterwards. The `allowedHosts` list names the hosts every node that calls through this configuration may reach. Flowker checks the request URL and each redirect hop against it at run time. An entry with a leading dot matches subdomains, so `.acme-kyc.example.com` matches `api.acme-kyc.example.com`. Entries are host names only, with no IP literal, no wildcard and no port.

`allowedPrivateHosts` is the companion list for a service that lives on a private network. It does not override `allowedHosts`: when `allowedHosts` is non-empty, it must also include the private host. A matching `allowedPrivateHosts` entry only lifts the private or loopback IP block. Cloud-metadata and link-local addresses remain blocked.

### Bind the document

Add a `schemaBindings` entry for the document you referenced. Each entry names one stored document. Set `type` to `"openapi"` and `schemaId` to the same id you put in `config.openapi_schema_id`. The optional `operations` array scopes the stored binding. Flowker validates that array against the document when you save the configuration.

That array does not verify what workflow nodes call, and it does not limit an `external_openapi` node at execution time. The node uses `config.openapi_schema_id`, `operation_path`, and `operation_method`.

The binding makes the document's dependants visible. With it, [List resources referencing an OpenAPI schema](/en/reference/products/flowker/list-openapi-schema-references) reports this configuration, and a delete of the document is refused while the configuration is active. See [Removing a document](#removing-a-document).

Flowker resolves every binding when you save. A `schemaId` that names no document in your tenant answers `FLK-0942`, and an `operations` entry the document does not declare answers `FLK-0943`, each naming the failing entry. A malformed entry answers `FLK-0293`. Malformed means an unknown `type`, a `schemaId` that is not a UUID, `operations` on a binding that is not `openapi`, or an operation with no path or method.

> **Example request**
>
> ```json theme={null}
> POST /v1/provider-configurations
>
> {
>   "name": "Acme KYC production",
>   "description": "Production KYC checks",
>   "kind": "external_openapi",
>   "config": {
>     "openapi_schema_id": "018f3e2a-1c4d-7b9e-a1b2-c3d4e5f6a7b8",
>     "base_url": "https://api.acme-kyc.example.com",
>     "auth": {
>       "type": "api_key",
>       "config": {
>         "key": "sk-live-xxx",
>         "header_name": "X-API-Key",
>         "location": "header"
>       }
>     }
>   },
>   "allowedHosts": ["api.acme-kyc.example.com"],
>   "schemaBindings": [
>     {
>       "type": "openapi",
>       "schemaId": "018f3e2a-1c4d-7b9e-a1b2-c3d4e5f6a7b8",
>       "operations": [
>         { "path": "/v1/checks", "method": "POST" },
>         { "path": "/v1/checks/{checkId}", "method": "GET" }
>       ]
>     }
>   ]
> }
> ```
>
> The response returns the new configuration's `id`. Keep it. [Step 4](#step-4-address-an-operation-from-a-workflow-node) puts it in the `providerConfigId` of every node that calls this service.

Flowker checks the configuration before it stores it. A `config` with no `openapi_schema_id`, or one whose value is not a UUID, answers `FLK-0946`. An id that names no document in your tenant answers `FLK-0947`. A `config.auth` block Flowker cannot read (an unknown type, or a type missing one of its required fields) answers `FLK-0948`. A malformed `config.headers` block answers `FLK-0955`.

Flowker does not call your target API here.

## Step 4: Address an operation from a workflow node

***

An executor node names one operation of the document with two fields in its `data`, alongside the `providerConfigId` of the configuration from Step 3.

| Field | Required | Description |
| - | - | - |
| `providerConfigId` | Yes | The UUID of the provider configuration that points at the document. |
| `operation_path` | To run | The operation path, exactly as the document writes it, including its `{...}` parameter templates. |
| `operation_method` | To run | The operation's HTTP method. Matching is case-insensitive. |
| `inputMapping` | No | Moves values from the workflow context into the request. Each `target` is a path in the operation's request body, or a parameter name. |
| `outputMapping` | No | Moves values out of the response for later nodes to read. |

Do not send `executorId` on such a node. Flowker resolves the provider configuration, recognises the kind, and fills the field in for you before it validates the workflow. The save path can persist a node missing either operation field, but execution then fails with `FLK-0950` before Flowker sends a request. Every other node field behaves as [Reference the provider configuration from a workflow node](/en/products/flowker/integration-guide#step-3-reference-the-provider-configuration-from-a-workflow-node) describes.

### How the request is assembled

Flowker reads the operation out of the stored document at run time and builds the request from it:

* **The destination** is `config.base_url` when the configuration sets it, otherwise the first usable `servers` entry of the document, joined with `operation_path`.
* **A `path` parameter** takes its value from the node's resolved data first, and from the request body second. Every `path` parameter needs a value.
* **A `query` or `header` parameter** resolves the same way. An optional parameter with no value is left out. A required parameter with no value fails the node before any request leaves Flowker, with `FLK-0954`. A static `config.headers` value or the configured authentication can satisfy a required header parameter.
* **The request body** with the default `request_format.type` (`json`) is what your `inputMapping` builds. With `xml_converted`, Flowker serializes that mapped object as XML. With `xml_passthrough`, Flowker ignores the mapping and forwards the webhook trigger's original XML bytes. Write each `target` exactly as the operation's request schema names it. There is no wrapper object and no prefix to add. [Working with request and response data](/en/products/flowker/working-with-request-and-response-data) covers mappings and transformations in full.

> **Example: a workflow that calls two operations of the document**
>
> ```json theme={null}
> POST /v1/workflows
>
> {
>   "name": "kyc-check",
>   "description": "Opens a KYC check on the Acme API and records the result.",
>   "nodes": [
>     {
>       "id": "kyc-received",
>       "type": "trigger",
>       "name": "KYC request received",
>       "position": { "x": 0, "y": 0 },
>       "data": {
>         "triggerType": "webhook",
>         "path": "kyc/requested",
>         "method": "POST",
>         "input_contract": "open",
>         "format": "json"
>       }
>     },
>     {
>       "id": "open-check",
>       "type": "executor",
>       "name": "Open KYC check",
>       "position": { "x": 200, "y": 0 },
>       "data": {
>         "providerConfigId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
>         "operation_path": "/v1/checks",
>         "operation_method": "POST",
>         "inputMapping": [
>           { "source": "workflow.documentNumber", "target": "documentNumber" },
>           { "source": "workflow.fullName", "target": "fullName" }
>         ],
>         "outputMapping": [
>           { "source": "body.checkId", "target": "checkId" },
>           { "source": "body.status", "target": "status" }
>         ]
>       }
>     },
>     {
>       "id": "record-check",
>       "type": "action",
>       "name": "Record the check",
>       "position": { "x": 400, "y": 0 },
>       "data": {
>         "actionType": "set_output",
>         "output": {
>           "checkId": "${open-check.checkId}",
>           "status": "${open-check.status}"
>         }
>       }
>     }
>   ],
>   "edges": [
>     { "id": "e1", "source": "kyc-received", "target": "open-check" },
>     { "id": "e2", "source": "open-check", "target": "record-check" }
>   ]
> }
> ```
>
> The `open-check` node sends `POST https://api.acme-kyc.example.com/v1/checks` with the body its `inputMapping` built. Its `outputMapping` lifts two response fields, so the next node reads `${open-check.checkId}`.
>
> A node that calls `GET /v1/checks/{checkId}` instead reads the parameter from the same node scope. Map a value onto `checkId`, and Flowker substitutes it into the path.

> [!TIP]
>
> A webhook trigger can validate the inbound payload against one operation of the same document. Set `input_contract` to `"openapi"` and give the trigger `openapi_schema_id`, `operation_path` and `operation_method`. See [Configuring a webhook trigger](/en/products/flowker/configuring-a-webhook-trigger).

## Step 5: Run it and confirm it worked

***

**1. Activate the workflow**

Call [Activate a workflow](/en/reference/products/flowker/activate-workflow). Activation registers the webhook route and resolves what the trigger's contract references.

**2. Run it**

Call [Execute a workflow](/en/reference/products/flowker/execute-workflow) with a fresh `Idempotency-Key` header, or send a request to the webhook route.

**3. Read the step results**

A node that reached your service records the response under its own id. With an `outputMapping`, the mapped names sit directly under that id: `open-check.checkId`. With no `outputMapping`, the node's output keeps the response envelope, so the response body sits one level down, under `body`.

## Publishing a new version of your document

***

A stored document does not change. To ship a revision, upload the file again under a new `version`. That gives you a second stored document with its own `id`.

Uploading a new document does not change existing configurations. However, each executor node reads its provider configuration when it runs. Updating `config.openapi_schema_id` can change the document used by later nodes of an in-progress execution, so coordinate the cutover.

Send the provider configuration's `config` with the new id through [Update a provider configuration](/en/reference/products/flowker/update-provider-configuration). The `config` field replaces the stored map rather than merging into it. Include any configured `base_url` and `auth` values that you need to retain in the same call. Flowker revalidates the new id against your tenant, and answers `FLK-0947` when it does not resolve.

Check [List resources referencing an OpenAPI schema](/en/reference/products/flowker/list-openapi-schema-references) on the previous document before you retire it. The response is a display list, not a complete inventory: it returns up to 100 entries in each of its two groups. An active provider configuration beyond that display limit still blocks deletion.

## Spec versions for the services in the catalog

***

Flowker's own catalog services resolve against a separate, shared registry of published specs. Three operations manage it. They never touch a document you uploaded in Step 1.

| Operation | What it does |
| - | - |
| [List OpenAPI spec versions](/en/reference/products/flowker/list-openapi-spec-versions) | Lists the published versions of a service's spec in `versions`, and reports the one your tenant has pinned in `pinnedVersion`. `pinnedVersion` is empty when your tenant has pinned none. |
| [Pin an OpenAPI spec version](/en/reference/products/flowker/pin-openapi-spec-version) | Selects the version your tenant resolves against for that service. It is idempotent: pinning again replaces the version in place. A request missing the service or the version answers `FLK-0801`. |
| [Upload an OpenAPI spec version](/en/reference/products/flowker/upload-openapi-spec-version) | Publishes one version of a service's spec, for every tenant. Versions are immutable: a `service` and `version` pair that already exists answers `FLK-0803`. The caller needs the `create` permission on the `catalog` resource. |

The pin is per tenant. Publishing a version changes nothing for a tenant until that tenant pins it. A new upload therefore never moves a running workflow onto a different spec. Flowker reads your pinned version when it reports that service's executor schemas in the catalog, so [Get a catalog executor](/en/reference/products/flowker/get-catalog-executor) describes the version you chose.

## Removing a document

***

**1. Check what would break**

[List resources referencing an OpenAPI schema](/en/reference/products/flowker/list-openapi-schema-references) returns two groups, `providerConfigurations` and `workflows`. Both are always present, each carries up to 100 entries, and each entry carries an `id`, a `name` and a `status`. It is a display list, not a complete inventory. An active provider configuration beyond the display limit still blocks the delete, while an inactive entry only warns.

**2. Delete it**

[Delete an OpenAPI schema](/en/reference/products/flowker/delete-openapi-schema) answers by what still references the document:

| Outcome | What it means |
| - | - |
| `204 No Content` | Nothing referenced the document. It is gone. |
| `200 OK` | Only inactive referrers held it: a draft or inactive workflow, or a disabled provider configuration. The document is gone, and the body shows its warnings under `warnings` and `providerConfigurationWarnings`; provider-configuration display details can be capped at 100. |
| `409` with `FLK-0945` | An active provider configuration binds the document. Nothing is deleted, and the body shows the referring provider configurations and workflows; provider-configuration display details can be capped at 100. |
| `409` with `FLK-0936` | An active workflow references the document from a webhook trigger. Nothing is deleted. |

To clear a block, disable the provider configuration or deactivate the active workflow. Move an inactive workflow to `draft` only if you need to edit it.

## What goes wrong

***

| Symptom | Cause | Fix |
| - | - | - |
| The upload is refused although the file opens in your editor. | The document declares an `openapi` version outside the 3.x series, or declares no operation. | Check the `openapi` field and the `paths` object, then upload again. |
| The create call reports the schema id is unknown. | The id belongs to another tenant, or the document was deleted. | Call [List OpenAPI schemas](/en/reference/products/flowker/list-openapi-schemas) and take the id from the response. |
| The workflow is refused with `FLK-0150`. | The node's `providerConfigId` names a configuration that does not exist, or one that is disabled. | Confirm the UUID on the node, and enable the configuration with [Enable provider configuration](/en/reference/products/flowker/enable-provider-configuration). |
| The node fails without reaching your service. | The operation is absent from the document, or no base URL resolves. | Compare `operation_path` and `operation_method` with the `operations` list from Step 2, and set `config.base_url` when the document declares no `servers` entry. |
| The service answers that a required field is missing. | A mapping `target` does not match the operation's request schema. | Read `inputSchema` from [Derive an operation schema](/en/reference/products/flowker/derive-openapi-operation-schema) and write each target exactly as it appears there. |
| The service is never reached and the step reports a rejected URL. | `allowedHosts` does not cover the destination host. | Add the host to `allowedHosts` on the provider configuration. |

| Error code | When | What it means |
| - | - | - |
| `FLK-0150` | Create or activate the workflow | The node's `providerConfigId` names a configuration that does not exist, or one that is not active. |
| `FLK-0812` | Upload | A document with this `name` and `version` already exists. Choose another version. |
| `FLK-0900` | Upload | The file does not parse as an OpenAPI 3.x document, or it declares no operation. |
| `FLK-0901` | Upload | The file is over 8 MiB. |
| `FLK-0811` | Read, derive, delete | The document id does not resolve for your tenant. |
| `FLK-0902` | Derive an operation schema | The document declares no operation with that path and method. |
| `FLK-0304` | Derive an operation schema | The `path` query parameter is missing, or `method` is missing or is not an HTTP method. |
| `FLK-0946` | Create or update the provider configuration | `config.openapi_schema_id` is missing, or is not a UUID. |
| `FLK-0947` | Create or update the provider configuration, and run time | The referenced document does not exist in your tenant. |
| `FLK-0948` | Create or update the provider configuration | The `config.auth` block is malformed. |
| `FLK-0293` | Create or update the provider configuration | A `schemaBindings` entry is malformed. |
| `FLK-0942` | Create or update the provider configuration | A `schemaBindings` entry names a document that does not exist in your tenant. |
| `FLK-0943` | Create or update the provider configuration | A `schemaBindings` entry restricts to an operation the document does not declare. |
| `FLK-0949` | Run time | Neither `config.base_url` nor a usable `servers` entry resolves a base URL. The node fails without calling the service. |
| `FLK-0950` | Run time | The bound operation is absent from the document, or a `path` parameter found no value. The node fails without calling the service. |
| `FLK-0954` | Run time | A required `header` or `query` parameter found no value. The node fails without calling the service. |
| `FLK-0955` | Create or update the provider configuration | The optional `config.headers` block is malformed. It must map valid, non-blank header names to string values without case-insensitive duplicates. |
| `FLK-0945` | Delete the document | An active provider configuration binds it. |
| `FLK-0936` | Delete the document | An active workflow references it from a webhook trigger. |
| `FLK-0803` | Upload a spec version | That service and version pair is already published. Versions are immutable. |
| `FLK-0801` | Pin a spec version | The request is missing the service or the version. |

See the [Flowker error list](/en/reference/products/flowker/flowker-error-list) for every code.

## What's next

***

> **[Working with request and response data](/en/products/flowker/working-with-request-and-response-data)**
>
> Map values into the operation's request body and read its response back out.

> **[Configuring a webhook trigger](/en/products/flowker/configuring-a-webhook-trigger)**
>
> Validate an inbound payload against one operation of the same document.

> **[Integration guide](/en/products/flowker/integration-guide)**
>
> Set the authentication, the retries and the circuit breaker every provider configuration shares.

> **[OpenAPI schemas API](/en/reference/products/flowker/list-openapi-schemas)**
>
> Explore the schema registry endpoints.


# Activating and deactivating a workflow
Source: https://docs.lerian.studio/en/products/flowker/console/activating-deactivating-workflow

Control whether a workflow is live for execution by activating, deactivating, or moving it back to draft status as your needs change.

You control whether a workflow is available for execution. You can activate a workflow, deactivate it, or move it back to draft status.

## Activating a workflow

***

Activating a workflow makes it live and available for execution. You can activate only **Draft** workflows. To activate an **Inactive** workflow again, first move it back to Draft.

To activate a workflow:

**Step 1**

On the **Workflows** page, find the workflow you want to activate.

**Step 2**

Click the three dots () on the **Actions** column and select **Activate**.

**Step 3**

The workflow status will change to **Active**.

> [!NOTE]
>
> Make sure the workflow has a complete configuration before you activate it. Active workflows will respond to their configured triggers and start executions automatically.

## Deactivating a workflow

***

Deactivating a workflow stops it from responding to triggers. It will not start new executions, but any in-progress executions will continue to completion.

To deactivate a workflow:

**Step 1**

On the **Workflows** page, find the active workflow you want to deactivate.

**Step 2**

Click the three dots () on the **Actions** column and select **Deactivate**.

**Step 3**

The workflow status will change to **Inactive**.

## Moving a workflow to Draft

***

Moving a workflow back to **Draft** status allows you to make significant changes before reactivating it.

> [!NOTE]
>
> The **Move to Draft** option is only available for workflows in the **Inactive** state. Workflows in **Draft** or **Active** states won’t show this option in the Actions menu.

To move a workflow to draft:

**Step 1**

On the **Workflows** page, find the workflow you want to move to draft.

**Step 2**

Click the three dots () on the **Actions** column and select **Move to Draft**.

**Step 3**

The workflow status will change to **Draft**.

> [!TIP]
>
> To edit an active workflow, open it and click **Edit**. The Console moves it to Draft for you. Save your changes and activate it again. You can also **Clone** it to iterate without touching the live version.


# Adding a provider
Source: https://docs.lerian.studio/en/products/flowker/console/adding-a-provider

Add a new provider in the Flowker Console so your workflows can connect to external systems. Set a name, choose a provider type, and configure it.

To use external services in your workflows, you need to configure at least one provider. A provider is a connection to an external system that Flowker can interact with.

To add a provider:

**Step 1**

Go to the **Providers** page and click the **+ New Provider** button.

**Step 2**

The **Add Provider** form will open. Fill in the fields:

* **Name**: a descriptive name to identify this provider configuration (e.g., `production-payment-gateway`).
* **Description** (optional): a description about the provider and what it does.
* **How do you want to connect?** Choose the connection type:
  * **Connect a Lerian provider**: select a provider from the Lerian catalog. Fields for the connection appear after you select it. The platform provisions the credentials of the Midaz ledger, CRM, Fees and Identity providers. Tracer and Auth need their authentication settings. The **HTTP** provider requires **Allowed hosts**.
  * **Add your own API**: connect an external API from its OpenAPI spec. Select an uploaded OpenAPI spec, and optionally set a **Base URL** (leave it blank to use the spec's server URL) and the authentication settings. [Connecting your own API](/en/products/flowker/connecting-your-own-api) covers uploading the spec and calling its operations from a node.

**Step 3**

Review the configuration and click **Add Provider** to save the provider.

> [!NOTE]
>
> The connection type is chosen at creation and cannot be changed later. Editing a provider keeps its original type.

After creation, the new provider appears in the providers list with status `Active`. Workflow nodes can then reference it.


# Canvas editor
Source: https://docs.lerian.studio/en/products/flowker/console/canvas-editor

Design workflows on the Flowker Canvas by dragging Trigger, Executor Call, Conditional, and Action nodes, then connecting and configuring each one.

The **Workflow Canvas** is a visual drag-and-drop editor for designing workflows in Flowker. It is an interactive surface where you can add, connect, and configure nodes to define the execution flow of your automated processes.

## Accessing the Canvas

***

The canvas opens when you create or open a workflow. Navigate to **Flowker → Workflows**, then create a new workflow or click the name of an existing one. A workflow that is not in Draft opens read-only until you click **Edit**. See [Editing a workflow](/en/products/flowker/console/editing-a-workflow).

## Canvas basics

***

The canvas has the following interactions:

* **Pan**: click and drag on the canvas background to move around.
* **Zoom**: use the scroll wheel or pinch gesture to zoom in and out.
* **Select**: click a node to select it.
* **Configure**: double-click a node to open its configuration panel on the right side.
* **Connect**: drag from a node's output handle to another node's input handle to create a connection.
* **Delete**: select a node or connection and press Delete or Backspace. You can also click the trash icon on a node or the × on a connection.

## Node types

***

Flowker workflows have four node types.

### Trigger Node

The **Trigger Node** defines the event that starts the workflow. An active workflow must have at least one trigger node. A draft workflow may be empty or omit a trigger while you design it. Node-level save validation still applies.

When you double-click a trigger node, the **Configure Trigger** panel opens with the following fields:

| Field | Description |
| - | - |
| **Name** | A descriptive label for the trigger (e.g., "Webhook Trigger"). |
| **Trigger** | A dropdown to select which trigger type to use. Options are loaded dynamically from the Flowker catalog. |

After selecting a trigger type, additional configuration fields may appear based on the trigger's schema. For the webhook trigger, those fields are the path, the method, the input contract, the response mode, the response view and the accepted headers. See [Configuring a webhook trigger](/en/products/flowker/configuring-a-webhook-trigger) for what each contract accepts. For the schedule trigger, they are the cron expression, the timezone, the enabled flag and the input data each run starts with. See [Running a workflow on a schedule](/en/products/flowker/running-a-workflow-on-a-schedule).

| Trigger | Description |
| - | - |
| **Webhook** | The workflow starts when Flowker receives an external HTTP request at the configured path and method. |
| **Schedule** | The workflow starts on a time-based schedule defined by a standard 5-field cron expression (minimum granularity of 1 minute), with an optional IANA timezone (defaults to UTC). |

### Executor Call Node

**Executor Call Nodes** perform specific operations by calling executors registered in the Flowker catalog. Each executor is a pre-built integration with Lerian products or external services.

When you double-click an executor call node, the **Configure Executor Call** panel opens. Its first two fields form a cascade: the provider configuration you pick first decides which executors the second field offers.

| Field | Description |
| - | - |
| **Provider** | The first field, and the one that sets the connection. It lists the provider configurations saved on the [Providers](/en/products/flowker/console/providers-overview) page, each shown by its name with its catalog provider beside it. Picking one binds the step to that connection (its base URL and credentials) and scopes the **Executor** dropdown below to the same provider. When no provider configuration exists yet, the dropdown shows **No connections yet — create one in Flowker → Providers**. A workflow does not save while an executor call node has no provider configuration. |
| **Executor** | The second field. It lists the catalog executors of the provider the selected configuration belongs to, and stays disabled until you pick a **Provider**, showing **Select a provider first**. When the selected configuration was built from your own OpenAPI spec, this field is replaced by **Operation**, which lists the operations of that spec. See [Connecting your own API](/en/products/flowker/connecting-your-own-api). |
| **Name** | Auto-filled with the executor's category after selection, but editable. |

After selecting an executor, additional configuration fields appear based on the executor's schema (e.g., data mapping parameters).

Available executors include:

| Executor | Description |
| - | - |
| **Create Account** | Creates a new account in Midaz. |
| **Create Transaction** | Creates a new transaction in Midaz. |
| **Get Account** | Retrieves account details from Midaz. |
| **Get Account Balance** | Retrieves the balance for a specific account. |
| **List Validations** | Lists transaction validations from Tracer. |
| **Validate Transaction** | Validates a transaction through Tracer's risk rules. |

> [!NOTE]
>
> Executors come from the Flowker catalog. The table is illustrative. Inspect the running catalog for the executors available to your deployment.

If the configuration is invalid, an error message will appear in the panel.

### Conditional Node

**Conditional Nodes** branch the workflow based on conditions evaluated at runtime.

A conditional node holds a structured condition made of **cases**. Each case has one or more rules and routes the execution to its own outgoing path when it matches. The conditional node evaluates cases in order, and the first matching case wins. An optional **default** path catches executions that match no case. So a conditional node has one outgoing connection per case, plus the default path when enabled.

When you double-click a conditional node, its configuration panel opens with the visual **condition builder**, where you define the cases and the rules inside each case (the value being tested, a comparison operator, and the value to compare against).

> [!NOTE]
>
> Workflows saved with a legacy free-text condition expression keep the original **true**/**false** output paths. New conditionals use the condition builder.

> [!TIP]
>
> Use descriptive case labels and node names (e.g., "High Value Check") to keep the workflow readable.

### Action Node

**Action Nodes** perform a workflow-level action without calling an external service. The available action type is `set_output`, which sets the execution's final output. It is useful as the terminal step of a workflow, especially with [synchronous webhook responses](/en/products/flowker/integration-guide#synchronous-response-mode).

Output values support `${...}` references resolved against the workflow context (for example, `${workflow.<field>}` for the trigger payload, or `${execution.id}`). For workflows triggered by a synchronous webhook, a `set_output` node can also carry a `responseStatusCode` (integer, `200`–`599`) to override the HTTP status of the sync response.

## Configuring nodes

***

To configure any node, double-click it on the canvas. A configuration panel slides in from the right side.

Each node type has its own panel layout:

* **Trigger**: Name field + trigger type dropdown + trigger-specific schema fields.
* **Executor Call**: Provider dropdown + Executor dropdown + auto-filled name + executor-specific schema fields.
* **Conditional**: Name field + the visual condition builder (cases and rules).
* **Action**: Name field + the `set_output` output configuration.

After filling in the configuration, click **Save & Close** to apply the changes and return to the canvas.

## Connections

***

Connections define the order in which nodes execute. Each connection forms a directed edge from one node's output to another node's input.

* A node can have multiple outgoing connections (e.g., conditional nodes have one per case, plus the default path when enabled).
* A node can receive input from multiple sources.
* Circular connections (loops) are not supported.

> [!TIP]
>
> Keep your workflows readable by arranging nodes from left to right or top to bottom. Use descriptive node names to make it clear what each step does.


# Cloning a workflow
Source: https://docs.lerian.studio/en/products/flowker/console/cloning-a-workflow

Clone a workflow in the Flowker Console to duplicate its nodes, connections, and configuration into a new Draft copy you can safely customize.

Cloning creates a duplicate of an existing workflow, including all its nodes, connections, and configurations. The cloned workflow starts in **Draft** status so you can customize it before activating.

To clone a workflow:

**Step 1**

On the **Workflows** page, find the workflow you want to clone.

**Step 2**

Click the three dots () on the **Actions** column and select **Clone**.

**Step 3**

The copy takes the original name followed by **(Copy)** and appears in the workflows list with **Draft** status. Workflow names are unique, so rename the copy before you clone the same workflow again.

After cloning, you can [edit the workflow](/en/products/flowker/console/editing-a-workflow) to update its name, modify nodes, and adjust configurations as needed.

> [!TIP]
>
> Cloning is useful when you want to create a variation of an existing workflow without modifying the original. For example, you can clone a workflow and adjust it for a different provider or data source.


# Create a workflow from scratch
Source: https://docs.lerian.studio/en/products/flowker/console/create-from-scratch

Create a Flowker workflow from a blank canvas by adding trigger, executor, conditional, and action nodes, then connecting them to shape the flow.

You can create a new workflow from scratch using the visual canvas editor. The workflow starts in **Draft** status. You must activate it before a trigger can start it.

To create a workflow:

**Step 1**

Go to the **Workflows** page and click the **+ New Workflow** button.

**Step 2**

The **Workflow Templates** modal will open. In the left sidebar, select **Blank Workflow** and click the **Create Blank Workflow** button to start from an empty canvas.

**Step 3**

An empty canvas opens. Flowker creates the workflow when you save it.

**Step 4**

Enter a **name** for the workflow in the **Workflow name...** field. You cannot save without a name.

**Step 5**

Build your workflow by adding nodes to the canvas. You can add the following node types:

* **Trigger**: defines the event that starts the workflow.
* **Executor**: performs a specific operation (e.g., API call, data transformation).
* **Conditional**: branches the workflow based on conditions organized in cases.
* **Action**: performs a workflow-level action, such as setting the execution's final output (`set_output`).

> [!TIP]
>
> To add a node, drag its card from the **Steps** panel to the canvas, double-click the card, or click the plus (+) that appears when you hover over it.

**Step 6**

Connect the nodes by dragging from one node's output to another node's input to define the execution flow.

**Step 7**

Configure each node by double-clicking it and filling in the required parameters in the side panel.

**Step 8**

Click **Save** to save your workflow.

For a complete reference on canvas interactions, node configuration fields, and available triggers and executors, see [Workflow Canvas](/en/products/flowker/console/canvas-editor).

The workflow will be created in **Draft** status. When your workflow is ready, you can [activate it](/en/products/flowker/console/activating-deactivating-workflow) to make it available for execution.


# Creating Workflows
Source: https://docs.lerian.studio/en/products/flowker/console/creating-workflows

Start a new Flowker workflow from the + New Workflow button and choose Blank Workflow to open a fresh canvas.

## How it works

***

When you click **+ New Workflow**, the **Workflow Templates** modal opens. Select **Blank Workflow** to get an empty canvas where you define every trigger, executor, and conditional node yourself.

Every new workflow starts in **Draft** status. You can design, test, and iterate before [activating it](/en/products/flowker/console/activating-deactivating-workflow) for production use.

## Next step

***

> **[Create from scratch](/en/products/flowker/console/create-from-scratch)**
>
> Start with a blank canvas and build your workflow node by node.


# Deleting a provider
Source: https://docs.lerian.studio/en/products/flowker/console/deleting-a-provider

Delete an unused provider configuration from the Flowker Console using the Actions menu, and see what happens to workflows that still reference it.

To remove a provider configuration from Lerian Console:

**Step 1**

On the **Providers** page, find the provider you want to delete.

**Step 2**

Click the three dots () on the **Actions** column and select **Delete**.

**Step 3**

A **Confirm Deletion** dialog will appear with the provider name. Confirm the deletion.

> [!CAUTION]
>
> Deleting a provider configuration cannot be undone. Any workflows that reference this provider will fail if they attempt to use it. Make sure no active workflows depend on the provider before deleting it.

> [!TIP]
>
> Before deleting a provider, check if any workflows reference it. You can update those workflows to use a different provider configuration first.


# Deleting a workflow
Source: https://docs.lerian.studio/en/products/flowker/console/deleting-a-workflow

Delete a workflow from the Flowker Console using the Actions menu, confirm the removal, and understand how in-progress runs and history are handled.

To remove a workflow from Lerian Console:

**Step 1**

On the **Workflows** page, find the workflow you want to delete.

**Step 2**

Click the three dots () on the **Actions** column and select **Delete**.

**Step 3**

A **Confirm Deletion** dialog will appear with the workflow name. Confirm the deletion.

> [!CAUTION]
>
> Deleting a workflow cannot be undone. The deletion permanently removes all associated configuration, nodes, and connections. After deletion, Flowker attempts to mark pending or running executions as failed. This best-effort cleanup may not update every in-progress execution. Past execution records for the workflow will remain available in the **Executions** page.

> [!NOTE]
>
> You can delete only **Draft** and **Inactive** workflows. Deactivate an **Active** workflow first. Otherwise, the Console shows **Active workflows cannot be deleted. Deactivate it first.**


# Editing a provider
Source: https://docs.lerian.studio/en/products/flowker/console/editing-a-provider

Edit a provider in the Flowker Console to update its name, description, or connection parameters, and see how the changes apply to running workflows.

You can update an existing provider configuration to change its connection parameters, credentials, or name.

To edit a provider:

**Step 1**

On the **Providers** page, find the provider you want to edit.

**Step 2**

Click the three dots () on the **Actions** column and select **Details**.

**Step 3**

The provider panel will open with the current configuration. Update the fields as needed:

* **Name**: the identifier for the provider.
* **Description** (optional): a description about the provider and what it does.
* **Provider-specific fields**: the connection parameters for the provider type (e.g., API URL, credentials).

**Step 4**

Click **Save** to apply your changes.

> [!NOTE]
>
> Updating a provider configuration affects all workflows that reference it. Each executor call node reads the configuration when it executes. So runs already in progress pick up the new settings for nodes that haven't executed yet.

> [!NOTE]
>
> You select the provider type at creation. You cannot change it when you edit the provider. To switch to a different provider, create a new configuration.


# Editing a workflow
Source: https://docs.lerian.studio/en/products/flowker/console/editing-a-workflow

Edit a workflow in the Flowker Console to rename it, add or remove nodes, adjust connections, and reconfigure parameters in the canvas editor.

You can edit an existing workflow to update its name, modify its nodes and connections, or reconfigure individual node parameters.

You edit a workflow in **Draft** status. A Draft workflow opens ready to edit. An **Active** or **Inactive** workflow opens read-only, with an **Edit** button. To iterate without touching the live version, [clone](/en/products/flowker/console/cloning-a-workflow) it instead.

To edit a workflow:

**Step 1**

On the **Workflows** page, click the workflow name, or click the three dots () on the **Actions** column and select **Details**.

**Step 2**

The visual canvas editor opens with the workflow's current configuration. If the workflow is not in Draft, click **Edit** and confirm in the **Edit workflow** dialog. The Console moves the workflow to Draft, and deactivates it first when it is Active.

**Step 3**

Make your changes:

* **Update the name**: edit the **Workflow name...** field in the header.
* **Add nodes**: drag nodes onto the canvas from the **Steps** panel.
* **Remove nodes**: select a node and press Delete, or click its trash icon.
* **Modify connections**: drag to create a connection, or click the × on a connection to remove it.
* **Configure nodes**: double-click any node to open its configuration panel and update parameters.

**Step 4**

Click **Save** to apply your changes. When the workflow is ready to run, click **Activate**.

> [!NOTE]
>
> If the workflow was Active and you leave the editor without saving, the **Your workflow is in Draft** dialog offers **Reactivate** or **Keep in Draft**. A Draft workflow does not run.

> [!NOTE]
>
> Your changes take effect on future executions. They do not affect runs already in progress.

> [!TIP]
>
> For more details about the canvas editor and its node types, see [Workflow Canvas](/en/products/flowker/console/canvas-editor).


# Executions overview
Source: https://docs.lerian.studio/en/products/flowker/console/executions-overview

Use the Executions page in the Flowker Console to browse all workflow runs, filter by workflow or status, and track Pending, Running, Completed, or Failed runs.

Executions are individual runs of your workflows. The Executions page lists every workflow execution. Use it to monitor progress, investigate failures, and review results. You manage executions in the [Lerian Console](/en/platform/console/about-lerian-console).

## Accessing the Executions page

***

To open the **Executions** page, click **Executions** from the left-side menu on the **Flowker** page.

The page displays all executions in a data table, with the following columns:

* **Workflow**: the name of the workflow in this run (or `Deleted workflow` when the workflow no longer exists).
* **Execution ID**: unique identifier of the execution.
* **Status**: the current state of the execution.
* **Started At**: the date and time of the trigger.
* **Duration**: how long the execution took to complete.
* **Actions**: action menu to view execution details or go to its workflow.

Use the fields above the table to filter executions by status or by workflow name. The status filter searches all executions. The workflow name filter searches the executions on the current page.

## Execution statuses

***

Each execution progresses through a lifecycle indicated by its status:

| Status | Description |
| - | - |
| **Pending** | The execution has been triggered and is waiting to start processing. |
| **Running** | The execution is currently in progress. |
| **Completed** | The execution finished successfully. |
| **Failed** | The execution encountered an error and did not complete successfully. |

## Related pages

***

> **[View execution details](/en/products/flowker/console/viewing-execution-details)**


# Flowker Dashboard
Source: https://docs.lerian.studio/en/products/flowker/console/flowker-dashboard

View an at-a-glance summary of workflow activity, key metrics, recent workflows, and execution history from the Flowker home page.

The **Dashboard** is the home page of the Flowker module. It shows your workflow activity: key metrics, recent workflows, and recent execution history.

## Accessing the Dashboard

***

Navigate to **Flowker → Dashboard** in the left sidebar, or select Flowker from the product launcher. The Dashboard opens by default.

## Stat cards

***

A row of four summary cards appears at the top of the page:

| Card | Description |
| - | - |
| **Total Workflows** | Total number of workflows, across all statuses. |
| **Active Workflows** | Total number of workflows ready for execution. |
| **Completed** | Number of executions that started in the last 24 hours and completed successfully. |
| **Failed** | Number of executions that started in the last 24 hours and ended in failure. |

## Recent Workflows

***

Below the stat cards, a list displays the five most recently created workflows. Each entry shows:

* **Workflow name**: the name assigned to the workflow.
* **Status**: the current lifecycle state of the workflow: `Draft`, `Active`, or `Inactive`.
* **Last change**: how long ago the workflow last changed.

Click any workflow to open it in the canvas editor.

## Recent Executions

***

A second list displays the five most recent workflow executions. Each entry shows:

* **Execution ID**: the unique identifier of the execution.
* **Status**: the current state of the execution: `Pending`, `Running`, `Completed`, or `Failed`.
* **Start time**: how long ago the execution started, or **Pending** before it starts.

Click any execution to go to the **Executions** page, where you can open its detailed results.


# Flowker module overview
Source: https://docs.lerian.studio/en/products/flowker/console/flowker-module

Design visual workflows, configure provider integrations, run automated processes, and monitor executions through the Flowker module.

**Flowker** is a product module in the Lerian Console for workflow automation. It lets you design visual workflows, configure provider integrations, execute automated processes, and monitor execution history, all through a visual interface.

Use the Console to create, edit, and manage workflows, configure providers, and monitor executions.

> [!WARNING]
>
> Flowker is only available if you've acquired the Flowker product. [Get in touch with our team](https://lerian.studio/contact) to learn more.

## Accessing Flowker

***

To access Flowker, select it from the product launcher in Lerian Console.

## Dashboard

***

The **Dashboard** page provides an at-a-glance overview of your workflow activity. Use it to monitor key metrics, review recent workflows, and track recent executions.

> **[Flowker Dashboard](/en/products/flowker/console/flowker-dashboard)**
>
> See a detailed walkthrough of the Dashboard page, including stat cards, recent workflows, and recent executions.

## Sidebar

***

The left sidebar allows you to navigate between Flowker pages: **Dashboard**, **Workflows**, **Executions**, **Providers**, and [**Schema Registry**](/en/products/flowker/console/schema-registry).

You can return to the product launcher by clicking **Back to products** in the sidebar.

## Available pages

***

### Workflows

> **[Workflows](/en/products/flowker/console/workflows-overview)**
>
> Create, edit, and manage automated workflows using a visual canvas editor with configurable nodes and connections.

> **[Workflow Canvas](/en/products/flowker/console/canvas-editor)**
>
> Learn about the visual canvas editor and its node types: triggers, executor calls, conditionals, and actions.

### Executions

> **[Executions](/en/products/flowker/console/executions-overview)**
>
> View and monitor the execution history of your workflows, including status tracking and detailed results.

### Providers

> **[Providers](/en/products/flowker/console/providers-overview)**
>
> Configure and manage provider integrations used by your workflows to connect to external services.


# Managing workflows
Source: https://docs.lerian.studio/en/products/flowker/console/managing-workflows

Manage Flowker workflows from the Console: edit nodes, clone for reuse, control the Draft, Active, and Inactive lifecycle, or delete when no longer needed.

Once a workflow exists, you can modify its structure, manage its lifecycle, duplicate it for reuse, or remove it entirely. All maintenance actions are available from the **Actions** menu () on each workflow row in the Workflows page.

## Workflow lifecycle

***

Every workflow moves through a defined set of statuses:

| Status | What it means |
| - | - |
| **Draft** | The workflow is being designed. It cannot be triggered or executed. |
| **Active** | The workflow is live and responds to triggers. |
| **Inactive** | The workflow has been paused. It won't respond to triggers until it is moved back to Draft and activated again. |

You control these transitions through the **Activate**, **Deactivate**, and **Move to Draft** actions. See [Activating and deactivating a workflow](/en/products/flowker/console/activating-deactivating-workflow) for details.

## Available actions

***

> **[Edit a workflow](/en/products/flowker/console/editing-a-workflow)**
>
> Modify the workflow's nodes, connections, and configuration in the visual canvas editor.

> **[Clone a workflow](/en/products/flowker/console/cloning-a-workflow)**
>
> Create a duplicate of an existing workflow to use as a starting point for a new one.

> **[Activate / Deactivate](/en/products/flowker/console/activating-deactivating-workflow)**
>
> Control whether the workflow is live and responsive to triggers, or paused.

> **[Delete a workflow](/en/products/flowker/console/deleting-a-workflow)**
>
> Permanently remove a workflow you no longer need.


# Providers overview
Source: https://docs.lerian.studio/en/products/flowker/console/providers-overview

Manage reusable provider configurations for external service integrations, including connection settings and credential references.

Flowker provider configurations connect workflows to external services. A configuration stores or references the connection settings and credentials it needs. Internally credential-managed catalog providers can require no client-supplied credentials. You manage provider configurations in the [Lerian Console](/en/platform/console/about-lerian-console).

## What is a Provider?

***

A **Provider** is a catalog integration type that groups related executors and declares a configuration schema. A **provider configuration** selects a catalog provider or references a tenant-provided OpenAPI document, then supplies or references connection settings for executor call nodes. This keeps credentials and endpoints out of individual workflows.

## Accessing the Providers page

***

To open the **Providers** page, click **Providers** from the left-side menu on the **Flowker** page.

The page lists your provider configurations in a data table, with the following columns:

* **Name**: the provider configuration name.
* **Provider**: the catalog provider, or **Your own API** for a connection to an OpenAPI document you uploaded.
* **Type**: **Native** or **External** for a catalog provider, or **OpenAPI** for your own API.
* **Schemas**: the number of XSD or OpenAPI schemas bound to the configuration.
* **Status**: the configuration status: `Active` or `Disabled`.
* **Last Modified**: the date of the last change to the configuration.
* **Actions**: action menu.

You can filter provider configurations by name, status, or type using the filter fields above the table.

## Provider Catalog

***

Flowker includes a catalog of available provider types. When creating a `catalog` provider configuration, you select which external service type you want to connect to. The catalog provides the configuration schema and required fields for each provider type.

## Available actions menu

***

For each provider configuration, the following actions are available in the action menu ():

* **Details**: opens the provider configuration for viewing and editing.
* **Enable / Disable**: toggles the configuration status. Workflow nodes that reference a disabled configuration fail at execution time until you enable it again.
* **Delete**: permanently removes the provider configuration.

## Related pages

***

> **[Add a provider](/en/products/flowker/console/adding-a-provider)**

> **[Edit a provider](/en/products/flowker/console/editing-a-provider)**

> **[Delete a provider](/en/products/flowker/console/deleting-a-provider)**


# Schema Registry
Source: https://docs.lerian.studio/en/products/flowker/console/schema-registry

Upload, view, and delete the XSD schemas and OpenAPI documents that Flowker workflows use to validate and map data.

The **Schema Registry** page stores the schemas that workflows use to validate and map data. Workflows validate XML payloads against XSD schemas. OpenAPI documents describe the external API operations that workflows call.

## Accessing the Schema Registry page

***

To open the **Schema Registry** page, click **Schema Registry** in the left-side menu on the **Flowker** page.

The page has two tabs:

* **XSD**: the XSD schemas.
* **External APIs**: the OpenAPI documents.

To see the schemas in a tab, you need the `list` permission on the `xsd-schemas` resource for **XSD** or on the `openapi-schemas` resource for **External APIs**. To upload a schema, you need `create` on the same resource. To delete a schema, you need `delete`.

## XSD tab

***

The **XSD** tab lists your XSD schemas, with the following columns:

* **Name**: the schema name.
* **Version**: the schema version.
* **Imports**: the number of schemas that this schema imports.
* **Content Hash**: the start of the hash of the file content.
* **Used by**: the number of provider configurations and workflows that reference the schema.
* **Created At**: the upload date.
* **Actions**: action menu.

## External APIs tab

***

The **External APIs** tab lists your OpenAPI documents, with the following columns:

* **Name**: the document name.
* **Version**: the document version.
* **OpenAPI Version**: the OpenAPI version of the document.
* **Operations**: the number of operations in the document.
* **Used by**: the number of provider configurations and workflows that reference the document.
* **Created At**: the upload date.
* **Actions**: action menu.

## Uploading an XSD schema

***

**Step 1**

On the **XSD** tab, click **Upload**.

**Step 2**

The **Upload XSD Schema** form opens. Fill in the fields:

* **Name**: the schema name (for example, `pain.001.001.09`).
* **Version**: the schema version.
* **Imports** (optional): the names of the schemas that this schema imports, separated by commas.
* **XSD File**: a `.xsd` file no larger than 1 MiB.

**Step 3**

Click **Upload**.

## Uploading an OpenAPI document

***

**Step 1**

On the **External APIs** tab, click **Upload**.

**Step 2**

The **Upload OpenAPI Schema** form opens. Fill in the fields:

* **Name**: the document name (for example, `orders-api`).
* **Version**: the document version.
* **OpenAPI File**: a `.json`, `.yaml`, or `.yml` file no larger than 8 MiB.

**Step 3**

Click **Upload**.

To call the operations of an uploaded document from a workflow, see [Connecting your own API](/en/products/flowker/connecting-your-own-api).

## Viewing a schema

***

Click the schema name, or select **Details** in the action menu (). The **Schema Details** panel opens. You cannot edit a schema in this panel.

For an XSD schema, the panel shows the **Target Namespace** and the **Imports**. For an OpenAPI document, it shows the **OpenAPI Version** and a table of the document operations, with their **Path** and **Method**.

The **Used by** section lists the provider configurations and workflows that reference the schema. Each one shows its status: **Active** or **Disabled**.

## Deleting a schema

***

**Step 1**

Click the three dots () on the **Actions** column and select **Delete**.

**Step 2**

The Console checks which provider configurations and workflows reference the schema. The next dialog depends on the result:

* **No reference**: a confirmation dialog opens. Click **Confirm**.
* **Only references that are not active**: the **Delete schema anyway?** dialog lists them. After you delete the schema, they point to a schema that does not exist. Click **Delete anyway**.
* **One or more active references**: the **Schema in use** dialog lists them, and you cannot delete the schema. Deactivate the active references or point them to another schema, then try again.

## Related pages

***

> **[Add a provider](/en/products/flowker/console/adding-a-provider)**

> **[Connecting your own API](/en/products/flowker/connecting-your-own-api)**


# Viewing execution details
Source: https://docs.lerian.studio/en/products/flowker/console/viewing-execution-details

Open the Execution Details panel in the Flowker Console to view summary fields and, after an execution completes or fails, its step results, output data, and errors.

You can inspect the status of any workflow execution. After an execution completes or fails, you can also review its step results, outputs, and errors.

## Opening the execution detail

***

To view execution details:

**Step 1**

On the **Executions** page, find the execution you want to inspect.

**Step 2**

Click the workflow name or select **View Details** from the action menu ().

**Step 3**

An **Execution Details** side panel opens with the full execution information.

## Execution detail panel

***

The panel shows the summary fields, the execution error when there is one, the input as received, the step results, and the final output.

### Summary fields

| Field | Description |
| - | - |
| **Workflow Name** | Name of the workflow that was executed. |
| **Workflow ID** | Unique identifier of the workflow that was executed. |
| **Execution ID** | Unique identifier for the execution. |
| **Started At** | Timestamp when the execution was triggered. |
| **Completed At** | Timestamp when the execution finished (if applicable). |
| **Duration** | Total time elapsed from start to completion. |

> [!TIP]
>
> The execution status appears as a tag next to the panel title.

> [!NOTE]
>
> Step results are available only after an execution reaches **Completed** or **Failed**. Pending and running executions do not have results yet.

### Execution step results

For a completed or failed execution, Flowker records results for the executed workflow steps. Trigger nodes start traversal and do not create a step result. Executor calls, conditionals, and actions do. Each step result includes:

* **Step name**: the name recorded for the executed step.
* **Status**: whether the step completed successfully or failed.
* **Output data**: the data produced by the step.
* **Error details**: if the step failed, the error message and relevant context.

> [!TIP]
>
> Use the execution step results to trace through the workflow. When an execution fails, they help you identify which step encountered the error and its output.


# Workflows overview
Source: https://docs.lerian.studio/en/products/flowker/console/workflows-overview

Browse the Workflows page in the Flowker Console to see every workflow, filter by name or status, and access lifecycle-aware actions.

Each workflow defines an automated process composed of trigger, executor call, conditional, and action nodes connected in a visual canvas. You manage workflows in the [Lerian Console](/en/platform/console/about-lerian-console).

## Accessing the Workflows page

***

To open the **Workflows** page, click **Workflows** from the left-side menu on the **Flowker** page.

The page lists your workflows in a data table, with the following columns:

* **Name**: the workflow name (and its description, when set).
* **Status**: the current lifecycle state: `Draft`, `Active`, or `Inactive`.
* **Created**: the workflow creation date.
* **Last Updated**: the date of the last change to the workflow.
* **Actions**: action menu.

You can filter workflows by name or status using the filter fields above the table.

## Workflow statuses

***

Each workflow has a lifecycle status that determines whether it can run:

| Status | Description |
| - | - |
| **Draft** | The workflow is being designed and is not yet available for execution. |
| **Active** | The workflow is live and can be triggered for execution. |
| **Inactive** | The workflow has been deactivated and will not respond to triggers. |

## Available actions menu

***

The action menu shows these actions, subject to your permissions:

* **Details**: opens the workflow in the visual canvas editor (clicking the workflow name does the same).
* **Schedule**: opens the schedule panel, showing the workflow's schedule status, upcoming runs, and missed runs pending review. See [Running a workflow on a schedule](/en/products/flowker/running-a-workflow-on-a-schedule).
* **Execute**: triggers an immediate execution with an empty input. Only an **Active** workflow runs.
* **Clone**: creates a duplicate of the workflow.
* **Activate**: available only for a **Draft** workflow.
* **Deactivate**: available only for an **Active** workflow.
* **Move to Draft**: available only for an **Inactive** workflow. Returns it to draft status.
* **Delete**: permanently removes a **Draft** or **Inactive** workflow. Deactivate an **Active** workflow first.

## Related pages

***

> **[Create a workflow](/en/products/flowker/console/create-from-scratch)**

> **[Edit a workflow](/en/products/flowker/console/editing-a-workflow)**

> **[Workflow Canvas](/en/products/flowker/console/canvas-editor)**

> **[Activate / Deactivate](/en/products/flowker/console/activating-deactivating-workflow)**

> **[Clone a workflow](/en/products/flowker/console/cloning-a-workflow)**

> **[Delete a workflow](/en/products/flowker/console/deleting-a-workflow)**


# Core concepts
Source: https://docs.lerian.studio/en/products/flowker/flowker-concepts

Understand the building blocks of Flowker: workflows, nodes, edges, catalog, provider configurations, templates, executions, and dashboard.

This page describes each Flowker concept. The last section shows how they connect.

## Workflows

***

A workflow is the definition of a business process, the sequence of steps Flowker follows to complete an operation.

Workflows go through a lifecycle:

| Status | Description |
| - | - |
| `draft` | Created and editable. Not yet runnable. |
| `active` | Ready to execute. Structure is locked. |
| `inactive` | Deactivated. No new executions accepted. |

To move a workflow between states, use the [activate](/en/reference/products/flowker/activate-workflow), [deactivate](/en/reference/products/flowker/deactivate-workflow), and [move to draft](/en/reference/products/flowker/move-workflow-to-draft) endpoints.

## Nodes and edges

***

Nodes are the individual steps of a workflow, or **tasks** in business terms. Each node is a unit of work: receive an event, call a service, evaluate a condition, or perform an action.

Flowker supports four node types:

| Type | Purpose | When to use |
| - | - | - |
| `trigger` | Entry point for the workflow | Starts execution when an event occurs. |
| `executor` | Calls an external service through a provider configuration | When you need to call an external API or integration. |
| `conditional` | Branches execution based on conditions | When the next step depends on the result of a previous one. |
| `action` | Performs a built-in action; the available type is `set_output`, which sets the execution's final output | For setting the workflow's final output without an external call. |

**Edges** connect nodes and define the order of execution. Branching happens in the conditional node, not in the edge. The conditional node evaluates its condition and produces an outcome handle. Flowker then follows the single outgoing edge whose `sourceHandle` matches that handle. Every other node type follows all of its outgoing edges.

## Catalog

***

The catalog is the registry of the built-in providers, executors, and triggers available in Flowker.

Before configuring any integration, browse the catalog to see what's already available:

* **Catalog executors** are the built-in components a workflow node invokes. They include the generic HTTP connector, and the operations of native providers such as the Midaz ledger and Tracer.
* **Triggers** define the event types that can start a workflow (e.g., webhooks).

Use these endpoints to explore what's available:

* [List catalog executors](/en/reference/products/flowker/list-catalog-executors) and [List catalog triggers](/en/reference/products/flowker/list-catalog-triggers) to discover executor and trigger types.
* [List catalog providers](/en/reference/products/flowker/list-catalog-providers) (`GET /v1/catalog/providers`) to list all available providers.
* [Get catalog provider](/en/reference/products/flowker/get-catalog-provider) (`GET /v1/catalog/providers/{id}`) to get details for a specific provider.
* [List executors by provider](/en/reference/products/flowker/list-executors-by-provider) (`GET /v1/catalog/providers/{id}/executors`) to list the executors available for a specific provider.

## Provider configurations

***

A **provider configuration** is your connection to one live instance of an external service. It is the object a workflow node points at, and the object Flowker reads when that node runs.

Flowker separates the type of service from your connection to it:

| Concept | What it is | Nature |
| - | - | - |
| **Provider** | A type of external service (e.g., Midaz, Tracer, a generic HTTP endpoint). | Static (published in the catalog). |
| **Provider configuration** | Your connection to one instance of that provider. | Dynamic (you create and manage these). |

Each provider configuration holds:

* **`config`**: the connection details for that instance, such as the base URL and authentication credentials. For the default `catalog` kind, Flowker validates this map against the catalog provider's JSON Schema. For `external_openapi`, it uses an external-OpenAPI configuration validator. A read never returns the credential the authentication type declares.
* **`allowedHosts`**: the public hosts this configuration is allowed to call.
* **`allowedPrivateHosts`**: named private hosts your operations team allows this configuration to reach. It lifts only Flowker's private or loopback restriction: if `allowedHosts` is non-empty, it must also include the host. Cloud metadata and link-local addresses stay blocked.
* **`schemaBindings`**: the XSD or OpenAPI schemas bound to this configuration, each with an optional restriction to specific OpenAPI operations.

A configuration also carries a **`kind`**. Supported values are `catalog` (the default), which connects to a catalog provider, and `external_openapi`, which connects to an OpenAPI document you uploaded yourself so a workflow node calls your own API's operations. See [Connecting your own API](/en/products/flowker/connecting-your-own-api).

Provider configurations have two statuses: `active` (in use) and `disabled` (temporarily offline). Use [Disable provider configuration](/en/reference/products/flowker/disable-provider-configuration) to take a connection out of service and [Enable provider configuration](/en/reference/products/flowker/enable-provider-configuration) to bring it back.

### How a workflow reaches it

Every executor node can carry a `providerConfigId`, the identifier of the provider configuration it calls through. At run time, Flowker builds each outgoing request from the base URL of that provider configuration plus the path on the node, and the node fails if the provider configuration is not `active`.

Use the [Provider configurations](/en/reference/products/flowker/list-provider-configurations) endpoints to create, read, update, disable, enable, and delete your connections.

## Templates

***

Workflow templates are pre-built workflow patterns published in the catalog. Each template describes a known integration pattern and the parameters that pattern expects.

Each template has a parameter schema that defines what inputs it expects (e.g., which provider configuration to use, threshold values). When Flowker can retrieve active provider configurations, it enriches referenced parameter fields with selectable options.

To inspect a template:

1. [List the catalog templates](/en/reference/products/flowker/list-catalog-templates).
2. [Get the template detail](/en/reference/products/flowker/get-catalog-template) to see its parameter schema.
3. [Validate a set of parameters](/en/reference/products/flowker/validate-catalog-template-params) against that schema.

## Executions

***

An execution is a runtime instance of a workflow. A trigger normally starts a new execution. A retry that reuses an existing idempotency key returns the pre-existing execution instead of creating another.

Each execution tracks:

* `executionId`: unique identifier for this run.
* `status`: current state (`pending`, `running`, `completed`, or `failed`).
* `stepResults`: the output of each executed executor, conditional, or action node, in order. Trigger nodes start graph traversal and do not create execution-step records.
* `finalOutput`: the final value persisted for the execution. When a `set_output` action produces an object, Flowker uses that object. Otherwise Flowker returns the accumulated workflow context.

Use [Get execution status](/en/reference/products/flowker/get-execution-status) to monitor progress and [Get execution results](/en/reference/products/flowker/get-execution-results) to retrieve the full output.

> [!NOTE]
>
> The status endpoint returns the execution record, including its current status. The dedicated results endpoint ([`GET /v1/executions/{id}/results`](/en/reference/products/flowker/get-execution-results)) returns `status`, `stepResults`, and `finalOutput` when present. A failed step can include `errorMessage`. This response has no top-level error-details field.

## Idempotency

***

Direct execution requests require a non-empty `Idempotency-Key` string. Flowker does not enforce UUID format. The webhook header is optional.

If Flowker receives a second request with the same `Idempotency-Key`, it returns the pre-existing execution instead of creating another. A direct replay includes `idempotencyReplayed: true` in the response.

```
Idempotency-Key: 7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b
```

Use a new key when you intentionally want a new execution. Reuse the same key only when retrying the exact same request.

## Dashboard

***

The Dashboard API provides aggregated summaries of your workflows and executions. Use it whenever you need a high-level view of system health without querying individual executions.

* [Workflow summary](/en/reference/products/flowker/get-dashboard-workflow-summary) returns totals and breakdowns by status (draft, active, inactive).
* [Execution summary](/en/reference/products/flowker/get-dashboard-execution-summary) returns totals and breakdowns by status, with optional time range and status filters.

Example response from [`GET /v1/dashboards/executions`](/en/reference/products/flowker/get-dashboard-execution-summary):

```json theme={null}
{
  "total": 12847,
  "completed": 11903,
  "failed": 712,
  "pending": 130,
  "running": 102
}
```

Common use cases:

* **Monitoring execution health**: track completion and failure rates over time to spot degradation early.
* **Building status pages**: surface workflow throughput and success metrics in internal or client-facing dashboards.
* **Alerting on failure rate spikes**: compare `failed / total` against a threshold to trigger alerts before issues cascade.

## How it all fits together

***

Flowker's concepts build on each other in this order:

1. **Explore the catalog** to discover available providers, catalog executors, triggers, and templates.
2. **Create provider configurations** to connect Flowker to live instances of external services.
3. **Define workflows**: each executor node names a catalog executor and the provider configuration it calls through.
4. **Execute workflows** to run your business process and retrieve results.
5. **Monitor**: use the dashboard for operational summaries and the executions API for step-level detail.

Follow the [Getting started guide](/en/products/flowker/flowker-getting-started) to run your first workflow end to end.


# Getting started with Flowker
Source: https://docs.lerian.studio/en/products/flowker/flowker-getting-started

Learn how Flowker automates financial operations through real business scenarios, from payment orchestration to fraud prevention.

Financial operations involve multiple steps, approvals, and external checks. Managing these manually leads to errors, delays, and compliance gaps. Flowker lets you define these processes once as workflows and execute them consistently, with step-level execution records and real-time visibility.

## How Flowker works

***

You start by exploring what integrations are available, connect them to your environment, define a workflow that models your business process, and then execute it. Every execution leaves a record that is traceable and available for inspection through the API.

**1. Explore the catalog**

Browse the catalog to discover the providers, executors, and triggers available in your Flowker deployment.

**2. Connect your providers**

Create a provider configuration for each external service your workflows call: fraud engines, payment processors, KYC providers, and notification services. It identifies the connection a workflow node uses for that service.

**3. Define your workflows**

Model your business process as a workflow: define the steps (nodes), the order they run (edges), and the conditions that control branching.

**4. Execute and monitor**

Trigger workflows through the API, a webhook, or a schedule trigger. Read each execution's status and retrieve results when it completes.

## What you can automate

***

Flowker is designed for multi-step financial processes that require reliability, traceability, and integration with external services.

### Payment orchestration

**The challenge:** A payment involves multiple steps: validation, routing to the right provider, confirmation, and notification. When handled manually or through scattered integrations, failures go unnoticed and reconciliation becomes painful.

**How Flowker solves it:** Define a workflow that coordinates the entire payment lifecycle:

1. **Trigger**: A new payment request arrives via API or webhook.
2. **Validate**: Check that the payment data is complete and the account has sufficient balance.
3. **Route**: Select the appropriate payment provider based on amount, currency, or rail (Pix, TED, SWIFT).
4. **Confirm**: Call the provider and wait for confirmation.
5. **Notify**: Send a confirmation event to the customer and update the ledger.

For executor calls, you configure retry behavior per node. By default, `POST` and `PATCH` calls run once unless you opt the node into retries. Flowker does not deduplicate the provider side effect on retries: the execution `Idempotency-Key` deduplicates Flowker executions, not outbound provider requests.

Opt a `POST` or `PATCH` node into retries only when the provider operation is idempotent. You can also opt in when the provider documents a stable business key and atomically enforces it. Send that key in a header as an idempotency key on every attempt. Otherwise, keep retries disabled for the node. Flowker records every executed executor, conditional, and action node for reconciliation and review.

### Anti-fraud validation

**The challenge:** Fraud checks must happen before transaction processing. They involve external services, scoring logic, and different thresholds depending on the transaction type. Hard-coding this logic makes it hard to maintain.

**How Flowker solves it:** Define a pre-transaction workflow that runs fraud checks before anything reaches the ledger:

1. **Trigger**: A new transaction arrives.
2. **Enrich**: Collect customer history, device data, and geolocation from internal systems.
3. **Score**: Call one or more fraud detection providers and collect risk scores.
4. **Decide**: Apply rules: if the score is above the threshold, block. If borderline, flag for review. If clear, approve.
5. **Act**: Proceed with the transaction or notify the compliance team.

All decisions are traceable. You can adjust thresholds and add new providers without changing the core logic.

### Customer onboarding

**The challenge:** Onboarding a new customer requires identity verification, document validation, AML/KYC checks, and account creation. These steps involve multiple external providers and regulatory requirements that vary by jurisdiction.

**How Flowker solves it:** Define an onboarding workflow that automates the entire process:

1. **Trigger**: A new customer registration arrives.
2. **Verify identity**: Call a KYC provider to validate the customer's documents and identity.
3. **Check compliance**: Run AML screening against sanctions lists and PEP databases.
4. **Evaluate risk**: Apply internal risk rules based on the customer profile, jurisdiction, and transaction history.
5. **Create account**: If all checks pass, create the customer's account in the system.
6. **Notify**: Send a welcome email or notify the relationship manager if manual review is needed.

Each step's result determines the next action. If a check fails, the workflow stops and records the step result that explains why.

### Manual approval workflows

**The challenge:** Some operations (high-value transfers, credit limit changes, account closures) require human approval. But building approval flows with email notifications, timeouts, and escalation paths is complex and error-prone.

**How Flowker solves it:** Define a workflow that calls an external approval service through an executor node:

1. **Trigger**: A high-value transfer request arrives.
2. **Evaluate**: Check the amount, customer risk profile, and internal policies.
3. **Request approval**: Call an external approval service (manager, compliance officer) through an executor node.
4. **Decide**: A conditional node evaluates the approval response.
5. **Act**: If approved, proceed with the transfer. If rejected, cancel and notify the requester.

You can define multi-level approvals by chaining executor nodes that call your approval service at each level.

## Key capabilities

***

* **Pre-ledger validation**: Put every check before the posting node in your graph and use conditional nodes with matching `sourceHandle` edges to route only approved outcomes to posting.
* **Step-level execution records**: Execution results record status, duration, output, and error for each executed executor, conditional, or action node. Trigger nodes start graph traversal and do not create execution-step records.
* **Provider integrations**: Connect to fraud engines, KYC providers, payment processors, and any HTTP-based service.
* **Conditional branching**: A conditional node selects the outgoing edge whose `sourceHandle` matches its outcome, so you can route execution based on step results, amounts, risk scores, or any data field.
* **Idempotent execution**: Reusing an `Idempotency-Key` returns the existing Flowker execution instead of creating another. Direct execution requires a non-empty key. The webhook header is optional.
* **Execution monitoring**: Read execution status through the API while a workflow runs. Retrieve execution results, including step results, after it reaches a terminal state.

> [!NOTE]
>
> With `PLUGIN_AUTH_ENABLED=true`, Flowker's management routes require a Bearer token and enforce resource/action permissions. Production deployments require this setting. The signed Streaming Hub ingress under `/v1/hub/webhooks/` uses the hub's signature instead of a Bearer token. Provider-specific credentials (for external services) are managed through [provider configurations](/en/reference/products/flowker/list-provider-configurations).

## What's next

***

> **[Core concepts](/en/products/flowker/flowker-concepts)**
>
> Understand workflows, nodes, edges, and the execution model in detail.

> **[What is Flowker?](/en/products/flowker/what-is-flowker)**
>
> Read about Flowker's architecture, features, and design philosophy.

> **[API reference](/en/reference/products/flowker/create-workflow)**
>
> Explore the full API for workflows, executions, and configurations.


# Flowker in Lerian Console
Source: https://docs.lerian.studio/en/products/flowker/flowker-in-lerian-console

See what the Flowker module in Lerian Console offers: visual canvas editor, provider management, and execution monitoring.

The **Lerian Console** provides a visual interface for designing workflows, managing provider configurations, and inspecting executions.

## What you get

***

The Flowker module in Lerian Console gives you:

* A *visual canvas editor* for designing workflows with drag-and-drop nodes, triggers, conditionals, and connections
* *Provider management* for configuring external integrations directly from the UI
* *Execution monitoring* with status and step result inspection

## When to use the Console vs. the API

***

The Console calls the same Flowker API for these flows. Choose the visual interface or the API based on your workflow:

| Use the Console when | Use the API when |
| :- | :- |
| Designing workflows visually | Automating workflow creation in CI/CD |
| Configuring provider integrations | Integrating Flowker into your own tooling |
| Monitoring executions | Triggering workflows programmatically |
| Inspecting step results | Building custom dashboards or alerts |

Most teams use both: the Console for design and monitoring, the API for runtime execution and automation.

## Get started

***

> **[Flowker module overview](/en/products/flowker/console/flowker-module)**
>
> Full walkthrough of the Flowker module in Lerian Console: accessing the module, navigating the sidebar, and understanding the available pages.

> **[Dashboard](/en/products/flowker/console/flowker-dashboard)**
>
> Monitor workflow activity at a glance with stat cards, recent workflows, and execution history.

> **[Managing workflows](/en/products/flowker/console/managing-workflows)**
>
> Create, edit, clone, activate, and delete workflows through the Console interface.

> **[Workflow canvas](/en/products/flowker/console/canvas-editor)**
>
> Learn how to use the visual canvas editor: triggers, executor calls, conditionals, and connections.

> **[Managing providers](/en/products/flowker/console/providers-overview)**
>
> Configure and manage the provider integrations used by your workflows.

> [!NOTE]
>
> If Flowker is not enabled for your organization, an administrator can enable it in the Console under **Settings**, in **Products**.


# Observability in Flowker
Source: https://docs.lerian.studio/en/products/flowker/flowker-observability-guide

Track Flowker workflow runs through their execution records and know what to send to Lerian support.

Lerian operates and monitors the Flowker service. You follow your workflows through their execution records: each run has a status, step results, and a final output.

## Investigate a workflow run

***

For an individual workflow run, use [Get execution results](/en/reference/products/flowker/get-execution-results) to see its status, step results, and final output when present. A failed step can include an `errorMessage`. This response has no top-level error-details field.

## How to interpret execution status

***

Each workflow execution in Flowker has a status that tells you where it stands.

| Status | Meaning | What to do |
| - | - | - |
| `pending` | The execution has been created but has not started. In the normal execution path, Flowker changes it to `running` synchronously before responding; do not treat it as a scheduler queue. | — |
| `running` | Execution is in progress | Normal. Monitor for completion |
| `completed` | The workflow ran to its end without an error | No action needed |
| `failed` | Execution finished with an error | Check `stepResults` for a failed step. A failure before any step runs has no step error in this response. |

> [!TIP]
>
> If you see a significant number of `failed` executions in a short period, collect their execution ids and error details before you escalate.

## When to contact Lerian support

***

Contact Lerian support when:

* `failed` executions keep growing and the cause is not clear from `stepResults`
* Flowker does not process new executions

Share the execution ids, the UTC timeframe, and the relevant API error payloads.


# Integration guide
Source: https://docs.lerian.studio/en/products/flowker/integration-guide

Connect external services to Flowker through provider configurations. Set up authentication, map fields, and run workflows against real integrations.

Flowker calls external services (such as fraud engines, payment processors, and KYC providers) through provider configurations. A provider configuration is your connection to one live instance of an external service.

In this guide, you explore the catalog, create a provider configuration, and reference it from a workflow node. You then map fields between your data and the service, and learn how Flowker retries and protects those calls.

## Step 1: Explore the catalog

***

The catalog is the registry of the providers, catalog executors, and triggers that ship with Flowker.

**1. List available providers**

Call the [List catalog providers](/en/reference/products/flowker/list-catalog-providers) endpoint to see the service types Flowker connects to. The catalog always includes the generic HTTP connector. Native providers such as `ledger` (Midaz) and `tracer` are synthesized from published OpenAPI specifications and appear only when the native schema registry is configured and synthesis succeeds.

**2. List available catalog executors**

Call the [List catalog executors](/en/reference/products/flowker/list-catalog-executors) endpoint to see the operations a workflow node can invoke. Use [List executors by provider](/en/reference/products/flowker/list-executors-by-provider) to narrow the list to one provider.

**3. List available triggers**

Call the [List catalog triggers](/en/reference/products/flowker/list-catalog-triggers) endpoint to see the built-in trigger types: webhooks and schedules. The Execute workflow API starts a workflow but is not a catalog trigger.

**4. Pick what you need**

Note the `providerId` and the catalog executor id that match your integration. You use the first in [Step 2](#step-2-create-a-provider-configuration) and the second in [Step 3](#step-3-reference-the-provider-configuration-from-a-workflow-node).

> [!TIP]
>
> The catalog shows what Flowker can call. Provider configurations hold the base URL, the credentials, and the settings for each service instance you use.

## Step 2: Create a provider configuration

***

Call [`POST /v1/provider-configurations`](/en/reference/products/flowker/create-provider-configuration) to define your connection to one instance of an external service.

| Field | Required | Description |
| - | - | - |
| `name` | Yes | A name for this connection, 1–100 characters. |
| `kind` | No | Which kind of connection this is. Omit it, or send `catalog`, for a connection to a catalog provider (the case this guide covers). Send `external_openapi` for a connection to an OpenAPI document you uploaded; see [Connecting your own API](/en/products/flowker/connecting-your-own-api). You choose the kind when you create the configuration. |
| `providerId` | For `catalog` | The catalog provider this connection is an instance of, such as `ledger` or `http`. A configuration of kind `external_openapi` may omit it, and a read of it returns the reserved id `external.openapi`. |
| `config` | Yes | The connection details for that instance, such as the base URL and the authentication credentials. Flowker validates this map against the provider's JSON Schema from the catalog and returns `422` when it does not match. |
| `allowedHosts` | For `http` | The public hosts this configuration is allowed to call. The generic HTTP connector (`providerId: "http"`) requires at least one entry, and an empty list is rejected with `FLK-0323`. Native providers accept an empty list. An entry with a leading dot matches subdomains: `.kyc-provider.io` matches `api.kyc-provider.io`. Host names only: no IP literals, wildcards, or ports. The host in `config.base_url` must be covered by the list, otherwise the create is rejected with `FLK-0320`. |
| `allowedPrivateHosts` | No | Named private hosts your operations team allows this configuration to reach. Cloud metadata and link-local addresses stay blocked. |
| `schemaBindings` | No | The XSD or OpenAPI schemas bound to this configuration, each with an optional restriction to specific OpenAPI operations. |
| `description` | No | Free text, up to 500 characters. |
| `metadata` | No | Your own key-value pairs. |

> [!NOTE]
>
> A `providerId` is a catalog identifier, and it does not always match the product name. The catalog registers Midaz as `ledger`. Always take the value from [List catalog providers](/en/reference/products/flowker/list-catalog-providers) rather than guessing it from the product name.

> [!WARNING]
>
> The `providerId` on the configuration and the `executorId` on the node that uses it must belong to the same catalog provider. The generic HTTP connector uses `http` for both. Flowker rejects a workflow that pairs a configuration of one provider with an executor of another, with `FLK-0151`.

The example below builds the connection this guide uses from here on: a fraud scoring service reached through the generic HTTP connector.

> **Example request**
>
> ```json theme={null}
> POST /v1/provider-configurations
>
> {
>   "name": "FraudShield Production",
>   "description": "Production fraud scoring service",
>   "providerId": "http",
>   "config": {
>     "base_url": "https://api.fraudshield.example.com",
>     "auth": {
>       "type": "api_key",
>       "config": {
>         "key": "sk-prod-xxx",
>         "header_name": "X-API-Key",
>         "location": "header"
>       }
>     }
>   },
>   "allowedHosts": ["api.fraudshield.example.com"],
>   "metadata": {
>     "environment": "production"
>   }
> }
> ```
>
> The response returns the new configuration's `id`. Keep it. [Step 3](#step-3-reference-the-provider-configuration-from-a-workflow-node) and [Step 4](#step-4-run-the-workflow) put it in the `providerConfigId` of the node that calls the service.

### Authentication

The `config.auth` block holds the authentication the external service requires, as a `{ type, config }` pair. Use the method your service expects.

| Type | Description | Config fields |
| - | - | - |
| `none` | No authentication. | — |
| `api_key` | API key in header or query. | `key`, `header_name`, `location`, `query_param_name`, `prefix` |
| `bearer` | Bearer token in Authorization header. | `token` |
| `basic` | Username and password (Base64). | `username`, `password` |
| `oidc_client_credentials` | OAuth 2.0 client credentials flow with automatic token management. | `issuer_url`, `client_id`, `client_secret`, `scopes` |
| `oidc_user` | OAuth 2.0 resource owner password flow. | `issuer_url`, `client_id`, `username`, `password`, `client_secret`, `scopes` |
| `oauth2_token_endpoint` | OAuth 2.0 client credentials against a token endpoint (no OIDC discovery). | `token_url`, `client_id`, `client_secret`, `scopes` |
| `hmac` | Signs each request with a shared HMAC secret. | `secret`, `algorithm`, `encoding`, `header_name`, `signature_prefix`, `signing_string`, `timestamp_header` |

A read never returns the credential the authentication type declares. Store credentials only in the fields the authentication type declares.

To rotate a secret, send the new value in an update. To keep the current one, omit the field or send it blank. This works while `auth.type` stays the same. An update that changes `auth.type` must carry a value for each secret the new type requires and the previous one did not. Otherwise Flowker rejects it with `FLK-0952`. A change between two types that use the same secret, such as `oidc_user` to `oidc_client_credentials`, does not need that value again.

> [!TIP]
>
> For OAuth 2.0 integrations, use `oidc_client_credentials`. Flowker handles token acquisition and renewal automatically.

> **Example: OIDC client credentials**
>
> ```json theme={null}
> {
>   "auth": {
>     "type": "oidc_client_credentials",
>     "config": {
>       "issuer_url": "https://auth.fraudshield.com/realms/fraudshield",
>       "client_id": "flowker-integration",
>       "client_secret": "secret-value",
>       "scopes": ["transactions:read", "transactions:score"]
>     }
>   }
> }
> ```

### Enabling and disabling

Provider configurations have two statuses: `active` (in use) and `disabled` (temporarily offline). A new provider configuration starts in `active` status. Use [Disable provider configuration](/en/reference/products/flowker/disable-provider-configuration) to take a connection out of service and [Enable provider configuration](/en/reference/products/flowker/enable-provider-configuration) to bring it back.

See the [Provider configurations API](/en/reference/products/flowker/list-provider-configurations) for the full reference.

## Step 3: Reference the provider configuration from a workflow node

***

Every executor node carries a `providerConfigId`, the identifier of the provider configuration it calls through. Flowker rejects a workflow whose executor node has no `providerConfigId`, and rejects a value that is not a UUID. At run time it builds each outgoing request from the base URL of that provider configuration plus the path on the node. The node fails if the provider configuration is not `active`.

These are the fields an executor node sets in its `data` object when it calls through the generic HTTP connector:

| Field | Required | Description |
| - | - | - |
| `executorId` | Yes | The catalog executor this node invokes, taken from [Step 1](#step-1-explore-the-catalog). Flowker rejects the workflow when the id is not in the catalog. A node that calls an uploaded OpenAPI document omits it (see below). |
| `providerConfigId` | Yes | The UUID of the provider configuration this node calls through. |
| `path` | No | The request path appended to the provider configuration's base URL. The destination host is always that base URL. A node cannot supply an absolute URL. |
| `endpointName` | No | Used as the request path when the node sets no `path`. A node that carries both sends `path`. |
| `method` | No | `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, or `OPTIONS`. Defaults to `POST`. |
| `headers` | No | Request headers, merged over the ones the provider configuration defines. A node header wins over a provider-configuration header of the same name. |
| `query` | No | Query parameters appended to the URL. |
| `auth` | No | A `{type, config}` authentication block for this node, in the same shape the provider configuration uses. When present it takes precedence over the authentication on the provider configuration. |
| `body` | No | An explicit request body, resolved against the workflow context. When set, it is the only body source. Field mappings are not applied to it. |
| `content_digest` | No | A SHA-256 pin for the assembled request body. Set a 64-character hexadecimal digest, or a value resolved from the workflow context. Flowker hashes the final bytes after assembling the body and sends the request only when they match. |
| `config` | No | Fixed literal values that seed the request body. See [Field mapping and data transformation](#field-mapping-and-data-transformation). |
| `inputMapping`, `outputMapping`, `transforms` | No | Field mappings and transformations. See [Field mapping and data transformation](#field-mapping-and-data-transformation). |
| `timeout_seconds`, `retry`, `success_status_codes` | No | Per-node resilience settings. See [Retry and circuit breaker](#retry-and-circuit-breaker). |
| `request_format` | No | An object whose `type` sets how Flowker serializes the request body: `json` (the default), `xml_converted`, or `xml_passthrough`. `xml_converted` also requires `root_element`. |

A node that calls an operation of an uploaded OpenAPI document names it with `operation_path` and `operation_method` instead of an `executorId`. Flowker fills the `executorId` in for you from the provider configuration the node points at. [Connecting your own API](/en/products/flowker/connecting-your-own-api) walks that whole path.

### Validate a node configuration before you save

Call the [Validate a node configuration](/en/reference/products/flowker/validate-executor-config) endpoint (`POST /v1/catalog/executors/{id}/validate`) to check a node's configuration against the catalog executor's JSON Schema.

This performs **JSON Schema validation only**. It checks that your configuration object matches the structure the catalog executor expects (required fields, types, formats). It does not call the external service, so the first real round trip happens when a workflow runs the node.

Pass `mappedTargets` to name the fields your node supplies through an `inputMapping` rather than a fixed value. Those fields count as satisfied, so a node that maps a required field from the trigger validates before you save it.

## Field mapping and data transformation

***

Use field mappings and transformations when workflow data doesn't match the format an external service expects. Use them too when a service returns data in a shape the next step can't consume.

You define field mappings and transformations inside the `data` object of executor nodes. Flowker applies input mappings before calling the external service, and output mappings after receiving the response.

An input `target` is a path in the outgoing request body, written exactly as the external service expects it. There is no wrapper object and no prefix to add. An output `source` is a path into the response envelope, so response fields sit under `body`.

> **Quick example: mapping workflow fields to an executor node**
>
> ```json theme={null}
> {
>   "id": "executor-balance",
>   "type": "executor",
>   "name": "Check Balance",
>   "data": {
>     "executorId": "http",
>     "providerConfigId": "a1b2c3d4-e5f6-4789-a012-345678901234",
>     "path": "/accounts/balance",
>     "inputMapping": [
>       { "source": "workflow.customerId", "target": "accountId" },
>       { "source": "workflow.amount", "target": "minimumBalance" }
>     ],
>     "outputMapping": [
>       { "source": "body.currentBalance", "target": "balance" },
>       { "source": "body.accountStatus", "target": "status" }
>     ]
>   }
> }
> ```
>
> Downstream nodes read the mapped output under this node's ID: `${executor-balance.balance}`.

For complex integrations, you can also attach transformations to individual mapping entries (e.g., stripping characters, adding prefixes, changing case). You can define Kazaam operations for advanced JSON-to-JSON transformations.

[Working with request and response data](/en/products/flowker/working-with-request-and-response-data) walks the whole path. It covers declaring the mappings, choosing what builds the request body, and reshaping values in flight. It also covers reading the response back out, and checking the assembled request before you call the service.

## Step 4: Run the workflow

***

Reference the provider configuration in a workflow node of type `executor`.

The example below creates a payment validation workflow on top of the FraudShield connection from [Step 2](#step-2-create-a-provider-configuration). When a payment arrives, Flowker calls the fraud check service, evaluates the risk score, and either approves or rejects the payment based on the result.

The workflow has five nodes. A webhook **trigger** receives the payment, and an **executor** node calls the fraud check service. A **conditional** node evaluates the score, and there are two **action** nodes for the approve and reject outcomes. Edges connect them in sequence, with the conditional node branching to either path based on the score threshold.

Use the [Create workflow](/en/reference/products/flowker/create-workflow) endpoint to define the workflow, then [Activate](/en/reference/products/flowker/activate-workflow) it, and finally [Execute](/en/reference/products/flowker/execute-workflow) it.

> **Example: Create a payment validation workflow**
>
> ```json theme={null}
> POST /v1/workflows
>
> {
>   "name": "payment-validation",
>   "description": "Validates a payment before processing.",
>   "nodes": [
>     {
>       "id": "trigger-payment",
>       "type": "trigger",
>       "name": "Payment received",
>       "position": { "x": 0, "y": 0 },
>       "data": {
>         "triggerType": "webhook",
>         "path": "payments/received",
>         "method": "POST",
>         "input_contract": "open",
>         "format": "json"
>       }
>     },
>     {
>       "id": "check-fraud",
>       "type": "executor",
>       "name": "Fraud check",
>       "position": { "x": 200, "y": 0 },
>       "data": {
>         "executorId": "http",
>         "providerConfigId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
>         "path": "/score-transaction",
>         "method": "POST",
>         "inputMapping": [
>           { "source": "workflow.transactionId", "target": "transactionId" },
>           { "source": "workflow.amount", "target": "amount" }
>         ]
>       }
>     },
>     {
>       "id": "evaluate-score",
>       "type": "conditional",
>       "name": "Score evaluation",
>       "position": { "x": 400, "y": 0 },
>       "data": {
>         "condition": "check-fraud.body.score < 80"
>       }
>     },
>     {
>       "id": "approve",
>       "type": "action",
>       "name": "Approve payment",
>       "position": { "x": 600, "y": -100 },
>       "data": {
>         "actionType": "set_output",
>         "output": { "decision": "approved" }
>       }
>     },
>     {
>       "id": "reject",
>       "type": "action",
>       "name": "Reject payment",
>       "position": { "x": 600, "y": 100 },
>       "data": {
>         "actionType": "set_output",
>         "output": { "decision": "rejected" }
>       }
>     }
>   ],
>   "edges": [
>     { "id": "e1", "source": "trigger-payment", "target": "check-fraud" },
>     { "id": "e2", "source": "check-fraud", "target": "evaluate-score" },
>     { "id": "e3", "source": "evaluate-score", "target": "approve", "sourceHandle": "true" },
>     { "id": "e4", "source": "evaluate-score", "target": "reject", "sourceHandle": "false" }
>   ]
> }
> ```
>
> The `check-fraud` node names `http`, the generic HTTP connector from the catalog. It also names the FraudShield configuration from Step 2, which holds the base URL and the credentials. Both sides name the same provider, so the workflow saves. Flowker sends the request to `https://api.fraudshield.example.com/score-transaction`.
>
> The node declares no `outputMapping`, so its output keeps the response envelope shape. The score therefore sits at `check-fraud.body.score`, which is what the `evaluate-score` condition reads. Add an `outputMapping` when you prefer a flatter name. See [Field mapping and data transformation](#field-mapping-and-data-transformation).

> **Example: Execute the workflow**
>
> ```json theme={null}
> POST /v1/workflows/{workflowId}/executions
> Idempotency-Key: {unique-uuid}
>
> {
>   "inputData": {
>     "transactionId": "txn-98765",
>     "amount": 1500.00,
>     "currency": "BRL",
>     "customerId": "cust-12345"
>   }
> }
> ```

## Triggering workflows

***

You trigger workflow executions via the [Execute workflow](/en/reference/products/flowker/execute-workflow) endpoint:

```
POST /v1/workflows/:workflowId/executions
```

The request body contains the `inputData` for the execution. All fields are available to subsequent nodes via the `workflow` namespace (for example, `workflow.transactionId` or `workflow.amount`). Node outputs are available via the node's ID (for example, `check-fraud.body.score` for a node that declares no `outputMapping`).

### Idempotency

Every Execute workflow request must include an `Idempotency-Key` header. A request without it fails with `400 Bad Request` (error `FLK-0509`). Generate a fresh UUID for each new execution, and reuse the same key only when retrying the identical request.

## Webhook triggers

***

Webhooks are the primary way external systems trigger Flowker workflows. Instead of your system calling the executions API directly, you register a webhook path in a workflow. External services then send HTTP requests to that path.

### How it works

1. Add a trigger node of type `webhook` to your workflow with a `path` and a `method` in its `data`. Set `input_contract` explicitly for new nodes when you need `open`, `xsd`, or `openapi` validation.
2. When you activate the workflow, Flowker registers the path in its webhook registry.
3. External systems send requests to [`POST /v1/webhooks/{path}`](/en/reference/products/flowker/trigger-webhook) (or the method you configured).
4. Flowker resolves the path to the matching workflow and executes it.

### Defining a webhook trigger node

The webhook trigger is a node with `type: "trigger"` and `triggerType: "webhook"` in its `data`, plus a `path`, a `method`, and an optional `input_contract`. [Configuring a webhook trigger](/en/products/flowker/configuring-a-webhook-trigger) covers every field, the three `input_contract` modes and what each one requires, and carries a worked node for each mode.

The trigger configuration follows a closed contract. Saving a workflow fails with `FLK-0934` when its webhook trigger omits `path` or `method`, or misses a field its selected `input_contract` mode requires. It also fails when the trigger names another mode's schema id or operation field. It fails too when the trigger carries a key or a value the schema does not accept. An `accepted_headers` name that is not a valid header name, repeats another name or is on the denylist fails with `FLK-0957` instead.

The schema also declares the optional `response_mode`, `response_view`, and `accepted_headers` fields. See [Configuring a webhook trigger](/en/products/flowker/configuring-a-webhook-trigger).

### Securing a webhook

With `PLUGIN_AUTH_ENABLED=true`, requests to `/v1/webhooks/*` require a Bearer token and the `execute` permission on the `webhooks` resource. Production deployments require plugin authentication.

Grant that permission to a machine-to-machine identity for each system you let call your webhooks, and manage the grant in Access Manager. This keeps webhook access under the same role and policy model as workflow management, rather than a credential attached to the path.

### Webhook metadata

Flowker automatically injects a `_webhook` object into the execution's `inputData` with metadata about the incoming request:

| Field | Description |
| - | - |
| `_webhook.method` | HTTP method used (e.g., `POST`). |
| `_webhook.path` | The request path after the route prefix that received the call (`/v1/webhooks/`, or `/v1/hub/webhooks/` for the Streaming Hub ingress), as received. |
| `_webhook.headers` | Request headers, filtered through a safe allowlist (`Content-Type`, `Accept`, `User-Agent`, `X-Request-Id`, `X-Forwarded-For`, `Idempotency-Key`) plus this trigger's optional `accepted_headers` and, for an `openapi` route, its operation's header parameters. The fixed denylist blocks `Authorization`, `Proxy-Authorization`, `Cookie`, `Set-Cookie`, `X-API-Key`, `X-Auth-Token`, and `X-Webhook-Signature`. Other admitted headers are persisted verbatim; never admit secret-bearing names such as `X-Amz-Security-Token`. |
| `_webhook.query` | Preserves the names of received query parameters. It preserves values only for `customerId`, `page`, `cursor`, `limit`, `offset`, and `sortOrder` (case-insensitive); every other value is stored as `[redacted]`. |
| `_webhook.remote_ip` | IP address of the caller. |

This metadata is available to all nodes in the workflow via the `workflow._webhook` namespace.

### Path rules and body size

* Activating a workflow whose webhook path and method another active workflow holds fails with `FLK-0360`.
* Webhook paths support nested segments (e.g., `payments/stripe/received`).
* The request body maximum size is 1 MB.

See the [Trigger a webhook](/en/reference/products/flowker/trigger-webhook) API reference for the complete endpoint documentation.

### Synchronous response mode

By default, a webhook trigger responds with a `202` receipt as soon as the execution starts (the async mode). The caller must poll the execution status separately. Set `response_mode` to `"sync"` in the trigger node's `data` to have Flowker hold the HTTP connection open and return the execution's outcome directly in the response:

| Field | Type | Required | Description |
| - | - | - | - |
| `response_mode` | string | No | `"async"` (default) returns a `202` receipt immediately. `"sync"` blocks (up to an internal cap) for the execution to reach a terminal state and returns the outcome in the response body. |
| `response_view` | string | No | Shapes the sync response body. Only meaningful when `response_mode` is `"sync"`. See the table below. Defaults to `"full"`. |

If the execution does not reach a terminal state before the internal wait cap elapses, Flowker falls back to the async mode's `202` receipt. That receipt carries a `Location` header pointing at the results endpoint.

`response_view` selects the shape of the sync response body:

| Value | Description |
| - | - |
| `full` (default) | The complete execution dump (`executionId`, `workflowId`, `status`, `stepResults`, `finalOutput`), in the same shape you would fetch from the execution results endpoint. |
| `final_output` | Only the execution's `finalOutput` map, with no envelope wrapper. |
| `receipt` | The lean execution receipt (`executionId`, `workflowId`, `status`, `startedAt`), in the same shape the async path returns. |
| `passthrough` | Shapes the response by the terminal (last-executed) step's node type. For a terminal executor that captured a provider response, it returns the provider status (including `4xx`) and `Content-Type`. It relays at most 8 KiB of the captured body; longer bodies are truncated. JSON bodies are decoded and re-serialized before capture, so byte-for-byte relay is not guaranteed. If the terminal step is a `set_output` action with a configured output, the response is that node's business output, honoring its `responseStatusCode` override. When the execution failed, its last step captured no provider response, and no `set_output` node that ran set a `responseStatusCode`, the response is the `full` envelope at HTTP `200`. |

A failed execution's `finalOutput` in the `final_output` view carries `status: "failed"` and `errorMessage`, and `errorClass` when Flowker could classify the failure, never a bare `{}`. Absent a `responseStatusCode` override (see below), the sync HTTP status stays `200` for `full`/`final_output`/`receipt` (it reports transport health, not business outcome). A valid `responseStatusCode` on a `set_output` node that runs overrides that status for those three views.

An action node with `actionType: "set_output"` can carry an optional `responseStatusCode` (integer, `200`–`599`) to override the HTTP status a `sync` webhook response returns. An out-of-range or non-integer value fails at save time (`FLK-0122`). For `passthrough`, a terminal executor's relayed provider status wins over the override.

A `set_output` terminal downstream of an executor shapes the response as its own output. Flowker never walks back to an earlier executor's response. On a failed execution the halting step is the terminal step, so Flowker relays a provider `4xx` that stopped the workflow as the real `4xx`.

Values in a `set_output` node's output support `${...}` references resolved against the workflow context, including `${workflow.<field>}` (trigger payload), `${execution.id}`, `${execution.startedAt}`, and `${execution.now}` (stamped at interpolation time). An unresolvable `${...}` reference fails the step (fail-closed).

## Error handling

***

If a node fails, the execution stops and its status becomes `failed`.

There is no automatic fallback. After the retries run out, the execution fails.

Execution results report the execution `status` and `stepResults`. A failed step provides `stepNumber`, `nodeId`, `status`, and `errorMessage`, with `statusCode` and `errorClass` when available. The `output` field is optional.

## Retry and circuit breaker

***

Flowker includes built-in resilience for executor calls.

### Retries

When an executor call fails with a transient error (a network error, a timeout on the attempt, any `5xx` status, or status `408` or `429`), Flowker retries automatically. Retry behavior is configurable per node, in the executor node's `data`:

| Setting | Default | Bounds | Description |
| - | - | - | - |
| `timeout_seconds` | 30 | 1–300 | Per-request timeout. |
| `retry.max_attempts` | 3 (1 for unconfigured `POST` and `PATCH`) | 1–10 accepted; 1–5 effective | Accepts `1`–`10` in the node schema, but Flowker clamps the effective runtime attempt count to `1`–`5`. |
| `retry.backoff_seconds` | 1 | 1–60 | First backoff ceiling; each wait is a random value between zero and the ceiling, which doubles per attempt. |
| `success_status_codes` | `[200, 201, 202, 204]` | 100–599 | HTTP status codes treated as success. |

Retries only apply when the operation is safe to repeat. By default, Flowker treats `POST` and `PATCH` calls as non-idempotent and does **not** retry them (a single attempt), while `GET`, `PUT`, `DELETE`, and other verbs retry normally. A `retry.max_attempts` greater than `1` opts that node into retries whatever the method is. A `retry.max_attempts` of `1` is not an opt-in. It sets a single attempt.

**Non-retryable errors** short-circuit to a single attempt regardless of configuration. They are: circuit breaker open, context cancelled, configuration errors, and secret-resolution failures. They also include a request body over the configured size cap, a provider response body over the same cap, and non-transient `4xx` provider responses. That means any `4xx` except `408` and `429`.

The retry applies per node execution. If all attempts fail, the step fails and the execution stops.

### Circuit breaker

Flowker uses a circuit breaker so that repeated failing calls do not overwhelm external services:

| Parameter | Value |
| - | - |
| Failure threshold | 20 consecutive failures opens the circuit |
| Recovery timeout | 30 seconds before trying again (half-open state) |
| Half-open requests | 1 request allowed to test if the service recovered |

A provider `4xx` response does **not** count toward the threshold, except `408` and `429`: it reflects the request, not the health of the provider.

When the circuit is open, executor calls fail immediately with `FLK-0507` instead of reaching the external service. This prevents cascading failures and gives the external service time to recover.

![Circuit breaker states](https://mintcdn.com/lerian-49cb71fc/Mmb3JaVhlcaSV8yn/images/en/d2/flowker-circuit-breaker.svg?fit=max\&auto=format\&n=Mmb3JaVhlcaSV8yn\&q=85\&s=60f59fb0d092e1f2ad73ea4b7628627e)

Circuit breaker state transitions

The circuit starts in the **Closed** state, where all requests pass through normally. After the circuit reaches the failure threshold, it transitions to **Open** and blocks all requests immediately. After 30 seconds, it moves to **Half-Open** and allows one test request. If that request succeeds, the circuit returns to Closed. If it fails, the circuit reopens for another 30-second cycle.

> [!WARNING]
>
> The circuit breaker operates per provider configuration, scoped to your tenant. Failures against one connection do not affect another, and one tenant cannot open the circuit for another. Circuit breaker thresholds (failure count, recovery timeout) are global deployment defaults. You cannot customize them per connection.

## What's next

***

> **[Core concepts](/en/products/flowker/flowker-concepts)**
>
> Understand workflows, nodes, edges, and executions.

> **[Provider configurations API](/en/reference/products/flowker/list-provider-configurations)**
>
> Explore the provider configuration API.


# Running a workflow on a schedule
Source: https://docs.lerian.studio/en/products/flowker/running-a-workflow-on-a-schedule

Start a Flowker workflow on a cadence, read the occurrences it plans to run, and decide what happens to an occurrence that could not run on time.

A schedule trigger starts a workflow on a cadence you write as a cron expression. Flowker records the next firing as an occurrence. An occurrence that cannot run on time waits in a parked list until you run it or discard it.

Use this page to write the trigger, confirm the cadence, and work the parked list.

## Before you start

***

* A workflow in `draft` status. Only a draft workflow accepts an edit, so write the trigger before you activate it. See [Step 4: Run the workflow](/en/products/flowker/integration-guide#step-4-run-the-workflow) for the create-and-activate path.
* The `read` permission on the `workflows` resource to list occurrences and counts, and `update` on the same resource to run or discard one.

## Step 1: Write the schedule trigger node

***

Triggers come built in. You discover them in the catalog, and you never create one. [Get a catalog trigger](/en/reference/products/flowker/get-catalog-trigger) returns the schedule trigger's JSON Schema from the running instance:

```bash theme={null}
curl -s https://your-flowker-host/v1/catalog/triggers/schedule \
  -H "Authorization: Bearer <token>" | jq -r '.schema' | jq .
```

The schedule trigger is a node with `type: "trigger"` and these fields in its `data`:

| Field | When you set it | Value |
| - | - | - |
| `triggerType` | Always | `"schedule"`. |
| `cron` | Always | The cadence, as a standard 5-field cron expression: `minute hour day-of-month month day-of-week`. |
| `timezone` | Optional | The IANA identifier of the zone the cron fields belong to, such as `"America/Sao_Paulo"`. Defaults to `UTC`; an empty timezone is also evaluated as `UTC`. A name that is not an IANA zone fails with `FLK-0119` when you save or activate the workflow. |
| `enabled` | Optional | `false` stops the schedule from firing while the workflow stays active. Defaults to `true`. |
| `inputData` | Optional | An object that starts every run. The workflow reads it as `workflow.*`, the way a webhook run reads its request body. |

### What the cron expression accepts

Five fields, separated by spaces. Each field takes `*`, a value, a list (`0,30`), a range (`9-17`), or a step (`*/15`, `9-17/2`). Day-of-week runs `0`–`7`, where both `0` and `7` mean Sunday. When you restrict day-of-month and day-of-week at the same time, the schedule fires on a day that matches either field. The expression `0 9 13 * 5` fires on the 13th and on every Friday.

One minute is the finest cadence a 5-field expression can express. For anything faster, take the call in as it arrives with a [webhook trigger](/en/products/flowker/configuring-a-webhook-trigger).

Flowker checks the expression when you save the workflow and again when you activate it, and answers `FLK-0117` when it does not hold. These forms do not hold:

* A six-field expression, such as `*/30 * * * * *`.
* A macro, such as `@daily` or `@every 5m`.
* A named day or month, such as `MON`, `MON-FRI` or `sun`.
* An `L` or `#` token, such as `0 9 L * *` or `0 9 * * 5#2`.
* A value outside its field's range, such as `60` minutes, `24` hours, day-of-month `0` or `32`, month `13`, or day-of-week `8`.
* A `/0` step.

### How the timezone works

The cron fields are wall-clock time in the zone you name, and every time the API returns is UTC. A `0 9 * * *` schedule in `America/Sao_Paulo` reports `12:00Z`. A zone that observes daylight saving keeps the wall-clock hour across the change: the same expression in `America/New_York` reports `14:00Z` in winter and `13:00Z` in summer.

```json daily theme={null}
{
  "id": "trigger-1",
  "type": "trigger",
  "name": "Daily settlement",
  "position": { "x": 0, "y": 0 },
  "data": {
    "triggerType": "schedule",
    "cron": "0 9 * * *",
    "timezone": "America/Sao_Paulo"
  }
}
```

```json every 15 minutes theme={null}
{
  "id": "trigger-1",
  "type": "trigger",
  "name": "Poll for new statements",
  "position": { "x": 0, "y": 0 },
  "data": {
    "triggerType": "schedule",
    "cron": "*/15 * * * *"
  }
}
```

```json weekdays, paused theme={null}
{
  "id": "trigger-1",
  "type": "trigger",
  "name": "Weekday reconciliation",
  "position": { "x": 0, "y": 0 },
  "data": {
    "triggerType": "schedule",
    "cron": "30 7 * * 1-5",
    "timezone": "America/Sao_Paulo",
    "enabled": false
  }
}
```

```json monthly theme={null}
{
  "id": "trigger-1",
  "type": "trigger",
  "name": "Month-open batch",
  "position": { "x": 0, "y": 0 },
  "data": {
    "triggerType": "schedule",
    "cron": "0 3 1 * *",
    "timezone": "UTC"
  }
}
```

## Step 2: Activate the workflow and read the cadence

***

**1. Save the workflow**

Send the node with the rest of your workflow to [Create a workflow](/en/reference/products/flowker/create-workflow), or to [Update a workflow](/en/reference/products/flowker/update-workflow) if the draft already exists. Flowker validates the cron here.

**2. Check the cadence before you commit to it**

[List upcoming scheduled occurrences](/en/reference/products/flowker/list-upcoming-scheduled-occurrences) computes the next firings straight from the trigger, so you can read them while the workflow is still a draft.

```bash theme={null}
curl -s "https://your-flowker-host/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/schedule/upcoming?limit=3" \
  -H "Authorization: Bearer <token>" | jq .
```

```json theme={null}
{
  "occurrences": [
    { "scheduledFor": "2026-08-01T12:00:00Z" },
    { "scheduledFor": "2026-08-02T12:00:00Z" },
    { "scheduledFor": "2026-08-03T12:00:00Z" }
  ]
}
```

`limit` takes `1` to `50` and defaults to `10`. A value outside that range answers `FLK-0304`.

**3. Activate it**

Call [Activate a workflow](/en/reference/products/flowker/activate-workflow). The leader-gated producer sweeps every 60 seconds. After a successful sweep, Flowker records and queues the next occurrence for its slot.

```bash theme={null}
curl -s -X POST https://your-flowker-host/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/activate \
  -H "Authorization: Bearer <token>" | jq .
```

Flowker records only the next firing, never a calendar of future firings. When that occurrence runs, the engine records the firing after it, so the cadence carries itself forward one occurrence at a time.

## Step 3: See which occurrences did not run

***

An occurrence **parks** when the engine reaches it more than a minute after its slot and nobody has asked for that slot to run. Common causes are a service that was down, a queue that was behind, or a process that restarted. Flowker never runs a parked occurrence on its own. It holds it for your decision, in the `pending-review` state.

An occurrence also parks when the queue gives up on it before its run starts. A run that starts and then fails is recorded as failed. A parked occurrence stays available to the run and discard endpoints.

Flowker never back-fills a slot that passed. So the parked list holds the firings Flowker had already recorded and could not run. It does not hold one entry for every slot that went by during an outage. The cadence itself resumes from the next future slot.

An occurrence is **skipped** when the engine took it up and closed it without running the workflow. The scheduler never runs a skipped occurrence again. A skipped occurrence carries a `skipReason`, and the run and discard endpoints do not accept it:

| `skipReason` | What happened |
| - | - |
| `active-run` | Another run of this workflow was still going. A schedule runs one occurrence at a time, so this firing stood down. |
| `workflow-gone` | The workflow was deleted, or it was not active when the occurrence reached the engine. |
| `execution-duplicate` | The work for that slot had already run, so the engine did not run it twice. |

The two classes do not split on timing, with one exception. A late slot you never asked to run lands in the parked list, never in the skipped list. After you ask for a parked slot to run, its age stops holding it back. The engine then takes it up like any other occurrence, and all three reasons above can close it. So a `scheduledFor` far in the past is normal in the skipped list, and it does not mean the slot fired on time. [Step 4](#step-4-run-or-discard-a-parked-occurrence) covers what your own run can end in.

Three reads cover the whole picture:

**1. List the parked occurrences of one workflow**

[List parked scheduled occurrences](/en/reference/products/flowker/list-parked-scheduled-occurrences) returns them oldest first.

```bash theme={null}
curl -s https://your-flowker-host/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/schedule/missed \
  -H "Authorization: Bearer <token>" | jq .
```

```json theme={null}
{
  "occurrences": [
    {
      "id": "019c96a0-3f21-7b44-8d0e-5a1c7e2b9f30",
      "workflowId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
      "status": "pending-review",
      "cronExpr": "0 9 * * *",
      "timezone": "America/Sao_Paulo",
      "scheduledFor": "2026-07-29T12:00:00Z",
      "attempts": 0,
      "createdAt": "2026-07-29T11:00:04Z",
      "updatedAt": "2026-07-30T08:12:41Z"
    }
  ]
}
```

`scheduledFor` is the slot the occurrence stands for, and `status` is what decides whether you can act on it.

This route takes no `limit` and no page cursor, and it returns at most 100 occurrences. Plan a bulk recovery around that: work the rows you get, then read the list again.

The count below reports the total in `pending-review`. The parked list can hold more rows than that count, because it also includes `missed` occurrences. The `missed` state is short-lived: a late slot holds it while the engine parks the slot as `pending-review`. The run and discard endpoints do not accept that state, so read the list again and act once the row shows `pending-review`. Discarding the whole list also covers every occurrence pending review, not only the 100 a single read shows you.

**2. List the skipped occurrences**

[List skipped scheduled occurrences](/en/reference/products/flowker/list-skipped-scheduled-occurrences) returns them oldest first, each with its `skipReason`. When supplied, `limit` takes `1` to `50`. When omitted, it defaults to `100`.

```bash theme={null}
curl -s "https://your-flowker-host/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/schedule/skipped?limit=10" \
  -H "Authorization: Bearer <token>" | jq '.occurrences[] | {scheduledFor, skipReason}'
```

```json theme={null}
{ "scheduledFor": "2026-07-28T12:00:00Z", "skipReason": "active-run" }
```

Repeated `active-run` skips mean the workflow takes longer than the gap between two firings. Widen the cadence, or make the workflow finish faster.

**3. Count what is waiting across every workflow**

[Count pending-review occurrences](/en/reference/products/flowker/count-pending-review-occurrences) answers for the whole tenant in one call, which is what you poll for a review badge. The map is sparse: a workflow with nothing waiting is absent from it.

```bash theme={null}
curl -s https://your-flowker-host/v1/workflows/schedule/pending-review-counts \
  -H "Authorization: Bearer <token>" | jq .
```

```json theme={null}
{
  "counts": {
    "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a": 2
  }
}
```

Add `?workflowIds=<id>,<id>` to scope the counts to the workflows you care about.

Both lists answer `200` with an empty `occurrences` array for a workflow id your tenant does not own, so an empty list means "nothing to review here".

Flowker exposes the underlying schedule data through its upcoming, parked, and pending-review-count APIs. Consult the Console documentation for UI guidance.

## Step 4: Run or discard a parked occurrence

***

Run and discard act on an occurrence whose `status` is `pending-review`. Any other state answers `FLK-0755`, which also makes a repeated call safe: the second call answers an error instead of acting twice. Your own run puts the occurrence in one of those other states: it leaves `pending-review` straight away.

A run you ask for leaves the parked list at once, and the age of the slot no longer holds it back. It does not promise that the workflow runs:

* **The workflow runs.** The execution appears in [List executions](/en/reference/products/flowker/list-executions) for that workflow.
* **The engine closes the occurrence as skipped.** It leaves the parked list for the skipped list with one of the three reasons above. An `active-run` reason means another run of the workflow was still in progress. A `workflow-gone` reason means the workflow was not active when your run reached the engine. An `execution-duplicate` reason means the work for that slot had already run.

After your run, the scheduler never runs a skipped occurrence again, and the run and discard endpoints do not accept it. Read both lists before you conclude anything about a slot you tried to recover. The skipped row may record the refusal of your recovery, not of the original firing.

Keep the workflow active while you work the list. A run reloads the workflow, and a workflow that is not active closes the occurrence as a `workflow-gone` skip instead of running it.

**1. Run one occurrence**

[Run a parked occurrence](/en/reference/products/flowker/run-parked-occurrence) moves it to `queued` and enqueues a force-run on the same execution path a scheduled firing uses. The delayed-task forwarder checks every second. Actual start time depends on worker availability and queue capacity.

```bash theme={null}
curl -s -X POST https://your-flowker-host/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/schedule/missed/019c96a0-3f21-7b44-8d0e-5a1c7e2b9f30/run \
  -H "Authorization: Bearer <token>" | jq '{id, status}'
```

```json theme={null}
{ "id": "019c96a0-3f21-7b44-8d0e-5a1c7e2b9f30", "status": "queued" }
```

The run covers that one slot. It does not shift the cadence: the next firing stays the one the engine already planned.

**2. Discard one occurrence**

[Discard a parked occurrence](/en/reference/products/flowker/discard-parked-occurrence) moves it to `discarded`, which is terminal. The occurrence never executes and leaves the parked list.

```bash theme={null}
curl -s -X POST https://your-flowker-host/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/schedule/missed/019c96a0-3f21-7b44-8d0e-5a1c7e2b9f30/discard \
  -H "Authorization: Bearer <token>" | jq '{id, status}'
```

```json theme={null}
{ "id": "019c96a0-3f21-7b44-8d0e-5a1c7e2b9f30", "status": "discarded" }
```

**3. Clear the whole parked list of one workflow**

[Discard all parked occurrences](/en/reference/products/flowker/discard-all-parked-occurrences) discards, in a single write, every occurrence of that workflow pending review, and reports how many it moved.

```bash theme={null}
curl -s -X POST https://your-flowker-host/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/schedule/missed/discard-all \
  -H "Authorization: Bearer <token>" | jq .
```

```json theme={null}
{ "discarded": 7 }
```

With nothing pending review it answers `200` with `"discarded": 0`, so a repeat call is safe.

> [!WARNING]
>
> A discard cannot be undone, and it never runs anything. Read the parked list before you clear it.
>
> Discarding all parked occurrences covers exactly the occurrences of that one workflow, in your tenant, pending review. It leaves the schedule itself running and leaves the upcoming occurrences alone. It does not touch another workflow's occurrences, or occurrences that already ran, failed, were skipped, or were discarded earlier.

## Confirm it worked

***

* The cadence is healthy when [List upcoming scheduled occurrences](/en/reference/products/flowker/list-upcoming-scheduled-occurrences) returns future slots and the parked list stays short.
* A run worked when the occurrence has left the parked list and the execution shows up in [List executions](/en/reference/products/flowker/list-executions) for that workflow.
* A discard worked when the occurrence has left the parked list and the pending-review count for that workflow has dropped.

## Change or pause a cadence

***

Only a draft workflow accepts an edit, so a cadence change is four calls:

1. [Deactivate the workflow](/en/reference/products/flowker/deactivate-workflow). Flowker stops recording new occurrences for it.
2. [Move it to draft](/en/reference/products/flowker/move-workflow-to-draft).
3. [Update the workflow](/en/reference/products/flowker/update-workflow) with the new `cron`, `timezone`, or `enabled` value.
4. [Activate it](/en/reference/products/flowker/activate-workflow). The leader-gated producer sweeps every 60 seconds. After a successful sweep, Flowker records and queues the next occurrence from the new cadence.

Flowker does not back-fill the slots that passed while the workflow was inactive. The parked occurrences survive all four steps. They stay listed and stay actionable once the workflow is active again.

> [!NOTE]
>
> A parked occurrence Flowker recorded before the change remains pending review. Read the parked list after a cadence change, and clear anything you no longer want.

## When something goes wrong

***

| Code | When it happens | What to do |
| - | - | - |
| `FLK-0117` | You save or activate the workflow. | The cron is not a standard 5-field expression. Compare it against [What the cron expression accepts](#what-the-cron-expression-accepts). |
| `FLK-0119` | You save or activate the workflow. | The `timezone` is not an IANA zone name. Use an identifier such as `America/Sao_Paulo`. |
| `FLK-0118` | You list the upcoming occurrences. | The workflow carries no schedule trigger, or its cron is not an expression Flowker can compute. Check the trigger node's `triggerType` and `cron`. |
| `FLK-0100` | You list the upcoming occurrences. | No workflow in your tenant has that id. |
| `FLK-0002` | Any of these calls. | A path id is not a valid UUID. |
| `FLK-0304` | You list upcoming or skipped occurrences. | `limit` is outside `1`–`50`. |
| `FLK-0755` | You run or discard an occurrence. | The occurrence is not pending review. Your own run may have moved it on already, or it may have run, been skipped, or been discarded. Read the parked list and the skipped list before you call again. |
| `FLK-0760` | You run or discard an occurrence. | No occurrence of that workflow has that id. Take the id from the parked list of the same workflow. |
| `FLK-0762` | You run an occurrence. | A run of that occurrence is already in flight. Read the parked list and the skipped list before you call again. |
| `FLK-0763` | Any of these calls. | The scheduler is temporarily unavailable for your tenant. Listing and discarding may still work. If it persists, contact Lerian support. |

Two failures answer no error code:

* **The upcoming list shows occurrences, but nothing ever runs.** Confirm that the trigger node has `enabled` set to `true` and that the workflow is active. If both hold and nothing runs, contact Lerian support with the workflow id.
* **Flowker records nothing new for an active workflow.** Check `enabled` on the trigger node: `false` keeps the workflow active and its schedule quiet.

## What's next

***

> **[Configuring a webhook trigger](/en/products/flowker/configuring-a-webhook-trigger)**
>
> Start the same workflow from an inbound HTTP call instead of a cadence.

> **[Workflow design guide](/en/products/flowker/workflow-design-guide)**
>
> Build the rest of the graph the trigger enters.


# Security
Source: https://docs.lerian.studio/en/products/flowker/security

Protect Flowker workflows, data, and integrations with Access Manager authentication, per-connection credentials, and TLS on every API call.

Flowker protects your workflows, data, and integrations through Access Manager authentication and per-connection credential management. Lerian serves the API over TLS. This page covers the security model as implemented in the current release.

## Platform authentication

***

Flowker delegates platform authentication to **Access Manager**. Every request to a protected API route must carry a Bearer token (OIDC JWT), and each protected route enforces a per-resource, per-action permission. This is how role- and policy-based authorization works.

```bash theme={null}
curl -X GET https://your-flowker-instance/v1/workflows \
  -H "Authorization: Bearer <token>"
```

Invalid or missing credentials return `401 Unauthorized`.

## Provider authentication

***

When Flowker calls an external service, it authenticates with the credentials on the provider configuration that the node calls through. Your platform credentials and your provider credentials stay separate.

**Supported authentication types:**

| Type | Description | Use case |
| - | - | - |
| `none` | No authentication | Internal services behind a VPN or service mesh |
| `api_key` | API Key sent as header or query parameter | Third-party APIs with key-based access |
| `bearer` | Bearer token in the `Authorization` header | Services using static or pre-generated tokens |
| `basic` | HTTP Basic authentication (username:password) | Legacy systems or internal APIs |
| `oidc_client_credentials` | OAuth 2.0 client credentials flow | Machine-to-machine integrations with identity providers |
| `oidc_user` | OAuth 2.0 user token flow | Integrations that act on behalf of a specific user |
| `oauth2_token_endpoint` | OAuth 2.0 client credentials against a token endpoint (no OIDC discovery) | OAuth2-style providers without OIDC discovery metadata |
| `hmac` | Request signing with a shared HMAC secret | Providers that verify a request signature header |

The `config.auth` block on the provider configuration holds the authentication the external service requires, as a `{ type, config }` pair. Flowker applies it to every call a node makes through that connection.

A read never returns the credential the authentication type declares. Store credentials only in the fields the authentication type declares.

To rotate a secret, send the new value in an update. To keep the current one, omit the field or send it blank. This works while `auth.type` stays the same. An update that changes `auth.type` must carry a value for each secret the new type requires and the previous one did not. Otherwise, Flowker rejects it with `FLK-0952`. A change between two types that use the same secret, such as `oidc_user` to `oidc_client_credentials`, does not need that value again.

```json theme={null}
{
  "config": {
    "auth": {
      "type": "bearer",
      "config": {
        "token": "eyJhbGciOiJSUzI1NiIs..."
      }
    }
  }
}
```

> [!NOTE]
>
> For OIDC flows (`oidc_client_credentials` and `oidc_user`), Flowker handles token acquisition and refresh automatically. For `oidc_client_credentials`, provide the issuer URL, client ID, and client secret. For `oidc_user`, provide the issuer URL, client ID, username, and password. `client_secret` is optional for public clients.

## Network security

***

**TLS:**

* Lerian terminates TLS for Flowker API traffic.
* Use `https://` base URLs for external calls. Flowker accepts a URI for the generic HTTP provider's `base_url`. It does not restrict it to HTTPS.
* Transmit credentials and sensitive payloads only over encrypted links.

**CORS configuration:**

Flowker applies these CORS rules:

* Only allowed origins can call the API from a browser. To add an origin, contact Lerian support
* Cross-origin requests cannot carry credentials (`AllowCredentials` stays off)
* Preflight responses tell the browser to cache them for one hour

## Resilience

***

Flowker protects against cascading failures from external services using circuit breaker and retry patterns.

**Circuit breaker:**

When an external service fails repeatedly, the circuit breaker opens and stops sending requests. This prevents your workflows from hanging on an unresponsive provider.

* Transitions through `closed` → `open` → `half-open` states
* Each circuit applies to one provider configuration and one tenant, so failures against one connection do not affect another
* The half-open state allows a limited number of test requests before fully closing

**Retries:**

Flowker resolves the retry budget for each node with the first two rules. The failure class then decides whether that budget is spent:

1. **Node opt-in.** A `retry.max_attempts` greater than `1` turns retries on whatever the method is. The value is the total attempt count, and the platform caps it at 5. A `retry.max_attempts` of `1` is not an opt-in. It sets a single attempt.
2. **HTTP method.** With no opt-in, Flowker treats `POST` and `PATCH` as non-idempotent and gives them a single attempt. Every other verb retries, with 3 total attempts by default. This includes `GET`, `HEAD`, `OPTIONS`, `PUT`, and `DELETE`.
3. **Failure class.** The budget is spent only on a transient failure: a network error, a timeout on the attempt, any `5xx` status, or status `408` or `429`. Every other `4xx` fails on the first attempt however high the budget is. An open circuit and a cancelled execution also stop the loop. A request body over the configured size cap and a response body over the same cap stop it too.

Backoff is exponential with full jitter. Each wait is a random value between zero and a ceiling. The ceiling starts at 1 second and doubles on each attempt. `retry.backoff_seconds` sets the first ceiling, between 1 and 60. The random wait prevents many executions from retrying the same service at the same moment.

## What's next

***

> **[Integration guide](/en/products/flowker/integration-guide)**
>
> Learn how to create provider configurations and connect external services.

> **[Observability](/en/products/flowker/flowker-observability-guide)**
>
> Track workflow runs through their execution records.


# Use cases
Source: https://docs.lerian.studio/en/products/flowker/use-cases

Common financial scenarios where Flowker orchestrates validation, provider calls, and data routing.

Flowker targets the operations of financial institutions. This page walks through five common scenarios for structuring workflows. The controls and outcomes depend on the external systems and integration enforcement you configure.

## Transaction validation

***

### The problem

When validation happens **after** a transaction is written to the ledger, the damage is already done. Invalid writes create compliance violations, trigger costly rollbacks, and erode data integrity. Remediation is expensive, time-consuming, and often incomplete.

### How Flowker solves it

Use a Flowker workflow to orchestrate KYC, AML, fraud-scoring, and balance-validation calls before a ledger-posting step. You define the sequence in the order your compliance policies require. Your ledger integration must enforce that no other path can post without the required checks.

If a validation node fails, the workflow execution fails. Execution records capture the configured processing steps and their results.

### Business outcome

* **Configurable validation path**: place the checks required for your operation before its posting step
* **Execution records**: inspect configured processing steps and their results
* **Integration-owned posting control**: enforce the required checks at the ledger boundary

## Customer onboarding (KYC/AML)

***

### The problem

Customer onboarding in financial services involves identity verification, document checks, AML screening, and risk scoring, often spread across multiple systems, teams, and manual handoffs. It can be difficult to see where a customer is in the process or which checks have completed.

### How Flowker solves it

Flowker lets you define the entire onboarding sequence as a single workflow: identity verification, then document check, then AML screening, then risk scoring. Each step calls the appropriate external provider automatically. Conditional logic routes customers to enhanced verification when risk scores exceed your thresholds.

The workflow tracks every step, so you always know exactly where each customer is in the process.

### Business outcome

* **Automated sequencing**: structure the configured checks and handoffs in one workflow
* **Standardized process**: every customer goes through the same validated steps, regardless of which team handles them
* **Evidence-ready**: the execution record shows exactly what checks ran, when, and with what results

## Payment orchestration

***

### The problem

Payment routing involves multiple providers, each with different APIs, authentication methods, and response formats. Building and maintaining custom integrations for each provider consumes engineering resources and creates fragile, hard-to-change payment flows.

### How Flowker solves it

Flowker coordinates multi-step payment flows as a single workflow: fraud check, then balance verification, then payment gateway call, then confirmation. You configure each service instance once as a provider configuration that holds its base URL and credentials. Every workflow node that calls it carries its own field mappings. If a provider call fails on a transient error, Flowker retries it automatically with exponential backoff. A `POST` or `PATCH` call runs once unless the node opts into retries. Circuit breakers prevent cascading failures when a provider goes down.

### Business outcome

* **Consistent payment processing**: every payment follows the same validated path
* **Automatic failure recovery**: Flowker retries transient errors without manual intervention
* **Provider resilience**: circuit breakers isolate failing providers so the rest of your operations continue

## Fraud detection workflows

***

### The problem

In many systems, fraud checks come after the transaction is already in progress, or worse, after it's committed. By the time a fraudulent transaction is flagged, the financial and reputational damage may already be done.

### How Flowker solves it

Use Flowker to run fraud scoring before the posting or action step that you configure. Conditional branching lets you define different paths based on risk level. Low-risk transactions can continue. Medium-risk transactions can trigger additional verification. High-risk transactions can route to a rejection path.

The integration that posts or acts on the transaction must enforce that its required Flowker checks ran. A workflow definition alone cannot block another system path.

### Business outcome

* **Risk decisions in the configured flow**: place fraud scoring before the posting or action step
* **Risk-based routing**: different risk levels trigger different responses automatically
* **Traceable workflow checks**: inspect the configured score, branch, and execution record

## Provider integration acceleration

***

### The problem

Integrating an external provider involves its API contract, authentication, error handling, security review, and testing. The effort varies by provider and by the controls your integration requires.

### How Flowker solves it

Flowker separates the connection from the workflow logic. You create a provider configuration (base URL, credentials, and the hosts it may call) and reference it from workflow nodes. The mappings that reshape data for that service live on the node. You can update settings of an existing provider configuration. A migration that changes provider, executor, or provider-configuration ID can also require updates to draft workflow nodes.

Flowker validates catalog provider configurations against the provider JSON Schema. `external_openapi` configurations use dedicated external OpenAPI and configuration validation.

### Business outcome

* **Centralized configuration and mappings**: keep connection settings and node mappings in their respective workflow surfaces
* **Reusable across workflows**: configure a provider once, use it everywhere
* **Provider migration control**: update settings directly and update draft nodes when their provider or executor reference changes

## What's next

***

> **[Getting started](/en/products/flowker/flowker-getting-started)**
>
> Set up Flowker and run your first workflow end to end.

> **[Integration guide](/en/products/flowker/integration-guide)**
>
> Learn how to create provider configurations for your workflows.


# What is Flowker?
Source: https://docs.lerian.studio/en/products/flowker/what-is-flowker

Orchestrate financial workflows with Flowker. Coordinate anti-fraud checks, external approval systems, payment routing, and onboarding with step-level execution records.

**Flowker** is Lerian's workflow orchestration platform for financial operations. It coordinates the steps around a transaction: anti-fraud checks, calls to external approval systems, payment routing, customer onboarding, and more.

Instead of building custom logic for each approval flow or validation step, you define workflows once and Flowker executes them consistently, with step-level execution records and real-time visibility.

## Why use Flowker?

***

Financial operations involve multiple steps, approvals, and external checks. Managing these manually leads to errors, delays, and compliance gaps. Flowker centralizes this orchestration so every step stays traceable and repeatable. For the full business case, see [Why Flowker?](/en/products/flowker/why-flowker).

## Core concepts

***

Flowker works with workflows and nodes:

* **Workflows**: The overall process, a graph of nodes and edges that defines what happens for a given operation. For example, "process a Pix payment" or "onboard a new customer". Workflows can branch, and retry policy can retry eligible executor-call failures.
* **Nodes**: The individual elements in a workflow, such as a trigger, an external-service call, a condition, or an action.

The workflow graph determines routing. Conditional nodes select an outgoing edge from the execution context, while other node types follow their outgoing edges after completing successfully.

## What makes Flowker different?

***

### Purpose-built for the financial domain

Flowker is modeled for the transactional ecosystem. Its architecture reflects the operational and regulatory realities of banking, payments, Pix, and financial orchestration.

### Pre-ledger validation

Use Flowker to orchestrate validation calls before a ledger-posting step. Your ledger integration must enforce that no other path can post without the required checks.

### Integrations with APIs and webhooks

Flowker receives webhooks and calls external services through provider configurations. You define input and output expectations, then configure the provider connection and the nodes that call it.

### Step-level execution records

Each executed executor, conditional, or action node records its status, duration, output, and error message. Trigger nodes start graph traversal and do not create execution-step records.

This gives you a step-by-step view of what each execution did through the API.

### Enterprise-grade security

Token-based authentication through Access Manager, with per-resource, per-action authorization. Lerian serves the API over TLS.

## Features by area

***

### Workflow orchestration

* Run nodes according to the workflow graph and selected conditional branches.
* Apply conditional logic based on HTTP status codes and response fields.
* Persist workflow execution state for review.
* Manage versions with full lifecycle control, including draft, activation, deactivation, and clone-based iteration.

### Integration and connectivity

* Send HTTP requests (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS).
* Receive and process webhooks from external systems.
* Connect to multiple financial service providers.

### Workflow configuration

* Define workflows as graphs of nodes and edges.
* Validate workflow definitions before activation.
* Map and transform data between executor calls.

### Authentication and security

* Token-based authentication through Access Manager, with per-resource, per-action authorization.
* Structured logs. Lerian encrypts stored data and secrets at rest.

### Observability

Lerian monitors Flowker's API and service operations.

Use execution records to investigate workflow behavior.

## Common use cases

***

### Anti-fraud operations

* Send transaction and account data to external fraud prevention services.
* Collect and process responses from multiple providers, and apply configurable rules to decide whether to proceed.
* Every step is recorded with its status and result.

### Manual approvals

* Submit a request to, or query, an external approval system with executor nodes.
* Route on the decision that the external system returns.
* Flowker does not have a built-in pause. Model asynchronous human review with an external system and a later workflow trigger or execution.

### Payment orchestration

* Coordinate multi-step payment flows that span multiple providers or rails.
* Flowker can retry eligible executor-call failures. Reconciliation and posting controls belong to the systems you integrate.

### Customer onboarding

* Automate KYC and AML processes, integrate with credit bureaus and validation services, and set up conditional onboarding rules based on risk profiles.

## API architecture

***

Flowker’s API has three main categories: **Authoring**, **Runtime**, and **Administrative**.

* **Authoring routes**: create, update, and manage workflow definitions and versions.
* **Runtime routes**: start and monitor workflow executions.
* **Administrative routes**: manage provider configurations and system health.

## Current status

***

For additional information about specific integrations or implementation details, [contact us](https://lerian.studio/contact).

> [!TIP]
>
> [Explore the Flowker API](/en/reference/products/flowker/create-workflow). Browse endpoints for workflows, executions, and provider configurations.


# Why Flowker?
Source: https://docs.lerian.studio/en/products/flowker/why-flowker

How Flowker centralizes provider configuration, workflow routing, and execution records for financial operations.

Financial institutions need to integrate providers, validate transactions, and preserve evidence for compliance. Flowker centralizes workflow routing, provider configuration, and execution records. The controls and outcomes still depend on the systems and integration boundaries you configure.

## The problem

***

Financial services teams face these challenges:

* **Variable provider-integration effort**: each provider has its own API contract, authentication, error handling, security review, and test scope
* **Scattered validation evidence**: validation data is spread across multiple systems, making it difficult to reconstruct what happened during audits
* **Compliance gaps**: when validation happens after the ledger write, invalid transactions create regulatory exposure
* **Provider migration complexity**: changing provider, executor, or provider-configuration reference can require updates to draft workflow nodes
* **Costly rollbacks**: invalid ledger writes require expensive manual remediation and damage data integrity

## How Flowker changes this

***

Flowker provides one orchestration platform for workflow routing, provider configuration, mappings, and execution records.

| | Before Flowker | With Flowker |
| - | - | - |
| **Provider integration** | Provider-specific integration work | Centralize provider configuration and node mappings |
| **Step traceability** | Partial, scattered across systems | Every executed processing node recorded automatically |
| **Provider flexibility** | Changes can require integration work | Update settings; update draft nodes when references change |
| **Validation model** | Depends on the integration boundary | Orchestrate checks before a configured posting step; enforce at the ledger boundary |
| **Failure handling** | Custom retry logic per integration | Built-in retries and circuit breakers |
| **Workflow visibility** | Limited, requires log aggregation | Full execution tracking with step-level detail |

## For compliance teams

***

Compliance teams need to prove that every transaction was validated correctly.

Flowker gives compliance teams:

* **Step-level traceability**: every execution records each executed processing node with its status, duration, output, and error message
* **Queryable execution history**: filter executions by workflow and status, then read the step detail of any execution through the API
* **Integration-owned posting control**: use Flowker to orchestrate checks before a ledger-posting step, then enforce them at the ledger boundary

> [!NOTE]
>
> Flowker records execution steps automatically. You do not need to enable or configure anything.

## For engineering teams

***

Engineering teams need to integrate providers quickly, handle failures gracefully, and stop rebuilding the same integration plumbing for every new service.

Flowker gives engineering teams:

* **Configure once, reuse everywhere**: set up a service instance's base URL and credentials once as a provider configuration, then reference it from any workflow node
* **Built-in resilience**: circuit breakers prevent cascading failures when providers go down. Retries with exponential backoff handle transient errors. A `POST` or `PATCH` call runs once unless the node opts into retries
* **Configuration and mappings**: centralize connection settings and node mappings in their workflow surfaces
* **Configuration validation**: catalog configurations use the provider JSON Schema. `external_openapi` configurations use dedicated external OpenAPI and configuration validation
* **Field mapping and data transformation**: map workflow fields to provider-specific formats without writing transformation code

## For product teams

***

Product teams need to ship faster, respond to market changes, and measure what's working, without waiting months for engineering to build or modify validation flows.

Flowker gives product teams:

* **Faster time to market**: new validation workflows can be defined and deployed without waiting for custom integration work
* **Flexibility without code changes**: add, remove, or reorder validation steps by updating workflow definitions, not by requesting engineering sprints
* **Observable and measurable operations**: execution records and deployment telemetry provide evidence for workflow investigation

## What's next

***

> **[Use cases](/en/products/flowker/use-cases)**
>
> See how Flowker applies to transaction validation, onboarding, payments, and more.

> **[Getting started](/en/products/flowker/flowker-getting-started)**
>
> Set up Flowker and run your first workflow end to end.


# Workflow Design Guide
Source: https://docs.lerian.studio/en/products/flowker/workflow-design-guide

Design Flowker workflows: node types, edges, real-world patterns, status transitions, and best practices for reliable orchestration.

This guide walks through node types, edges, real-world patterns, status transitions, technical limits, and best practices.

## Node types

***

Every workflow consists of nodes. Each node has a `type` that defines how Flowker processes it at runtime.

### trigger

A trigger node is an execution entry point. Draft workflows can be incomplete, but activation requires at least one trigger node.

The examples on this page show node topology only. A real trigger node also carries a `triggerType` and that trigger's configuration in its `data`. See [Configuring a webhook trigger](/en/products/flowker/configuring-a-webhook-trigger) or [Running a workflow on a schedule](/en/products/flowker/running-a-workflow-on-a-schedule).

```json theme={null}
{
  "id": "node-trigger",
  "type": "trigger",
  "name": "Payment Received"
}
```

### executor

Calls an external service through a provider configuration. This node is the main integration point for fraud engines, payment providers, notification services, and other external systems.

The examples on this page show node topology only. A real executor node also carries a `providerConfigId` in its `data`, plus an `executorId` naming the catalog executor it invokes. A node that calls an operation of an uploaded OpenAPI document omits the `executorId` and carries `operation_path` and `operation_method` instead. See the [Integration guide](/en/products/flowker/integration-guide).

```json theme={null}
{
  "id": "node-fraud-check",
  "type": "executor",
  "name": "Check Fraud Score"
}
```

### conditional

Evaluates a condition against the execution context and routes to different branches based on the result. Use conditional nodes to implement branching logic, for example, routing to an approval path when risk is high, or continuing directly when it is low.

The condition lives in the node's `data.condition`. A free-text expression evaluates to a boolean and produces the output handle `true` or `false`. Each outgoing edge declares which handle it follows via `sourceHandle`. Conditional nodes built in the Console use a structured, case-based condition where each case routes to its own output handle. See the [Canvas editor](/en/products/flowker/console/canvas-editor).

```json theme={null}
{
  "id": "node-risk-decision",
  "type": "conditional",
  "name": "Evaluate Risk Score",
  "data": { "condition": "node-fraud-check.body.riskScore < 70" }
}
```

### action

Represents a synchronous internal `set_output` operation. It can write an interpolated output value and, optionally, override the synchronous HTTP response status. It does not provide a built-in pause, generic event emission, or a generic state-change operation.

```json theme={null}
{
  "id": "node-record-approval",
  "type": "action",
  "name": "Record Approval Decision"
}
```

## Edges

***

Edges connect nodes and define execution paths. Each edge includes the following fields:

| Field | Description |
| - | - |
| `id` | Unique identifier for the edge. |
| `source` | ID of the origin node. |
| `target` | ID of the destination node. |
| `sourceHandle` | Output handle of the source node this edge follows. Required to route out of a conditional node: it must match the branch outcome (`true` or `false` for a free-text condition). |
| `condition` | Legacy free-text field kept for backward compatibility. Flowker does not evaluate it for routing. Leave it empty for new workflows. |
| `label` | Human-readable label used for visualization and debugging. |

### Example edge

```json theme={null}
{
  "id": "edge-approved",
  "source": "node-risk-decision",
  "target": "node-process-payment",
  "sourceHandle": "true",
  "label": "Approved"
}
```

Routing depends on the source node's type. A conditional node evaluates its `data.condition` and follows the single outgoing edge whose `sourceHandle` matches the branch outcome. If no edge matches, that branch ends. Every other node type follows all of its outgoing edges when it completes successfully.

## Status transitions

***

Workflows follow a well-defined lifecycle.

![Workflow status transition diagram showing three states: draft, active, and inactive. An arrow labeled 'activate' points from draft to active. An arrow labeled 'deactivate' points from active to inactive. An arrow labeled 'draft' points from inactive back to draft.](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/flowker-workflow-status-transitions.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=a046e93f9e4a2cbf44f5a32b69254b06)

* **draft**: the initial state. You can add nodes, edit edges, and change configuration only in `draft` status.
* **active**: a workflow you activated. Flowker can execute it. It accepts no modification while active.
* **inactive**: a workflow you deactivated. Flowker can no longer execute it, but you can move it back to `draft` for editing.

### Rules

* You can activate only a `draft` workflow (transition: `draft → active`).
* You can deactivate only an `active` workflow (transition: `active → inactive`).
* You can move only an `inactive` workflow back to draft (transition: `inactive → draft`).
* Attempting an invalid transition returns error `FLK-0102`.
* Attempting to modify a workflow that is not in `draft` returns error `FLK-0103`.

### Moving an inactive workflow back to draft

If you deactivated a workflow and want to edit it again, move it back to `draft` by calling [`POST /v1/workflows/{id}/draft`](/en/reference/products/flowker/move-workflow-to-draft). This makes the workflow editable without needing to clone it.

Use this when you deactivated a workflow by mistake, or when you want to iterate on an existing workflow instead of creating a copy.

> [!NOTE]
>
> You can move only inactive workflows to draft. To modify an active workflow while it keeps running, use the clone approach described below.

### Iterating safely with clone

To modify an active workflow, clone it first. Cloning creates a new `draft` from any status, copying all nodes and edges. You can then update it without impacting the current version.

Use this approach for production versioning.

## Technical limits

***

| Limit | Value | Error code |
| - | - | - |
| Maximum nodes per workflow | 100 | `FLK-0113` |
| Maximum edges per workflow | 200 | `FLK-0114` |
| Maximum execution input payload | 1 MB | `FLK-0506` |

Workflows with more than \~50 nodes usually indicate that the flow should be split into smaller, composable workflows.

## Common patterns

***

### Sequential

The simplest pattern. Nodes execute in a linear sequence. Use this when each step depends on the previous one and needs no branching.

![Sequential workflow pattern: a trigger node connects to a first executor node, which connects to a second executor node, which connects to a third executor node. All connections are single directed arrows forming a straight line.](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/flowker-pattern-sequential.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=340149b4d91ac1ceb12d735624e90861)

**Example: Payment orchestration**

```json theme={null}
{
  "nodes": [
    { "id": "n1", "type": "trigger",  "name": "Payment Initiated" },
    { "id": "n2", "type": "executor", "name": "Validate Payment Data" },
    { "id": "n3", "type": "executor", "name": "Route to Provider" },
    { "id": "n4", "type": "executor", "name": "Send Confirmation Notification" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Valid" },
    { "id": "e3", "source": "n3", "target": "n4", "label": "Routed" }
  ]
}
```

### Conditional branching

A `conditional` node evaluates its condition and routes execution accordingly. The branch outcome selects the outgoing edge the node follows, matched by `sourceHandle`.

![Conditional branching workflow pattern: a trigger node connects to an executor node, which connects to a conditional node. The conditional node has two outgoing arrows: one labeled 'Path A' pointing to a first executor node, and one labeled 'Path B' pointing to a second executor node.](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/flowker-pattern-conditional.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=bf118a79f905ff81a2994ea171eef3bf)

**Example: Anti-fraud check**

```json theme={null}
{
  "nodes": [
    { "id": "n1", "type": "trigger",     "name": "Transaction Received" },
    { "id": "n2", "type": "executor",    "name": "Get Fraud Score" },
    {
      "id": "n3",
      "type": "conditional",
      "name": "Evaluate Score",
      "data": { "condition": "n2.body.fraudScore < 70" }
    },
    { "id": "n4", "type": "executor",    "name": "Approve Transaction" },
    { "id": "n5", "type": "executor",    "name": "Reject Transaction" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Score received" },
    {
      "id": "e3",
      "source": "n3",
      "target": "n4",
      "sourceHandle": "true",
      "label": "Approved"
    },
    {
      "id": "e4",
      "source": "n3",
      "target": "n5",
      "sourceHandle": "false",
      "label": "Rejected"
    }
  ]
}
```

## Real-world examples

***

### Anti-fraud check

A transaction arrives, an executor node gets the fraud score, and a conditional node routes execution to approval or rejection.

```json theme={null}
{
  "nodes": [
    { "id": "n1", "type": "trigger",     "name": "Transaction Received" },
    { "id": "n2", "type": "executor",    "name": "Get Fraud Score" },
    {
      "id": "n3",
      "type": "conditional",
      "name": "Evaluate Fraud Score",
      "data": { "condition": "n2.body.fraudScore < 70" }
    },
    { "id": "n4", "type": "executor",    "name": "Approve Transaction" },
    { "id": "n5", "type": "executor",    "name": "Reject and Notify" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Score received" },
    {
      "id": "e3",
      "source": "n3",
      "target": "n4",
      "sourceHandle": "true",
      "label": "Low risk"
    },
    {
      "id": "e4",
      "source": "n3",
      "target": "n5",
      "sourceHandle": "false",
      "label": "High risk"
    }
  ]
}
```

### Payment orchestration

A linear flow that validates incoming payment data, routes it to the appropriate provider, and sends a confirmation.

```json theme={null}
{
  "nodes": [
    { "id": "n1", "type": "trigger",  "name": "Payment Initiated" },
    { "id": "n2", "type": "executor", "name": "Validate Payment Data" },
    { "id": "n3", "type": "executor", "name": "Route to Payment Provider" },
    { "id": "n4", "type": "executor", "name": "Send Confirmation" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Valid" },
    { "id": "e3", "source": "n3", "target": "n4", "label": "Payment routed" }
  ]
}
```

### KYC onboarding

Use a workflow to submit a document check to an external approval system. Flowker does not have a built-in pause: for asynchronous human review, start a later, separate workflow execution after your approval system publishes its decision.

### Manual approval flow

An executor node submits the request for review. An executor retrieves the review decision from the external system. A conditional node then routes to either the approved or rejected path. Flowker executions run straight through. Flowker has no built-in pause step, so a human decision must come from an external system the workflow queries.

```json theme={null}
{
  "nodes": [
    { "id": "n1", "type": "trigger",     "name": "Request Submitted" },
    { "id": "n2", "type": "executor",    "name": "Submit for Review" },
    { "id": "n3", "type": "executor",    "name": "Get Approval Decision" },
    {
      "id": "n4",
      "type": "conditional",
      "name": "Decision Received",
      "data": { "condition": "n3.body.decision == 'approved'" }
    },
    { "id": "n5", "type": "executor",    "name": "Process Approved Request" },
    { "id": "n6", "type": "executor",    "name": "Notify Rejection" }
  ],
  "edges": [
    { "id": "e1", "source": "n1", "target": "n2", "label": "Start" },
    { "id": "e2", "source": "n2", "target": "n3", "label": "Submitted" },
    { "id": "e3", "source": "n3", "target": "n4", "label": "Decision received" },
    {
      "id": "e4",
      "source": "n4",
      "target": "n5",
      "sourceHandle": "true",
      "label": "Approved"
    },
    {
      "id": "e5",
      "source": "n4",
      "target": "n6",
      "sourceHandle": "false",
      "label": "Rejected"
    }
  ]
}
```

## Best practices

***

### Node naming conventions

Use descriptive, action-oriented names that communicate what the node does, not what type it is.

* **correct**: `Validate Payment Data`, `Get Fraud Score`, `Notify Customer`, `Get Approval Decision`
* **wrong**: `executor1`, `conditional node`, `node3`

Good names make workflows readable without opening the node configuration. They also appear in execution records and traces.

### Condition expressions

Flowker evaluates free-text conditions on conditional nodes against the execution context at runtime. A node without an output mapping stores its response envelope, so a condition reads a response field under `body`. Keep conditions simple and explicit:

* Use direct field comparisons: `<nodeId>.body.status == 'approved'`
* Use numeric comparisons: `<nodeId>.body.riskScore < 70`
* Use boolean fields: `<nodeId>.body.reviewRequired == true`
* Combine with `AND` / `OR` when needed: `<nodeId>.body.score < 70 AND <nodeId>.body.verified == true`

Avoid complex expressions. They make the workflow hard to read and debug. If logic is non-trivial, give the `conditional` node a clear name that encapsulates the decision.

A missing condition fails the execution, and so does a condition that fails to evaluate at runtime. Always test conditions before activating a workflow.

### Error handling strategies

Design workflows to handle failure explicitly:

* Add rejection paths from `conditional` nodes for every decision point that can fail.
* Use separate `executor` nodes for retry logic or fallback providers.
* Name error paths clearly (e.g., `Reject and Notify`, `Fallback to Manual Review`) so execution records are self-explanatory.

### Avoiding cycles

Flowker uses a DFS-based cycle guard at runtime. When the cycle guard finds a cycle during execution, the workflow fails with `FLK-0508`. Cycles are not caught at design time, so validate your edge structure before activating.

Rules to prevent cycles:

* Edges must always point forward in the flow, never back to a previously executed node.
* Review the graph visually before activating any workflow with branching or merging paths.
* If you need a retry or a loop, model it as a separate workflow invocation, not a back-edge in the current graph.

### Versioning via clone

Never edit an active workflow directly. Instead:

**Step 1**

Clone the workflow (creates a new `draft` with all nodes and edges copied).

**Step 2**

Make your changes in the draft.

**Step 3**

Validate or preview the draft.

**Step 4**

Activate the new version. A webhook method and path belong to one active workflow at a time: for a webhook-triggered workflow, deactivate the old version first, or give the new version its own path.

**Step 5**

Deactivate the old version if you no longer need it.

This preserves the execution history of the active version and gives you a clean rollback path if the new version has issues.

## Error reference

***

The following error codes are relevant to workflow design and execution:

| Code | Description |
| - | - |
| `FLK-0102` | Invalid status transition |
| `FLK-0103` | Workflow cannot be modified (not in draft status) |
| `FLK-0113` | Too many nodes (maximum is 100) |
| `FLK-0114` | Too many edges (maximum is 200) |
| `FLK-0506` | Execution input payload too large (maximum is 1 MB) |
| `FLK-0508` | Cycle detected during workflow execution |


# Working with request and response data
Source: https://docs.lerian.studio/en/products/flowker/working-with-request-and-response-data

Move values into an executor node's request and out of its response. Declare the mappings, reshape values in flight, and check the assembled request before you call the service.

An executor node sends data to an external service and receives data back. The service names its own fields, and your workflow names its own. Mappings are how you move values between the two. They are a list of source-to-target entries on the node. Flowker applies them to the request before the call and to the response after it.

You need this whenever the shape your workflow carries is not the shape the service accepts. One example is a document that must travel without punctuation. Another is an amount that belongs under a nested object, or a score that a later node reads under a short name.

## Before you start

***

* A provider configuration for the service, and an executor node that references it. See [Reference the provider configuration from a workflow node](/en/products/flowker/integration-guide#step-3-reference-the-provider-configuration-from-a-workflow-node).
* The field names the service expects. When the service's OpenAPI document is in the registry, [Derive an operation schema](/en/reference/products/flowker/derive-openapi-operation-schema) returns `inputSchema` (the operation's request body) and `outputSchema` (its success response). Both give you the field names you write as mapping targets and sources.
* A workflow in `draft` status. To edit an active workflow, [deactivate it](/en/reference/products/flowker/deactivate-workflow) and [move it to draft](/en/reference/products/flowker/move-workflow-to-draft), then activate it again.

> [!NOTE]
>
> Do not send `executorId` on a node that calls an operation of an uploaded OpenAPI document. Such a node names the operation with `operation_path` and `operation_method`. Flowker fills the `executorId` in for you, from the provider configuration the node points at, before it validates the workflow. It does this when you create the workflow and when you update it. [Connecting your own API](/en/products/flowker/connecting-your-own-api) walks that whole path. The nodes on this page name `http`, the generic HTTP connector, which does need an explicit `executorId`.

## Step 1: Know what a mapping can read

***

Every mapping reads from the workflow context, one JSON object that grows as the execution advances:

| Path | What it holds |
| - | - |
| `workflow` | The trigger payload: the `inputData` of an execution request, or the body a webhook route received. A webhook route also adds `workflow._webhook` with the call's metadata. See [Webhook metadata](/en/products/flowker/integration-guide#webhook-metadata). |
| `execution.id` | The execution identifier. |
| `execution.startedAt` | When the execution started, in UTC. |
| `<nodeId>` | The output of each executor node that has completed, under that node's id. |

Address a value by its path from one of those top-level keys:

| Source | What it selects |
| - | - |
| `workflow.customer.document` | A nested field of the trigger payload. |
| `workflow.items[0].sku` | One element of an array. |
| `workflow.items[*].sku` | The same field across every element, as an array. |
| `workflow` | The whole trigger payload as an object. |
| `score-transaction.body.score` | A field of the `score-transaction` node's output. |

> [!NOTE]
>
> A mapping `source` is a plain path. Do not wrap it in `${...}`. Inside a mapping Flowker reads a `${...}` string as a literal path name that selects nothing.

## Step 2: Declare the input mapping

***

Input mappings live in an `inputMapping` array inside the executor node's `data` object. Each entry moves one value into the outgoing request body.

| Field | Type | Required | Description |
| - | - | - | - |
| `source` | string | Yes | The path in the workflow context to read. |
| `target` | string | Yes | The path in the outgoing request body to write. A dotted target creates the nested object (`payment.amount` sends `{"payment":{"amount":…}}`). |
| `transformation` | object | No | A change applied to the value after it lands on the target. See [Step 4](#step-4-reshape-a-value-on-its-way-through). |
| `required` | boolean | No | Whether the source path must exist. Defaults to `false`. Applies to the whole node. See below. |

The mapped result is the request body. Write each `target` exactly as the service expects to receive it: there is no wrapper object and no prefix to add.

> **Example: map the trigger payload into a fraud check**
>
> ```json theme={null}
> {
>   "id": "score-transaction",
>   "type": "executor",
>   "name": "Score transaction",
>   "position": { "x": 200, "y": 0 },
>   "data": {
>     "executorId": "http",
>     "providerConfigId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
>     "method": "POST",
>     "path": "/score-transaction",
>     "inputMapping": [
>       { "source": "workflow.transactionId", "target": "reference" },
>       { "source": "workflow.amount", "target": "payment.amount" },
>       { "source": "workflow.customer.document", "target": "payment.document" }
>     ]
>   }
> }
> ```
>
> With a trigger payload of `{"transactionId":"txn-98765","amount":1500.00,"customer":{"document":"12345678900"}}`, the service receives:
>
> ```json theme={null}
> {
>   "reference": "txn-98765",
>   "payment": { "amount": 1500, "document": "12345678900" }
> }
> ```

### When a source selects nothing

A source path that is absent from the context is not an error. Flowker still writes the target, with the value `null`, and the request goes out.

Set `required: true` when the node must not call the service without a value. Flowker then checks every source path on that node before it builds the request, and fails the step when any of them is absent. The execution fails and the step reports `input transformation failed`.

> [!NOTE]
>
> `required` applies to the node, not to the one entry that carries it. If any entry in a node's `inputMapping` sets `required: true`, every source path in that array must resolve. To keep some fields optional, leave `required` off across the whole node.

Give each `target` one entry. When two entries write the same target, the last one wins.

## Step 3: Decide what builds the request body

***

A node has three sources for a request body. Only `data.body` is exclusive: when present, it is the whole body. Without it, Flowker composes the body from the other two sources, with the mapping overlay written over the `config` literals:

**1. data.body**

An explicit body template wins outright. Flowker resolves its `${...}` references against the workflow context and sends the result. While `data.body` is present, `inputMapping`, `transforms`, and `config` contribute nothing to the body.

Every `${...}` reference here must resolve. One that does not fails the node with `FLK-0143`, before any call goes out (the opposite of a mapping source, which resolves to `null`). Use `data.body` when a missing value must stop the workflow, and a mapping when the request must go out regardless.

**2. inputMapping or transforms**

Otherwise Flowker builds an overlay from `inputMapping`. When `inputMapping` is empty it builds the overlay from `transforms` instead. The two are mutually exclusive: a node with at least one `inputMapping` entry never runs its `transforms` on the input.

**3. config literals**

Literal values in `data.config` seed the body. With an overlay present, the literals are the base and the overlay wins on any key both set. One node can therefore combine fixed values with mapped ones. With no overlay, the literals are the body on their own.

Transport never becomes body content. Before `config` can seed the body, Flowker removes these names from it: `method`, `path`, `url`, `endpointName`, `query`, `headers`, `auth`, `retry`, `timeout`, `timeout_seconds`, `request_format`, `success_status_codes`, `content_digest`, `allowedHosts`, and `allowedPrivateHosts`. A node that keeps transport in `config` by mistake therefore sends none of it to the destination. An `auth` block placed there can never ship as request content.

The node reads its own transport from the top of its `data` object: `path`, `endpointName`, `method`, `headers`, `query`, `auth`, `timeout_seconds`, `retry`, `success_status_codes`, `request_format`, and `content_digest`. The outbound host allow-lists are not among them: you set `allowedHosts` and `allowedPrivateHosts` on the provider configuration, where each applies to every node that calls through it.

> **Example: fixed values plus mapped ones**
>
> ```json theme={null}
> {
>   "data": {
>     "executorId": "http",
>     "providerConfigId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
>     "method": "POST",
>     "path": "/score-transaction",
>     "config": {
>       "channel": "web",
>       "payment": { "currency": "BRL" }
>     },
>     "inputMapping": [
>       { "source": "workflow.transactionId", "target": "reference" },
>       { "source": "workflow.amount", "target": "payment.amount" }
>     ]
>   }
> }
> ```
>
> The literals and the mapped values merge, and nesting merges with nesting:
>
> ```json theme={null}
> {
>   "channel": "web",
>   "reference": "txn-98765",
>   "payment": { "currency": "BRL", "amount": 1500 }
> }
> ```

## Step 4: Reshape a value on its way through

***

When the service needs a value in a different form, attach a `transformation` to the mapping entry. It applies to the value after it lands on the target.

| Type | What it does | Config |
| - | - | - |
| `remove_characters` | Removes the given characters from the text. | `characters`: the characters to remove. |
| `add_prefix` | Puts text in front of the value. | `prefix`: the text to add. |
| `add_suffix` | Puts text after the value. | `suffix`: the text to add. |
| `to_uppercase` | Converts the text to uppercase. | — |
| `to_lowercase` | Converts the text to lowercase. | — |

Two rules to write them by:

* They act on text. A value that is not text reaches the target unchanged.
* The `prefix` and `suffix` values each need at least one character, and a single space counts. The `characters` value needs at least one character that is not a space, a tab, or a line break. A value that does not meet this fails the step at run time.

> **Example: normalize a document and stamp a reference**
>
> ```json theme={null}
> {
>   "inputMapping": [
>     {
>       "source": "workflow.customer.document",
>       "target": "payer.document",
>       "transformation": {
>         "type": "remove_characters",
>         "config": { "characters": ".-/" }
>       }
>     },
>     {
>       "source": "workflow.customer.name",
>       "target": "payer.name",
>       "transformation": { "type": "to_uppercase" }
>     },
>     {
>       "source": "workflow.transactionId",
>       "target": "payer.reference",
>       "transformation": {
>         "type": "add_prefix",
>         "config": { "prefix": "BR-" }
>       }
>     }
>   ]
> }
> ```
>
> From `{"customer":{"document":"123.456.789-00","name":"ada lovelace"},"transactionId":"txn-98765"}`, the node sends:
>
> ```json theme={null}
> {
>   "payer": {
>     "document": "12345678900",
>     "name": "ADA LOVELACE",
>     "reference": "BR-txn-98765"
>   }
> }
> ```

### Whole-document transforms

For work that entry-by-entry mapping does not express (combining two fields, choosing the first value that is present, filling a default), declare a `transforms` array instead. Each operation reads the whole workflow context and writes the whole overlay.

Flowker accepts `shift` (move or rename), `concat` (join values), `coalesce` (first value present), `default` (fill a missing key), `extract` (lift a subtree to the root), `delete` (drop a key), `timestamp`, `uuid`, and `pass`. The five transformation types above are available here too. As operations they take the target path in the spec as `path`.

> **Example: shift and a default in one node**
>
> ```json theme={null}
> {
>   "data": {
>     "executorId": "http",
>     "providerConfigId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
>     "transforms": [
>       {
>         "operation": "shift",
>         "spec": {
>           "reference": "workflow.transactionId",
>           "payment.amount": "workflow.amount"
>         }
>       },
>       { "operation": "default", "spec": { "channel": "web" } }
>     ]
>   }
> }
> ```
>
> The node sends:
>
> ```json theme={null}
> {
>   "reference": "txn-98765",
>   "payment": { "amount": 1500 },
>   "channel": "web"
> }
> ```
>
> `shift`, `concat`, `coalesce`, `extract`, `delete`, and `timestamp` accept `require: true`, which demands that every path the `spec` names exists, the same way `required` works on a mapping entry.

> [!NOTE]
>
> `transforms` runs only when the node has no `inputMapping`. Use one or the other in a given node, never both.

## Step 5: Read the response back out

***

Output mappings extract fields from the response and store them in the workflow context under the node's id, so later nodes read short, stable names. Declare them in an `outputMapping` array in the node's `data`, with the same four entry fields as an input mapping.

An output `source` is a path into the response envelope, not into the response body:

| Path | What it holds |
| - | - |
| `status` | The HTTP status code. |
| `status_text` | The HTTP status line, such as `200 OK`. |
| `url` | The URL Flowker requested, with the query string it assembled. |
| `headers` | The response headers, as a key-value object under their canonical names, such as `Content-Type`. A header the service sent more than once arrives as one comma-separated value. |
| `body` | The response body, parsed when the response is `application/json`, a type whose name ends in `+json`, or an XML type (`application/xml`, `text/xml`, or a type whose name ends in `+xml`). |
| `raw_body` | The response exactly as it arrived, as text. Present for an XML response. |
| `body_format` | Set to `xml` when an XML body was decoded. |
| `body_parse_error` | Present in place of `body` when an XML body could not be decoded, so the workflow can branch on it. |

Response fields therefore sit under `body`:

```json theme={null}
{
  "outputMapping": [
    { "source": "body.score", "target": "score" },
    { "source": "body.decision", "target": "decision" },
    { "source": "status", "target": "httpStatus" }
  ]
}
```

On a node with the id `score-transaction`, that stores:

```json theme={null}
{ "score": 42, "decision": "review", "httpStatus": 200 }
```

A downstream mapping then reads `score-transaction.score` and `score-transaction.httpStatus`, and a downstream `data.body` reads `${score-transaction.score}`.

A node that declares no `outputMapping` stores the whole envelope under its id instead, and downstream nodes read the envelope path directly: `score-transaction.body.score`. Add an output mapping when you want the shorter name. Skip it when the envelope path is clear enough.

An output source that selects nothing behaves like an input one. Flowker stores the target as `null` unless an entry on that node sets `required: true`.

## Step 6: Check the mapping before you call the service

***

[Preview an executor request](/en/reference/products/flowker/preview-executor-request) uses the mapping, transformation, and request-assembly paths without making a service-network call. It does not read the vault or fetch an authentication token. The preview masks with `***` the credential the authentication type declares where it appears as a value. Any other value, including a free-form authentication parameter, can appear as Flowker would send it.

Send the node, the provider configuration it targets, and a sample payload. The provider configuration goes in the request itself, so preview does not need a saved provider configuration:

```json theme={null}
POST /v1/workflows/preview-request

{
  "node": {
    "executorId": "http",
    "method": "POST",
    "path": "/score-transaction",
    "inputMapping": [
      {
        "source": "workflow.customer.document",
        "target": "payer.document",
        "transformation": {
          "type": "remove_characters",
          "config": { "characters": ".-/" }
        }
      },
      {
        "source": "workflow.customer.name",
        "target": "payer.name",
        "transformation": { "type": "to_uppercase" }
      },
      {
        "source": "workflow.transactionId",
        "target": "payer.reference",
        "transformation": {
          "type": "add_prefix",
          "config": { "prefix": "BR-" }
        }
      }
    ]
  },
  "providerConfig": {
    "providerId": "http",
    "config": { "base_url": "https://api.fraudshield.example.com" },
    "allowedHosts": ["api.fraudshield.example.com"]
  },
  "sampleInput": {
    "transactionId": "txn-98765",
    "customer": { "document": "123.456.789-00", "name": "ada lovelace" }
  }
}
```

Your `sampleInput` becomes the trigger payload, so the mapping sources read it as `workflow.*`, exactly as they will at run time.

The response is the assembled request:

```json theme={null}
{
  "method": "POST",
  "url": "https://api.fraudshield.example.com/score-transaction",
  "headers": { "Content-Type": "application/json" },
  "body": "{\"payer\":{\"document\":\"12345678900\",\"name\":\"ADA LOVELACE\",\"reference\":\"BR-txn-98765\"}}",
  "curl": "curl -X POST -H 'Content-Type: application/json' --data '{\"payer\":{\"document\":\"12345678900\",\"name\":\"ADA LOVELACE\",\"reference\":\"BR-txn-98765\"}}' 'https://api.fraudshield.example.com/score-transaction'",
  "unresolved": []
}
```

Each transformation resolved: the punctuation is gone from the document, the name is uppercase, and the reference carries its prefix. No call reached the service.

Read it in this order:

**1. Check the URL**

It is the provider configuration's base URL plus the node's `path`. A path you did not expect is a node field to fix, not a mapping.

**2. Check the body against the field names the service expects**

Every `target` should appear where the service wants it. A field carrying `null` is a `source` path that selects nothing.

**3. Check `unresolved`**

It lists the `${...}` references in the node's headers, query, and URL that the preview could not resolve. Flowker leaves them literal in the rendered request. An unresolved reference in `data.body` fails the preview with `FLK-0143` instead.

To check a node's fixed fields against the catalog executor's schema as well, call [Validate a node configuration](/en/reference/products/flowker/validate-executor-config). Send the node's configuration in `config` and, in `mappedTargets`, the target paths your `inputMapping` supplies. Flowker counts those as satisfied, so a node that maps a required field from the trigger passes the check.

## What goes wrong

***

| Symptom | Cause | Fix |
| - | - | - |
| The service receives a field set to `null`. | The `source` path is absent from the workflow context. | Compare the path with a preview's rendered body. Set `required: true` on the node when it must not run without the value. |
| The service receives a nested object it did not ask for. | The `target` carries a prefix. | Write the target exactly as the service expects it. A target of `executor.accountId` sends an `executor` object. |
| The request body is empty. | The node has no `data.body`, no mapping and no `transforms`, and its `config` holds only transport names. | Add the values as `config` literals or as mapping entries. |
| The mappings appear to be ignored. | The node also carries `data.body`, which is the only body source while it is present. | Remove `data.body` to let the mappings build the body. |
| `transforms` appears to be ignored. | The node has at least one `inputMapping` entry. | Remove the `inputMapping` entries, or move the logic into them. |
| A downstream node reads nothing. | The reference does not name the producing node. | Read `<nodeId>.<target>` in a mapping, or `${<nodeId>.<target>}` in `data.body`. There is no shared top-level namespace. |
| An output mapping stores `null`. | The `source` omits the envelope prefix. | Map `body.score`, not `score`. |

| Error code | When | What it means |
| - | - | - |
| `FLK-0140` | Create, update, or activate | The node's `inputMapping` does not form a valid specification (most often, an unknown `transformation.type`). |
| `FLK-0141` | Create, update, or activate | The same, for the node's `outputMapping`. |
| `FLK-0142` | Create, update, or activate | The same, for the node's `transforms`. |
| `FLK-0143` | Run time | A `${...}` reference in the node's `data.body` does not resolve against the workflow context. The node fails without calling the service. |

See the [Flowker error list](/en/reference/products/flowker/flowker-error-list) for every code.

## What's next

***

> **[Integration guide](/en/products/flowker/integration-guide)**
>
> Create the provider configuration a node calls through, and set its authentication.

> **[Configuring a webhook trigger](/en/products/flowker/configuring-a-webhook-trigger)**
>
> Choose the payload contract that fills the `workflow` namespace your mappings read.


# Accounting and accrual runs
Source: https://docs.lerian.studio/en/products/lender/accounting-and-accrual-runs

How Lender books to the ledger: accounting profiles and posting rules, durable posting intents, accrual runs, and journal references.

Money events, such as a disbursement, a repayment, or an interest accrual, reach the ledger (The core financial book that records all transactions, balances, and operations for an organization. It is the single source of truth for a business unit's finances.). Lender's accounting layer is how they get there. A product declares its posting rules once. From then on, each of those events books automatically and traceably.

## Accounting profiles and posting rules

***

An **accounting profile** binds a product version to the ledger. It defines the **posting rules**: the double-entry (Every financial movement is recorded as at least two operations: a debit from one account and a credit to another, so the system always balances.) legs that fire for each kind of financial event. It also defines the ledger organization and ledger the resulting transactions book into. You create a profile per product:

`POST /api/v1/loan-products/{id}/accounting-profiles`

Lender validates the posting rules when you create the profile. A product therefore cannot go live with legs that would not balance.

## Posting intents and the relay

***

Lender does not call the ledger inline. When a financial event happens, Lender persists a durable **posting intent**. That write happens in the same database transaction that changes domain state. A relay then posts the balanced transaction to Midaz asynchronously. These properties make bookings reliable:

* **The intent commits with the state change**: both land in one database transaction, through a transactional outbox.
* **Idempotent**: each posting carries a deterministic key, so retries collapse to one ledger transaction.
* **Fails closed**: if routing cannot resolve a non-empty ledger target, Lender refuses the post and does not write it to the wrong place.

[Lender in the platform](/en/products/lender/lender-in-the-platform) describes the full path.

## Accrual runs

***

An **accrual run** recognizes interest and the other time-based amounts. One run closes the last civil month that had fully ended before its business date, for every loan it selects. It also produces the postings for that month.

`POST /api/v1/accrual-runs` starts a run. Lender selects the candidate loan accounts itself, recognizes interest per account, and writes one posting intent per recognition.

> [!TIP]
>
> Recognition is idempotent per loan account, per accounting month, and per amount kind. A run started twice for the same month recognizes interest once.

## Retrying a run

***

A recognition is durable the moment the run commits. The ledger booking is not. When a posting never arrives, retry the run instead of starting a new one.

`POST /api/v1/accrual-runs/{id}/retry` names the items to re-send, and takes the same `X-Idempotency` header the run itself takes. It is a second attempt on the same run, so Lender records no second run.

Lender rebuilds the posting behind every named item the ledger has not acknowledged, and enqueues it under the deterministic key the original run used. The relay delivers it, and the ledger treats a duplicate as a duplicate rather than as a second booking. Lender leaves alone the items the ledger already acknowledged.

The answer names, item by item, what it could not re-send. It also names why: the posting had already been delivered, it was quarantined, the contract behind it is gone, or the product is misconfigured.

> [!WARNING]
>
> A retry refuses with `LENDER-0405` when the posting it rebuilds differs from the one already enqueued under that key. The product's accounting profile changed after the run, so re-sending would book the month against legs nobody chose for it. Reconcile the enqueued posting first, because repeating the request reproduces the same refusal.

## Journal references

***

Each accrual run records a **journal reference**, the run's own accounting identifier. The reference record also stores the correlation id that Lender derived for the run. The journal reference id identifies one run exactly. A read by correlation id returns the most recent run that shares that mode, business date, and product scope.

A run emits one posting per loan account, per accounting month, per amount kind. Lender therefore records the tie back to the ledger per posting, not per run. Once the ledger acknowledges a posting, Lender stores a receipt under that posting's own key. A read by that key answers with the ledger transaction that booked it. A run-level reference carries no ledger transaction of its own: it names the run, and the receipts name the bookings.

| Operation | Purpose |
| - | - |
| `GET /api/v1/journal-references` | Look up a journal reference by correlation id. |
| `GET /api/v1/journal-references/{id}` | Read a single journal reference. |

## Next steps

***

> **[Jurisdictions](/en/products/lender/jurisdictions)**
>
> See how the active jurisdiction shapes disclosures and endpoints.

> **[Brazil regulatory pack](/en/products/lender/brazil-regulatory-pack)**
>
> Layer CET, IOF, and PDD staging on top of the accounting model.


# Assign receivables
Source: https://docs.lerian.studio/en/products/lender/assignment-of-receivables

Manage a receivables-assignment journey: register a fund, assess a pool, approve a set, exchange files, and record the external facts that complete the cession.

An **assignment of receivables** (*cessão*) transfers a selected set of receivables to a fund. Lender keeps the set, its eligibility decision, its documents, and the externally observed lifecycle facts together. An operator can therefore work the journey without treating a file exchange as proof of a completed transfer.

This guide describes the operational flow. The [Lender REST API](/en/products/lender/lender-rest-api) and its generated reference define the request and response contracts.

## Before you start

***

* Use a Lender identity authorized for the assignment operations. The service derives the tenant from that validated identity. You do not supply a tenant in a request.
* Register the receiving fund before creating a set. The registration holds its administrator details, cession rate, eligibility limits, document mode, and the layout used for its offer file.
* Treat each external fact as evidence. Sending a file, receiving a remessa, signing a term, paying, transferring, and accepting are separate facts with separate controls.

## The assignment flow

***

**1. Register the fund**

Create or update the assignment-fund registration. Its configuration supplies the cession rate and the concentration and repeated-cut rules used when Lender evaluates a pool. The receiving fund's document and registry settings also determine the later document and acceptance paths.

**2. Review eligible receivables**

Read the fund-scoped candidate pool. Lender evaluates each candidate against the fund configuration and the assignment context, returning an eligibility verdict rather than silently dropping ineligible receivables. When it cannot read a required source, it reports that condition instead of treating the constraint as satisfied.

**3. Assemble and score a draft set**

Create a draft from the receivables you selected. Lender freezes the set's composition and the fund settings it needs for that journey. Score the draft against the fund rule before approval. An unapproved set can be re-scored.

**4. Approve the set**

Approval re-reads the relevant receivable state before it records the decision. A receivable that changed since assembly can leave the set, or Lender can reprice it. Review the approval result, and do not assume the draft survives unchanged.

**5. Call off a set that cannot continue**

`POST /api/v1/assignment/sets/{setId}/discard` cancels an unsold composition and releases its receivables back to the assignable pool. It preserves the set, its evidence, and its audit trail. It does not undo a sale. Lender refuses the call when the set is accepted, partly sold or paid, or has a transfer lodged at the registry.

**6. Exchange the fund files**

Download the offer file only after approval, then record that you sent it. Ingest the fund administrator's remessa against that same set. Lender reconciles the file with the offered composition and records the outcome.

**7. Record the completion facts**

Record the endorsement term and the externally observed payment, transfer, and acceptance facts as they occur. Lender enforces the lifecycle transition for each fact. Lender removes an accepted receivable from the active holding path only when the required acceptance processing succeeds.

## Documents and exceptions

***

Lender can produce a receivable dossier from the facts it holds. The first materialization freezes the evidence snapshot used for that dossier, so a later retrieval represents the same recorded evidence.

The journey can also surface exception cases. Those cases include a repeated cut, a remessa conflict or divergence, a receivable that cannot be valued, or a derecognition that cannot be posted. Resolve those cases through the assignment exception flow. Do not substitute a lifecycle fact for the missing resolution.

## Operational guardrails

***

* **A set is not a completed cession.** Draft, eligibility, approval, offer delivery, remessa, term, payment, transfer, and acceptance are distinct lifecycle steps.
* **Fund changes do not rewrite a set already in progress.** Lender freezes the relevant fund configuration at set assembly.
* **Approval is intentionally defensive.** It validates the current receivable state before a fund receives an offer.
* **Acceptance is money-path sensitive.** If Lender cannot complete its required processing, it refuses the acceptance instead of marking the receivable as sold.

## Next steps

***

> **[Lender REST API](/en/products/lender/lender-rest-api)**
>
> Start from the service API and the generated operation reference.

> **[Accounting and accrual runs](/en/products/lender/accounting-and-accrual-runs)**
>
> See how Lender keeps durable accounting work separate from inline requests.


# Brazil regulatory pack
Source: https://docs.lerian.studio/en/products/lender/brazil-regulatory-pack

Explore Lender's Brazilian profile: CET disclosure, IOF tax preview, capitalization consent, PDD staging, prepayment quotes, and business calendar rules.

The Brazilian **profile** carries the regulated behavior of the loans Lender books in Brazil. You reach everything here through the BR-prefixed endpoints (`/api/v1/br/...`). Everything here applies to loans originated under the Brazil jurisdiction. Portuguese domain terms stay as-is, with a gloss (see [Core concepts](/en/products/lender/core-concepts) for the full list).

## CET (Custo Efetivo Total)

***

**CET** (*Custo Efetivo Total*, total effective cost of credit) is the all-in cost disclosed to the borrower (interest plus taxes and fees). Lender persists the CET disclosure at origination and exposes it per loan account:

`GET /api/v1/br/loan-accounts/{id}/cet-disclosure`

## IOF and tax preview

***

**IOF** (*Imposto sobre Operações Financeiras*) is the federal tax on credit operations. The Brazilian profile pins the IOF rates, so a preview and the disbursement that follows it compute the same amounts.

Preview the daily and the additional IOF component, and the net amount the borrower receives, before you originate:

`POST /api/v1/br/tax/preview`

At disbursement, send `jurisdictionExtensions` with `disbursedAt`, `loanProductVersionId`, and `requestId`, the call's `X-Idempotency` value. Lender computes the IOF from them and accepts the disbursement only when the net equals gross minus that IOF, minus a retained origination fee.

## Capitalization consent

***

Brazilian compound-interest (*juros compostos*) capitalization requires the borrower's explicit consent. Lender records that consent as an integrity-checked ceremony. The client submits the clause text and its hash. The server canonicalizes the text, recomputes the hash, and rejects any mismatch. The recorded consent is therefore provably the clause the borrower saw.

`POST /api/v1/br/loan-applications/{id}/capitalization-consents`

## PDD staging

***

**PDD** (*Provisão para Devedores Duvidosos*) is loan-loss provisioning. Each loan account sits in a PDD stage. Lender records each stage change as a transition, not as a silent overwrite.

| Operation | Purpose |
| - | - |
| `GET /api/v1/br/loan-accounts/{id}/pdd-stage` | Read the current PDD stage. |
| `POST /api/v1/br/loan-accounts/{id}/pdd-stage/transitions` | Apply a PDD stage transition. |

The number of days overdue drives staging. The later stages also suspend interest accrual, so the [accrual run](/en/products/lender/accounting-and-accrual-runs) skips those accounts.

### The nightly promotion sweep

Stages also advance on their own. A daily sweep reads the overdue book for the business day, measures each account against the Res. CMN 4.966 provisioning ladder in force, and applies the same transition operation above wherever the stage should change. A loan that ages past a boundary is therefore restaged without anyone calling the API. The sweep is on by default, and it runs at 05:00 UTC until you give it another schedule.

Every deployment runs it against its own book.

The sweep reads the portfolio snapshot for the business day, so it builds that snapshot itself when nothing else did, and fails that tenant's sweep when it cannot. A book nobody measured and a book with nothing overdue look identical from the outside, and the sweep refuses to report the first as the second.

Set `JOBS_PDD_PROMOTION_ENABLED=false` to turn it off. Stages then change only when you call the transition operation.

On a default deployment this sweep is also the only producer of the portfolio snapshot, because the dedicated snapshot job ships off. Turn the sweep off and you have to enable `JOBS_PORTFOLIO_SNAPSHOT_ENABLED` in its place, or the portfolio dashboard and the delinquent-loan register refuse every business date with `503`.

### Qualitative problem assets

Res. CMN 4.966 art. 3 paragraphs 1 and 2 also make an asset a problem asset for a qualitative reason, with nothing overdue. Record that judgment as a declaration on the loan account.

| Operation | Purpose |
| - | - |
| `POST /api/v1/br/loan-accounts/{id}/problem-asset-assessments` | Declare that the contract is, or is not, a problem asset under one article. Requires `X-Idempotency`. |
| `GET /api/v1/br/loan-accounts/{id}/problem-asset-assessments` | List the declarations, newest first. |
| `PUT /api/v1/br/loan-product-versions/{id}/problem-asset-reassessment-horizon` | Set how many days a characterisation can stand on a contract of this product version before somebody must re-assess it. |
| `GET /api/v1/br/problem-asset-reassessment-overdue` | List the contracts whose characterisation has outlived that horizon. |

A declaration needs `trigger` (the article, for example `art_3_p2_iii`), `source`, `evidenceReference`, `evaluatedOn`, and `characterizesProblemAsset`. Declarations are immutable. To withdraw a characterisation, declare the same `trigger` again with `characterizesProblemAsset: false` and its own evidence.

The nightly promotion sweep reads the live declarations. A characterised contract takes the more severe of its arrears stage and the problem-asset floor of the ladder in force. It can therefore enter a PDD stage with nothing overdue. Passing the re-assessment horizon changes no stage and no provision. The contract stays on the re-assessment worklist until somebody declares again, with either verdict.

## Credit operation descriptor

***

The **credit descriptor** is the SCR-style credit-operation profile for a loan account, the regulated description of the operation.

`GET /api/v1/br/loan-accounts/{id}/credit-descriptor`

## Prepayment quote

***

A Brazilian loan account settles early against a **prepayment quote**: create the quote first, then prepay with its identifier. The quote is valid for 24 hours and accepts one settlement, and the amount you settle must equal the quote's net settlement amount. The BR prepayment route mirrors the generic one and takes the same `X-Idempotency` key.

| Operation | Purpose |
| - | - |
| `POST /api/v1/br/loan-accounts/{id}/prepayment-quote` | Create a prepayment quote (partial or full). |
| `POST /api/v1/br/loan-accounts/{id}/prepayments` | Prepay the loan account (BR alias). |

## CDC caps

***

Brazilian consumer-credit (CDC) products can carry regulatory caps, for example a late-fee ceiling. Lender enforces caps by rejecting a charge that would violate them, rather than silently clamping the amount. The contract and its audit trail then stay explicit about each refusal.

## Business calendar

***

Brazilian date math (accruals, schedule dates, settlement) uses a Brazilian business calendar. That calendar has ANBIMA holidays and an Actual/252 day-count convention. Installment and accrual dates therefore land on business days.

## BR products

***

You create and version Brazilian products through jurisdiction-aware aliases that accept the BR extensions:

* `POST /api/v1/br/loan-products`, `GET /api/v1/br/loan-products`, `GET /api/v1/br/loan-products/{id}`
* `POST /api/v1/br/loan-products/{id}/versions`, `POST /api/v1/br/loan-products/{id}/activate`, `POST /api/v1/br/loan-products/{id}/promote`

## Next steps

***

> **[Consignado privado](/en/products/lender/consignado-privado)**
>
> The Brazilian journey: payroll-deducted lending end to end.


# Configuration and deploy
Source: https://docs.lerian.studio/en/products/lender/configuration-and-deploy

How Lender is packaged and run: the container shape, its dependencies, a curated environment-variable surface, and the ledger posting path.

Lender is a single Go service, packaged as a container and configured entirely through environment variables. This page is the operator's reference: what it runs as, what it depends on, the settings that matter, and how tenancy and ledger routing behave.

## The container

***

Lender builds from a multi-stage Dockerfile (a Go Alpine builder producing a static binary, copied into a distroless nonroot runtime) and listens on port `8080`. It ships as a container image you deploy into your Kubernetes (A platform for running and managing software applications at scale. It automatically handles deployment, scaling, and recovery across multiple servers.) cluster with the platform's standard [lifecycle tooling](/en/platform/lifecycle-management). This page does not assume any particular packaging beyond the image.

Operational probes:

| Endpoint | Purpose |
| - | - |
| `GET /health` | Liveness. |
| `GET /readyz` | Dependency readiness. |
| `GET /version` | Build and version metadata. |

## Dependencies

***

| Dependency | Role |
| - | - |
| **PostgreSQL 17** | Primary data store, with primary/replica support. |
| **Valkey 8** (Redis-compatible) | Cache, rate limiting, and the M2M-credential cache. |
| **RabbitMQ** | Optional, and off by default. It is not the transport for Lender's event catalog. |
| **RedPanda** | Kafka-compatible event backbone for lifecycle facts, published through Lerian's streaming library and transactional outbox. Required: the service does not start without it. |
| **Midaz** | The double-entry ledger (The core financial book that records all transactions, balances, and operations for an organization. It is the single source of truth for a business unit's finances.), reached through the official SDK. Lender authenticates via [Access Manager](/en/platform/access-manager) with machine-to-machine (M2M) credentials. You keep them in your secret vault (see Ledger M2M custody below). |
| **Caradhras** | Identity backend behind Access Manager. Route authorization runs through Lerian's auth library. |
| **Systemplane** | Runtime configuration plane, mounted under `/api/v1/systemplane`. |

## Configuration surface

***

Configuration is entirely environment-driven. The keys below shape behavior. They are not the full list.

| Group | Key | What it controls |
| - | - | - |
| App | `ENV_NAME`, `LOG_LEVEL`, `DEPLOYMENT_MODE`, `SERVER_ADDRESS` | Environment name, log verbosity, deployment mode, and listen address. |
| Tenancy | `DEFAULT_TENANT_ID` | The tenant the deployment serves. |
| Postgres | `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_NAME`, `POSTGRES_SSLMODE` | Primary database connection. Migration directories are fixed in the service image, not configurable. |
| Cache | `REDIS_HOST`, `REDIS_PASSWORD`, `M2M_CREDENTIAL_CACHE_TTL_SEC` | Valkey connection and how long M2M credentials are cached. |
| Messaging | `RABBITMQ_ENABLED`, `RABBITMQ_HOST`, `OUTBOX_DISPATCH_INTERVAL_SEC` | Separate RabbitMQ messaging path and dispatcher cadence. These variables do not configure lifecycle event topics. The PostgreSQL outbox is always initialized; it has no enable flag. |
| Streaming | `STREAMING_ENABLED`, `STREAMING_BROKERS`, `STREAMING_TLS_ENABLED`, `STREAMING_TLS_CA_CERT` | The event backbone, Kafka-compatible broker addresses, TLS, and an optional base64-encoded PEM CA certificate for private broker trust. Startup requires `STREAMING_ENABLED=true` and at least one broker. Invalid base64 or decoded non-PEM content prevents startup. |
| Auth | `PLUGIN_AUTH_ENABLED`, `AUTH_M2M_INVERSION_ENABLED` | Route authorization, on by default, and the required M2M-inversion gate for BYOC. |
| Proxy security | `TLS_TERMINATED_UPSTREAM`, `TRUST_PROXY_ENABLED`, `TRUSTED_PROXIES` | Upstream TLS termination and the restrictive trusted-proxy list it requires in hardened deployments. |
| Consignado | `CONSIGNADO_ENABLED` | Defaults to `true`. It gates the inbound `consignado.averbacao.rejected` handling. When you disable it, also keep `CONSUMER_CONSIGNADO_AVERBACAO_REJECTED_ENABLED` off; startup rejects that contradictory configuration. Existing-contract servicing and the booking and payment paths configure independently. See [Consignado privado](/en/products/lender/consignado-privado). |
| Ledger M2M custody | `M2M_SECRETS_BACKEND`, `M2M_VAULT_MOUNT`, `AWS_REGION` | Where the ledger M2M credentials are kept on your own deployment. On Lerian Cloud, Lerian manages them. |
| Ledger accounts | `MIDAZ_LEDGER_ACCOUNT_PROVISIONING_ENABLED` | Defaults to `true`. Before a relay posts, Lender ensures the non-external account aliases from the accounting profile exist; disable it only when you pre-provision the chart of accounts. It never creates assets. |
| Observability | `ENABLE_TELEMETRY`, `OTEL_EXPORTER_OTLP_ENDPOINT` | Telemetry toggle and OTLP collector endpoint. |
| Limits | `RATE_LIMIT_ENABLED` | Request rate limiting. Always on when `ENV_NAME=production`. |
| Docs | `SWAGGER_ENABLED` | Serve the OpenAPI document and API reference UI. Always off when `ENV_NAME=production`. |

## Tenant and ledger defaults

***

Lender serves one tenant (`DEFAULT_TENANT_ID`) with one database schema, and uses a construction-time ledger organization and ledger as the posting default.

## Ledger posting and fails-closed routing

***

A booking reaches the ledger through a durable posting intent and an asynchronous relay. The full path is in [Lender in the platform](/en/products/lender/lender-in-the-platform). Routing fails closed.

A posting books into the ledger organization and ledger resolved from the accounting profile. A posting that resolves no profile target falls back to the env default. If neither resolves a non-empty target, Lender refuses to post rather than book into an empty or wrong ledger.

## Next steps

***

> **[Lender in the platform](/en/products/lender/lender-in-the-platform)**
>
> The posting path, event catalog, and tenant isolation in detail.


# Consignado privado
Source: https://docs.lerian.studio/en/products/lender/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 is 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. 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`. It gates the 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 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

***

> **[Brazil regulatory pack](/en/products/lender/brazil-regulatory-pack)**
>
> CET, IOF, capitalization consent, PDD staging, and the rest of the BR profile.

> **[Lender events](/en/products/lender/lender-events)**
>
> The wire contract, the topics Lender publishes, and how a handler stays safe.


# Core concepts
Source: https://docs.lerian.studio/en/products/lender/core-concepts

Learn Lender's vocabulary: loan products and versions, accounting profiles, applications, loan accounts, schedules, accrual runs, and Brazil-specific terms.

Learn these terms once and every guide, event, and API operation reads the same way. The concepts group by domain: the product catalog, origination, servicing, accounting, and the Brazil extensions.

## Product catalog

***

### Loan product

A **loan product** is the template a loan originates from. It is the named credit offering (a CDC line, a consignado line) that carries its terms, charges, and rate configuration.

### Product version

A product's terms change over time, so a loan product owns **immutable product versions**. Each version freezes the terms as they stood, and every originated contract traces back to the exact version it used at origination. You **activate** the product to pin one version as its current version. Existing loans keep the version they started on.

### Charge

A **charge** is a fee or cost component attached to a product (and inherited by the loans originated from it), for example an origination fee. A charge lives on the product and applies to the schedule.

### Floating rate

A product can reference a **floating-rate table** rather than a fixed rate. Lender resolves the applicable rate from the table at the moments the schedule requires it.

### Accounting profile

An **accounting profile** binds a product version to the ledger (The core financial book that records all transactions, balances, and operations for an organization. It is the single source of truth for a business unit's finances.). It declares the posting rules: which double-entry (Every financial movement is recorded as at least two operations: a debit from one account and a credit to another, so the system always balances.) legs fire for each accounting event (disbursement, prepayment, accrual). It also declares which ledger organization and ledger the transaction books into. Without an accounting profile, a product cannot be activated.

## Origination

***

### Loan application

A **loan application** is a request to originate a loan against a product version. It moves through an explicit lifecycle:

| Action | Meaning |
| - | - |
| **Submit** | Create the application in a pending state. |
| **Approve** | Accept the application; a decision record is kept. |
| **Reject** | Decline the application, with a decision record. |
| **Withdraw** | Retract an application that is pending approval or approved. |
| **Disburse** | Record the funds delivered; the disbursement facts and the resulting loan account are kept. |

### Schedule preview

**Schedule preview** computes the amortisation schedule for a prospective loan without originating anything. You preview the installments and disclosures before an application (or before approval) commits to them.

## Servicing

***

### Loan account

A **loan account** is an active, disbursed loan, the servicing view of a contract. It carries the live schedule, the transactions posted against it, its charges, and its audit history.

### Schedule and installment

The **schedule** is the set of **installments** a loan account owes, in order. Each installment carries its due date and its principal, interest, and charge components.

### Repayment and prepayment

A **repayment** records money received against the schedule. Lender allocates it across the outstanding installments, oldest first. A **prepayment** settles ahead of schedule, in whole or in part. You can **preview a repayment** to see the allocation before recording it.

### Reschedule

A **reschedule** rewrites the remaining schedule of a loan account, for example after a renegotiation.

### Reversal and replay

Corrections are never destructive. A **reversal** undoes a recorded transaction with a compensating entry. A **replay** re-derives account state from its event history. Both preserve a consistent, auditable timeline rather than editing the past.

## Accounting

***

### Posting intent

A **posting intent** is the durable record of a financial event that must book to the ledger. Lender persists the intent as part of the same transaction that changes domain state. It then hands the intent to the ledger relay. The intent lives in the database, so it survives a restart.

### Accrual run

An **accrual run** computes interest (and other time-based amounts) accrued over a period across the book, producing the postings that recognize it. Each recognition covers one loan account, one month, and one amount kind. A repeated run does not accrue twice.

### Journal reference

A **journal reference** is an accrual run's own accounting identifier. It is a separate value from the run's correlation id, which the reference record also stores. The journal reference id identifies one run exactly. A read by correlation id returns the most recent run that shares it.

## Jurisdictions

***

### Jurisdiction and profile

A **jurisdiction** is a market whose credit rules Lender knows about. Each jurisdiction supplies a **profile**: the rules, disclosures, and calendar that market requires. Lender ships a **generic** base profile, which books no credit, and a **Brazil (BR)** profile. The active jurisdiction shapes which disclosures and endpoints apply. See [Jurisdictions](/en/products/lender/jurisdictions).

## Brazil terms

***

The Brazilian profile adds regulated concepts. The Portuguese terms stay as-is, with a gloss. For the use of each term, see the [Brazil regulatory pack](/en/products/lender/brazil-regulatory-pack).

| Term | Gloss |
| - | - |
| **CET** | *Custo Efetivo Total*, the total effective cost of credit disclosed to the borrower, covering interest, taxes, and fees. |
| **IOF** | *Imposto sobre Operações Financeiras*, a federal tax on credit operations, previewable before origination. |
| **Capitalization consent** | The borrower's recorded consent to compound-interest (*juros compostos*) capitalization on the contract. |
| **PDD stage** | *Provisão para Devedores Duvidosos*, the loan-loss provisioning stage a loan account sits in, with tracked transitions. |
| **Credit descriptor** | The SCR-style credit-operation descriptor for a loan account (the regulated operation profile). |
| **Prepayment quote** | A quote for settling a loan account early. A Brazilian prepayment settles against one, within the quote's 24-hour validity. |
| **CCB** | *Cédula de Crédito Bancário*, the bank credit instrument for a consignado contract. |
| **Averbação** | Registration of the payroll deduction with the paying entity, so installments are withheld at source. |

## Next steps

***

> **[Lender in the platform](/en/products/lender/lender-in-the-platform)**
>
> See how these concepts book to the ledger and emit events.

> **[Define a loan product](/en/products/lender/define-a-loan-product)**
>
> Put the product-catalog concepts to work.


# Define a loan product
Source: https://docs.lerian.studio/en/products/lender/define-a-loan-product

Create a loan product, freeze its terms in an immutable version, attach charges and rates, bind an accounting profile, and activate it for origination.

A loan product is the template every loan originates from. Defining one is a small sequence: create the product, version its terms, describe how it books to the ledger, then activate the product. You originate each loan against a **product version**, and activation needs that version to carry an accounting profile.

## Before you start

***

* You need a Lender bearer token (a JWT issued by your Access Manager). Every operation is authenticated and tenant-scoped.
* Decide which [jurisdiction](/en/products/lender/jurisdictions) the product belongs to. Credit books under Brazil. The generic base, `XX`, books no credit. Brazilian products carry extra fields covered in the [Brazil regulatory pack](/en/products/lender/brazil-regulatory-pack).

## Steps

***

**1. Create the product**

`POST /api/v1/loan-products` registers the named product. This is the catalog entry the versions hang off. (Brazil has an alias, `POST /api/v1/br/loan-products`, that accepts the BR extensions.)

**2. Create a version**

`POST /api/v1/loan-products/{id}/versions` freezes a set of terms (rate configuration, term, and the schedule shape) as an **immutable version**. Every loan traces back to the version it used at origination. You never edit a version, you publish a new one. A version must declare its rate band and the borrower kinds it admits, or it originates nothing.

**3. Attach charges**

`POST /api/v1/loan-products/{id}/charges` applies a charge template (an origination fee, a service charge) that the loans originated from this product inherit.

**4. Bind an accounting profile**

`POST /api/v1/loan-products/{id}/accounting-profiles` declares how the product books to the ledger (The core financial book that records all transactions, balances, and operations for an organization. It is the single source of truth for a business unit's finances.). The profile carries the posting rules (which double-entry legs fire for each event) and the ledger organization and ledger they book into. Activation refuses a version that has no profile. See [Accounting and accrual runs](/en/products/lender/accounting-and-accrual-runs).

**5. Activate the product**

`POST /api/v1/loan-products/{id}/activate` sets the product to active and pins the version you name as its current version. Until activation, the product originates nothing. A Brazilian version also needs its carteira, `normPortfolioClass`, before it activates. Each application names the version it uses at origination, so existing loans keep the version they started on.

## Promote a new version

***

Activation pins the first version. Promotion pins every version after it. It repoints a product that is already live at a different current version, without taking the product down and putting it back up.

`POST /api/v1/loan-products/{id}/promote` names the version to pin. Brazil has an alias, `POST /api/v1/br/loan-products/{id}/promote`, that behaves identically.

Promotion carries the same two readiness checks activation carries: an accounting profile is present, and the version is complete for its jurisdiction. It carries them because it is the same act. A second route without them would be a quiet way around the first.

| Refusal | What it means |
| - | - |
| `LENDER-0101` (`409`) | The product is not active, so there is no current version to repoint. Activate it instead, naming the version to pin. |
| `LENDER-0102` (`422`) | The version named is not a version of this product. Read the product's own versions and name one of them. |

> [!WARNING]
>
> **Promotion changes no contract and no application.** Every loan already written keeps the version it was born on. Its schedule, pricing, and charges read from that version for the life of the loan. Every application still in flight keeps its version too. Only new applications read the current version.

## Inspecting products

***

| Operation | Purpose |
| - | - |
| `GET /api/v1/loan-products` | List loan products. |
| `GET /api/v1/loan-products/{id}` | Read a single product, including the version pinned as current. |
| `GET /api/v1/loan-products/{id}/floating-rates` | Read the product's floating-rate table, if it references one. |

> [!TIP]
>
> A floating-rate product resolves its applicable rate from the table when the schedule needs it, rather than pinning a fixed rate at origination.

## What happens downstream

***

Creating and activating products emits `loan_product.created`, `loan_product_version.created`, `loan_product.activated`, `accounting_profile.configured`, and `loan_charge.applied` on the event backbone (see [Lender in the platform](/en/products/lender/lender-in-the-platform)).

## Next steps

***

> **[Originate a loan](/en/products/lender/originate-a-loan)**
>
> Take an active product and originate a loan against it.


# How accrual works
Source: https://docs.lerian.studio/en/products/lender/how-accrual-works

What an accrual run does: the accounting month it recognizes, the amount it computes, what the run produces, and where the resulting posting goes.

Lender does not recognize interest continuously. It recognizes interest in an **accrual run**. One run covers one business date, and for every loan it selects it recognizes exactly one accounting month.

## One closed civil month, the same one for every loan

***

A loan's accounting month is its **competência**, and the calendar anchors it, not the disbursement date. A run recognizes the last civil month that had fully ended before its **business date**. It recognizes that same month for every loan it selects. A run on any day of April closes March.

The mapping is total. Every business date names exactly one competência, and that competência is always a month that is over. No run can recognize a month still in progress. The service sets the month a run closes, whatever day you start the run.

A loan disbursed mid-month is not left out of its first month. Interest spreads across the days of each schedule interval, and a competência collects whatever falls inside it. A loan disbursed on the 12th therefore recognizes that first part-month inside the month it was contracted in.

## What a run does

***

`POST /api/v1/accrual-runs` takes the business date and the run **mode**, and, optionally, up to 100 loan product ids that scope the run. Both `businessDate` and `mode` are required. `mode` labels the run for your own reporting, with one reservation. The `heartbeat` mode belongs to the scheduled driver, and Lender refuses a call that sends it.

**1. Lender selects the loans**

You do not send a list. Lender reads its own book and takes each loan account in a disbursed or active application, within the products you scoped. A loan account that already settled drops out. One run covers the whole book. It walks the candidates page by page until they run out, so no contract misses a competência because the book grew.

**2. Lender recognizes the interest**

For each loan, Lender solves the effective interest rate of the contractual schedule and takes the line for that competência. Recognition works on the contractual cash flows. What the borrower paid does not change it.

**3. Lender writes the recognition and the posting intent**

One database transaction stores the run, one item per recognition, and the balanced posting intent behind each item. Either all of it is durable, or none of it is.

**4. The relay delivers the posting**

After the run commits, the outbox relay posts the balanced transaction to Midaz, and Midaz books it.

## The amount Lender recognizes

***

Recognition follows the effective interest method. The amortized cost starts at the principal the schedule amortizes, less the origination fee. Withholding taxes stay outside it: in Brazil, IOF is a pass-through and never enters the amortized cost.

Lender solves the rate from the schedule itself, so the recognized interest reproduces the contract instead of a separate rate you maintain.

Where the jurisdiction taxes interest revenue, the run recognizes that tax too. The tax is a second amount on the same loan and the same competência, with its own balanced posting. Interest and tax never share a transaction.

## Once per loan, per month, per amount

***

A recognition is unique on three things: the loan account, the competência, and the kind of amount. A second run for the same business date recognizes nothing new for a loan already recognized. It does not double the interest and it does not enqueue a second posting.

That uniqueness is the money-path guarantee. It also makes a run safe to repeat after an interruption.

## What a run produces

***

A run answers with:

* The run identifier and the status of the run.
* A **journal reference**: the accounting identifier of the run.
* The **correlation id** Lender derives from the mode, the business date, and the products in scope.

Behind that answer, the run stores one item for each recognition: the loan account, the competência, the kind of amount, and the amount. Those items are what Lender builds the postings from.

Use the journal reference id to tie the run to your own accounting records: it identifies one run exactly. The reference record also stores the correlation id. Lender derives that id from the mode, the business date, and the products in scope. A read by correlation id therefore returns the most recent run that shares it. [Accounting and accrual runs](/en/products/lender/accounting-and-accrual-runs) covers the two operations that read it back.

## The run does not write the ledger entry

***

A run recognizes interest and enqueues a posting intent. It does not call Midaz, and it does not wait for a booking. The relay posts afterwards, and the ledger books the transaction. A successful run means the recognition and its intent are durable, not that the ledger already shows the entry.

A posting that never reached the ledger is not lost work. Retry the run. Lender rebuilds the intent behind every item the ledger has not acknowledged and enqueues it again under the same deterministic key. As a result, the relay delivers it, and a duplicate stays a duplicate. [Accounting and accrual runs](/en/products/lender/accounting-and-accrual-runs) covers what a retry answers back.

Configure two things before a posting can book:

* Give the product version's accounting profile a rule for the `accrual` event, with balanced legs. Where the jurisdiction taxes interest revenue, add the optional `accrual_tax` rule as well, so the tax has legs of its own.
* Lender always initializes the outbox. Configure the connection to the ledger so the relay can deliver the durable intent. See [Configuration and deploy](/en/products/lender/configuration-and-deploy).

Configure the profile before the first run. Without an accrual rule, Lender has no legs to build a posting from, and the run leaves that loan out.

## Loans a run passes over

***

A selected loan can still recognize nothing:

* The jurisdiction suspends its accrual. In Brazil, the two deepest stages of the provisioning ladder suspend accrual (see [Brazil regulatory pack](/en/products/lender/brazil-regulatory-pack)). A suspended contract still books its retained origination fee; the interest is what it withholds.
* An earlier run already decided that competência for it.
* Its interest for that competência is zero.

None of these fails the run. A run recognizes what it can and reports what it recognized.

## Running accrual on a schedule

***

The run also has a scheduled driver inside the service, and it is on by default. It fires every day at 06:00 UTC until you give it another cron expression.

Daily does not mean a competência a day. Every fire closes the same month, the first one that succeeds decides it, and every later fire that month finds the work already done. The daily cadence is a retry. A service that is down on the 1st closes the month on the 2nd. A once-a-month expression would have lost that competência for good.

The scheduled path and the API path use the same code. A run from cron and a run from a call behave identically.

## Next steps

***

> **[Accounting and accrual runs](/en/products/lender/accounting-and-accrual-runs)**
>
> Accounting profiles, posting rules, and the journal-reference operations.

> **[Lender architecture](/en/products/lender/lender-architecture)**
>
> The domains, the jurisdiction seam, and the outbox that carries money out.

> **[Define a loan product](/en/products/lender/define-a-loan-product)**
>
> Products, versions, and the accounting profile a run depends on.

> **[Brazil regulatory pack](/en/products/lender/brazil-regulatory-pack)**
>
> Provisioning stages, taxes, and the disclosures the Brazilian profile adds.


# How origination works
Source: https://docs.lerian.studio/en/products/lender/how-origination-works

The path one loan application takes: what it binds to, the four lifecycle decisions, the single transaction that disburses it, and the loan account it leaves behind.

Origination turns a request for credit into a live loan account. It has four decisions and one transaction that does everything at once. This page follows one application from submitted to disbursed.

> [!NOTE]
>
> Jurisdiction `XX` books no credit. Lender refuses its products, versions, and applications with 422. Read the [Brazil regulatory pack](/en/products/lender/brazil-regulatory-pack) for what the `BR` profile adds to this path.

## What an application binds to

***

An application binds to a **product version**, never to a product on its own. The version pins the currency, the rate terms, and the accrual basis, so a contract always traces back to the terms it was created under. A later version does not change a loan that already exists. The product must be active, and the version must be the one the product currently originates on.

Activation requires an **accounting profile** on the version. The disbursement builds its posting from the profile's legs. See [Define a loan product](/en/products/lender/define-a-loan-product).

## Preview, if you want it

***

Schedule preview computes the installments and the cost disclosure for prospective terms. When it records the result as an offer, it returns the offer's identifier. It creates no application. Use it to show a borrower what the loan looks like before anyone commits. This step is optional.

## Submit

***

The submit call creates the application in `pending_approval`. It carries the product version, the borrower and the borrower kind, the requested principal, the requested **monthly** interest rate, the number of installments, and an expected disbursement date. Lender accepts up to 600 installments. The requested rate must fall inside the version's rate band.

The body does not carry the **assigned officer**. Lender takes it from the authenticated subject of the submit call. Later decisions are checked against that officer, so submit with the identity that will also approve and disburse.

## Decide

***

Exactly one decision resolves a pending application.

| Decision | Result | Who may act |
| - | - | - |
| Approve | `approved`, with the approved amount and a decision timestamp | The jurisdiction's approval policy. Under `BR`, the assigned officer. |
| Reject | `rejected` | The assigned officer. |
| Withdraw | `withdrawn` | The borrower, or the assigned officer. |

An approved application can still be withdrawn. `rejected` and `withdrawn` are final, and nothing moves out of them.

The approved amount moves no money. It bounds every disbursement that follows.

## Disburse

***

Disbursement moves money, so it carries the most guards. Three things belong in the request:

* An `X-Idempotency` header. Lender requires it on this operation.
* The **loan account identifier**. It is a UUID you choose, and Lender does not mint one for you. That identifier addresses the schedule, the transactions, the charges, and the audit trail.
* The gross requested amount and the net delivered amount.

Lender checks five rules. It checks the first four before it writes anything. It checks the balance rule inside the disbursement transaction, so a failure there rolls the whole disbursement back.

| Guard | Rule |
| - | - |
| Amount | A single disbursement must release the approved amount exactly. A tranche declares its `trancheNumber`. |
| Total | Gross across every tranche must stay within the approved amount. |
| Chronology | The disbursement must not predate the application's creation or the approval decision. |
| Identity | The loan account identifier must be the same on every tranche. |
| Balance | Net must equal gross minus the withholdings the jurisdiction computes, minus the retained origination fee. |

Under `BR` the withholding is IOF. Quote it before you disburse with the tax preview in the [Brazil regulatory pack](/en/products/lender/brazil-regulatory-pack).

## One transaction, four results

***

A disbursement is a single database transaction. Four things happen inside it.

**1. The application becomes disbursed**

Lender appends a disbursement event that records the amounts, the date, and the actor who disbursed.

**2. Lender writes the schedule**

Lender computes a Price (French) amortisation schedule over the cumulative disbursed principal. It stores the result as schedule version 1, with the change reason `origination`.

**3. The jurisdiction pipeline runs**

Under `BR` the pipeline computes the IOF withholding.

**4. Lender enqueues the posting intent**

Lender writes a balanced posting intent to the outbox: principal debited at gross, cash credited at net, one credit for each withholding, and one credit for a retained origination fee.

All four commit together, or all four roll back together. There is no half-disbursed loan. If the schedule cannot be written, or the posting does not balance, the application stays `approved`.

## More than one tranche

***

You can disburse an approved application more than once. The status stays `disbursed`, Lender appends another disbursement event, and Lender writes a **new schedule version** over the cumulative principal. The new version supersedes the previous one on read.

The total across tranches still cannot exceed the approved amount, and every tranche uses the same loan account identifier.

## Two callers, one application

***

Every lifecycle write states the status it expects to find. When two callers decide the same application at the same time, one wins and the other receives `409 Conflict` without changing anything. A repeated disburse that does not match the first one is refused the same way.

## The state model

***

| From | Decision | To |
| - | - | - |
| `pending_approval` | approve | `approved` |
| `pending_approval` | reject | `rejected` |
| `pending_approval` or `approved` | withdraw | `withdrawn` |
| `approved` or `disbursed` | disburse | `disbursed` |

## What you have at the end

***

* An application that reads `disbursed`, with one disbursement event per tranche.
* A loan account under the identifier you supplied, carrying its schedule, its transactions, its charges, and its audit events.
* A posting intent on the way to the ledger. That booking is asynchronous, so it lands shortly after the request returns rather than during it.
* One lifecycle event on the event backbone for each transition.

Continue in [Service a loan](/en/products/lender/service-a-loan).

## Next steps

***

> **[Service a loan](/en/products/lender/service-a-loan)**
>
> Record repayments, prepay, reschedule, and correct an active loan account.

> **[Lender architecture](/en/products/lender/lender-architecture)**
>
> The domains, the jurisdiction seam, and the outbox that carries money out.

> **[Accounting and accrual runs](/en/products/lender/accounting-and-accrual-runs)**
>
> Posting rules, accrual runs, and the journal reference that ties a booking back.

> **[Brazil regulatory pack](/en/products/lender/brazil-regulatory-pack)**
>
> IOF, CET, capitalization consent, and the rest of the Brazilian profile.


# Jurisdictions
Source: https://docs.lerian.studio/en/products/lender/jurisdictions

How Lender stays jurisdiction-aware: the profile registry, the generic base, the Brazil profile, and the discovery endpoints that expose them.

Credit rules differ by market. Lender is **jurisdiction-aware**: it carries a registry of jurisdiction **profiles**, each supplying the rules, disclosures, and calendar its market needs. The active jurisdiction shapes which behavior applies.

## The profile model

***

* **Generic (XX)**: the base profile. It books no credit: Lender refuses to create a product, a version, or an application under it. A tenant with no jurisdiction binding is refused with 403.
* **Brazil (BR)**: the profile that books credit. It adds CET disclosure, IOF preview, capitalization consent, PDD staging, the credit-operation descriptor, prepayment quotes, a Brazilian business calendar, and the consignado privado journey.

You reach Brazilian behavior through BR-prefixed endpoints (`/api/v1/br/...`). Several of those endpoints are jurisdiction-aware aliases of the generic operations. See the [Brazil regulatory pack](/en/products/lender/brazil-regulatory-pack) and [Consignado privado](/en/products/lender/consignado-privado).

## Discovery endpoints

***

The compiled-in profiles are discoverable at runtime, so a client can learn which jurisdictions a deployment supports:

| Operation | Purpose |
| - | - |
| `GET /api/v1/jurisdictions` | List the registered jurisdiction profiles. Each one reports `booksCredit`. |
| `GET /api/v1/jurisdictions/{code}` | Read one jurisdiction profile by its code. |

> [!NOTE]
>
> Profiles ship with the service, not as runtime configuration. Discovery tells you what a given deployment can do. You cannot edit a profile through the API.

## Next steps

***

> **[Brazil regulatory pack](/en/products/lender/brazil-regulatory-pack)**
>
> Everything the Brazilian profile adds.


# Lender architecture
Source: https://docs.lerian.studio/en/products/lender/lender-architecture

The parts Lender is built from: eight domains, the jurisdiction profile that supplies every market rule, the request pipeline, and the outbox that carries money to the ledger.

Lender is one service. Inside it, eight domains own the credit journey, a jurisdiction **profile** supplies every market-specific rule, and money reaches the ledger through a durable queue instead of an inline call.

## Eight domains, one service

***

| Domain | What it owns | Where it stops |
| - | - | - |
| **Products** | Loan products, product versions, charge templates, floating-rate tables. | A version never changes. New terms are a new version. |
| **Origination** | The application lifecycle, and the schedule that disbursement produces. | It records the intent to book. It does not write to the ledger. |
| **Servicing** | The active loan account: schedule versions, repayments, prepayments, reschedules, corrections. | It never edits history. A correction is a new transaction. |
| **Accounting** | Accounting profiles, posting rules, posting intents, accrual runs, journal references. | It builds balanced postings. The relay delivers them. |
| **Audit** | The trail of what happened to a loan account. | Append-only. Nothing rewrites an event. |
| **Assignment** | Funds, sets of receivables assigned to them, their documents, and the cession facts. | It records external facts as evidence of each step. |
| **Issuance** | The credit instruments that evidence an application. | An instrument evidences an application that already exists. |
| **Portfolio** | The portfolio dashboard and the delinquency reads. | It reads. It does not change a loan account. |

Each domain owns its own tables and its own operations. The **loan account identifier** is the key that joins them. Lender does not mint that identifier. You supply it when you disburse, and every domain addresses the loan by it from then on.

## The jurisdiction seam

***

Credit rules differ by market, so no domain names a market. Everything market-specific arrives through a jurisdiction profile, which supplies a fixed set of capabilities:

* The tax engine that computes withholdings at disbursement and revenue taxes on accrual.
* The holiday calendar and the day-count convention.
* The effective-cost method behind the cost disclosure.
* The caps registry that holds regulated rate and fee limits.
* The disclosures the market requires.
* The disbursement pipeline that runs inside the disbursement transaction.
* The product validator and the schedule-preview extension.
* The actor policies that decide who may approve and who may disburse.

Profiles are compiled into the service rather than configured at runtime. Two ship: **BR** for Brazil, and **XX**, the generic base, which books no credit. The jurisdictions table in the database is a projection of what the service carries, so no API call creates a jurisdiction. See [Jurisdictions](/en/products/lender/jurisdictions).

## How a request resolves

***

Every request passes the same three gates before a handler runs.

**1. Authentication**

Lender expects a bearer JWT. The two jurisdiction-discovery reads are the only public operations.

**2. Tenant resolution**

The tenant comes from the validated identity. It is never a header, a body field, or a path parameter, so a caller cannot select a tenant.

**3. Jurisdiction resolution**

Lender reads the tenant's jurisdiction binding and puts the matching profile in the request context. The lookup is cached for five minutes, so a rebinding takes effect within that window.

Bind every tenant to a jurisdiction before it sends traffic. Lender refuses a request from an unbound tenant.

## Money leaves through the outbox

***

Lender never posts to the ledger during your request. The path has four properties:

1. A money event, such as a disbursement, a repayment, or an interest accrual, writes a **posting intent** in the same database transaction as the business row. A crash between the two is not possible.
2. A dispatcher reads the intent from the outbox and relays it to Midaz.
3. Each intent carries a deterministic idempotency key, so a retried relay collapses onto one ledger transaction.
4. Routing fails closed. A posting books into the organization and ledger that the accounting profile resolves, and a single-tenant deployment can fall back to its configured default. When no target resolves, Lender does not post at all.

Configure the ledger endpoint and its credentials before you expect bookings. Until they resolve, intents wait in the outbox and nothing reaches the ledger.

[Lender in the platform](/en/products/lender/lender-in-the-platform) covers the full path, including what the accounting profile contributes to it.

## What the service exposes

***

| Surface | Purpose |
| - | - |
| `/api/v1/...` | The whole product API, described by one OpenAPI document. |
| `/health`, `/readyz`, `/version` | Liveness, dependency readiness, and build metadata. All three answer before authentication. |
| `/api/v1/streaming/manifest` | The catalog of events this deployment publishes. |
| `/api/v1/systemplane/...` | Runtime configuration administration. |

Read the [health and readiness reference](/en/reference/health-and-readiness) for the probe contract shared across Lerian products.

## Stores

***

| Dependency | Role |
| - | - |
| PostgreSQL | Every domain table, and the outbox. One migration set applies. |
| Valkey or Redis | Idempotency records, and the jurisdiction cache. |
| RedPanda | Lifecycle events. The service does not start without it. |
| Midaz | The destination of every posting. |

[Configuration and deploy](/en/products/lender/configuration-and-deploy) lists the settings behind each one.

## Time-driven work

***

The accrual run also runs as a scheduled job. Each job has its own on or off default and its own schedule, and you can override both. See [Accounting and accrual runs](/en/products/lender/accounting-and-accrual-runs).

## Next steps

***

> **[How origination works](/en/products/lender/how-origination-works)**
>
> One application from submitted to disbursed, and the transaction that does the work.

> **[Core concepts](/en/products/lender/core-concepts)**
>
> The vocabulary the whole product shares.

> **[Lender in the platform](/en/products/lender/lender-in-the-platform)**
>
> The posting path, the event catalog, and tenant isolation.

> **[Configuration and deploy](/en/products/lender/configuration-and-deploy)**
>
> Dependencies, the container, and the settings that shape a deployment.


# Lender console
Source: https://docs.lerian.studio/en/products/lender/lender-console

The Lender web console: how it signs in, the screens it ships with, and the work it leaves to the API.

The **Lender console** is a browser interface over the same [API](/en/products/lender/lender-rest-api) you can drive programmatically. It is a single environment-agnostic bundle: a deployment serves the console its configuration at start-up, so the same image points at any environment.

This page documents the screens in the console.

## Signing in

***

The console is a standard OpenID Connect client. It runs the authorization-code flow with PKCE straight from the browser to the identity provider you configure. Point it at the same Access Manager that issues the API tokens. The console exchanges the code for tokens, and refreshes them on demand before they expire.

Tokens live in memory only. The console never writes them to browser storage. A reload or a new tab therefore starts from the sign-in screen rather than from a session someone else could read off the device.

After the exchange the console asks Lender who the caller is, and takes the permissions it renders from that answer rather than from the token. The console does not show an action the identity may not perform, unless the deployment's tokens carry no declared permissions at all. In that case, the console shows every action and lets the server refuse the ones the identity may not take. Signing out ends the local session and, when you configure the provider's end-session URL, signs the user out at the provider too. Without that URL, the provider's own session survives and the next sign-in skips the prompt.

> [!WARNING]
>
> **Authentication ships turned off.** In its default configuration the console establishes no session, shows every screen, and sends no bearer token. A deployment gets this state if nobody configures the identity provider. Turn it on and supply the authorization endpoint, the token endpoint, and the client id before the console reaches anyone. If you turn it on without those three, the console refuses loudly, with a misconfiguration screen rather than partial access.

## What you can do in it

***

| Area | Screens | What an operator does there |
| - | - | - |
| Portfolio | Dashboard | The landing screen. Exposure, delinquency buckets, the trend over recent months, and the delinquent-loan register for a business date, each row opening the loan account behind it. See [Portfolio and delinquency](/en/products/lender/portfolio-and-delinquency). |
| Credit | Loan products | List and filter the catalog, walk the wizard that creates a product and its first version, and build a version's accounting profile. See [Define a loan product](/en/products/lender/define-a-loan-product). |
| Credit | Loan applications | List and filter applications, create one against a product version after previewing its schedule, and open one to approve, reject, withdraw, or disburse it. See [Originate a loan](/en/products/lender/originate-a-loan). |
| Credit | Credit instrument | Emit the CCB for an application against the loan product's published document template, list the instruments already emitted for it, and download one. |
| Credit | Loan accounts | List live accounts and open one for its schedule, transactions, charges, and audit trail, with record-repayment, prepay, and reschedule actions and the Brazilian panel for PDD stage, prepayment quote, and tax. See [Service a loan](/en/products/lender/service-a-loan). |
| Accounting | Accrual runs | Queue a run for a business date, and retry the items of one that did not finish. See [Accounting and accrual runs](/en/products/lender/accounting-and-accrual-runs). |
| Accounting | Journal references | Resolve a correlation id or a reference id to the posting it names. |
| Operations | Re-assessments | The worklist of contracts whose qualitative problem-asset characterisation has outlived the re-assessment horizon of its product version. |
| Operations | Divergence queue | The consignado exception desk: filter by category, effect, status, assignee, and breached deadline, then open one to compare the client's declared fact against Lender's own, assign it, dispose of it, or send it back to the queue. |
| Operations | Assignment desk | Assemble a set of receivables for a fund, check its eligibility, approve it, produce the offer file, ingest the remessa the fund returns, record the endorsement term, and work the exceptions the set raises. |
| Settings | Jurisdictions | Read the jurisdiction profiles compiled into the service. |

The console has no permission model of its own. Every action it offers goes through the same API operation, authorized by the same identity and tenant.

## What the console does not do

***

The console has no screen for reconciliation, CNAB export, rescission capture, portability capture, or a consignado contract sheet and list. An account already in a portability-requested state still displays as one.

There is no consignado contract screen because a consignado contract is not created in the console. A CLT contract arrives as a fact from the gateway once the client's own systems have registered it with the payroll rail. Private and INSS lending is originated through the ordinary loan application above. See [Consignado privado](/en/products/lender/consignado-privado).

## Next steps

***

> **[Lender REST API](/en/products/lender/lender-rest-api)**
>
> Everything the console does, driven programmatically.


# Lender events
Source: https://docs.lerian.studio/en/products/lender/lender-events

Use Lender's v3 application streams, source-qualified CloudEvents types, outbox delivery, manifest, and runtime consumer contract.

Lender publishes business facts and commands as CloudEvents 1.0 over Kafka. Publication is required, tenant-scoped, and backed by a transactional outbox.

## Configure publication

***

| Setting | Value |
| - | - |
| `STREAMING_ENABLED` | `true` |
| `STREAMING_BROKERS` | Your Kafka or RedPanda brokers. |
| `STREAMING_CLOUDEVENTS_SOURCE` | `lender`. Startup rejects any other source. |

Lender does not start when publication is disabled, when no broker is set, or when the source is invalid.

## Wire contract

***

Lender uses the v3 application-stream contract. A topic identifies the producing application and message class, not one event.

| Wire element | Value |
| - | - |
| Fact topic | `lerian.streaming.lender` |
| Command topic | `lerian.streaming.lender.commands` |
| `ce-source` | `lender` |
| `ce-type` | `studio.lerian.lender.<resource>.<event>` |
| Dispatch key | `<resource>.<event>` from `ce-resourcetype` and `ce-eventtype` |
| Partition key | Tenant identifier |

For example, a disbursement fact travels on `lerian.streaming.lender` with `ce-type: studio.lerian.lender.loan_application.disbursed`.

`ce-schemaversion` carries the payload version. Schema v2 does not add a topic suffix under the v3 contract. Route on the CloudEvents headers, not on a per-event topic name.

## Published contract

***

The manifest declares 39 definitions: 37 facts and two commands. Feature gates control individual integration paths, so consume only the contracts exposed by the deployed manifest.

The two catalog commands are:

* `consignado.exclusao.requested`: requests a consignado exclusion from the payroll rail.
* `consignado.redirecionamento.requested`: requests a consignado redirection from the payroll rail.

See [Lender event reference](/en/reference/events/lender) for every catalog definition and its source-qualified `ce-type`.

## Events Lender consumes

***

Lender wires 15 gateway-facing fact keys from `lerian.streaming.consignado-gw`. The keys include contract registration, disbursement confirmation, averbação rejection, employment status, redirection outcomes, reconciliation, exclusion outcomes, correction availability, portability outcomes, and refinance outcomes. The corresponding consumers are configuration-gated. Portability and refinance each use one opt-in flag for their pair of outcomes.

The gateway has emission paths for the first 13 keys. The portability pair reaches Lender only when its outcome consumer is enabled and the deployed gateway manifest declares the event. The manifest does not declare the two refinance outcomes, so those two listeners receive no live traffic from the current gateway runtime.

A Lender handler consumes `match_run.completed` from `lerian.streaming.matcher`. For the default handoff, Matcher must use `STREAMING_CLOUDEVENTS_SOURCE=matcher`. Lender 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 runtimes.

See [Consignado privado](/en/products/lender/consignado-privado) for the payroll journey.

## Durability and delivery

***

Lender writes each outbound business event to the PostgreSQL outbox in the same database transaction as the state change. A relay publishes it after commit. Broker delivery is at least once: deduplicate on `(ce-source, ce-id)` and make handlers idempotent.

The relay retries each row up to `OUTBOX_MAX_DISPATCH_ATTEMPTS` times. The `OUTBOX_RETRY_WINDOW_SEC` value sets the minimum wait between attempts for a row. It is a per-attempt delay, not a total retry window. The defaults are `10` attempts and `300` seconds.

## Payload conventions

***

Payloads are JSON facts, not diffs. Money and rate values use decimal strings rather than JSON numbers. Timestamps use RFC 3339 UTC. Read `ce-schemaversion` before decoding a versioned payload.

## Check the deployed contract

***

`GET /api/v1/streaming/manifest` returns the deployed catalog, application topics, schema versions, and delivery policies. It requires a bearer token with `streaming_manifest` `read`.

Read the manifest when your consumer starts and reject an unexpected source, event key, or schema version before processing traffic.

## Next steps

***

> **[Lender event reference](/en/reference/events/lender)**
>
> Inspect emitted, catalog-only, and consumed contracts.

> **[Consignado privado](/en/products/lender/consignado-privado)**
>
> Follow the payroll command and fact flow.


# Lender in the platform
Source: https://docs.lerian.studio/en/products/lender/lender-in-the-platform

See how Lender posts to the Midaz ledger, emits lifecycle events on the event backbone, scopes each event and posting to its tenant, and reports telemetry data.

Lender is a Lerian primitive that runs on the platform. Four platform seams matter when you operate it: the ledger posting path, the event stream, tenant isolation, and observability.

## The Midaz posting path

***

Lender is the source of truth for the credit journey. [Midaz](/en/products/midaz/about-midaz) is the source of truth for balances. Each money event, such as a disbursement, a repayment, or an interest accrual, becomes a balanced double-entry (Every financial movement is recorded as at least two operations: a debit from one account and a credit to another, so the system always balances.) transaction bound for the ledger (The core financial book that records all transactions, balances, and operations for an organization. It is the single source of truth for a business unit's finances.). The path preserves that posting intent and delivers it idempotently. The ledger reaches consistency once the outbox delivery succeeds and the dispatcher posts, which may lag or stay pending while routing is unavailable.

**1. A domain event produces a posting intent**

Lender persists a durable **posting intent** on a money event. The intent lands in the same database transaction that changes domain state. Lender writes the intent to a transactional **outbox**, so it survives a crash between "state changed" and "ledger booked."

**2. The relay posts a balanced transaction to Midaz**

With the Midaz ledger relay configured, an outbox dispatcher posts the balanced double-entry transaction through the official SDK. Otherwise, the durable intent remains in the outbox. The legs come from the product's **accounting profile**.

**3. Idempotency is durable**

Each posting carries a deterministic idempotency key computed by Lender. A retried post collapses to the same Midaz transaction. Midaz's own idempotency window is a backstop, not the primary guard.

**4. Routing fails closed**

The transaction books into the ledger organization and ledger the accounting profile resolves. If routing cannot resolve a non-empty target, the post **fails closed**: Lender refuses to book rather than write into an empty or wrong target.

With the ledger relay configured, Lender reaches Midaz through [Access Manager](/en/platform/access-manager). It authenticates with machine-to-machine (M2M) credentials and a short-lived JWT, per tenant.

## Lifecycle events

***

Lender's event catalog contains 39 definitions: 37 facts and two commands. Every event Lender emits is outbox-backed and tenant-scoped. Runtime emission also depends on the applicable feature gates. Check the deployed manifest and the [Lender event reference](/en/reference/events/lender) before depending on a definition as a live integration.

Lender uses the v3 application-stream contract:

| Wire element | Value |
| - | - |
| Fact topic | `lerian.streaming.lender` |
| Command topic | `lerian.streaming.lender.commands` |
| `ce-source` header | `lender` |
| `ce-type` header | `studio.lerian.lender.<resource>.<event>` |
| Partition key | the tenant |

All facts share one application topic, and all commands share the command topic. Route by `ce-resourcetype` and `ce-eventtype`. Schema version travels in `ce-schemaversion` and does not change the topic.

The events ride the same outbox as the ledger relay, so they share one durability guarantee. The local state change and the event commit together in a single database transaction. The posting intent joins them when the change produces one. The outbox dispatcher applies the ledger posting afterward, when it relays the intent to Midaz. Lender's state and the Midaz booking therefore reach consistency later, not in the same transaction.

> [!NOTE]
>
> Lender wires 15 payroll-gateway keys from `lerian.streaming.consignado-gw`. The corresponding consumers are configuration-gated. Its Matcher listener consumes `match_run.completed` from `lerian.streaming.matcher`. The contract matches only when Matcher uses `STREAMING_CLOUDEVENTS_SOURCE=matcher` and sends `ce-source: matcher`, `ce-type: studio.lerian.matcher.match_run.completed`, `ce-resourcetype: match_run`, and `ce-eventtype: completed`. See [Lender events](/en/products/lender/lender-events) and [Consignado privado](/en/products/lender/consignado-privado).

## Tenant isolation

***

Like every Lerian product, Lender is built for full tenant isolation.

* **Tenant-scoped** events and ledger postings: every emitted event and every Midaz transaction carries the tenant it belongs to.

## Observability

***

Lender emits structured logs, OpenTelemetry traces, and metrics on the same observability stack as the rest of the platform, including database, assertion, and panic-recovery metrics. See [Observability](/en/platform/observability).

## Next steps

***

> **[Accounting and accrual runs](/en/products/lender/accounting-and-accrual-runs)**
>
> Go deeper on posting rules, accrual runs, and journal references.

> **[Configuration and deploy](/en/products/lender/configuration-and-deploy)**
>
> See the dependencies and configuration the posting path and event stream require.


# Prerequisites
Source: https://docs.lerian.studio/en/products/lender/lender-prerequisites

What must be true before your first Lender call: the services it depends on, the migrations, the configuration that origination requires, and the token that carries the officer.

Lender needs a small set of things in place before its first API call. This page lists them in the order you set them up. When every item here is true, follow the [Quick start](/en/products/lender/lender-quick-start) to originate a loan.

## Services Lender depends on

***

| Service | Version | Why Lender needs it |
| - | - | - |
| **PostgreSQL** | 17 | The primary data store. Every product, application, schedule, and posting intent lives here. |
| **Valkey** (Redis-compatible) | 8 | Idempotency records, cache, and rate limiting. |
| **Identity provider** | — | Issues the bearer tokens Lender authorizes each route against. |
| **Midaz** | — | The ledger the disbursement posting reaches. Optional for your first loan. |
| **RedPanda** | — | The event backbone for the event catalog. Required. |

PostgreSQL, Valkey, and RedPanda are required: Lender does not start without the event backbone. An identity provider is required when route authorization is enabled, which is the default. Production requires it. A first loan needs no Midaz. Read [Ledger postings](#ledger-postings) below for what waits.

## Run Lender locally

***

Lender is a single Go service. A local run needs the Go toolchain at 1.26 or later, Docker with Compose, and Make.

**1. Create the environment file**

`make set-env` copies `config/.env.example` to `config/.env`. Edit that file for every setting on this page.

**2. Start the dependencies**

`make up` starts the Compose dependencies and the service on port `8080`.

**3. Apply the migrations**

`make migrate-up` applies the migrations. See the next section.

**4. Run with live reload**

`make dev` runs the service with Air.

## Apply the migrations

***

Lender does not migrate the database when it starts. You apply migrations out of band, from one set in the `migrations` directory. The container image carries a `/migrate` binary that applies it.

The set also seeds the **jurisdiction registry**: two active jurisdictions, `BR` for Brazil and `XX`, the generic base. No API creates a jurisdiction. The deployed binary carries each profile's behavior, and the table records which codes that binary knows. Read [Jurisdictions](/en/products/lender/jurisdictions) for what a profile decides.

## Required configuration

***

The PostgreSQL outbox is mandatory and is initialized automatically. Configure authentication when your deployment enables route authorization.

### An authenticated subject: `PLUGIN_AUTH_ENABLED=true`, the default

Lender records who acted on every loan application. It reads the assigned officer from the bearer token's subject, not from the request body. Every loan-application call therefore needs an authenticated identity.

`PLUGIN_AUTH_ENABLED` defaults to `true`. Set `PLUGIN_AUTH_HOST` to the address of your identity provider.

Then send a bearer token on every call. The token needs a non-empty subject claim, and the same subject must create, approve, and disburse the application.

Lender defines its roles and permissions in a seed file. Load that seed into your identity provider. The officer's role needs these permissions:

| Resource | Actions |
| - | - |
| `loan_product` | `write` |
| `accounting` | `write` |
| `loan_applications` | `preview:schedule`, `create`, `approve`, `disburse` |
| `loan_accounts` | `read` |

### A durable posting sink: always present

A disbursed loan records its posting intent durably. Lender initializes its transactional PostgreSQL outbox on every deployment, in the same database transaction that moves the application to `disbursed`. `OUTBOX_ENABLED` does not exist.

The dispatcher relays each intent afterwards, on the cadence `OUTBOX_DISPATCH_INTERVAL_SEC` sets. Read [Accounting and accrual runs](/en/products/lender/accounting-and-accrual-runs) for what the ledger receives.

## Ledger postings

***

Point Lender at Midaz when you want postings to land in the ledger:

| Variable | Purpose |
| - | - |
| `MIDAZ_LEDGER_BASE_URL` | The ledger address. |
| `MIDAZ_OAUTH_TOKEN_URL` | Where Lender gets its ledger credentials. |
| `MIDAZ_LEDGER_ORGANIZATION_ID`, `MIDAZ_LEDGER_ID` | The default posting target. |

The loan originates with or without these. Until you configure a ledger endpoint, posting intents stay durable in the outbox and the ledger entry waits. Configure the ledger before you expect bookings.

## Tenant defaults

***

`DEFAULT_TENANT_ID` identifies the tenant, and it must be a valid UUID. The migrations bind the default tenant, `11111111-1111-1111-1111-111111111111`, to `BR`. If you set another `DEFAULT_TENANT_ID`, add its row to `public.tenant_jurisdictions`, or Lender refuses its requests with 403.

## Event streaming

***

Lender does not start without the event backbone. Set `STREAMING_ENABLED=true`, point `STREAMING_BROKERS` at RedPanda, and set `STREAMING_CLOUDEVENTS_SOURCE=lender`. Lender validates these values when it starts.

## Checklist

***

* PostgreSQL 17, Valkey 8, and RedPanda reachable.
* Migrations applied.
* `STREAMING_ENABLED=true` and `STREAMING_BROKERS` set.
* When route authorization is enabled, ensure the identity provider is reachable, and use a bearer token with a subject and every permission in the table above.
* `DEFAULT_TENANT_ID` a valid UUID.

## Next steps

***

> **[Quick start](/en/products/lender/lender-quick-start)**
>
> Seven calls from an empty database to a disbursed loan.

> **[Configuration and deploy](/en/products/lender/configuration-and-deploy)**
>
> The full container shape, the wider environment surface, and the ledger posting path.


# Quick start
Source: https://docs.lerian.studio/en/products/lender/lender-quick-start

Seven calls from an empty database to a disbursed loan: a product, a version, an accounting profile, an activation, an application, an approval, and a disbursement.

This page takes you from an empty database to one disbursed loan in seven calls. Every call sends `application/json`. **Send every money and rate field as a decimal string**, never as a JSON number.

Complete the [Prerequisites](/en/products/lender/lender-prerequisites) first. Send the same bearer token on all seven calls. Lender takes the officer from the token subject, and only that officer can approve and disburse the application.

> [!NOTE]
>
> This walkthrough books a Brazilian loan with tax regime `none`, which computes no IOF and keeps the amounts in step 7 simple. Read the [Brazil regulatory pack](/en/products/lender/brazil-regulatory-pack) for a product that withholds IOF. A payroll-deducted contract belongs to the consignado privado bounded context. Read [Consignado privado](/en/products/lender/consignado-privado) for its vocabulary and its lifecycle topics.

## The seven calls

***

```
1. POST /api/v1/loan-products                          → productId
2. POST /api/v1/loan-products/{productId}/versions     → versionId
3. POST /api/v1/loan-products/{productId}/accounting-profiles
4. POST /api/v1/loan-products/{productId}/activate     → active
5. POST /api/v1/loan-applications                      → pending_approval
6. POST /api/v1/loan-applications/{id}/approve         → approved
7. POST /api/v1/loan-applications/{id}/disburse        → disbursed
```

## 1. Create the product

***

`POST /api/v1/loan-products`

```json theme={null}
{
  "name": "Personal loan",
  "loanType": "personal",
  "jurisdictionCode": "BR"
}
```

`loanType` takes `personal`, `commercial`, or `card`. `jurisdictionCode` is `BR`. Any other code returns 422.

The response carries the new `id`. The product is in `draft`.

## 2. Create a version

***

`POST /api/v1/loan-products/{productId}/versions`

```json theme={null}
{
  "jurisdictionCode": "BR",
  "changeReason": "initial version",
  "currency": "BRL",
  "rateMode": "fixed",
  "fixedAnnualRateBps": 1800,
  "rateBand": { "minAnnualRateBps": 1200, "maxAnnualRateBps": 4800 },
  "admittedBorrowerKinds": ["pessoaFisica"],
  "jurisdictionExtensions": {
    "taxRegime": "none",
    "normPortfolioClass": "C5"
  }
}
```

The version is the immutable snapshot of terms an application binds to.

* **`currency` has no default.** Supply a valid ISO-4217 code in uppercase. The version is the currency source of truth from here to the ledger.
* **`rateBand` is required.** It is the price band the version authorizes, in annual basis points. An application whose rate falls outside it is refused.
* **`admittedBorrowerKinds` names who the version lends to.** An empty or omitted list admits no borrower.
* **`normPortfolioClass` is the carteira.** A Brazilian version without one cannot be activated in step 4.
* **A fixed version carries no floating linkage.** With `rateMode: fixed`, omit `floatingRateTableId`, `floatingSpreadBps`, and `requiresFloatingRate`. Lender rejects a fixed version that carries any of them.
* **`jurisdictionCode` is required**, and it must match the product's. A version cannot move a product to another jurisdiction.

The response carries the `versionId`.

## 3. Bind an accounting profile

***

`POST /api/v1/loan-products/{productId}/accounting-profiles`

The profile maps each accounting event onto general-ledger accounts. Activation refuses a product without one, so bind it now.

```json theme={null}
{
  "loanProductVersionId": "<versionId>",
  "accountingMode": "accrual",
  "postingRules": [
    {
      "eventType": "disbursement",
      "legs": [
        { "account": "1100.10.001", "role": "principal", "side": "debit" },
        { "account": "1000.10.001", "role": "cash", "side": "credit" }
      ]
    },
    {
      "eventType": "repayment",
      "legs": [
        { "account": "1000.10.001", "role": "cash", "side": "debit" },
        { "account": "1100.10.001", "role": "principal", "side": "credit" }
      ]
    },
    {
      "eventType": "prepayment",
      "legs": [
        { "account": "1000.10.001", "role": "cash", "side": "debit" },
        { "account": "4200.10.001", "component": "charge_rebate", "side": "debit", "optional": true },
        { "account": "4300.10.001", "component": "iof_refund", "side": "debit", "optional": true },
        { "account": "1100.10.001", "role": "principal", "side": "credit" },
        { "account": "2400.10.001", "component": "iof_due", "side": "credit", "optional": true }
      ]
    },
    {
      "eventType": "accrual",
      "legs": [
        { "account": "1200.10.001", "role": "interest", "side": "debit" },
        { "account": "4100.10.001", "role": "interest", "side": "credit" }
      ]
    },
    {
      "eventType": "collection_unapplied",
      "legs": [
        { "account": "1000.10.001", "role": "cash", "side": "debit" },
        { "account": "2100.10.001", "role": "unapplied_cash", "side": "credit" }
      ]
    },
    {
      "eventType": "collection_reapply",
      "legs": [
        { "account": "2100.10.001", "role": "unapplied_cash", "side": "debit" },
        { "account": "1100.10.001", "role": "principal", "side": "credit" }
      ]
    },
    {
      "eventType": "collection_refund",
      "legs": [
        { "account": "2100.10.001", "role": "unapplied_cash", "side": "debit" },
        { "account": "1000.10.001", "role": "cash", "side": "credit" }
      ]
    }
  ]
}
```

Send one rule per accounting event. Seven events need a rule: `disbursement`, `repayment`, `prepayment`, `accrual`, `collection_unapplied`, `collection_reapply`, and `collection_refund`. The other event types are optional. Fewer than seven rules is rejected before the handler runs. A product under Brazilian credit-loss rules also needs `provision_constitution` and `provision_reversal`, or its measured provision does not post to the ledger. Activation does not check them.

Each leg declares exactly one of `role` or `component`, and no account appears on both sides of the same rule. Four events also carry a fixed leg shape:

| Event | Legs |
| - | - |
| `accrual` | Exactly one debit and one credit. |
| `prepayment` | Exactly five, in this order: `cash` debit, optional `charge_rebate` debit, optional `iof_refund` debit, `principal` credit, optional `iof_due` credit. |
| `collection_unapplied` | Exactly two: `cash` debit, `unapplied_cash` credit. |
| `collection_refund` | Exactly two: `unapplied_cash` debit, `cash` credit. |

`collection_reapply` takes `unapplied_cash` as its only debit. Each credit it carries must also appear as a credit on `repayment` or `prepayment`, with the same account and the same role. `disbursement` and `repayment` each need at least one debit and one credit.

Keep the `disbursement` rule at two legs, as above. Lender fills the `cash` leg with the net amount and every other structural leg with the gross amount. A `component` leg takes a computed withholding, and tax regime `none` computes none, so the two-leg rule is the one that balances in this walkthrough.

Read [Define a loan product](/en/products/lender/define-a-loan-product) for the wider product surface.

## 4. Activate the product

***

`POST /api/v1/loan-products/{productId}/activate`

```json theme={null}
{ "versionId": "<versionId>" }
```

Activation pins the version that new applications originate on. It refuses a product that has no accounting profile, and a Brazilian version that has no carteira. An application on a product that is not active is refused.

## 5. Create the application

***

`POST /api/v1/loan-applications`

Send the header `X-Idempotency`. Lender requires it on this call and on steps 6 and 7. A retry with the same value replays the first response and writes nothing new.

```json theme={null}
{
  "loanProductVersionId": "<versionId>",
  "borrowerId": "3f2b8c1e-7a4d-4e9b-9c2a-5d6e7f8a9b0c",
  "borrowerKind": "pessoaFisica",
  "requestedPrincipalAmount": "50000.00",
  "requestedInterestRate": "0.01500000",
  "requestedInstallments": 24,
  "expectedDisbursementDate": "2026-08-01T12:00:00Z"
}
```

* `borrowerId` is a UUID. `borrowerKind` takes `pessoaFisica` or `pessoaJuridica`, and the version must admit it.
* `requestedInterestRate` is the **monthly** rate as a decimal string at scale 8. It must be greater than `0` and no greater than `1`. Lender builds the schedule from this rate and compares it with the version's rate band in annual basis points: `"0.01500000"` a month is `1800` bps a year, inside the band from step 2.
* `requestedInstallments` is between 1 and 600.
* `previewScheduleSnapshotId` is optional. To cite the quote you showed the borrower, send the `scheduleOfferSnapshotId` that `POST /api/v1/loan-applications/preview-schedule` returned.
* There is no `assignedOfficerId` field. Lender sets it from the token subject.

The application comes back in `pending_approval`, carrying the jurisdiction code and profile version Lender resolved from the product version.

## 6. Approve

***

`POST /api/v1/loan-applications/{id}/approve`

```json theme={null}
{
  "approvedAmount": "48000.00",
  "decisionAt": "<current time, RFC3339>",
  "note": "within policy"
}
```

`approvedAmount` becomes the ceiling on everything you disburse. The application moves to `approved` and carries the decision record.

## 7. Disburse

***

`POST /api/v1/loan-applications/{id}/disburse`

```json theme={null}
{
  "loanAccountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "grossRequestedAmount": "48000.00",
  "netDeliveredAmount": "48000.00",
  "disbursedAt": "<current time, RFC3339>",
  "jurisdictionExtensions": {
    "disbursedAt": "<the same instant>",
    "loanProductVersionId": "<versionId>",
    "requestId": "<the X-Idempotency value of this call>"
  }
}
```

> [!WARNING]
>
> **With tax regime `none`, `netDeliveredAmount` must equal `grossRequestedAmount`.** Lender accepts a disbursement only when net equals gross minus withholdings minus the retained origination fee. This regime computes no withholdings, and this walkthrough retains no fee.

`loanAccountId` is a UUID **you** supply. Lender does not mint it. It identifies the loan account this contract services under, and it is immutable across later tranches of the same application. `jurisdictionExtensions` carries what the Brazilian pipeline reads: the disbursement instant, the version from step 2, and this call's `X-Idempotency` value as `requestId`. The disbursement fails when one is absent.

Lender also checks that:

* `netDeliveredAmount` does not exceed `grossRequestedAmount`.
* `grossRequestedAmount` equals `approvedAmount`, because this is the application's only disbursement. A release in tranches declares `trancheNumber`, and its running total does not exceed `approvedAmount`.
* `decisionAt` and `disbursedAt` are not before the application's creation, and `disbursedAt` is not before the approval decision.
* The jurisdiction and profile version still match the pair Lender resolved at step 5.

## Confirm the loan exists

***

The disburse response carries the application in `disbursed` with its disbursement event. Then read the loan account:

| Call | What it returns |
| - | - |
| `GET /api/v1/loan-accounts/{loanAccountId}` | The active loan account: status, principal balance, open balance, and disbursement date. |
| `GET /api/v1/loan-accounts/{loanAccountId}/schedule` | The origination schedule, one entry per installment, all unpaid. |

The response also carries `profileVersion`, the jurisdiction profile version, not a product version. It carries no currency. The loan uses the `currency` you set on the loan product version in step 2.

If you configured the Midaz ledger relay, the disbursement posting reaches the ledger when the outbox dispatcher relays the intent. That happens shortly after the call, not inside it. Otherwise the intent remains in the outbox.

## Next steps

***

> **[Service a loan](/en/products/lender/service-a-loan)**
>
> Record repayments, prepay, reschedule, and correct a live loan account.

> **[How accrual works](/en/products/lender/how-accrual-works)**
>
> Interest recognition runs on its own schedule. Start an accrual run, or enable the heartbeat.


# Lender REST API
Source: https://docs.lerian.studio/en/products/lender/lender-rest-api

Orient yourself in the Lender API: the /api/v1 base path, bearer authentication, resource-and-action authorization, decimal-string money, scoped idempotency, pagination, the problem+json error shape, and the operations grouped by job.

Lender serves one HTTP API. Every operation sits under the base path `/api/v1`, and nothing versions in the host. A product list is `GET /api/v1/loan-products`.

This page covers what the operations share, then groups them by the job they do. Each operation has its own page under the **Lender** anchor in the [API Reference](/en/reference/introduction), with full request and response shapes.

> [!NOTE]
>
> The OpenAPI documents in this portal are render sources for the reference pages. They are not client contracts, and they are not a basis for SDK generation.

## Authentication

***

Authentication is deployment-configured. `PLUGIN_AUTH_ENABLED` defaults to `true`. When enabled, protected routes require a JWT bearer token:

```http theme={null}
Authorization: Bearer <token>
```

On Lerian Cloud, Lender resolves the tenant from the `tenantId` claim of the validated identity.

Two reads are public and take no token: [list jurisdictions](/en/reference/products/lender/list-jurisdictions) and [get a jurisdiction](/en/reference/products/lender/get-jurisdiction). The registry is deployment metadata, so a client can read it before it has an identity.

The probes stay outside authentication so an orchestrator reaches them without a token: `/health`, `/readyz`, and `/version`.

### Authorization

***

Lender authorizes each request against the `lender` application, a resource, and an action. The resource follows the surface, and the actions are granular rather than one write:

| Resource | Actions |
| - | - |
| `loan_product` | `read`, `write` |
| `loan_applications` | `read`, `preview:schedule`, `create`, `approve`, `reject`, `withdraw`, `disburse`, `capitalization-consent:ingest`, `preview:tax` |
| `loan_accounts` | `read`, `write`, `audit:read`, `charge:apply`, `repayment:preview`, `repayment:record`, `repayment:reverse`, `returned_payment:collect`, `prepayment:record`, `reschedule`, `cet:read`, `pdd:transition` |
| `accounting` | `read`, `write`, `retry`, `supersede` |
| `streaming_manifest` | `read` |

Grant the officer role only the actions its job needs. Lender defines its roles and permissions in a seed file you load into your identity provider. [Prerequisites](/en/products/lender/lender-prerequisites) shows the minimum set for origination.

### Tenant and officer identity

***

**The tenant is never a header, a query parameter, or a body field.** A self-hosted Lender uses `DEFAULT_TENANT_ID`. On Lerian Cloud, Lender resolves the tenant from the validated identity.

The assigned officer comes from the token subject in the same way. No loan-application body carries an officer field, and no client-supplied value overrides the subject.

## Requests and responses

***

Every operation that carries a body sends and returns `application/json`.

Send money amounts and decimal rates such as `requestedInterestRate` as decimal strings: `"50000.00"`, `"0.01500000"`. Product-version and floating-rate values `fixedAnnualRateBps`, `floatingSpreadBps`, and `annualRateBps` are integer basis points. Timestamps are RFC 3339 in UTC.

## Idempotency

***

Lender holds 29 operations to an at-most-once contract, in two classes. The class decides which header you send and where the guarantee lives.

| Class | Header | Where the guarantee lives | Operations |
| - | - | - | - |
| Enforced at the edge | `X-Idempotency`, required by the schema | A middleware in front of the handler, backed by the idempotency store | 26 writes: the five loan-application writes (create, approve, reject, withdraw, disburse), prepayment and its Brazil alias, the Brazil prepayment quote, the Brazil problem-asset assessment, reschedule, product charges, accrual runs and their retry, the chart-supersession sweep, assignment-set facts, assignment funding payoff, consignado collection settlement, and the nine consignado operator actions |
| Committed with the money | `X-Request-ID`, with `X-Idempotency` as the fallback | A marker written in the same database transaction as the money | 3 writes: record a repayment, reverse a transaction, collect a returned-payment receivable |

Send your own key. On the 26 edge-enforced operations:

* A retry of a **completed** call replays the first response and stamps `X-Idempotency-Replayed: true` on it. Lender records nothing a second time.
* A retry while the first call is still **in flight** answers `409`. Wait and read the resource. Do not send the command again.
* A request carrying **no key** answers `400` with the code `IDEMPOTENCY_KEY_REQUIRED`. The key is a required header on the operation's schema, so the refusal happens before any handler logic runs.
* A key sent under a spelling Lender does not read (`Idempotency-Key` or `X-Idempotency-Key`) answers `400` with the code `IDEMPOTENCY_KEY_HEADER_UNKNOWN`, rather than executing the command unprotected. Sending one of those alongside the contract header is fine. The refusal fires only when `X-Idempotency` is absent.
* Lender scopes the key to your tenant, and the key expires after the window `IDEMPOTENCY_RETRY_WINDOW_SEC` sets, which defaults to 86400 seconds (24 hours).

**The contract is fail-closed, in both directions.** A deployment with no reachable idempotency store does not start. If the store becomes unreachable while it runs, a guarded operation answers `503` with the code `IDEMPOTENCY_UNAVAILABLE` rather than executing unprotected.

Every refusal carries a machine-readable code, and a client branches on it to choose between resending and reconciling. The `IDEMPOTENCY_OUTCOME_UNKNOWN` and `IDEMPOTENCY_OUTCOME_UNKNOWN_UNFENCED` codes say the request reached the handler and the outcome cannot be established. Read the resource before deciding. The refusal codes form a published contract. Renaming a code breaks that contract.

The three transactional operations work differently. All read `X-Request-ID` first and fall back to `X-Idempotency` when it is absent. Send one of the two: a call that carries neither answers `422`.

Lender stores the request id in the database together with the facts of the call. A retry that carries the same id and the same facts replays the first response on the normal response path, with no replay header. The same request id with **different** facts answers `409` rather than replaying, so one id can never record two different amounts. That record does not expire.

The facts Lender compares differ by operation:

| Operation | Facts compared against the stored request id |
| - | - |
| Record a repayment | The loan account, the amount, and the effective date (`transactionDate` when `effectiveDate` is absent). |
| Reverse a transaction | The transaction being reversed, the loan account, the reversal effective date, the reason, the profile version, and the jurisdiction code. The amount comes from the original transaction, so it is not compared. |
| Collect a returned-payment receivable | The receivable and the collection itself. Redelivering the same collection under the same request identity answers `200` with the receivable that already stands; a second, different collection against a collected receivable answers `409`. |

## Pagination

***

Paging is per operation, not global. Read the reference page for the operation you call, and send only the parameters it declares.

| Read | Parameters |
| - | - |
| [List loan products](/en/reference/products/lender/list-loan-products) and [list Brazilian loan products](/en/reference/products/lender/list-loan-products-br) | `limit` (default 25, ceiling 100) and `offset` (default 0, ceiling 10000) |
| [Audit events](/en/reference/products/lender/list-loan-account-audit-events-huma) | `limit` alone (default 50, ceiling 100) |

Lender rejects a value outside the range rather than clamping it. Every other read declares its own parameters, so narrow it with the identifiers and filters on its reference page.

## Errors

***

Huma and global-handler errors answer `application/problem+json` and follow [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457). Authorization and idempotency middleware can use their own response formats.

| Field | What it carries |
| - | - |
| `status` | The HTTP status code. |
| `title` | The status name. |
| `detail` | What went wrong on this occurrence. |
| `errors` | Optional schema-validation details. Each entry carries a `location`, a `message`, and the `value` Lender received. |

Branch on status and content type. For a `422`, use `errors` when present. Handler or domain validation can return only top-level `detail`. A server-side failure answers with a generic detail, so a raw cause never reaches a client.

## The operations by job

***

### Catalogue a product

Eight operations own the catalog. [Create a product](/en/reference/products/lender/create-loan-product) and [append a version](/en/reference/products/lender/create-loan-product-version) build the terms an application binds to. The version is immutable. [Bind an accounting profile](/en/reference/products/lender/create-loan-product-accounting-profile) maps each accounting event onto general-ledger accounts, and activation requires it. [Apply a charge](/en/reference/products/lender/create-loan-product-charges) and [read floating rates](/en/reference/products/lender/list-loan-product-floating-rates) complete the surface, alongside [list](/en/reference/products/lender/list-loan-products), [get](/en/reference/products/lender/get-loan-product), and [activate](/en/reference/products/lender/activate-loan-product). Read [Define a loan product](/en/products/lender/define-a-loan-product).

### Originate

Six operations carry an application from submitted to disbursed: [create](/en/reference/products/lender/create-loan-application), then one of [approve](/en/reference/products/lender/approve-loan-application), [reject](/en/reference/products/lender/reject-loan-application), or [withdraw](/en/reference/products/lender/withdraw-loan-application), then [disburse](/en/reference/products/lender/disburse-loan-application). [Preview a schedule](/en/reference/products/lender/preview-loan-schedule) computes installments for a quote and can record it as an offer.

[List](/en/reference/products/lender/list-loan-applications) and [get](/en/reference/products/lender/get-loan-application) read applications. Read [How origination works](/en/products/lender/how-origination-works) for the state machine and [Quick start](/en/products/lender/lender-quick-start) for the seven calls end to end.

### Service a live loan

Five reads describe the account: [the account](/en/reference/products/lender/get-active-loan-account), [its schedule](/en/reference/products/lender/get-active-loan-schedule), [its transactions](/en/reference/products/lender/list-active-loan-transactions), [its charges](/en/reference/products/lender/list-active-loan-charges), and [its audit history](/en/reference/products/lender/list-loan-account-audit-events-huma).

Five writes move money or the schedule: [preview a repayment](/en/reference/products/lender/preview-repayment) before you [record it](/en/reference/products/lender/record-repayment), [prepay](/en/reference/products/lender/prepay-loan-account), [reschedule](/en/reference/products/lender/reschedule-loan-account), and [reverse a transaction](/en/reference/products/lender/reverse-loan-account-transaction). Nothing rewrites history. A reversal posts a new transaction that compensates the original. Read [Service a loan](/en/products/lender/service-a-loan).

### Account and book

[Start an accrual run](/en/reference/products/lender/create-accrual-run) recognizes interest for a competence period. [List journal references](/en/reference/products/lender/get-journal-reference) by correlation id and [read one](/en/reference/products/lender/get-journal-reference-by-id) to find the accounting record a run wrote. Read [Accounting and accrual runs](/en/products/lender/accounting-and-accrual-runs).

### Discover jurisdictions

The two public reads report which jurisdiction codes this deployment carries and what each profile decides. Read [Jurisdictions](/en/products/lender/jurisdictions).

### Brazil

The Brazil pack adds regulated reads and writes under `/api/v1/br`. They are [CET disclosure](/en/reference/products/lender/get-loan-account-cet-disclosure), [the credit-operation descriptor](/en/reference/products/lender/get-loan-account-credit-operation-descriptor), [PDD stage](/en/reference/products/lender/get-loan-account-pdd-stage) and [its transitions](/en/reference/products/lender/apply-loan-account-pdd-stage-transition), [a prepayment quote](/en/reference/products/lender/create-prepayment-quote) with [its payoff statement](/en/reference/products/lender/get-payoff-statement), [tax preview](/en/reference/products/lender/preview-tax), and [capitalization consent](/en/reference/products/lender/ingest-capitalization-clause-consent). The pack also carries its own product paths, which behave like the generic ones under Brazilian rules. Read [Brazil regulatory pack](/en/products/lender/brazil-regulatory-pack).

The payroll-deducted journey is an event conversation with the payroll rail, not a set of REST calls. Read [Consignado privado](/en/products/lender/consignado-privado).

### More surfaces

Each of these families has its own operations in the reference.

* **Assign receivables to a fund.** `/api/v1/assignment/...` registers funds, assembles and scores sets of receivables against a fund's eligibility rule, and approves or discards them. It also produces the offer file and the endorsement term, and ingests the administrator's return file. It records externally-observed facts, registers a receivable's credit instrument at the registradora, and works the exception queue.
* **Collect a returned payment.** `/api/v1/returned-payment-receivables` lists and reads the separate borrower debts a reversed final payment opens when the contract it closed can no longer take the money back. It also records a collection against one.
* **Promote a product version.** `POST /api/v1/loan-products/{id}/promote` repoints a live product at another of its versions. As a result, new applications originate on it, while contracts already written keep the version they were born on. The operation's Brazil alias is `/api/v1/br/loan-products/{id}/promote`.
* **Read and revise product versions.** `/api/v1/loan-product-versions` lists and reads the version snapshots, and declares a charge model revision on one. Under the Brazil pack, it also declares a version's norm classification.
* **Template the documents.** `/api/v1/loan-products/{productId}/document-templates` and the matching surface under an assignment fund draft, read, and publish the template versions Lender renders a generated document from.
* **Table the floating rates.** `/api/v1/rate-tables` creates a floating-rate table and appends the periods Lender reads a floating product's rate from.
* **Issue a credit instrument.** `/api/v1/loan-applications/{applicationId}/credit-instruments` issues the instrument that evidences an application, lists the instruments issued, and downloads one.
* **Follow an accrual run.** `/api/v1/accrual-runs` lists runs, reads one and its per-item decisions, and re-posts the recognitions the ledger has not acknowledged through `POST /api/v1/accrual-runs/{id}/retry`. The `/api/v1/accounting-profiles` surface lists the configured profiles. The supersession pair supersedes a product's chart of accounts and settles the change onto every live contract's balances.
* **Watch the portfolio.** `/api/v1/dashboard/portfolio` and the two delinquency reads answer from the daily portfolio snapshot. The daily PDD promotion sweep builds that snapshot for its business date before it scans, and it ships enabled, so a default deployment has one. The separate `core-daily-portfolio-snapshot` job drives the same producer on its own schedule for deployments that want it built independently of the sweep.
* **Ladder the provision stages.** `/api/v1/br/pdd-stage-ladders` publishes a PDD stage ladder version and reads the one in force.
* **Work the extraordinary collection.** `/api/v1/br/consignado/collection-instructions` and the settlement pair list the open instructions, and ingest the collection agent's Arquivo de Baixa Extraordinária. They also list the lines it refused. The operator surface under `/api/v1/internal/br/consignado/...` appoints the agent's channel, works quarantined lines and inbox items, and disposes over-deduction refunds owed to workers.
* **Inspect the identity and the stream.** `GET /api/v1/me` reports the session the token resolves to, and `GET /api/v1/internal/streaming/discards` lists the inbound records quarantined by the consumers.

## Next steps

***

> **[Quick start](/en/products/lender/lender-quick-start)**
>
> Seven calls from an empty database to a disbursed loan.

> **[Events](/en/products/lender/lender-events)**
>
> Subscribe to the credit journey instead of polling.

> **[API Reference](/en/reference/introduction)**
>
> Every operation, with full request and response shapes.

> **[Prerequisites](/en/products/lender/lender-prerequisites)**
>
> The services, migrations, and configuration a first call needs.


# Lender SDK and embedding
Source: https://docs.lerian.studio/en/products/lender/lender-sdk-and-embedding

Integrate Lender from your own software: the REST surface that carries every operation, what your client must handle for money, errors, retries and paging, and the pattern for running Lender behind a product your users already use.

**Lender's REST API is the whole client surface.** Products, applications, loan accounts, accrual runs, and the Brazilian regulatory records are all HTTP calls under `/api/v1`. Nothing exists only inside a client library.

Call Lender with the HTTP client your stack already has. There is no Lender client library to install, so the API is the contract you write against. This page covers what your client must handle and what to keep on your own side. It then covers how to place Lender behind a product your users already talk to. Read [Lender REST API](/en/products/lender/lender-rest-api) for the operations themselves.

> [!NOTE]
>
> The OpenAPI documents in this portal are render sources for the reference pages. They are not client contracts, and they are not a basis for client or SDK generation.

## What your client must handle

***

Four rules cover most of the code you write against Lender.

### Money travels as a decimal string

Money amounts are JSON decimal strings, normally with two decimal places. Decimal rates such as `requestedInterestRate` are strings with eight decimal places. The `fixedAnnualRateBps`, `floatingSpreadBps`, and `annualRateBps` fields are integer basis points:

```json theme={null}
{
  "requestedPrincipalAmount": "50000.00",
  "requestedInterestRate": "0.01500000"
}
```

Send the string, and parse the string with your language's decimal type. A binary float loses cents, and a JSON number invites one. Timestamps are RFC 3339 in UTC.

### Errors answer problem+json

Most operation and fallback errors answer `application/problem+json`. Do not assume that for 401 and 403 responses. Branch on `status` and content type. A schema-validation `422` can include an `errors` array with field details, while handler or domain validation can return only top-level `detail`.

Treat `detail` as text for a person, not as a key your code matches on. A server-side failure answers with a generic detail on purpose, so no internal cause reaches a client. Log the status and your own correlation identifier, and let Lender's traces carry the rest.

### Retry your writes with your own key

The money and lifecycle writes take an idempotency key that you generate. They include the five loan-application writes, product charges, prepayment, reschedule, repayment, and reversal. Derive the key from your own request identifier, so a retry replays the first answer instead of writing a second time.

The operations that require `X-Idempotency` replay a completed call with `X-Idempotency-Replayed: true` on the response. They answer `409` while the first call is still in flight. Repayment, reversal, and returned-payment collection key on `X-Request-ID` instead, and fall back to `X-Idempotency` when it is absent. A retry with the same facts replays. The same id with different facts answers `409`. So branch on the response body, never on the presence of the replay header.

The middleware fails **closed** during an idempotency-store outage: it refuses with `503` rather than letting an unprotected write through. Treat that refusal as "not executed, try again", and reconcile before reaching for a new key.

[Lender REST API](/en/products/lender/lender-rest-api#idempotency) lists which header each of those operations takes, and how long a key lives.

### Page with filters, not with deep offsets

Paging is per operation. The product list reads take `limit` and `offset`. The audit history takes `limit` alone. A value outside the declared range answers `422` rather than a quietly reduced page. Read the reference page for the operation you call, and narrow the query instead of walking a long offset.

## Keep the identifiers your writes return

***

The origination operations are commands: create, approve, reject, withdraw, and disburse. Each one answers with the full application body. Its `id` identifies the loan application. After disbursement, `disbursementEvent.loanAccountId` identifies the loan account.

Store both on your side as you go. Your own record then links your borrower to the loan account. Every servicing read starts from an identifier you already hold. The schedule, the transactions, the charges, and the audit history all key on the loan account.

## Embedding Lender behind your own product

***

Lender is a service you deploy, not a library you link. To put it behind an application your customers already use, keep the credentials on your side and call Lender server to server. Four rules keep that boundary clean.

**Never hand a Lender token to a browser or a mobile app**. Your service authenticates your user and decides whether that user may act. It then calls Lender with a token of its own.

**Mint the token for the person who acts**. Lender derives the HTTP actor from the token subject, never from a request field. The assigned officer approves and rejects. Either the borrower or assigned officer may withdraw. The pinned jurisdiction's actor policy governs approval and disbursement, so do not assume one human subject performs every transition.

**Hold one credential per tenant**. A self-hosted Lender uses `DEFAULT_TENANT_ID`. On Lerian Cloud, the tenant comes from the validated identity, never from a header, a query parameter, or a body field, so your service holds one credential for every tenant it serves.

**Learn about state changes from events**. Lender publishes business events through its outbox, and it does not start without the event backbone. Read [Lender events](/en/products/lender/lender-events).

> [!NOTE]
>
> A disbursement records its posting intent in the same database transaction that moves the application to `disbursed`. Lender relays it to Midaz only when the ledger relay is configured. Otherwise, the intent remains in the outbox. Do not treat a `200` on disburse as proof that the ledger already carries the entry. Read [Accounting and accrual runs](/en/products/lender/accounting-and-accrual-runs).

## Next steps

***

> **[Lender REST API](/en/products/lender/lender-rest-api)**
>
> The base path, authentication, idempotency, and the operations by job.

> **[Lender events](/en/products/lender/lender-events)**
>
> The wire contract and the events you can subscribe to.

> **[Quick start](/en/products/lender/lender-quick-start)**
>
> Seven calls from an empty database to a disbursed loan.

> **[Prerequisites](/en/products/lender/lender-prerequisites)**
>
> The services, migrations, and configuration a first call needs.


# Originate a loan
Source: https://docs.lerian.studio/en/products/lender/originate-a-loan

Walk a loan application through its lifecycle (preview the schedule, submit, decide, and disburse) and see the loan account it produces.

Origination is the journey from "a borrower wants credit" to "a loan account exists and the disbursement is recorded". Lender models it as an explicit application lifecycle. The lifecycle keeps a record of every decision, and it makes every disbursement traceable.

## The application lifecycle

***

An application moves through named states. Each transition is a distinct operation, and each keeps a decision or disbursement record:

```
submit ─────► pending_approval ── approve ──► approved ── disburse ──► loan account
                    │       │                     │
                 reject  withdraw               withdraw
```

## Steps

***

**1. Preview the schedule (optional)**

`POST /api/v1/loan-applications/preview-schedule` computes the amortisation schedule for prospective terms **without originating anything**. When it records the quote as an offer, it returns the offer's `scheduleOfferSnapshotId`, which the application can cite. Use it to show installments and disclosures before anyone commits.

**2. Submit the application**

`POST /api/v1/loan-applications` creates the application against the product's current version. It declares the borrower kind, and the requested rate must fall inside the version's rate band.

**3. Decide**

Resolve the application with exactly one of:

* `POST /api/v1/loan-applications/{id}/approve`: accept it, with a decision record.
* `POST /api/v1/loan-applications/{id}/reject`: decline it, with a decision record.
* `POST /api/v1/loan-applications/{id}/withdraw`: retract it while pending approval or, after approval, before disbursement.

**4. Disburse**

`POST /api/v1/loan-applications/{id}/disburse` records the funds delivered. It takes the `X-Idempotency` key every write on this page takes. A retry under the same key therefore replays the first response and records no second disbursement.

One database transaction commits the disbursement event, the origination schedule, and a balanced posting intent. When the call returns, the loan is an active **loan account** you service from here on.

The ledger booking is not in that transaction. With the ledger relay configured, an outbox dispatcher relays the intent to Midaz shortly after the response, through the product's accounting profile. Otherwise, the intent remains in the outbox. See [the posting path](/en/products/lender/lender-in-the-platform).

## Every write takes an idempotency key

***

Creating an application and moving it (approve, reject, withdraw, disburse) all require the `X-Idempotency` header. Lender reads the key from that spelling and no other. It refuses `Idempotency-Key` and `X-Idempotency-Key` by name, so a client is never silently unprotected because it guessed the header. Sending one of those alongside the contract header is fine. The refusal fires only when `X-Idempotency` is absent.

| What you send | What you get |
| - | - |
| No key | `400`, and nothing runs. |
| The same key, the same body | The first response, replayed. Nothing runs a second time. |
| The same key, a different body | `422`. The key is already spent on a different instruction. |

The guard fails **closed**. When the idempotency store cannot answer, Lender refuses the request with `503` instead of waving it through unprotected.

Creation costs a key deliberately: without one, a client that times out on create and calls again books a second application for the same borrower. That is the cheapest duplicate in the service to produce and the most expensive to unpick. It is expensive because both copies look legitimate and only a person can say which one is real.

> [!NOTE]
>
> On the four lifecycle writes, you can reconcile a request that ends unresolved and resubmit it under a **new** key. Read the application by id and ask whether it already holds the state you wanted. Disbursement is the exception, where a new key is not a safe recovery at all. A genuine second release declares its tranche instead.

## The product has to be active

***

Origination reads the loan product's activation status and refuses a product that is not active, with `LENDER-0225` and a `422`. The refusal sits on the three steps that decide new credit: creating the application, approving it, and releasing the money over the API. A product switched off after an application was filed therefore stops that application before the money leaves.

Creating an application must also name the product's **current** version, or Lender refuses it with `LENDER-0226` and a `422`. That check runs at creation and nowhere else, because an application keeps the version it was born on for life. Promoting a new version therefore never kills the applications standing against the old one, and each of them still books on the version it named. See [Define a loan product](/en/products/lender/define-a-loan-product).

Two paths sit outside this gate on purpose:

* The **consignado** rail, which records a contract the client's own systems already registered with the payroll rail. Refusing a fact that already happened would leave the book denying a contract the borrower holds.
* A **substantial renegotiation**, whose replacement contract inherits the product version of the contract it replaces. The replacement contract inherits that version whether or not that product is still active and whether or not that version is still current. Renegotiating services credit already written. Only a new application is new credit.

Lender gates nothing after origination. Reject, withdraw, servicing, and accounting keep working against a product retired years later.

## What you get

***

Disbursement produces a **loan account**, the servicing view of the live contract, carrying its schedule, transactions, charges, and audit history. Continue in [Service a loan](/en/products/lender/service-a-loan).

## What happens downstream

***

The lifecycle emits `loan_application.submitted`, `loan_application.approved`, `loan_application.rejected`, `loan_application.withdrawn`, and `loan_application.disbursed`, each at schema version `2.0.0`. Disbursement records a durable posting intent and relays it to the ledger only when you configure the ledger relay. Read [the posting path](/en/products/lender/lender-in-the-platform).

> [!NOTE]
>
> Brazilian origination adds regulated steps (CET disclosure and capitalization consent) covered in the [Brazil regulatory pack](/en/products/lender/brazil-regulatory-pack). The payroll-deducted **consignado** flow forms its own Brazilian bounded context. See [Consignado privado](/en/products/lender/consignado-privado).

## Next steps

***

> **[Service a loan](/en/products/lender/service-a-loan)**
>
> Record repayments, prepay, reschedule, and correct an active loan account.


# Portfolio and delinquency
Source: https://docs.lerian.studio/en/products/lender/portfolio-and-delinquency

Read the active loan book in aggregate: the portfolio dashboard, the delinquent-loan register, and the nightly snapshot both of them read.

Servicing tracks each loan account individually. The portfolio surface reads the book in aggregate. With it, you can see the shape of the portfolio (A grouping of accounts belonging to the same account holder, business unit, or purpose. It ties together checking, savings, and investment accounts for a unified view.) and which loans fall behind, without querying loan by loan.

Both reads answer from a **snapshot** of one business day, never from a live scan of the book. That makes them cheap enough to put on a dashboard. It is also why they answer for a date rather than for "now".

## Portfolio dashboard

***

`GET /api/v1/dashboard/portfolio` returns the aggregate picture of the active book for a business date. The picture holds outstanding, current and delinquent exposure, the count of active and delinquent loans, and disbursement and repayment volume. It also holds the portfolio-at-risk ratios at 30, 60 and 90 days. Alongside them, it returns the loan count and exposure per delinquency bucket, and a month-by-month trend leading up to the date. It also returns the drill-down rows for the bucket you asked about.

Narrow the read with `productIds` and `productVersionIds`. Omit `asOf` and Lender uses the current business day in Brazil.

## Delinquent loans

***

`GET /api/v1/dashboard/delinquent-loans` returns the register behind the numbers: the loan accounts sitting in one delinquency bucket, page by page, so you can prioritise collections and provisioning. Ask for a bucket with `bucketCode` (`current`, `1_30`, `31_60`, `61_90`, `91_plus`, or the cumulative `par30`, `par60` and `par90`), and narrow to one loan officer's book with `assignedOfficerId`.

Brazil has an alias, `GET /api/v1/br/dashboard/delinquent-loans`, that adds a filter on the regulatory *carteira* C1 to C5 of Res. BCB 352/2023 to every filter above: the business date, the products, the product versions, the bucket, the loan officer and the paging all still apply. Lender derives the carteira from the product, so one that no product declares returns an empty page.

## Where the numbers come from

***

A nightly snapshot job, off by default, measures every live loan account against the business day and writes the snapshot these two reads answer from. The **PDD promotion sweep** described in the [Brazil regulatory pack](/en/products/lender/brazil-regulatory-pack) depends on the same snapshot. It builds the snapshot for its own business day when nothing else did. A deployment that leaves the snapshot job off and keeps the sweep on therefore still has a measured book.

> [!WARNING]
>
> Lender refuses a business date nobody measured with `503`, and never answers it with a page of zeros. An unmeasured book and a book with nothing overdue produce the same numbers. Answering the first as if it were the second would report a healthy portfolio that was never looked at. Treat the refusal as "retry", not as "the book is empty".
>
> The retry only starts answering once a producer has measured that date. The producer is the [nightly PDD promotion sweep](/en/products/lender/brazil-regulatory-pack#the-nightly-promotion-sweep), which ships on, or the dedicated snapshot job, which ships off. With both of them off, no amount of retrying helps.

Each answer carries its own provenance. It names which snapshot it came from, the business date that snapshot measured, and when it was generated. It also says whether the freshness policy considers it stale, and why.

## Audit is per-account

***

Portfolio views are aggregate reads. The authoritative, immutable record of what happened to any single loan is its audit trail (A chronological, immutable record of every action and transaction in the system, essential for regulatory compliance and dispute resolution.) (`GET /api/v1/loan-accounts/{id}/audit-events`), covered in [Service a loan](/en/products/lender/service-a-loan). Every repayment, reversal, and replay lands there.

## Next steps

***

> **[Brazil regulatory pack](/en/products/lender/brazil-regulatory-pack)**
>
> PDD staging, the nightly promotion sweep, and the provisioning the stages drive.


# Service a loan
Source: https://docs.lerian.studio/en/products/lender/service-a-loan

Operate an active loan account: read its schedule and transactions, record and preview repayments, prepay, reschedule, and correct with reversals.

After disbursement, a loan becomes a **loan account**, the servicing view of the live contract. Servicing covers the whole life of the account. Money comes in, the schedule changes, and you correct mistakes without a rewrite of history.

## Read the account

***

| Operation | Purpose |
| - | - |
| `GET /api/v1/loan-accounts/{id}` | Read the active loan account. |
| `GET /api/v1/loan-accounts/{id}/schedule` | Read the current installment schedule. |
| `GET /api/v1/loan-accounts/{id}/transactions` | List transactions posted against the account. |
| `GET /api/v1/loan-accounts/{id}/charges` | List active charges on the account. |
| `GET /api/v1/loan-accounts/{id}/audit-events` | Read the immutable audit trail (A chronological, immutable record of every action and transaction in the system, essential for regulatory compliance and dispute resolution.) of lifecycle events. |

## Record money

***

**1. Preview the allocation**

`POST /api/v1/loan-accounts/{id}/preview-repayment` shows how Lender would allocate a repayment across outstanding installments **without recording it**. Lender pays the oldest due installment first. Inside each installment it pays penalties, then fees, then interest, then principal.

**2. Record the repayment**

`POST /api/v1/loan-accounts/{id}/repayments` records money received and allocates it across the schedule. Send a request id in `X-Request-ID`, or in `X-Idempotency` as the fallback. A call with neither answers `422`. The same id with the same loan account, amount, and effective date returns the repayment already recorded. The same id with different facts answers `409`. See [Idempotency](/en/products/lender/lender-rest-api#idempotency).

**3. Prepay**

`POST /api/v1/loan-accounts/{id}/prepayments` settles the loan ahead of schedule, in whole or in part. A Brazilian loan account needs a [prepayment quote](/en/products/lender/brazil-regulatory-pack) first.

## Change the schedule

***

`POST /api/v1/loan-accounts/{id}/reschedules` rewrites the remaining schedule, for a renegotiation, for example. The change is a new schedule state, not an edit of the old one.

## Correct without destroying

***

Corrections preserve a consistent, auditable timeline. To undo a recorded transaction, reverse it:

`POST /api/v1/loan-accounts/{id}/transactions/{transactionId}/reverse`

A reversal appends a compensating transaction rather than deleting anything, so the account keeps a complete audit trail.

A reversal takes a request id on the same headers as a repayment. The same id replays the reversal already recorded only when every reversal fact matches too. The reversal facts are the transaction you reverse, the loan account, the reversal effective date, the reason, the profile version, and the jurisdiction code. Any difference in those facts answers `409`.

> [!WARNING]
>
> Servicing never edits the past. Repayments, reschedules, and reversals all append new facts. Lender re-derives the current state from that history, so the account stays explainable from its own record.

## A returned final payment becomes a receivable

***

Reversing the payment that settled a **consignado** loan does not always give the debt back to the contract. The exclusion order tells the payer entity to stop deducting from payroll. Once the order has gone to the rail and the rail did not reject it, the payroll mandate is gone. Nothing in Lender registers it again. A contract revived there would be debt with no instrument behind it. It would be chased for arrears, provisioned, and offered back to the official as something whose deduction could be cancelled a second time.

Lender still accepts the reversal, because the bank returned the money and the ledger has to agree with the bank. The destination changes. Lender opens a **returned-payment receivable** against the borrower, outside the credit operation, with no payroll mandate and collected by other means. The reversal answers with which of the two happened, and with the receivable's id when one opened.

The contract keeps its settled state. Nothing reopens. Lender replays no schedule and undoes no allocation.

> [!NOTE]
>
> An exclusion still in flight counts as issued. A reversal cannot wait for the rail to answer. If a revival happens before the rail answers, nothing undoes it when the answer comes back confirmed. Where the rail **rejected** the exclusion, the mandate never died, and the reversal revives the contract exactly as it always did.

### Working the receivable

| Operation | Purpose |
| - | - |
| `GET /api/v1/returned-payment-receivables` | List receivables, narrowed by loan account, borrower, or status. |
| `GET /api/v1/returned-payment-receivables/{id}` | Read one receivable. |
| `POST /api/v1/returned-payment-receivables/{id}/collections` | Record that the borrower paid it. |

A collection settles the whole debt, so it carries no amount: Lender reads the figure from the receivable. It takes a request id on the same headers a repayment takes. Resending the same collection under that same request id answers `200` with the collection already standing. A second, different collection against a debt already collected answers `409` with `LENDER-0325`. Lender refuses a collection with `422` and `LENDER-0326` when its collection instant is not RFC 3339, or when it has no request id. The same refusal covers a collector name longer than the field holds, or a request id already spent collecting a different debt.

The receivable names the contract it came from, so you find a contract's receivables by narrowing the list to that loan account. It is not part of the contract's own servicing view, because it is no longer the contract's debt.

> [!WARNING]
>
> Lender refuses a returned payment that carried cash the institution held unapplied, with `422` and `LENDER-0323`. That refusal is terminal by design. Lender does not record the reversal, and it leaves the contract exactly as it was.

Lender carries the receivable at **face value**. The daily PDD sweep ages it along the ladder of the product it came from, and provisions the expected loss for its age. At the final stage, the sweep writes it off. A product whose chart can divert a returned payment must carry the three rules for that allowance and charge-off. Otherwise, Lender refuses the chart with `422` and `LENDER-0406`.

## What happens downstream

***

Servicing emits `repayment.recorded`, `repayment_reversal.recorded`, `loan_schedule.prepayment_applied`, `loan_schedule.rescheduled`, `returned_payment_receivable.opened`, `returned_payment_receivable.collected`, and `returned_payment_receivable.written_off`. A repayment, a reversal, and a prepayment record durable posting intents. Lender relays them to the ledger only when you configure the ledger relay. Read [the posting path](/en/products/lender/lender-in-the-platform).

## Next steps

***

> **[Accounting and accrual runs](/en/products/lender/accounting-and-accrual-runs)**
>
> Recognize interest over time and read the journal reference each run records.

> **[Brazil regulatory pack](/en/products/lender/brazil-regulatory-pack)**
>
> Read the PDD stage of an overdue loan and apply a stage transition.


# What is Lender?
Source: https://docs.lerian.studio/en/products/lender/what-is-lender

Meet Lender, Lerian's credit journey engine for consumer credit (CDC), from product definition through origination, servicing, and audit.

**Lender** is Lerian's credit journey engine. It gives financial institutions one product to run the full lifecycle of a credit operation. The lifecycle runs from the loan product definition, through origination and disbursement, to servicing, repayment, and audit-ready history. The journey it runs is **consumer credit (CDC)**.

Lerian offers Lender to licensed institutions and maintains its repository internally.

## What a credit journey engine is

***

A credit operation is a journey that spans months or years and touches many teams. A credit journey engine manages that journey end to end:

* **Product definition**: Loan products with versioned terms, charges, and rate configurations. Every contract traces back to the exact product version it used at origination.
* **Origination**: Application intake, approval or rejection decisions, disbursement, schedule preview, and the regulatory disclosures the jurisdiction requires.
* **Servicing**: Active contract schedules, repayment recording, prepayment, rescheduling, and corrections, with reversals and replays that keep history consistent.
* **Accounting**: Posting rules that map financial events onto general-ledger accounts, durable posting intents, and accrual runs that recognize interest month by month.
* **Audit**: An immutable audit trail (A chronological, immutable record of every action and transaction in the system, essential for regulatory compliance and dispute resolution.) of every lifecycle event, preserved for compliance.

Most institutions assemble this from separate systems: a product catalog here, an origination tool there, servicing in the core, spreadsheets in between. Lender's premise is that the journey belongs in one engine, with one consistent history.

## The domains

***

Lender has eight bounded domains. Every credit journey, whatever the product, flows through the first five:

| Domain | What it owns |
| - | - |
| **Products** | Loan products, immutable product versions, activation, charge templates, floating-rate tables, and the accounting profile that says how the product books to the ledger. |
| **Origination** | The loan application lifecycle (submit, approve, reject, withdraw, disburse), plus schedule preview and decision records. |
| **Servicing** | The active loan account: schedules, repayments, prepayments, reschedules, and corrections applied through reversals and replays. |
| **Accounting** | Accounting profiles, posting rules, the posting intents that carry an event to the ledger, accrual runs, and the journal references that identify each run to your own accounting. |
| **Audit** | The immutable audit trail of every lifecycle event on a loan account. |
| **Assignment** | Assigning receivables to a fund: funds, sets, their documents, and the cession facts. |
| **Issuance** | The credit instruments that evidence an application. |
| **Portfolio** | The portfolio dashboard and the delinquency reads. |

Start with [Core concepts](/en/products/lender/core-concepts) for the vocabulary, then follow the guides for each domain.

## Jurisdiction-aware, Brazil first

***

Credit rules differ by jurisdiction, so Lender is jurisdiction-aware from the start. It has a generic base, which books no credit, and a Brazilian profile that books credit. The CDC journey maps onto that model. CDC covers fixed-schedule consumer credit, with the disclosures consumer regulation requires.

The deepest journey is **consignado privado**, payroll-deducted lending in Brazil, with its own collateral model and averbação lifecycle tracking. See [Consignado privado](/en/products/lender/consignado-privado).

For everything the Brazilian profile adds (CET disclosure, IOF preview, capitalization consent, PDD staging, and more), see the [Brazil regulatory pack](/en/products/lender/brazil-regulatory-pack).

## How Lender composes with the platform

***

Lender is a Lerian primitive: it runs on the platform rather than beside it.

* **Ledger**: Money events, such as a disbursement, a repayment, or an interest accrual, record durable posting intents. Those intents follow the accounting profiles and posting rules you configure. Lender relays them to the double-entry (Every financial movement is recorded as at least two operations: a debit from one account and a credit to another, so the system always balances.) ledger (The core financial book that records all transactions, balances, and operations for an organization. It is the single source of truth for a business unit's finances.) only when you configure the ledger relay. The ledger stays the source of truth for balances. Lender stays the source of truth for the credit journey.
* **Multi-tenancy**: Like every Lerian product, Lender is built for full tenant isolation from the ground up.
* **Events**: Lifecycle events publish on the platform's event backbone. Downstream products and your own services can react to the credit journey as it unfolds.
* **Observability**: Structured logs, traces, and metrics on the same observability stack as the rest of the platform.

See [Lender in the platform](/en/products/lender/lender-in-the-platform) for the posting path, the event catalog, and tenant isolation.

## Next steps

***

> **[Core concepts](/en/products/lender/core-concepts)**
>
> Learn the vocabulary: loan products, accounting profiles, applications, loan accounts, accrual runs, and the Brazil terms.

> **[Lender in the platform](/en/products/lender/lender-in-the-platform)**
>
> See how Lender posts to the ledger (The core financial book that records all transactions, balances, and operations for an organization. It is the single source of truth for a business unit's finances.), emits events, and isolates tenants.

> **[Originate a loan](/en/products/lender/originate-a-loan)**
>
> Walk an application from intake through preview, approval, and disbursement.

> **[Consignado privado](/en/products/lender/consignado-privado)**
>
> Explore the Brazilian journey: the vocabulary, the collateral model, and averbação.

If you want to talk about credit journeys on the Lerian platform, [contact us](https://lerian.studio/contact).


# Matcher MCP server
Source: https://docs.lerian.studio/en/products/matcher/mcp/matcher-mcp-overview

Connect AI assistants to Matcher through the Model Context Protocol, a secure, token-relayed tool surface over the reconciliation engine.

The **Matcher MCP server** exposes Matcher's reconciliation surface as [Model Context Protocol](https://modelcontextprotocol.io) tools. An AI assistant, or any MCP client, can then operate Matcher on your behalf. It can inspect contexts, start reconciliation runs, work exceptions, and pull reports. It has the same permissions you already have.

> [!WARNING]
>
> Matcher is only available if you've acquired the Matcher product. To get access, [get in touch with our team](https://lerian.studio/contact).

## How it connects

***

The server speaks **Streamable HTTP** and exposes one MCP endpoint (`POST /mcp`). There is no stdio transport: every client connects to it as a *remote* server over the network.

Point any Streamable-HTTP MCP client at the endpoint URL Lerian provides and send your Matcher bearer token on the connection. For example, with Claude Code:

```bash theme={null}
claude mcp add --transport http matcher https://your-matcher-mcp.example.com/mcp \
  --header "Authorization: Bearer <matcher-jwt>"
```

Any MCP client that supports Streamable HTTP works the same way: give it the URL and the `Authorization: Bearer <matcher-jwt>` header.

## Auth posture

***

For Matcher API calls, the server is a **credential relay** that adds no identity of its own:

* **Bearer token for API calls.** Tools that dispatch Matcher API requests fail closed without a bearer token. They forward the client-supplied credential without logging, storing, or echoing it.
* **Local utilities.** `mcp_ping`, `matcher_list_operations`, and `matcher_describe_operation` run locally and need no token. `mcp_whoami` does not call Matcher. It still needs a bearer credential, because it reports that a credential arrived. Without a credential, it returns a tool error.
* **Tenant follows the token for API calls.** No API-dispatching tool accepts a tenant parameter. Matcher resolves the tenant from the relayed JWT.
* **No session state.** Each request builds a fresh in-memory server.

To check your client configuration, call `mcp_whoami` with a bearer credential after you connect. It reports only that the credential arrived, never its value.

## What you can do with it

***

The server exposes curated tool families for configuration, reconciliation runs, exceptions and disputes, ingestion, and reporting. It also exposes a generic bridge for operations with JSON request bodies. See [Matcher MCP tools](/en/products/matcher/mcp/matcher-mcp-tools) for the catalog.


# Matcher MCP tools
Source: https://docs.lerian.studio/en/products/matcher/mcp/matcher-mcp-tools

The tool families the Matcher MCP server exposes: curated tools by category, plus generic discovery and JSON-relay tools for Matcher operations.

The Matcher MCP server exposes a **curated** tool surface: ergonomic, validated tools for common operations. It also exposes a **generic discovery pair** and a **JSON relay** for indexed operations. Curated tools follow a `family_action` naming convention (for example, `context_list` or `match_run_start`), so related tools share a prefix.

This page lists the families with representative examples. It is not an exhaustive catalog. Connect a client and list the available tools to see the full surface for your version.

## Curated families

***

| Category | Families | What they cover | Representative tools |
| - | - | - | - |
| **Configuration** | `context_*`, `source_*`, `field_map_*` | Reconciliation contexts, their data sources, and the field maps that normalize incoming records. | `context_create`, `context_setup_progress`, `source_list`, `field_map_update` |
| **Matching rules** | `match_rule_*` | The match rules a context applies, including their evaluation order. | `match_rule_create`, `match_rule_reorder` |
| **Fees** | `fee_schedule_*`, `fee_rule_*` | Expected-fee schedules and the rules attached to them, including simulation before rollout. | `fee_schedule_simulate`, `fee_rule_create` |
| **Reconciliation runs** | `match_run_*` | Driving reconciliation: start a run, follow its progress, inspect the resulting match groups. | `match_run_start`, `match_run_groups` |
| **Exceptions** | `exception_*` | Working unmatched transactions: listing, history and comments, per-exception actions, and bulk operations. | `exception_list`, `exception_force_match`, `exception_bulk_resolve` |
| **Disputes** | `dispute_*` | The dispute lifecycle for contested exceptions. | `dispute_submit_evidence`, `dispute_close` |
| **Ingestion** | `ingestion_*` | The import lifecycle: upload data, inspect jobs and per-row errors, search and ignore transactions. | `ingestion_upload`, `ingestion_job_errors_list` |
| **Reporting** | `dashboard_*`, `report_*` | Dashboard aggregates and focused slices, plus report reads, counts, and exports. | `dashboard_match_rate`, `report_summary`, `report_export_unmatched` |

## Generic trio

***

Sometimes a curated tool does not cover the operation you need. Then use the generic tools to inspect the API contract that the server embeds at startup. When the operation accepts a JSON body, or needs no body, you can invoke it:

| Tool | Purpose |
| - | - |
| `matcher_list_operations` | List the operations in the embedded OpenAPI index built when the MCP server starts; optionally filter by tag. It does not call Matcher or require a credential. |
| `matcher_describe_operation` | Describe one indexed operation: its method, templated path, path and query parameters, summary, and, when present, a dereferenced JSON request-body schema. It does not include response schemas. |
| `matcher_invoke` | Assemble, validate, and dispatch an indexed operation with path/query parameters and, where applicable, a JSON request body, using your relayed credentials. |

`matcher_invoke` does not support multipart or raw-binary bodies. Use an applicable curated tool or call the Matcher HTTP API directly for those operations. Curated tools and `matcher_invoke` share the same HTTP-client contract, fail-closed token relay, and [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) error mapping. For Matcher API failures, both return structured tool errors that preserve the problem's status, title, detail, and code.

`exception_dispatch`, `exception_bulk_dispatch`, and `matcher_invoke` accept an optional `idempotencyKey`. If you omit it on a dispatch, the server sends an `X-Idempotency` key that it derives from the request. A retry of the same dispatch carries the same key.

## Utilities

***

| Tool | Purpose |
| - | - |
| `mcp_ping` | Confirm the server is reachable. |
| `mcp_whoami` | Report whether your client's bearer credential arrived (presence only, never the value). It returns a tool error when none is present. |


# Governance
Source: https://docs.lerian.studio/en/products/matcher/reference/matcher-governance

Manage actor PII mappings, list audit-log archives and download archive objects, and re-verify Matcher's audit hash chain.

Matcher's governance surface groups three capabilities under `/v1/governance`:

* **Actor mappings**: link opaque actor IDs to PII, with pseudonymize and delete operations.
* **Archives**: list completed audit-log archives and download archive objects from object storage.
* **Audit logs**: append-only, hash-chained history with a read-only integrity check.

> [!NOTE]
>
> Every governance route stays inside the caller's tenant. Actor-mapping reads have two authorization tiers: the list, which omits `displayName` and `email`, and the single-record de-anonymization read. This separation keeps identity resolution apart from browse access.

## Actor mappings

***

An actor mapping links an opaque `actorId` (for example `user:550e8400-e29b-41d4-a716-446655440000`) to human-readable PII (`displayName`, `email`). Matcher encrypts `displayName` and `email` before it stores them and never stores them in plaintext.

List rows omit the mapping PII fields (`displayName`, `email`) by design, but they do return the `actorId` itself. On upsert, Matcher trims leading and trailing whitespace and rejects empty or whitespace-only IDs and IDs longer than 255 characters. Matcher does not impose an opaque-ID format and does not redact the value. An `actorId` that itself contains PII, such as an email address, appears in list rows as its stored value. Pseudonymization keeps that value. Use opaque identifiers if list access must stay PII-free.

The single-record `GET` returns cleartext identity and requires the `deanonymize` permission. Audit logs can retain the raw `actorId`, which can be an email address.

### List actor mappings

Cursor-paginated rows that omit `displayName` and `email`. Filter by an actor-ID prefix.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/actor-mappings?actorId=user:&limit=25" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "items": [
    {
      "actorId": "user:550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-01-15T10:30:00Z"
    }
  ],
  "limit": 25
}
```

Query parameters: `actorId` (prefix filter), `limit` (default 25, capped at 100), and `cursor`.

### Upsert an actor mapping

Creates or updates the PII for an actor ID. `PUT` is idempotent. The same call creates the record on first use and updates it thereafter. Supply at least one of `displayName` or `email`.

```bash theme={null}
curl -X PUT "https://api.matcher.example.com/v1/governance/actor-mappings/{actorId}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "John Doe",
    "email": "john.doe@example.com"
  }'
```

```json theme={null}
{
  "actorId": "user:550e8400-e29b-41d4-a716-446655440000",
  "displayName": "John Doe",
  "email": "john.doe@example.com",
  "createdAt": "2026-01-15T10:30:00Z",
  "updatedAt": "2026-01-15T10:30:00Z"
}
```

### Get one actor mapping (de-anonymize)

Returns the cleartext PII for a single actor ID. This is the de-anonymization primitive, so the narrower `deanonymize` permission gates it rather than plain read.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/actor-mappings/{actorId}" \
  -H "Authorization: Bearer $TOKEN"
```

### Pseudonymize

Replaces the mapping's `displayName` and `email` with `[REDACTED]` while preserving the record and its `actorId` link. This scrubs PII from the mapping only. Immutable audit records keep the raw `actorId` from the original write, and that value can itself be an email address. Historical audit logs and archived files keep their original values. Responds `204 No Content`.

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/governance/actor-mappings/{actorId}/pseudonymize" \
  -H "Authorization: Bearer $TOKEN"
```

### Delete a mapping

Permanently removes the mapping. Responds `204 No Content`.

```bash theme={null}
curl -X DELETE "https://api.matcher.example.com/v1/governance/actor-mappings/{actorId}" \
  -H "Authorization: Bearer $TOKEN"
```

> [!NOTE]
>
> Pseudonymize keeps the record and scrubs its PII. Delete removes the record entirely. Choose pseudonymize when you must retain the audit linkage, delete when the record itself must not persist.

## Archives

***

When Lerian enables audit archival for your environment, Matcher exports each monthly audit-log partition older than the retention period that Lerian sets to object storage. It verifies the export and then drops the partition from the database.

### List archives

Offset-paginated. Filter by date range.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/archives?from=2024-01-01&to=2024-03-31&limit=20&offset=0" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "partitionName": "audit_logs_2024_01",
      "dateRangeStart": "2024-01-01T00:00:00Z",
      "dateRangeEnd": "2024-02-01T00:00:00Z",
      "rowCount": 150000,
      "compressedSizeBytes": 10485760,
      "storageClass": "GLACIER",
      "checksum": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b",
      "status": "COMPLETE",
      "archivedAt": "2024-04-01T02:30:00Z"
    }
  ],
  "limit": 20,
  "hasMore": true
}
```

Query parameters: `from`, `to` (`YYYY-MM-DD` or RFC 3339), `limit` (1–200, default 20), and `offset`. The endpoint lists only `COMPLETE` archives and never surfaces in-progress or failed archives. `checksum` is the hex-encoded SHA-256 of the decompressed JSONL content, so decompress a downloaded archive before you hash it.

### Download an archive

Returns a presigned URL plus the checksum for integrity verification.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/archives/{id}/download" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "downloadUrl": "https://s3.amazonaws.com/bucket/archive.gz?X-Amz-Signature=...",
  "expiresAt": "2026-02-05T13:00:00Z",
  "checksum": "3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b"
}
```

> [!NOTE]
>
> To download only completed archives, take archive IDs from the list endpoint, which returns `COMPLETE` archives only.

## Audit logs

***

Matcher records configuration changes and exception resolutions as append-only, per-tenant audit records. It links each record into a SHA-256 hash chain (`recordHash` = `SHA-256(prevHash || canonical content)`). Use the verify endpoint below for the integrity verdict.

### List audit logs

Cursor-paginated, with rich filters.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/audit-logs?actor=user@example.com&action=create&entity_type=context&date_from=2025-01-01&date_to=2025-01-31&limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tenantId": "550e8400-e29b-41d4-a716-446655440001",
      "entityType": "context",
      "entityId": "550e8400-e29b-41d4-a716-446655440002",
      "action": "create",
      "actorId": "user@example.com",
      "changes": { },
      "truncated": false,
      "originalSize": 0,
      "createdAt": "2025-01-15T10:30:00Z",
      "tenantSeq": 1,
      "recordHash": "dd3f8a09dda3a8fdcd1e5c54ef76a9168bbabbfd92ad1dd736400d03a3f8a585",
      "prevHash": "0000000000000000000000000000000000000000000000000000000000000000",
      "hashVersion": 1
    }
  ],
  "limit": 20,
  "hasMore": false
}
```

Query parameters: `actor`, `action`, `entity_type`, `date_from`, `date_to` (`YYYY-MM-DD` or RFC 3339), `limit` (1–200, default 20), and `cursor`.

`actor` filters on the record's `actorId` value. That value is the raw actor identifier from the original write, an email address in this example. Audit records store the identifier as-is. It does not have to match an actor-mapping `actorId`.

When a diff is too large to keep in full, `changes` carries a truncation-marker envelope instead of the full diff, and `truncated` becomes `true` with `originalSize` reporting the pre-truncation byte size.

### Verify the audit chain

Re-verifies that every inspected record matches its stored hash. Verification walks a contiguous span with a `maxRecords` bound, so `intact` speaks only for that inspected span. At the HTTP endpoint, a supplied `maxRecords` must be in the 1–10,000 range, and a value outside it returns `422`. When you omit it, Matcher uses the 10,000-record default.

By default, verification starts at the lowest stored sequence. To start at a later record, send the optional `fromSeq`: the first `tenantSeq` to inspect, an integer of 1 or higher. When the first record the check reads is not sequence 1, the check trusts that record's stored link. It does not verify the records before it. The check stays strictly read-only.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/audit-logs/verify?maxRecords=10000" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "intact": true,
  "fromSeq": 1,
  "verifiedCount": 1024,
  "truncated": false
}
```

The `intact` field is `true` when the whole span stays unbroken. When the check finds a break, `firstBrokenSeq` reports the `tenantSeq` of the first failing record, and `verifiedCount` reports how many records held before it. The `truncated` field is `true` when the chain holds more records than the `maxRecords` inspection bound allowed.

The response always carries `fromSeq`.

### Get one audit log

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/governance/audit-logs/{id}" \
  -H "Authorization: Bearer $TOKEN"
```

> [!NOTE]
>
> You can also list an entity's history directly with `GET /v1/governance/entities/{entityType}/{entityId}/audit-logs` (cursor-paginated), which is convenient when you already know the entity to audit.

## Response codes

***

| Status | Meaning |
| - | - |
| `200` | Mapping, archive, or audit data returned |
| `204` | Actor mapping pseudonymized or deleted |
| `400` | Application-level invalid input (missing displayName/email or an invalid date) |
| `403` | Missing the required permission tier (e.g. `deanonymize` for single-record PII) |
| `404` | Actor mapping, archive, or audit log not found |
| `422` | Request/schema validation failed (e.g. invalid email format or a constrained query value) |
| `503` | Archive storage is unavailable |


# Security
Source: https://docs.lerian.studio/en/products/matcher/reference/matcher-security

The security guarantees Matcher gives your data: audit records, encrypted actor-mapping names and emails, and verified integrations.

This page lists the security guarantees Matcher gives your data. It is not a compliance certification.

## Identity and permissions

***

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/contexts" \
  -H "Authorization: Bearer $TOKEN"
```

For the permission that each operation needs, see the [Matcher API reference](/en/reference/products/matcher/matcher-developer-quick-start).

## Tenant isolation

***

With authentication enabled, Matcher reads `tenant_id` or `tenantId` from the token. If tenant claims are optional and absent, it uses the configured default tenant. With `AUTH_ENABLED=false`, it uses that default tenant without reading a token.

## Audit records

***

Matcher records configuration changes and exception resolutions as audit records for your tenant. The records are append-only and linked in a SHA-256 hash chain.

You can re-check the chain. A check inspects up to 10,000 records, by default from the lowest stored sequence, and never changes a record. To start the check at a later sequence, use the `fromSeq` parameter. When the first record the check reads is not sequence 1, the check trusts that record's stored link. It does not verify the records before it. For the audit and archive endpoints, see [Governance](/en/products/matcher/reference/matcher-governance).

## Personal data

***

Matcher encrypts the display name and email of an actor mapping before it stores them. Audit records keep the raw actor identifier from the original request, which can be an email address. For details, see [Actor mappings](/en/products/matcher/reference/matcher-governance#actor-mappings).

## Credentials and inbound calls

***

* Matcher stores only the SHA-256 hash of an exception-callback token or an aggregator webhook token. It shows the raw token once, when it creates it.
* An exception callback must carry a valid callback token for your tenant.
* Matcher accepts an aggregator webhook only on a URL that carries a valid token for your tenant, and only after it verifies the source by HMAC signature or by IP address. A webhook that fails the source check answers `401`.

## Next steps

***

> **[Governance](/en/products/matcher/reference/matcher-governance)**
>
> Manage actor mappings, audit logs, and archives.


# Aggregator connections
Source: https://docs.lerian.studio/en/products/matcher/ui/aggregator-connections

Connect Matcher to the Pluggy or Belvo open finance aggregators, link the account holder's account through the vendor's consent window, and set up the vendor webhook.

The **Aggregators** screen in the Matcher module of Lerian Console manages your open finance aggregator connections. An aggregator connection links Matcher to Pluggy or Belvo, so that Matcher can pull account data. Data starts to arrive after the account holder completes consent in the vendor's own window.

For the API workflow, see [Aggregator connections](/en/products/matcher/integrations/matcher-aggregator-connections).

## Accessing the Aggregators page

***

Navigate to **Settings → Aggregators**.

## Connections table

***

| Column | Description |
| - | - |
| **Vendor** | **Pluggy** or **Belvo** |
| **Name** | The connection name |
| **Base URL** | The API address of the vendor |
| **Account ref** | The vendor reference of the linked account. It is empty until you link an account |
| **Consent** | **Awaiting consent** or **Linked**. This column also shows the result of a connectivity check |
| **Actions** | The menu of actions for the connection |

The table shows 20 connections on each page. Use **Previous** and **Next** to move between pages.

## Creating a connection

***

1. Click **New connection**. The **New aggregator connection** sheet opens.

2. Fill in the fields:

   | Field | Description |
   | - | - |
   | **Vendor** | **Pluggy** or **Belvo** |
   | **Connection name** | A name for the connection. Each connection needs a different name |
   | **Base URL** | The API address of the vendor, for example `https://api.pluggy.ai` |
   | **Account reference** | The vendor reference of the account (optional). Leave it blank to link the account later with **Connect** |
   | **Client ID** | The client ID that the vendor gave you |
   | **Secret** | The secret that the vendor gave you |

3. Click **Create connection**.

After the save, the **Webhook token created** dialog opens. For the next step, see [Setting up the vendor webhook](#setting-up-the-vendor-webhook).

## Linking an account

***

A new connection without an account reference shows **Awaiting consent**. To link the account:

1. Open the **Actions** menu of the row and click **Connect**. The consent window of the vendor opens.
2. The account holder completes consent in the vendor window.
3. Matcher saves the account reference from the vendor. The row then shows **Linked**.

If the account holder closes the window before the end, nothing changes. For a linked connection, the menu shows **Reconnect**. It runs the consent again for the same account.

If Matcher cannot save the account reference, the **Finish linking this account?** dialog opens. Click **Save reference** to try again.

## Setting up the vendor webhook

***

The vendor sends notifications to Matcher through a webhook. Open the **Actions** menu of a row and click **Mint webhook token**. The **Webhook token created** dialog opens.

1. Copy the **Webhook URL** from the dialog.
2. Paste the **Webhook URL** into the dashboard of the vendor.
3. Click **Done**.

## Testing a connection

***

Open the **Actions** menu of a row and click **Test credentials**. Matcher runs a connectivity check, and the **Consent** column shows the result. This action shows only when Matcher can test the connection. It requires a **Pluggy** connection that shows **Linked**.

## Editing a connection

***

Open the **Actions** menu of a row and click **Edit**. The **Edit aggregator connection** sheet opens.

You cannot change the **Vendor**. To use another vendor, delete the connection and create a new one. Leave **Account reference** blank to keep the stored reference. Click **Save changes** to apply the change.

## Deleting a connection

***

Open the **Actions** menu of a row and click **Delete**. In the **Delete connection?** dialog, click **Delete**. Matcher removes the connection, and you can use its name for a new connection. You cannot undo this action.


# Context fee rules
Source: https://docs.lerian.studio/en/products/matcher/ui/context-fee-rules

Bind fee schedules to the transactions of a context with side and field predicates, from the Fee Rules tab in the Matcher module of Lerian Console.

Use the **Fee Rules** tab of a context to decide which fee schedule applies to which transactions. A fee rule binds one fee schedule to the context. Its side and its predicates select the transactions that the schedule applies to. Matcher uses that schedule to compute the expected fee of each selected transaction.

You define the fee schedules themselves in **Settings → Fee Schedules**. See [Managing fee schedules](/en/products/matcher/ui/managing-fee-schedules).

## Accessing the Fee Rules tab

***

**Step 1**

In the Matcher module, select **Configure → Contexts**.

**Step 2**

Click a context to open its detail page.

**Step 3**

Select the **Fee Rules** tab.

The **Create rules** step of the [Context setup wizard](/en/products/matcher/ui/context-setup-wizard) also shows this tab when Matcher asks for a fee rule.

## Fee rule list

***

The table lists the fee rules of the context in priority order:

| Column | Description |
| - | - |
| **Name** | The fee rule name |
| **Side** | **Left side**, **Right side**, or **Either side** |
| **Priority** | The evaluation order. Matcher checks lower numbers first |
| **Fee schedule** | The fee schedule that the rule applies |
| **Predicates** | The number of predicates in the rule |
| **Actions** | Pencil button to edit the rule and trash button to delete it |

## How Matcher picks a fee schedule

***

For each transaction, Matcher checks the fee rules of the transaction's side in priority order. A rule with **Either side** applies to both sides. The first rule whose predicates all match decides the fee schedule. A rule with no predicates matches every transaction on its side.

## Creating a fee rule

***

**Step 1**

Click **New fee rule**. The **New fee rule** side sheet opens.

**Step 2**

Fill in the rule:

| Field | Description |
| - | - |
| **Name** (required) | A name of up to 100 characters. Each fee rule of a context needs a different name |
| **Side** | **Left side**, **Right side**, or **Either side** (default) |
| **Priority** | A number of 0 or more. The form proposes the number after the highest priority in use. Each fee rule of a context needs a different priority |
| **Fee schedule** (required) | The fee schedule to apply. The list shows each schedule with its currency |

**Step 3**

Add the predicates. Click **Add predicate** to add one. Click **Remove predicate** on a predicate to remove it. See [Predicates](#predicates).

**Step 4**

Click **Save**.

## Predicates

***

A predicate tests one metadata field of the transaction. Transaction metadata holds the source columns that the field map does not map. See [Context field maps](/en/products/matcher/ui/context-field-maps).

Each predicate has these fields:

* **Field**: the metadata field to test. Type the column name as it appears in the source data.
* **Operator**: the comparison to make.
* **Value**, **Values**, or **Lower bound** and **Upper bound**: what to compare with. The form shows the fields that the operator needs.

| Operator | Matches when |
| - | - |
| `EQUALS` | The field equals the **Value** |
| `NEQ` | The field does not equal the **Value** |
| `IN` | The field equals one of the **Values**. Click **Add value** to add a value |
| `EXISTS` | The field is present, whatever its value |
| `GT` | The field is greater than the **Value** |
| `GTE` | The field is greater than or equal to the **Value** |
| `LT` | The field is less than the **Value** |
| `LTE` | The field is less than or equal to the **Value** |
| `BETWEEN` | The field is between the **Lower bound** and the **Upper bound**, both included |

`EQUALS` and `IN` compare text without regard to case. `GT`, `GTE`, `LT`, `LTE`, and `BETWEEN` need numbers. A field that is not a number never matches them. A predicate on a field that the transaction does not have never matches.

## Editing a fee rule

***

Click the pencil button on a rule row. The **Edit fee rule** side sheet opens with the current values. Change the fields and click **Save**.

## Deleting a fee rule

***

Click the trash button on a rule row. A **Remove the fee rule** dialog opens with the rule name. Click **Confirm** to delete the rule.


# Context rules
Source: https://docs.lerian.studio/en/products/matcher/ui/context-rules

Create, reorder, and delete the Exact, Tolerance, Date lag, and Fuzzy match rules of a context from its Rules tab in the Matcher module.

Use the **Rules** tab of a context in the Matcher module of Lerian Console to manage its match rules. The rules tell the match engine how to pair transactions across the two sides of the context.

## Accessing the Rules tab

***

**Step 1**

In the Matcher sidebar, go to **Configure → Contexts**.

**Step 2**

Click the name of a context to open its page.

**Step 3**

Select the **Rules** tab.

## Rules list

***

The tab lists the match rules in priority order. Rules evaluate from top to bottom, and the first match wins. Each row shows the position number, the strategy badge, and a short summary of the configuration. A row can also show up and down arrows, an edit button, and a delete button.

The module sets the priority of a new rule for you. The form has no priority field. To change the order, use the up and down arrows.

## Creating a rule

***

**Step 1**

On the **Rules** tab, click **New rule**. The **New rule** sheet opens.

**Step 2**

Select a **Strategy**:

| Strategy | Description |
| - | - |
| **Exact** | Field-for-field equality |
| **Tolerance** | Amount and date within a band |
| **Date lag** | Settlement delay window |
| **Fuzzy** | Approximate reference similarity |

The fields of the strategy appear below it. See [Rule types](#rule-types).

**Step 3**

Optionally, click **Advanced settings** to show more fields.

**Step 4**

Click **Save**.

> [!WARNING]
>
> You cannot change the strategy of a rule after you create it. To change it, delete the rule and create it again.

Matcher never confirms a match from a **Fuzzy** or a **Date lag** rule automatically. These rules propose matches for review.

## Rule types

***

### Exact

Matches transactions when the selected fields are equal.

Top-level switches:

| Field | Description |
| - | - |
| **Match amount** | Compare the amounts |
| **Match currency** | Require the same currency |
| **Match date** | Compare the dates |
| **Match reference** | Compare the references |

**Advanced settings** adds:

| Field | Description |
| - | - |
| **Date precision** | `DAY` or `TIMESTAMP` |
| **Compare references ignoring case** | Ignore letter case when you compare references |
| **Reference must be present** | When **Match reference** is on, refuse a pair if either reference is blank |
| **Sign mode** | `same` matches like signs. `opposite` matches a refund against its charge. `ignore` compares magnitudes only |
| **Match base amount** | Also match on the base amount, which is the amount converted to the base currency |
| **Match base currency** | Also match on the base currency |
| **Allocation (1:N and N:1)** | Partial allocation settings. See [Allocation settings](#allocation-settings) |
| **Composite key fields** | Extra named fields to match on, together with the switches above. Click **Add key field** to add one |

### Tolerance

Matches transactions when the amounts and dates are within a band.

Top-level fields:

| Field | Description |
| - | - |
| **Absolute tolerance** | The largest amount difference that still matches. The amount band uses the larger of this value and the percent tolerance |
| **Percent tolerance** | A fraction: `0.005` is 0.5%. The amount band uses the larger of this value and the absolute tolerance |
| **Date window (days)** | How many days apart the two sides can be dated, from 0 to 3650 |
| **Match currency** | Require the same currency |

> [!NOTE]
>
> Both tolerances start at `0`. A value of `0` is valid.

**Advanced settings** adds:

| Field | Description |
| - | - |
| **Rounding mode** | How amounts round before Matcher compares them: `HALF_UP`, `BANKERS`, `FLOOR`, `CEIL`, or `TRUNCATE` |
| **Rounding scale** | Decimal places for rounding, from 0 to 10 |
| **Percentage base** | The amount that the percent tolerance applies to: `MAX`, `MIN`, `AVERAGE`, `LEFT`, or `RIGHT` |
| **Match reference** | Compare the references |
| **Compare references ignoring case** | Ignore letter case when you compare references |
| **Reference must be present** | When **Match reference** is on, refuse a pair if either reference is blank |
| **Sign mode** | `same`, `opposite`, or `ignore`, as for Exact |
| **Match base amount** | Apply the amount band to the base amounts, which are the amounts converted to the base currency |
| **Match base currency** | Also require the same base currency |
| **FX variance band** | Extra cross-currency tolerance as a fraction: `0.0025` is 25 basis points. A difference inside it still matches and opens an FX rate variance exception |
| **Lockbox deduction band** | How much a payment set can short-pay an invoice set in N:M matching, as a fraction of the invoice face: `0.05` is 5%. The shortfall stays open |
| **Business days and timezone** | The **Holiday calendar** and the **Timezone** for date comparison. The timezone starts at UTC |
| **Allocation (1:N and N:1)** | Partial allocation settings. See [Allocation settings](#allocation-settings) |
| **Composite key fields** | Extra named fields to match on, as for Exact |

### Date lag

Matches transactions that occur within a set number of days of each other.

Top-level fields:

| Field | Description |
| - | - |
| **Min days** | The smallest day lag that matches, from 0 to 3650. It starts at `0` |
| **Max days** | The largest day lag that matches, from 0 to 3650. It starts at `0` |
| **Expected order** | Which side you expect to have the earlier date: `ABS` (either side), `LEFT_BEFORE_RIGHT`, or `RIGHT_BEFORE_LEFT` |
| **Include the min and max days** | Include the boundary days in the lag window |

> [!NOTE]
>
> **Max days** must be equal to or greater than **Min days**. If you turn off **Include the min and max days**, **Min days** must be more than `0`.

**Advanced settings** adds:

| Field | Description |
| - | - |
| **Fee tolerance** | The largest amount difference that still matches. It starts at `0` |
| **Match currency** | Require the same currency |
| **Match reference** | Off by default. Turn it on to require equal references |
| **Compare references ignoring case** | Ignore letter case when you compare references |
| **Reference must be present** | When **Match reference** is on, refuse a pair if either reference is blank |
| **Business days and timezone** | The **Holiday calendar**, the **Timezone**, and **Count business days only**. **Count business days only** measures the lag in business days and needs a calendar |
| **Allocation (1:N and N:1)** | Partial allocation settings. See [Allocation settings](#allocation-settings) |

### Fuzzy

Matches transactions by approximate reference similarity, with optional checks on amount, currency, and date.

Top-level fields:

| Field | Description |
| - | - |
| **Minimum similarity** | A ratio from 0 to 1: `0.80` is 80% similar. References below it never match. At or above it, Matcher grades the pair into a confidence score. See [Confidence scoring](/en/products/matcher/reference/matcher-confidence-scoring). It starts at `0.80` |
| **Match amount** | Compare the amounts |
| **Match currency** | Require the same currency |
| **Match date** | Compare the dates |

**Advanced settings** adds:

| Field | Description |
| - | - |
| **Date precision** | `DAY` or `TIMESTAMP` |
| **Reference must be present** | On by default. Refuse a pair if either reference is blank |
| **Sign mode** | `same`, `opposite`, or `ignore` |
| **Allocation (1:N and N:1)** | Partial allocation settings. See [Allocation settings](#allocation-settings) |

## Allocation settings

***

Each strategy has an **Allocation (1:N and N:1)** block in **Advanced settings**:

| Field | Description |
| - | - |
| **Allow partial allocation** | Split one amount across several counterparts. A remainder stays open as an open item |
| **Fee-aware split** | Allocate the gross share of each leg (net plus fee) instead of its net amount |
| **Allocation direction** | `LEFT_TO_RIGHT` or `RIGHT_TO_LEFT` |
| **Allocation tolerance mode** | `ABS` or `PERCENT` |
| **Allocation tolerance** | The remainder that a split can leave: an amount in `ABS` mode, or a fraction in `PERCENT` mode (`0.01` is 1%) |
| **Allocate on the base amount** | Turn it on to allocate on the base amount, which is the amount converted to the base currency. On Exact and Tolerance rules, Matcher then also matches on the base amount and the base currency |

## Previewing a rule

***

On an **Active** context, the rule sheet also shows a **Preview matches** panel. Use it to test the rule before you save it.

**Step 1**

Fill in the rule fields.

**Step 2**

In **Preview matches**, click **Run preview**.

The panel shows how many pairs **Would match**, the **Unmatched left** and **Unmatched right** counts, and up to 25 would-match pairs. The preview forms 1:1 pairs only. It does not apply fee normalization, FX variance bands, or allocation, so a live run can match more. The preview saves nothing. When you change a field, run the preview again.

## Editing a rule

***

Click the edit button on a rule. The **Edit rule** sheet opens. The **Strategy** field stays locked. Change the other fields and click **Save**.

## Reordering rules

***

Use the up and down arrows on a row to move the rule. Rules evaluate from top to bottom, and the first match wins.

## Deleting a rule

***

Click the delete button on a rule. A dialog names the rule type and its priority and asks you to confirm. Click **Confirm**. The other rules keep their order.


# Context schedules
Source: https://docs.lerian.studio/en/products/matcher/ui/context-schedules

Run matching automatically by adding cron-based matching schedules to a context from its Matching schedules tab in the Matcher module.

Use the **Matching schedules** tab of a context in the Matcher module of Lerian Console to run matching automatically. Each matching schedule sets when Matcher runs matching for the context.

> [!NOTE]
>
> Matching schedules set when automated matching runs. They do not pull data. To schedule when a source pulls data, use the [ingestion schedules](/en/products/matcher/ui/context-sources#managing-ingestion-schedules) of the source.

## Accessing schedules

***

**Step 1**

In the Matcher sidebar, go to **Configure → Contexts**.

**Step 2**

Click the name of a context to open its page.

**Step 3**

Select the **Matching schedules** tab.

> [!NOTE]
>
> Scheduled matching runs only while the context is **Active**.

## Schedule list

***

The tab lists the matching schedules of the context. Each row shows:

* The cron expression
* An **Enabled** or **Disabled** badge
* The **Last run** and **Next run** times in UTC. An empty time shows `—`
* An edit (pencil) button and a delete (trash) button

## Creating a schedule

***

**Step 1**

On the **Matching schedules** tab, click **Add matching schedule**. The **Add matching schedule** sheet opens.

**Step 2**

Type the schedule in **Cron expression (UTC)**, up to 100 characters. The placeholder is `0 2 * * *`.

As you type, a preview appears below the field. A common expression shows a phrase such as "Runs every day at 02:00 (UTC)". An uncommon expression shows a generated phrase or "Custom schedule". An expression with the wrong shape shows "Matching schedules take a 5-field cron expression, such as 0 2 \* \* \*."

The preview does not block **Save**. Matcher checks the expression when you save.

**Step 3**

Leave the **Enabled** switch on to create an active schedule. Turn it off to create a disabled schedule. A disabled schedule has no next run time, so it does not run.

**Step 4**

Click **Save**.

> **How to write a schedule expression**
>
> Matcher reads a **cron expression** in UTC. It has five fields, separated by spaces: `minute hour day-of-month month day-of-week`.
>
> | Field | Range |
> | - | - |
> | Minute | `0–59` |
> | Hour | `0–23` |
> | Day of month | `1–31` |
> | Month | `1–12` |
> | Day of week | `0–7` (0 and 7 are Sunday) |
>
> Special characters:
>
> * `*`: any value
> * `,`: a list of values, such as `1,15,30`
> * `-`: a range, such as `9-17`
> * `/`: a step, such as `*/15` for every 15 units
>
> Examples:
>
> * `0 6 * * *`: every day at 06:00 UTC
> * `*/15 * * * *`: every 15 minutes
> * `0 9 * * 1-5`: at 09:00 UTC on weekdays
>
> Matcher does not accept `@every` or other named macros. When you restrict both day-of-month and day-of-week, a match in either field starts the schedule. Use an interval of five minutes or more. Matcher refuses `* * * * *` and `*/2 * * * *`.

## Editing a schedule

***

Click the pencil button on a schedule row. The **Edit matching schedule** sheet opens with the current **Cron expression (UTC)** and **Enabled** values. Change the fields and click **Save**. For an enabled schedule, Matcher calculates **Next run** again from the current UTC time. When you disable a schedule, it loses its next run time.

## Deleting a schedule

***

Click the trash button on a schedule row. A dialog names the schedule and asks you to confirm. Click **Confirm**.

> [!WARNING]
>
> You cannot undo a delete. The schedule does not run again.


# Discovery connections
Source: https://docs.lerian.studio/en/products/matcher/ui/discovery-connections

Connect Matcher to external databases and acquirer APIs, test each connection, browse the tables it exposes, and extract records into Matcher.

The **Discovery** screen in the Matcher module of Lerian Console manages your discovery connections. A discovery connection links Matcher to an external database or to an acquirer REST API. Matcher reads the tables and columns of the connection. An extraction then pulls records from the tables that you choose, and Matcher ingests them.

For the API workflow, see [Discovery](/en/products/matcher/integrations/matcher-discovery).

## Accessing the Discovery page

***

Navigate to **Settings → Discovery**.

The page header has two buttons:

* **New connection** opens the sheet to create a connection.
* **Refresh discovery** syncs all connections again. A message shows the number of synced connections.

Chips above the table show the number of connections and the health of the extraction engine.

## Connections table

***

| Column | Description |
| - | - |
| **Name** | The connection name |
| **Type** | The connector type, such as `POSTGRESQL` or `STRIPE` |
| **Status** | **Available**, **Unreachable**, or **Unknown**. The result of a test that you run on this page also shows here |
| **Schema** | **Discovered** when Matcher has read the tables of the connection, or **Pending** |
| **Actions** | The menu of actions for the connection |

## Creating a connection

***

1. Click **New connection**. The **New connection** sheet opens.
2. Enter the **Connection name**.
3. Select the **Connector type**. The fields below the select change with the type.
4. Fill in the fields of the type.
5. Click **Save**.

### Database connector types

The database types are **PostgreSQL**, **MySQL**, **Oracle**, **SQL Server**, and **MongoDB**.

| Field | Description |
| - | - |
| **Host** | The host name or address of the database server |
| **Port** | The port of the database server |
| **Database name** | The name of the database |
| **User name** | The database user |
| **Password** | The password of the database user (optional) |
| **Schema** | The schema in the database (optional) |

### REST connector types

Each REST type shows its own fields. All REST types also show an optional **Base URL** field, which sets the API address for this connection.

| Connector type | Fields |
| - | - |
| `PAGBANK` | **Establishment ID** and **EDI token** |
| `STRIPE` | **API key** |
| `PIX_BCB` | **Client ID**, **Client secret**, **Client certificate (PEM)**, and **Client private key (PEM)** |

## Editing a connection

***

Open the **Actions** menu of a row and click **Edit**. The **Edit connection** sheet opens.

* For a database type, you can change the name and the database fields.
* For a REST type, you can change only the **Connection name**. To change other values, delete the connection and create it again.

Click **Save** to apply the change.

## Testing a connection

***

Open the **Actions** menu of a row and click **Test connection**. The **Status** column shows the result:

* **Connection healthy** with the response time in milliseconds.
* **Connection failed**, with the reason when Matcher returns one.

## Viewing the schema

***

Open the **Actions** menu of a row and click **View schema**. The **Connection schema** sheet lists each table of the connection. For each table, it shows the **Column**, **Type**, and **Nullable** values.

If the sheet shows **No schema discovered yet**, click **Refresh discovery** when the connection is reachable.

The sheet can also show these markers:

| Marker | Meaning |
| - | - |
| **Last known map** | The connection is unreachable, or the tables are an archived version. The sheet shows the tables that Matcher read last, with the read date |
| **Not extractable yet** | Matcher has no confirmed columns for the tables. You cannot extract from them yet. The alert describes the possible causes |
| **Columns may be stale** | The columns of the table can be out of date |
| **Fewer columns than last read** | The last read returned fewer columns for the table than the read before it |

The **Earlier versions** section lists the archived versions of the schema. Each version shows the cause, the archive date, and the number of tables. Click a version to see its tables.

## Starting an extraction

***

1. Open the **Actions** menu of a row and click **Start extraction**. The **Start extraction** sheet opens.
2. In **Tables JSON**, enter a JSON object. Each key is a table name, exactly as the schema lists it. Use `{}` as the value to extract all columns. To extract only some columns, use `{"columns": ["id", "amount"]}`.
3. Click **Start extraction**.

The sheet then shows the extraction status, such as **Extracting** or **Complete**. When Matcher sends the records to ingestion, the sheet also shows the **Ingestion job**. If the extraction fails, the sheet shows the error.

Click **Run in background** to close the sheet while the extraction runs.

A source can also pull data on a schedule from a discovery connection. See [Context sources](/en/products/matcher/ui/context-sources).

## Deleting a connection

***

Open the **Actions** menu of a row and click **Delete**. In the **Delete discovery connection?** dialog, click **Delete connection**. Schema reads and extractions that depend on the connection can stop.


# Exception details
Source: https://docs.lerian.studio/en/products/matcher/ui/exception-details

Open one reconciliation exception in the Matcher module of Lerian Console: review its transaction, pair a suggested counterpart, resolve or escalate it, and follow its comments and history.

The **Exception** page in the Matcher module of Lerian Console shows one exception. Use it to review the transaction and pair it with a counterpart. You can also resolve or escalate the exception and follow its history.

## Opening an exception

***

On the [Exceptions](/en/products/matcher/ui/managing-exceptions) queue, click the **Reason** link of an exception row. On a dispute page, the **Exception** link also opens the exception.

## Page layout

***

The page title is **Exception**. A breadcrumb above the title links back to the **Exceptions** queue. Below the title, you see the exception ID, its severity and status badges, and the time of its last update.

The header can show these controls:

* **View audit trail** opens the **Audit trail** panel. It lists the governance audit events of the exception, newest first.
* **Resolve** opens the **Resolve exception** dialog.
* **More actions** opens a menu that can hold **Assign**, **Open dispute**, **Dispatch**, and **Adjust entry**. The **Force match** item comes last, under a separator.

**Assign** is in the menu only while the exception is **Open**. An exception in **Resolved** or **Pending Resolution** status has no **Resolve** button and no **More actions** menu. The **Pending Resolution** status means that a force match or an adjustment is in progress.

The page shows the **Transaction**, **Information**, **Comments**, and **History** panels. Other panels depend on the status of the exception.

## Panels

***

### Transaction

The **Transaction** panel shows the transaction ID, **Amount**, **Transaction date**, and **Source**. If the transaction or its source no longer exists, **Amount**, **Transaction date**, and **Source** show a dash.

For a **Fee Variance** exception, the panel can also show three settlement rows:

| Row | Description |
| - | - |
| **Expected** | The amount that the transaction should credit under the expected fee. |
| **Credited** | The amount that the transaction credited. |
| **Difference** | **Credited** minus **Expected**. A negative value means the credit fell short. |

### Information

| Field | Description |
| - | - |
| **Reason** | Why Matcher raised the exception. |
| **Originating run** | The latest reconciliation run that surfaced the exception, as a link. |
| **Assigned to** | The assignee, when one is set. |
| **Due date** | The resolution deadline, when one is set. An overdue date on an **Open** or **Assigned** exception shows in red. |
| **External system** | The external system that reported on the exception, when one did. |
| **External issue** | The issue ID in that external system. |
| **Created** | When Matcher created the exception. |

### Suggested counterparts

For an **Open** or **Assigned** exception, the **Suggested counterparts** panel can list possible matches from the opposite side. The panel uses the context of the exception, not the **Active context**.

Each candidate shows a score with a **Strong**, **Plausible**, or **Weak** band. It also shows the amount and date differences and why it scored that way. The ranking uses raw amounts. Fee normalization and FX bands do not apply here.

To pair a candidate with the exception transaction:

**1. Pick the candidate**

Click **Match to this** on the candidate. The **Pair these transactions?** dialog opens with the two transactions side by side.

**2. Add a note (optional)**

Type a reason in **Note (optional)**.

**3. Confirm**

Click **Pair selected**. Matcher links the two transactions into a confirmed match group.

> [!NOTE]
>
> Pairing a counterpart does not resolve the exception. Resolve the exception afterwards to close it.

### Resolution

A **Resolved** or **Pending Resolution** exception shows the **Resolution** panel instead of **Suggested counterparts**. It shows **Resolution type**, **Reason**, **Resolution notes**, **Resolved by**, and **Resolved at**.

### Comments

The **Comments** panel lists comments oldest first, with the author and a relative time. To add a comment, type it and click **Send**, or press Ctrl+Enter or Cmd+Enter. A comment can have up to 5,000 characters.

A comment can show a delete icon. Click it and confirm in **Delete this comment?** to remove the comment permanently. A **Resolved** or **Pending Resolution** exception takes no new comments.

### History

The **History** panel lists what happened to the exception, newest first. Each entry shows the action, the actor or `system`, and a relative time. A new entry can take a few seconds to appear.

## Actions

***

### Resolve

**Resolve** opens the **Resolve exception** dialog. It closes the exception with a resolution text. Matcher marks the exception **Resolved** and does not change the transaction.

| Field | Description |
| - | - |
| **Resolution** | Required. How you resolved the exception, up to 255 characters. |
| **Reason** | Optional. More context for the audit trail, up to 1,000 characters. |

Click **Resolve** to submit.

### Assign

The **Assign exception** dialog has one field, **Assignee**. Type who works the exception, up to 255 characters, and click **Assign**. The status changes to **Assigned**.

### Open dispute

The **Open dispute** dialog starts a formal dispute about the exception.

| Field | Description |
| - | - |
| **Category** | Required. Bank fee error, Unrecognized charge, Duplicate transaction, Amount mismatch, or Other. |
| **Description** | Required. The basis for the dispute, up to 5,000 characters. |

Click **Open dispute**. The new dispute starts in the **Open** state. You add evidence and record the outcome on the dispute page. See [Managing disputes](/en/products/matcher/ui/managing-disputes).

### Dispatch

The **Dispatch to an external system** dialog records a hand-off of the exception.

| Field | Description |
| - | - |
| **Target system** | Required. Select **Manual**. |
| **Queue or project** | Optional. A label for the team that takes the exception, up to 255 characters. |

Click **Dispatch**. Matcher adds the hand-off to the exception history. The exception status does not change.

### Adjust entry

**Adjust entry** records a correction for the exception transaction and resolves the exception.

| Field | Description |
| - | - |
| **Reason code** | Required. Amount correction, Currency correction, Date correction, or Other. |
| **Amount** | Required. A positive decimal amount, for example `150.50`. |
| **Currency** | Required. A three-letter currency code, for example `BRL`. |
| **Effective date** | Required. The dialog fills in today's date from your computer's calendar. |
| **Notes** | Required. An explanation of the correction, up to 1,000 characters. |

Click **Adjust entry**. Matcher records the adjustment for the transaction and marks the exception **Resolved**.

### Force match

**Force match** overrides the matching engine. Matcher marks the exception transaction as matched and resolves the exception. The transaction does not join a match group.

| Field | Description |
| - | - |
| **Override reason** | Required. Policy exception, Operations approval, Customer dispute, or Data correction. |
| **Justification** | Required. Why you force the match, up to 1,000 characters. |

Click **Force match** to submit.


# Running reconciliations
Source: https://docs.lerian.studio/en/products/matcher/ui/executing-reconciliation

Start match runs for the active Matcher context from the Reconciliations screen: preview with a dry run or persist with a commit run, then read the results and the run history.

The **Reconciliations** screen of the Matcher module in Lerian Console starts match runs for the active context. It also lists the runs of that context. Use a dry run to test your rules and read the statistics without writing results. Use a commit run to persist matches and exceptions.

## Accessing the Reconciliations screen

***

Click **Operate → Reconciliations** in the Matcher sidebar. The screen works on the **Active context** that you select in the Matcher sidebar. Badges under the header identify the context.

The screen has two parts: the **Run match** panel and the **Run history** table.

If no context exists, the screen asks you to create one and shows a **Browse contexts** button.

## Importing data first

***

A run matches only the transactions that you imported into the context. To upload a file, use **Operate → New Reconciliation**. See [Uploading reconciliation data](/en/products/matcher/ui/uploading-reconciliation-data).

> [!NOTE]
>
> When the panel finds no imported transactions in the context, it shows the warning **This context has no transactions to match**. The warning has an **Import data** button, and you cannot click **Run match**.

## Run modes

***

Choose a mode in the **Mode** list before you start:

| Mode | Description |
| - | - |
| **Commit: persist matches and exceptions** | Writes match groups and exceptions to the context. This is the default mode. |
| **Dry run: preview, write nothing** | Evaluates your rules and shows the statistics. It writes no match groups and no exceptions. Use it to test rules before a commit run. |

## Starting a run

***

Click **Run match**. The engine runs the match while the request is open, so the button shows **Starting…** until the run ends. You cannot change the mode during a run.

Below the controls, a progress block shows the run ID, its status, its mode, and the **Started** and **Finished** times.

If Matcher refuses to start the run, the message **The run could not start** shows the reason from Matcher. A run that fails shows its failure reason below the status.

### Following a run in progress

While a run is in progress, the panel refreshes every two seconds. It shows a **Stop watching** button. The button stops the refresh in your browser. The run continues in Matcher.

After three minutes, the panel stops the refresh and says that the run takes longer than expected. Click **Recheck status** to refresh again. The run detail page refreshes in the same way.

## Reviewing results

***

When a run completes with transactions to evaluate, a bar shows the matched share of the run as a percentage. Below the bar, the **Matches** figure gives the number of match groups. A list of statistics per side follows:

| Statistic | Description |
| - | - |
| **Candidates (left)** / **Candidates (right)** | Transactions the run evaluated on each side. |
| **Auto-matched (left)** / **Auto-matched (right)** | Transactions that the run matched automatically. |
| **Pending review (left)** / **Pending review (right)** | Transactions in matches that wait for manual review. |
| **Proposed (left)** / **Proposed (right)** | Transactions in proposed matches that nobody confirmed yet. |
| **Unmatched (left)** / **Unmatched (right)** / **Unmatched (external)** | Transactions that the run could not match. |
| **Exceptions raised** / **Exceptions updated** | New exceptions from the run, and existing exceptions that the run changed. Both are zero for a dry run. |

Below the statistics, a line confirms the mode. For a commit run, it says that Matcher persisted the matches and exceptions to the context.

If the run completes with no transactions on either side, the panel shows no statistics. It shows a warning that no transactions matched, with an **Import data** button.

## Viewing match groups

***

After a run completes, click **View match groups** to open the run detail page. The page shows the run summary and the match groups of the run. A dry run writes no match groups, so its detail page lists no groups. See [Managing matches](/en/products/matcher/ui/managing-matches).

## Run history

***

Below the panel, the **Run history** table lists the runs of the context, newest first. Click a run ID to open its detail page. Click **View exceptions** on a row to open the exceptions queue for that run. See [Managing exceptions](/en/products/matcher/ui/managing-exceptions).

While a run on the page is in progress, the table refreshes and shows a **Live** badge. For the columns and the run statuses, see [Operational history](/en/products/matcher/ui/operational-history).

If the context has no runs, the table shows a **Run reconciliation** button. The button takes you to the **Run match** panel.


# Extraction review
Source: https://docs.lerian.studio/en/products/matcher/ui/extraction-review

Approve or reject the transactions that Matcher extracts from a PDF document before they enter a source, in the Extraction Review queue of the Matcher module.

Matcher can read a PDF document, such as a bank statement, and propose the transactions it finds. These proposals are candidates. A candidate does not enter reconciliation until a person approves it. The **Extraction Review** screen of the Matcher module in Lerian Console is the queue where you approve or reject them.

> [!NOTE]
>
> Document extraction is not available in every environment. When it is off, the screen shows a message instead of the queue.

## How a review starts

***

**1. Extract from a document**

In the **Sources** tab of a context, use the **Extract from a document** action of a source. Upload one PDF document. See [Context sources](/en/products/matcher/ui/context-sources).

**2. Matcher reads the document**

Matcher uses AI to read the document and propose candidate transactions. Matcher sends a capped slice of the document's text layer to the language-model provider Lerian configures for your environment. When the PDF has no text layer, Matcher sends the PDF itself. Matcher queues the candidates as one review with the **Pending review** status.

**3. Open the review**

The dialog shows the number of candidates and an **Open review** link. You can also open the review later from the queue.

## Accessing the Extraction Review screen

***

Click **Resolve → Extraction Review** in the Matcher sidebar. The screen shows the **Active context** that you select in the Matcher sidebar. To see another context, change the **Active context**.

## The review queue

***

The queue shows the reviews of the context, 25 per page. Use **Previous** and **Next** to move between pages. The **Status** filter shows **Pending review** reviews by default. You can also show **Approved** or **Rejected** reviews.

| Column | Description |
| - | - |
| **Document / source** | The short ID of the source that the document belongs to. Click it to open the review. |
| **Status** | The review status. |
| **Candidates** | The number of candidate transactions in the review. |
| **Created At** | When Matcher created the review. |

## Reading a review

***

The review page shows each candidate as a card, **Candidate 1**, **Candidate 2**, and so on. A badge on the card shows how Matcher read it:

* **Text layer**: the candidates come from the text layer of the PDF.
* **Vision · lower trust**: an AI model produced the values from the document itself. Check these candidates with more care.

Each field of a candidate shows the value that Matcher read and an **Extraction confidence** meter. When known, it also shows the page and region of the value.

You cannot edit a candidate. You approve or reject the review as a whole. To go back to the queue, click **Queue**.

## Approving a review

***

1. On a **Pending review** review, click **Approve extraction**.
2. In the **Approve extracted transactions?** dialog, click **Approve and commit**.

Matcher sends all the candidates of the review to its source as one import, the same way it imports a file. After a successful approval, the review status is **Approved** and the review shows the ID of the import job. The import job also shows in the **Import jobs** table of **Operate → Operational History**. See [Operational history](/en/products/matcher/ui/operational-history).

If the context has **Auto-match on upload** turned on, the import starts a match run. You cannot undo an approval.

## Rejecting a review

***

1. On a **Pending review** review, click **Reject extraction**.
2. You can enter a **Rejection reason (optional)**, up to 1,000 characters.
3. Click **Reject extraction**.

Matcher discards the candidates. Nothing enters the source. The review status changes to **Rejected**. If you entered a reason, the review page shows it.

> [!TIP]
>
> If another person decides on the review first, the screen reloads the review and shows its new status.

For the API of this workflow, see [Extraction reviews](/en/products/matcher/imports/matcher-extraction-reviews).


# Layout templates
Source: https://docs.lerian.studio/en/products/matcher/ui/layout-templates

Define fixed-width file layouts, such as CNAB layouts, as record types and byte ranges, then select them as the file format when you upload data.

The **Layout Templates** screen in the Matcher module of Lerian Console holds your fixed-width file layouts. In a fixed-width file, such as a CNAB file, each line is a record with a fixed length. Each field is a byte range in the record. A layout template tells Matcher where each field starts and how long it is.

## Accessing the Layout Templates page

***

Navigate to **Settings → Layout Templates**.

## Templates table

***

| Column | Description |
| - | - |
| **Format key** | The key of the template. It combines the region, the family, and the variant. Click it to open the template |
| **Variant key** | The variant of the template |
| **Record types** | The number of record types in the layout |
| **Created At** | The date and time of the template creation |

## Creating a template

***

Click **New template**. The **New layout template** page opens.

### Template fields

| Field | Description |
| - | - |
| **Region** | A two-letter region code, such as `BR`, or `XX` for no region |
| **Family** | The format family, such as `cnab240` or `cnab400` |
| **Variant** | A lowercase name for the bank or brand layout. Use letters, digits, `-`, and `_` |
| **Discriminator start byte** | The zero-based position of the bytes that identify the record type |
| **Discriminator length** | The number of bytes that identify the record type |
| **Required field names (optional)** | Field names that the layout must declare. Separate the names with commas |

### Record types

Each record type is a card. Click **Add record type** to add a card. Click **Remove** to delete a card.

| Field | Description |
| - | - |
| **Record-type value** | The value in the discriminator bytes that identifies this record type |
| **Record width (bytes)** | The fixed length of a record of this type |

Each record type has one or more fields. Click **Add a field** to add a field row:

| Field | Description |
| - | - |
| **Name** | The field name |
| **Start byte** | The zero-based position where the field starts |
| **Length** | The number of bytes in the field |
| **Kind** | `string`, `decimal (money)`, or `date`. A field named `amount` must use `decimal (money)` |

Matcher maps fields named `external_id`, `amount`, `currency`, `date`, and `description` to the transaction fields with the same names. It keeps all other fields as transaction metadata. If a layout has no `currency` field, Matcher uses `BRL`.

The form shows **Byte-layout problems** when two fields in a record type overlap. It also shows them when a field ends after the record width. Matcher does not save a layout with these problems.

Click **Submit template** to save. The template page opens.

## Using a template

***

To use a template, upload a file on **Operate → New Reconciliation**. In the **Format** select, choose the format key of the template. The select lists your templates in the **Layout Templates** group. For the upload steps, see [Uploading reconciliation data](/en/products/matcher/ui/uploading-reconciliation-data).

## Template details

***

Click a format key in the table to open the template. The page shows two cards:

* **Template identity**: the **Format key**, **Region**, **Family**, and **Variant**.
* **Registration**: the **Variant key**, the number of **Record types**, the **Discriminator** byte range, and the creation date.

The **Byte layout** section has one card for each record type. Each card shows the record width and a table of fields with **Name**, **Byte range**, **Length**, and **Kind**.

## Editing a template

***

Click **Edit** on the template page. The **Edit layout template** page opens with the current values. Click **Save changes** to replace the stored layout. This change does not create a copy. Matcher validates the full layout again before it saves the change.

## Duplicating a template

***

Click **Duplicate as new** on the template page. The **New layout template** page opens with the values of the template. Change the values, then click **Submit template** to save a separate template.

## Deleting a template

***

Click **Delete** on the template page. In the **Delete layout template?** dialog, click **Delete**. Matcher removes the template and frees its format key for a new template. You cannot undo this action.


# Managing actor mappings
Source: https://docs.lerian.studio/en/products/matcher/ui/managing-actor-mappings

Link opaque actor IDs to a display name and an email in the Matcher module, then pseudonymize or delete the mappings.

The **Actor Mappings** page of the Matcher module in Lerian Console links an opaque actor ID to a display name, an email, or both. The [audit logs](/en/products/matcher/ui/managing-audit-logs) show actor IDs, not names. You can also pseudonymize or delete a mapping on this page.

## Opening the Actor Mappings page

***

In the Matcher module, go to **Settings → Actor Mappings**.

## Browsing actor mappings

***

The table shows up to 20 mappings per page. It has these columns:

| Column | Description |
| - | - |
| **Actor ID** | The opaque identifier that Matcher records |
| **Created At** | The date and time when the mapping was created |
| **Updated At** | The date and time of the last change |
| **Actions** | The row actions menu |

The table does not show display names or emails.

Type in the **Actor ID prefix** field to filter the table. The table updates as you type. It shows the mappings whose actor ID starts with your text. Use **Previous** and **Next** below the table to move between pages.

## Creating an actor mapping

***

1. Click **New mapping**. The **New actor mapping** sheet opens.
2. Fill in the fields.
3. Click **Save**.

| Field | Description |
| - | - |
| **Actor ID** | The opaque identifier. You cannot change it after you save the mapping |
| **Display name** | The name to show for this actor (for example, "John Doe") |
| **E-mail** | The email address of this actor. It must be a valid email address |

You must fill in **Display name**, **E-mail**, or both.

## Editing an actor mapping

***

1. Open the row actions menu and click **Edit**. The **Edit actor mapping** sheet opens with the current values.
2. Change **Display name**, **E-mail**, or both. The **Actor ID** field is locked.
3. Click **Save**.

If you clear a field, Matcher keeps its stored value. To erase the display name and email, pseudonymize the mapping.

## Pseudonymizing an actor mapping

***

1. Open the row actions menu and click **Pseudonymize**. The **Pseudonymize actor mapping?** dialog opens.
2. Click **Pseudonymize**.

Matcher replaces the display name and the email with `[REDACTED]`. The mapping and its actor ID stay. You cannot restore the original values.

## Deleting an actor mapping

***

1. Open the row actions menu and click **Delete**. The **Delete actor mapping?** dialog opens.
2. Click **Delete**.

> [!NOTE]
>
> Deletion permanently removes the mapping between the actor ID and its display name and email.


# Archives
Source: https://docs.lerian.studio/en/products/matcher/ui/managing-archives

Browse the completed audit-log archives in the Matcher module, filter them by the dates they cover, and download them.

The **Archives** page of the Matcher module in Lerian Console lists the completed audit-log archives. Matcher writes an archive when it moves old audit-log records out of the live database. Use this page to find and download those archives.

## Opening the Archives page

***

In the Matcher module, go to **Reporting → Archives**.

## Filters

***

Open the filter panel from the toolbar above the table. Use the two dates to find the archives whose entire covered period is inside a window. An archive whose covered period is partly outside the window does not appear in the list.

| Filter | Description |
| - | - |
| **Covered from** | The covered period of the archive starts on or after this date |
| **Covered to** | The covered period of the archive ends on or before this date. The window includes this whole day |

The list updates when you change a date. You do not need to click a button to apply the filter.

* If you leave a date empty, that side of the window has no limit.
* If **Covered from** is after **Covered to**, the Console swaps the two dates.
* A new window returns the list to the first page.
* Click **Clear filters** in the toolbar to go back to the default window.

> [!NOTE]
>
> When the page opens, the window ends on the current UTC date and starts 90 days earlier.

## Archive table

***

The table lists only **Complete** archives. It has these columns:

| Column | Description |
| - | - |
| **Partition** | The name of the archived database partition |
| **Date range** | The start and end dates of the covered period |
| **Rows** | The number of audit-log rows in the archive |
| **Size** | The compressed size of the archive |
| **Storage** | The object-storage class of the archive |
| **Status** | **Complete** for every archive in the list |
| **Archived** | When the archival finished |
| **Actions** | The **Download** button |

The page shows 10 archives at a time by default. Use the **Items per page** selector in the toolbar to change this number. Use **Previous** and **Next** below the table to move between pages.

## Downloading an archive

***

Click **Download** on the row of the archive. The Console prepares the file and starts the download. Then the checksum appears under the button, as **Checksum:** followed by the value.

The checksum is the hex-encoded SHA-256 hash of the decompressed content. Decompress the downloaded archive before you calculate its hash.

If the Console cannot prepare the file, the row shows **Could not prepare archive download**.


# Audit logs
Source: https://docs.lerian.studio/en/products/matcher/ui/managing-audit-logs

Search the recorded configuration and operational changes in the Matcher module, open one entry, and check the audit hash chain.

The **Audit Logs** page of the Matcher module in Lerian Console lists the recorded changes to reconciliation configuration and operations. Use it to find the actor, the action, and the time of each change.

The page is not limited to one context. It does not use the **Active context** selector.

## Opening the Audit Logs page

***

In the Matcher module, go to **Reporting → Audit Logs**.

## Verifying chain integrity

***

The **Tamper-evidence** panel is above the filters. Click **Verify integrity** to check the audit hash chain. The check reads the records and does not change them.

The panel then shows one of these verdicts:

| Verdict | What the panel shows |
| - | - |
| **Chain intact** | The number of records that the check verified |
| **Chain TAMPERED: integrity broken** | The chain position of the break, and the number of records verified before it |

One run inspects a limited number of records. If the chain is longer, the verdict tells you that the check skipped the most recent entries. Click **Continue from #N** to check the next records. **N** is the next chain position.

If the request fails, the panel shows an error and a **Retry** button. A failed request is not a verdict.

## Filters

***

Open the filter panel from the toolbar above the table. The list updates as you type. You do not need to click a button to apply a filter. Each change returns the list to the first page.

| Filter | Description |
| - | - |
| **Actor** | The actor ID recorded with the change (for example, `user-123`) |
| **Action** | The operation recorded with the change |
| **Entity type** | The type of resource that changed (for example, `context`) |
| **Date from** | The first day of the time range |
| **Date to** | The last day of the time range. The range includes this whole day |

The **Actor** and **Entity type** filters match the full value only. The toolbar also has an **Items per page** selector. Click **Clear filters** in the toolbar to remove all filters.

## Audit log table

***

The table shows the newest events first. Each row has these columns:

| Column | Description |
| - | - |
| **Entry** | The audit record ID. It links to the detail page of that entry |
| **Recorded** | When Matcher recorded the change |
| **Action** | The operation performed |
| **Entity type** | The type of resource that changed |
| **Entity ID** | The identifier of the changed resource |
| **Actor** | The actor ID recorded with the change (for example, `user-123`). It is not a person's name |
| **Chain** | The chain position (`#<sequence>`) and the record hash. A record without a hash shows **No chain proof** |
| **Changes** | A **View** button that opens the recorded change set. A row without recorded changes shows `-` |

Use **Previous** and **Next** below the table to move between pages. The table footer shows the number of events on the current page.

## Viewing change details

***

Click **View** in the **Changes** column. The **Audit log changes** panel opens. It names the action, the entity type, and the entity ID. Then it shows the recorded change set as JSON. The fields of the change set depend on the operation.

> [!NOTE]
>
> If a change set was larger than the audit payload limit, the row shows **Diff truncated**. Matcher stored a marker instead of the full change set. You cannot get the full change set back from that record.

## Viewing an entry

***

Click the ID in the **Entry** column. The **Audit entry** page opens with two panels:

| Panel | Fields |
| - | - |
| **Details** | **ID**, **Action**, **Entity type**, **Entity ID**, **Actor**, and **Recorded** |
| **Tamper-evidence** | **Chain position**, **Record hash**, **Previous hash**, and **Hash version** |

For a record without a hash, the **Tamper-evidence** panel shows a **Chain** note instead of these fields. Click **View** next to **Changes** to open the recorded change set.

## Audit trail of one entity

***

The **General Information** tab of a context and the detail page of an exception have a **View audit trail** button. Click it to open the **Audit trail** panel. The panel lists the events of that one entity, newest first. For more information, see [Managing contexts](/en/products/matcher/ui/managing-contexts) and [Exception details](/en/products/matcher/ui/exception-details).


# Managing disputes
Source: https://docs.lerian.studio/en/products/matcher/ui/managing-disputes

Track disputes raised against reconciliation exceptions in the Matcher module of Lerian Console: filter the list, submit evidence, and record the outcome.

Use the **Disputes** page in the Matcher module of Lerian Console to track disputes. A dispute is a formal challenge against an exception. You open a dispute from the exception page. Then you submit evidence and record whether the dispute was won or lost.

## Accessing the Disputes page

***

Click **Exception Handling → Disputes** in the Matcher sidebar. The list shows disputes from all contexts, not only the **Active context**.

Above the filters, badges count the disputes on the current page: **On page**, **Open**, **Pending evidence**, **Won**, and **Lost**.

## Filters

***

The list updates when you change a filter.

| Filter | Options |
| - | - |
| **State** | Draft, Open, Pending evidence, Won, or Lost. |
| **Category** | Bank fee error, Unrecognized charge, Duplicate transaction, or Other. |
| **Date from** / **Date to** | The range of creation dates. |
| **Sort by** / **Order** | Created, Updated, State, or Category, in Descending or Ascending order. **Order** appears after you select a field. |
| **Items per page** | The number of rows on each page. |

If no dispute matches the filters, the empty list shows a **Clear filters** button.

## Disputes table

***

| Column | Description |
| - | - |
| **Dispute** | The first eight characters of the dispute ID, as a link to the dispute page. |
| **Exception** | The ID of the related exception, with a copy control. |
| **Category** | The dispute category. |
| **State** | The current state. |
| **Opened by** | Who opened the dispute. |
| **Created** | When someone opened the dispute, as a relative time. |

## Dispute lifecycle

***

A dispute that you open from an exception starts in the **Open** state. When you close it, you record the outcome: **Won** or **Lost**. A **Won** or **Lost** dispute takes no more evidence, and you cannot close it again.

Closing a dispute does not change the exception or its transaction. To close the exception, resolve it on the exception page. See [Exception details](/en/products/matcher/ui/exception-details).

## Dispute categories

***

| Category | Description |
| - | - |
| **Bank fee error** | A discrepancy that an incorrect bank fee causes. |
| **Unrecognized charge** | A charge that you cannot identify. |
| **Duplicate transaction** | A transaction that appears more than once. |
| **Amount mismatch** | The amounts on the two sides do not agree. |
| **Other** | Any other reason. |

## Dispute page

***

Click a dispute ID in the list to open the **Dispute** page. A breadcrumb above the title links back to **Disputes**. Below the title, you see the dispute ID and its state.

While the dispute is **Open**, the header can show **Submit evidence** and **Close dispute**.

The page has two panels: **Information** and **Evidence**.

### Information

| Field | Description |
| - | - |
| **Exception** | The ID of the related exception, as a link to the exception page. |
| **Category** | The dispute category. |
| **Opened by** | Who opened the dispute. |
| **Description** | The full description of the dispute. |
| **Created** | When someone opened the dispute. |
| **Updated** | When the dispute last changed. |
| **Resolution** | The explanation of the outcome. It appears after you close the dispute. |

### Evidence

The **Evidence** panel lists the evidence items. Each item shows its comment, who submitted it, and when. An item with a link shows **Open attachment**. If the dispute has no evidence, the panel shows "No evidence submitted yet."

## Submitting evidence

***

**1. Open the dialog**

Click **Submit evidence** in the page header.

**2. Describe the evidence**

Type a **Comment** of up to 1,000 characters. You must fill in this field.

**3. Attach the evidence**

Use one of the two tabs:

* **Link**: Type an `https` address in **File URL (optional)**, up to 2,048 characters.
* **Upload file**: Choose a PDF, PNG, JPEG, or CSV file of up to 10 MB in **File**.

**4. Submit**

Click **Submit evidence**.

## Closing a dispute

***

Click **Close dispute** in the page header and fill in the dialog:

| Field | Description |
| - | - |
| **Outcome** | Required. Select **Won** or **Lost**. |
| **Resolution** | Required. The explanation of the outcome, up to 5,000 characters. |

Click **Close dispute** to record the outcome.


# Managing exceptions
Source: https://docs.lerian.studio/en/products/matcher/ui/managing-exceptions

Review reconciliation exceptions in the Matcher module of Lerian Console: read the queue tallies, filter the queue, run bulk actions, and open an exception to resolve it.

Use the **Exceptions** queue in the Matcher module of Lerian Console to review reconciliation exceptions. An exception is a break that needs human review, such as a transaction without a match.

## Accessing the Exceptions queue

***

Click **Exception Handling → Exceptions** in the Matcher sidebar. The queue shows the exceptions of the **Active context** that you select in the Matcher sidebar. To see another context, change the **Active context**.

### Queue tallies

Above the filters, tallies count the whole filtered queue, not only the current page.

| Tally | What it counts |
| - | - |
| **Queue** | The exceptions that match the filters. |
| **Open** | The exceptions that are not resolved yet: **Open**, **Assigned**, and **Pending Resolution**. |
| **Overdue** | The unresolved exceptions with a due date in the past. The tally shows in red when it is above zero. |
| **Resolved** | The **Resolved** exceptions. |

A small bar after the tallies shows the resolved share of the queue.

### Exceptions of one run

To see the exceptions of one reconciliation run, click **View exceptions** on that run in [Operational History](/en/products/matcher/ui/operational-history). The **Originating run** link on an exception page opens the same view. To go back to the full queue, click **View all exceptions**.

## Filters

***

The list updates when you change a filter.

| Filter | Options |
| - | - |
| **Search...** | Free text. Matcher searches the transaction ID, the reason, and the external issue ID. |
| **Status** | Open, Assigned, Pending Resolution, or Resolved. |
| **Severity** | Low, Medium, High, or Critical. |
| **Reason** | Why Matcher raised the exception, for example Unmatched, Fee Variance, or Aged Break. |
| **Assigned to** | Select **Assigned to me** to see the exceptions assigned to your email address. |
| **Date from** / **Date to** | The range of creation dates. |
| **Minimum age in days** | The minimum age of the exception, from 0 to 3,650 days. |
| **Sort by** / **Order** | Severity, Created, Updated, or Status, in Descending or Ascending order. **Order** appears after you select a field. |
| **Items per page** | The number of rows on each page. |

With **Sort by** set to **Default**, the queue shows unresolved statuses first. Inside each status, the newest exception comes first.

If no exception matches the filters, the empty list shows a **Clear filters** button.

## Exception table

***

| Column | Description |
| - | - |
| Checkbox | Selects the row for a bulk action. The header checkbox selects every row on the page. |
| **Severity** | A colored dot. Put the pointer on the dot to see the severity name. |
| **Transaction** | The transaction ID, with a copy control. |
| **Source** | The name of the source of the transaction. |
| **Amount** | The amount and currency of the transaction. |
| **Reason** | Why Matcher raised the exception, as a link to the exception page. A status badge follows the link when the status is not **Open**. |
| **Due date** | The resolution deadline, when one is set. An overdue date on an **Open** or **Assigned** exception shows in red with a warning icon. |
| **Assigned to** | The assignee, when one is set. |

Click a **Reason** link to open the exception. See [Exception details](/en/products/matcher/ui/exception-details).

Matcher classifies the severity of each exception automatically. For the rules, see [Exception routing](/en/products/matcher/configuration/matcher-exception-routing).

## Bulk actions

***

**1. Select the exceptions**

Select the row checkboxes. A bar above the table shows how many exceptions you selected.

**2. Extend the selection (optional)**

Click **Select all N matching** to select every exception that matches the filters. If the selection cannot hold all of them, a notice shows how many it holds.

**3. Choose the action**

Click **Assign**, **Resolve**, or **Dispatch** in the bar.

**4. Complete the dialog**

Fill in the fields and click the action button.

| Action | Fields |
| - | - |
| **Assign** | **Assignee**: the person who works the exceptions. |
| **Resolve** | **Resolution** and an optional **Reason**. All selected exceptions get the same values. |
| **Dispatch** | For **Target system**, select **Manual**. **Queue or project** is optional. |

The Console sends a selection of more than 100 exceptions in batches of 100. The bar shows the number of batches.

When all exceptions succeed, a message shows the count and the dialog closes. When some fail, the dialog shows how many succeeded and how many failed, with a reason for each failure. Exceptions that succeed leave the selection. Failed exceptions stay selected, so you can read each reason and try again.

Click **Clear selection** to clear the selection. A change to a filter or to the **Active context** also clears it.

## Resolving exceptions

***

Open an exception to resolve it. These actions on the exception page resolve the exception:

* **Resolve**: Close the exception with a resolution text.
* **Force match**: Mark the transaction as matched and close the exception.
* **Adjust entry**: Record an adjustment for the transaction and close the exception.

**Match to this** pairs the transaction with a suggested counterpart. After a pairing, you still resolve the exception. For each action, see [Exception details](/en/products/matcher/ui/exception-details).


# Managing fee schedules
Source: https://docs.lerian.studio/en/products/matcher/ui/managing-fee-schedules

Define flat, percentage, tiered, or formula fees in the Matcher module so that Matcher can check fees on matched transactions and flag differences.

The **Fee Schedules** page of the Matcher module in Lerian Console lists your fee schedules. A fee schedule defines expected fees: flat, percentage, tiered, or formula. Matcher uses them to check the fees between matched transactions and to flag differences.

All contexts share the same fee schedules. To apply a schedule to a context, add a fee rule on the **Fee Rules** tab of that context, as [Context fee rules](/en/products/matcher/ui/context-fee-rules) describes.

## Opening the Fee Schedules page

***

In the Matcher module, go to **Settings → Fee Schedules**. The page does not use the **Active context** selector.

## Fee schedules table

***

The table shows up to 25 schedules per page. It has these columns:

| Column | Description |
| - | - |
| **Name** | The name of the fee schedule |
| **Currency** | The currency code (for example, `BRL`) |
| **Application order** | **Parallel** or **Cascading** |
| **Rounding** | The rounding method and the number of decimal places (for example, "Half Up, 2 decimals") |
| **Items** | The number of fee items in the schedule |
| **Used by** | The number of contexts whose fee rules use the schedule, or "Not used by any context" |
| **Created At** | The date when the schedule was created |
| **Actions** | The row actions menu |

Use **Previous** and **Next** below the table to move between pages.

### Application order

| Order | Description |
| - | - |
| **Parallel** | Each fee item uses the original gross amount |
| **Cascading** | Each fee item uses the net amount that remains after the previous items |

Matcher applies the fee items in priority order, lowest number first.

### Rounding methods

| Method | Description |
| - | - |
| **Half Up** | Rounds to the nearest value. A value exactly halfway rounds away from zero |
| **Bankers** | Rounds to the nearest value. A value exactly halfway rounds to the nearest even digit |
| **Floor** | Rounds toward negative infinity |
| **Ceil** | Rounds toward positive infinity |
| **Truncate** | Removes the extra decimal places without rounding |

### Structure types

| Type | Description |
| - | - |
| **FLAT: flat amount** | A fixed amount in the schedule currency (for example, `5.00`) |
| **PERCENTAGE: percentage of base** | A rate on the base amount |
| **TIERED: marginal tranches** | Tiers by base amount. Each tier charges its rate on the part of the amount inside that tier |
| **EXPRESSION: formula** | A formula over the gross amount and transaction metadata keys |

## Creating a fee schedule

***

1. Click **New fee schedule**. The **New fee schedule** sheet opens.
2. Fill in the schedule fields.
3. Fill in the first fee item. Click **Add fee item** to add more items.
4. Click **Save**.

### Schedule fields

| Field | Description |
| - | - |
| **Name** | A name for the schedule (for example, "Bank Fees BRL") |
| **Currency** | The currency code (for example, `BRL`). You cannot change it later |
| **Application order** | **Parallel** or **Cascading**. The default is **Parallel** |
| **Rounding method** | **Half Up**, **Bankers**, **Floor**, **Ceil**, or **Truncate**. The default is **Half Up** |
| **Decimal places** | The number of decimal places after rounding, from 0 to 10. The default is 2 |

### Fee item fields

| Field | Description |
| - | - |
| **Name** | A name for the fee item (for example, "Wire Fee") |
| **Priority** | A whole number, 0 or more. Lower numbers apply first. Each item in a schedule needs a different priority |
| **Structure** | The structure type of the fee item |

The structure type adds more fields:

| Structure | Fields | Description |
| - | - | - |
| **FLAT: flat amount** | **Amount** | The fixed amount in the schedule currency |
| **PERCENTAGE: percentage of base** | **Rate** | A fraction of the base amount, from 0 to 1. For example, `0.029` is 2.9% |
| **TIERED: marginal tranches** | **Tier 1 rate**, **Tier 1 up to**, and one pair for each other tier | Each tier has a rate from 0 to 1 and an upper limit. Click **Add tier** to add a tier. Each limit must be higher than the limit before it. Leave the last limit empty to make that tier open-ended |
| **EXPRESSION: formula** | **Expression** | A formula over `gross` and transaction metadata keys. You can use `+ - * /`, parentheses, and the functions `days_late(a, b)`, `days_between(a, b)`, `max(…)`, `min(…)`, `abs(x)`, and `clamp(x, lo, hi)`. If the formula only multiplies or divides `gross` by numbers, its rate must be from 0 to 1. Matcher checks the formula when you save |

> [!NOTE]
>
> You cannot change the fee items after you save the schedule. To change them, create a new schedule.

## Viewing a fee schedule

***

Open the row actions menu and click **View**. A dialog shows the currency, the application order, and the rounding of the schedule. It lists the fee items in priority order.

## Editing a fee schedule

***

1. Open the row actions menu and click **Edit**. A sheet opens with the current values.
2. Change **Name**, **Application order**, **Rounding method**, or **Decimal places**.
3. Click **Save**.

The **Currency** field is locked. The sheet shows the fee items, but you cannot edit them.

## Simulating fees

***

Use a simulation to estimate the fees of a schedule for an amount. A simulation records nothing.

1. Open the row actions menu and click **Simulate**. The **Simulate fees** dialog opens.
2. Enter the amount in **Gross amount**. The label shows the currency of the schedule, for example **Gross amount (BRL)**.
3. Click **Run simulation**.

The result shows the **Gross** amount, the **Total fee**, and the **Net** amount. A table lists each fee item by **Name**, with the **Base used** and the **Fee**.

## Deleting a fee schedule

***

1. Open the row actions menu and click **Delete**. A confirmation dialog opens.
2. Click **Confirm**.

> [!NOTE]
>
> Matcher does not delete a schedule that a fee rule still uses. The **Used by** column shows how many contexts use the schedule.


# Managing matches
Source: https://docs.lerian.studio/en/products/matcher/ui/managing-matches

Review the match groups of a reconciliation run in the Matcher module, unmatch a wrong group, and record an adjustment against a group.

Match groups are the pairings that a reconciliation run produced. In the Matcher module of Lerian Console, they live inside the detail page of each run. To pair transactions by hand, use the **Unmatched** workbench. See [Manual matching](/en/products/matcher/ui/manual-matching).

## Viewing the match groups of a run

***

**Step 1**

Click **Operate → Reconciliations** in the Matcher sidebar.

**Step 2**

In **Run history**, click the run ID in the **Run** column. The **Match groups** page of the run opens.

The page shows a summary of the run, a **Rule breakdown** with the number of groups for each rule, and the match groups.

* **Match rate**: the share of the run's transactions that matched, by count.
* **Breakdown**: **Matches**, **Proposed**, **Pending review**, and the unmatched counts for the left side, the right side, and external transactions.
* **Rule breakdown**: after a completed run, a warning names each rule that matched no groups.

While the run is in progress, the page refreshes as the run advances. Click **Stop watching** to stop the refresh. If you stop watching, or the refresh times out, click **Recheck status** to read the run status again.

### Filtering by status

Use the status filter at the top of the page to show **All** groups or only the **Proposed**, **Confirmed**, **Rejected**, or **Revoked** groups. The filter applies to all groups of the run, not only to the loaded page.

### The match group card

Each card shows:

* The group status and its short ID.
* The **Rule** that produced the group.
* The rejection or revocation reason, when the group has one.
* Badges with the exception reasons on the group's transactions, when there are any.
* A confidence meter with the label **High confidence**, **Medium confidence**, or **Low confidence**.
* The items of the group, by side. Each item shows the **Allocated** and **Expected** amounts. A difference between them shows as a warning on the item.

## Unmatching a group

***

Unmatch a group when the match is wrong. Only **Proposed** and **Confirmed** groups offer **Unmatch**.

1. Click **Unmatch** on the group card.
2. In the **Unmatch this group?** dialog, enter a **Reason**. The reason is required.
3. Click **Unmatch**.

Matcher moves the group's transactions back to the unmatched backlog. A **Proposed** group becomes **Rejected**. A **Confirmed** group becomes **Revoked**.

Unmatching a **Confirmed** group also reverses what its confirmation recorded:

* Matcher takes back the group's entries on open items. An open item that only this group supports becomes **Withdrawn**. See [Open items](/en/products/matcher/ui/open-items).
* Matcher voids the fee variances that the confirmation recorded.
* Matcher closes the fee and FX exceptions that the confirmation raised, when they are still **Open** or **Assigned** and have no active dispute.

Matcher can refuse to unmatch a **Confirmed** group when other activity already depends on its open item. For example, a later run already netted against the same open item. A refused unmatch changes nothing. The error message says what to do next.

## Recording an adjustment

***

Record an adjustment to explain a variance in a match group, for example a bank fee or an FX difference.

1. Click **Adjust** on the group card. The **Record adjustment** dialog opens.
2. Fill in the fields. All fields are required.
3. Click **Record adjustment**.

| Field | Description |
| - | - |
| **Adjustment type** | **Bank fee**, **FX difference**, **Rounding**, **Write-off**, or **Miscellaneous**. |
| **Direction** | **Debit** or **Credit**. The direction sets the sign of the entry. |
| **Amount** | A positive amount. Matcher records it as you enter it. |
| **Currency** | A three-letter currency code. The field starts with the currency of the group's first item. |
| **Description** | A short label for the entry, up to 500 characters. |
| **Reason** | Why the entry closes the gap, up to 2,000 characters. |

Matcher records the adjustment against the group. The group and its transactions do not change.


# Manual matching
Source: https://docs.lerian.studio/en/products/matcher/ui/manual-matching

Pair transactions that the engine could not reconcile: build a basket in the Unmatched workbench of the Matcher module and link it into a confirmed match group.

Transactions that the matching engine did not reconcile appear in the **Unmatched** workbench of the Matcher module in Lerian Console. Use the workbench to review the backlog, pair counterpart transactions into a match group, or ignore a transaction.

## Accessing the Unmatched workbench

***

Click **Resolve → Unmatched** in the Matcher sidebar. The workbench shows the **Active context** that you select in the Matcher sidebar. To work on another context, change the **Active context**.

## The unmatched backlog

***

The table lists the transactions of the context that are not matched, 25 per page. Use **Previous** and **Next** to move between pages.

| Column | Description |
| - | - |
| **Transaction** | The short transaction ID. |
| **Source** | The source name. When the side of the source is known, a second line shows **Left side** or **Right side**. |
| **Amount** | The transaction amount and currency. |
| **Status** | The transaction status, for example **Unmatched** or **Ignored**. |
| **Exception** | The ID of the exception on the transaction, or a dash. |
| **Date** | The transaction date. |

### Date window

By default, the table shows the last 90 days in UTC, today included. To change the window:

1. Set **Date from** and **Date to**.
2. Click **Apply filters**.

A date window can cover up to 90 days. To see older transactions, click **Show all history**. The table then shows the full backlog. To go back to a date window, click **Use date window**.

> [!WARNING]
>
> **Apply filters**, **Show all history**, and **Use date window** empty the pairing basket. Moving between pages keeps the basket.

## Building a pairing basket

***

Select the checkbox of each transaction that you want to pair. The selected transactions go into a pairing basket. The basket bar above the table shows how many transactions you selected. To empty the basket, click **Clear**.

Select only transactions with the **Unmatched** status. A manual match must include at least two transactions, with at least one from the left side and one from the right side. Until your selection meets this rule, the basket bar shows a hint and **Pair selected** stays disabled.

### Suggested counterparts

When the basket holds exactly one transaction, the **Suggested counterparts** panel opens. It lists opposite-side transactions that the engine ranks as plausible matches. Each suggestion shows:

* The amount, the date, and the rule type that ranked it.
* A score with the label **Strong**, **Plausible**, or **Weak**.
* Badges that show which fields agree, for example **Amount agrees** or **Date differs**.
* The amount difference and the number of days between the dates.

The ranking uses raw amounts. It does not apply fee normalization or FX tolerance. To add a suggestion to the basket, click **Match to this**.

## Creating the match

***

**1. Open the confirmation**

Click **Pair selected** in the basket bar. The **Pair these transactions?** dialog opens.

**2. Check the selection**

The dialog shows the left-side and right-side transactions. It also shows the **Amount difference** between the two sides, over raw amounts.

**3. Confirm**

Click **Pair selected**. Matcher links the transactions into a confirmed match group, and they leave the backlog.

> [!NOTE]
>
> Matcher gives a manual match a confidence of 100 and confirms it immediately. Each manual match creates its own **Commit** run in the run history of the context. To undo a manual match, open that run and unmatch the group. See [Managing matches](/en/products/matcher/ui/managing-matches).

## Ignoring a transaction

***

Ignore a transaction to exclude it from matching, for example a duplicate entry. Only rows with the **Unmatched** status show the **Ignore** action.

1. Click **Ignore** on the row.
2. In the **Ignore this transaction?** dialog, click **Ignore transaction**.

Matcher sets the transaction status to **Ignored**. An ignored transaction no longer takes part in matching. You cannot undo this action.


# Open items
Source: https://docs.lerian.studio/en/products/matcher/ui/open-items

Track the residual balances that partial matches carry forward across reconciliation runs in the Matcher module, by status, age, and running balance.

An open item is the unpaid remainder of an obligation that Matcher carries from one run to the next. When a confirmed match covers only part of an expected amount, Matcher opens an open item for the rest. Later runs net new transactions against it.

Open items differ from unmatched transactions. An open item comes from a match that left a remainder. The **Open Items** screen of the Matcher module in Lerian Console lists them. You cannot change open items on this screen.

## Accessing the Open Items screen

***

Click **Resolve → Open Items** in the Matcher sidebar. The screen shows the **Active context** that you select in the Matcher sidebar. To see another context, change the **Active context**.

## Open item statuses

***

| Status | Description |
| - | - |
| **Open** | No later transaction has netted against the item. |
| **Partially cleared** | Later transactions netted part of the balance, and a remainder is still open. |
| **Cleared** | The running balance reached zero, within the tolerance. |
| **Aged** | The item stayed open longer than the aging threshold of the context. Matcher raised an exception for it. |
| **Withdrawn** | An operator unmatched the confirmed match behind the item, and no other match still counts toward it. |

Only **Open** and **Partially cleared** items take part in later runs.

## The open items table

***

The table shows 25 open items per page. Use **Previous** and **Next** to move between pages.

| Column | Description |
| - | - |
| **Identity** | The key that Matcher uses to find the item in later runs. It combines the match key values and the currency. |
| **Expected** | The total owed on this identity. |
| **Running balance** | The amount still open. It changes as later transactions net against the item. |
| **Status** | The open item status. |
| **Age** | The number of days the item has been open. The icon changes at 7 days and again at 30 days. |
| **Obligation date** | The business date of the original obligation, or a dash. |
| **Last activity** | When the balance or status last changed. |
| **Investigate** | A link to the related run or to the exceptions queue. |

### Filtering and sorting

* **Status**: show **All statuses** or one status.
* **Sort by**: keep the **Default order**, or sort by **Age** or **Running balance**.
* **Order**: **Descending** or **Ascending**. This filter shows when you sort by **Age** or **Running balance**.

## Investigating an open item

***

The **Investigate** column shows one link for each item:

* **View source run** opens the detail page of the match run linked to the item. See [Managing matches](/en/products/matcher/ui/managing-matches).
* **View aged break** or **View exceptions** opens the exceptions queue. These links show when the item has no linked run. See [Managing exceptions](/en/products/matcher/ui/managing-exceptions).

To take back an open item that a wrong match created, unmatch the confirmed match behind it. See [Managing matches](/en/products/matcher/ui/managing-matches).


# Operational history
Source: https://docs.lerian.studio/en/products/matcher/ui/operational-history

Review the reconciliation runs and import jobs of the active Matcher context on one screen, with live-refreshing tables and status badges.

The **Operational History** screen of the Matcher module in Lerian Console shows the history of the active context. It has two tables: **Run history** for reconciliation runs and **Import jobs** for data imports.

> [!NOTE]
>
> Export jobs are not on this screen. They are on **Reporting → Exports**. See [Reports and exports](/en/products/matcher/ui/reports-and-exports).

## Accessing the Operational History screen

***

Click **Operate → Operational History** in the Matcher sidebar. The screen shows the **Active context** that you select in the Matcher sidebar. To see another context, change the **Active context**.

If no context exists, the screen asks you to create one and shows a **Browse contexts** button.

## Run history

***

The **Run history** table lists the runs of the context, newest first, 20 per page. Use **Previous** and **Next** to move between pages. While a run on the page is in progress, the table shows a **Live** badge. It refreshes every two seconds, for up to three minutes.

| Column | Description |
| - | - |
| **Run** | The short run ID. Click it to open the run detail page with the match groups of the run. |
| **Mode** | **Commit** or **Dry run**. |
| **Status** | The run status, as a colored badge. |
| **Matches** | The number of match groups that the run found. |
| **Unmatched** | The unmatched transactions of both sides, plus the external unmatched count. The figure shows in red when it is above zero. |
| **Split** | A small bar with the matched share of the run. |
| **Started** | When the run started. |
| Last column (no header) | A **View exceptions** link. It opens the exceptions queue for the run. See [Managing exceptions](/en/products/matcher/ui/managing-exceptions). |

### Run statuses

| Status | Description |
| - | - |
| **Queued** | The run waits to start. |
| **Processing** | The engine processes the run. |
| **Finalizing** | The engine has stored the matches and finishes the run. |
| **Completed** | The run ended without an error. |
| **Failed** | The run ended with an error. |

### Run modes

| Mode | Description |
| - | - |
| **Commit** | The run persisted its match groups and exceptions. |
| **Dry run** | The run evaluated the rules and wrote no match groups or exceptions. Use it to test rules. |

For how to start a run, see [Running reconciliations](/en/products/matcher/ui/executing-reconciliation).

## Import jobs

***

The **Import jobs** table lists the import jobs of the context, newest first, 15 per page. While a job on the page waits or runs, the table refreshes every two seconds and shows a **Live** badge.

| Column | Description |
| - | - |
| **File** | The name of the imported file. |
| **Status** | The job status, as a colored badge. |
| **Rows imported** | The rows that Matcher stored, out of the total rows in the file. When the import dropped duplicate rows, a note shows how many. |
| **Failed rows** | The rows that failed to import. The figure shows in red when it is above zero. |
| **Created At** | When Matcher created the job. |
| **Finished at** | When the job finished. |
| Last column (no header) | **View errors** for a job that completed with errors. **Details** for other jobs. |

Click a row, **Details**, or **View errors** to open the **Import details** panel.

### Import details

The **Import details** panel shows the job status and **Rows imported**. Depending on the job, it can also show:

* Notes about duplicate rows, with the duplicate reason.
* The number of rows imported for review. The link opens **Resolve → Unmatched**.
* A summary of the outcome, for example the percentage of rows that failed.
* **Import errors**, for a completed job with failed rows. Each row of the list gives the file row number, the field, and the error message.
* **Produced transactions**, for a completed job. Each row gives the reference, amount, date, and status of a transaction that the job created.

### Import job statuses

| Status | Description |
| - | - |
| **Queued** | The job waits to start. |
| **Processing** | Matcher reads the file. |
| **Completed** | The job completed and no row failed. |
| **Completed with errors** | The job completed, but at least one row failed. Click **View errors** to see the failed rows. |
| **Failed** | The job stopped before it completed. Check the file and its format, then upload it again. |

To upload a file, see [Uploading reconciliation data](/en/products/matcher/ui/uploading-reconciliation-data).


# Reports and exports
Source: https://docs.lerian.studio/en/products/matcher/ui/reports-and-exports

Compare reconciliation health across contexts, read the variance, matched, unmatched, and summary reports, and export report files in CSV, JSON, or XML.

Three screens in the **Reporting** group of the Matcher module in Lerian Console show reconciliation figures. The **Portfolio** screen compares all your contexts. The **Reports** screen shows the reports for one context. The **Exports** screen writes a report to a file that you can download.

## Portfolio

***

Navigate to **Reporting → Portfolio**. The page shows reconciliation health for all contexts in one table, with one row for each context. This page does not use the **Active context**.

Use **Last 7 days**, **Last 30 days**, or **Last 90 days** to set the window. The default is **Last 90 days**.

| Column | Description |
| - | - |
| **Context** | The context name. Click it to open the context |
| **Match rate** | The percentage of the context's transactions that matched in the window |
| **Backlog** | The number of unmatched transactions |
| **Cash exposure** | The unmatched amount. If a context has amounts in more than one currency, the cell shows the number of currencies. Hover over the cell to see each amount |
| **SLA** | The SLA compliance rate of the context's exceptions |
| **Overdue** | The number of open exceptions that are past their SLA |

Click a column header to sort the table. The table opens sorted by **Backlog**, with the highest value first.

A row of totals above the table shows the number of contexts, **Match rate**, **Backlog**, **Overdue**, and the **Unmatched** amount for each currency. The totals include only the contexts that loaded. If a context does not load, its row shows **Failed** and a **Retry** button. Click **Retry failed** to load all failed contexts again.

## Reports

***

Navigate to **Reporting → Reports**. The page shows the reports for the **Active context** that you select in the Matcher sidebar.

### Report window

Set **Date from** and **Date to**, then click **Apply filters**. The default window starts 30 days before today (UTC) and ends today. The window can include at most 90 days. The **Window** chip shows the dates that the reports use.

### Report types

Select a tab to choose the report:

| Tab | Content |
| - | - |
| **Variance** | Fee totals for each source, fee schedule, and currency. Columns: **Source**, **Fee schedule**, **Expected**, **Actual**, **Net variance**, **Adjusted**, **Outstanding**, and **Variance %** |
| **Matched** | The matched transactions. Columns: **Transaction**, **Match group**, **Source**, **Amount**, and **Date** |
| **Unmatched** | The unmatched transactions. Columns: **Transaction**, **Source**, **Amount**, and **Date** |
| **Summary** | Five totals: **Matched records**, **Unmatched records**, **Total amount**, **Matched amount**, and **Unmatched amount** |

The **Variance** report columns have these meanings:

* **Expected**: the fee total that the fee schedule calculates.
* **Actual**: the fee total that Matcher found.
* **Net variance**: **Actual** minus **Expected**.
* **Adjusted**: the adjustments recorded against the fee variances of the row.
* **Outstanding**: the part of the variance that no adjustment explains.

The **Variance**, **Matched**, and **Unmatched** reports show 25 rows on each page. Use **Previous** and **Next** to move between pages.

## Exports

***

Navigate to **Reporting → Exports**. The page lists all export jobs. An export job writes a report to a file in the background.

Use the **Context** filter to show the jobs of one context. The default is **All contexts**.

| Column | Description |
| - | - |
| **File** | The name of the export file |
| **Context** | The context of the job |
| **Report type** | **Matched**, **Unmatched**, **Variance**, or **Exceptions** |
| **Format** | `CSV`, `JSON`, or `XML` |
| **Status** | **Queued**, **Running**, **Succeeded**, **Failed**, **Expired**, or **Canceled**. A failed job also shows the error |
| **Records** | The number of records written to the file |
| **Created** | The date and time of the job creation |
| **Finished at** | When the job ended |
| **Actions** | The action for the job status |

While a job is **Queued** or **Running**, the list refreshes every two seconds and shows a **Live** badge. After five minutes, the automatic refresh stops. Click **Recheck status** to start it again. The jobs continue to run in the background.

### Creating an export

1. Click **New export**. The **Create export job** sheet opens for the context in the **Context** filter. If the filter shows **All contexts**, the sheet uses the **Active context**.

2. Fill in the fields:

   | Field | Description |
   | - | - |
   | **Report type** | **Matched**, **Unmatched**, **Variance**, or **Exceptions**. The default is **Matched** |
   | **Format** | `CSV`, `JSON`, or `XML`. The default is `CSV` |
   | **Date from** and **Date to** | The window of the export. The default window starts 30 days before today. The dates can be at most 365 days apart |
   | **Source** | **All sources**, or one source of the context |

3. Click **Create export**. The new job appears in the list with the **Queued** status.

### Job actions

| Status | Action |
| - | - |
| **Succeeded** | Click **Download** to open the file in a new tab. The row then shows the SHA-256 digest of the file. You can copy the digest and compare it with the digest of the downloaded file |
| **Queued** or **Running** | Click **Cancel** to stop the job |
| **Failed** or **Expired** | Click **Retry** to create a new job with the same report type and format. The new job uses the default 30-day window, not the original dates |


# Rule suggestions
Source: https://docs.lerian.studio/en/products/matcher/ui/rule-suggestions

Review the match rules that Matcher proposes for a context, then approve or reject each one from the Rule Suggestions page of the Matcher module.

Use the **Rule Suggestions** page in the Matcher module of Lerian Console to review the match rules that Matcher proposes for a context. A suggestion changes nothing on its own. Matcher creates a rule from a suggestion only when you approve it.

To learn how Matcher produces suggestions, see [Rule suggestions](/en/products/matcher/matching/matcher-rule-suggestions).

## Accessing the Rule Suggestions page

***

**Step 1**

In the Matcher sidebar, select a context in **Active context**.

**Step 2**

Go to **Configure → Rule Suggestions**.

The page shows the suggestions of the active context. With no active context, the page asks you to select one and shows a **Browse contexts** button.

When rule suggestions are off, the page shows a notice.

## Generating suggestions

***

Click **Suggest rules** in the page header. A message shows how many suggestions Matcher added to the list. Matcher proposes **Exact**, **Tolerance**, and **Date Lag** rules only.

Matcher uses AI to propose these rules. It sends aggregate statistics of your match history to the language-model provider Lerian configures for your environment.

## Suggestions list

***

| Column | Description |
| - | - |
| **Type** | The strategy of the proposed rule |
| **Priority** | The priority that the proposed rule gets |
| **Confidence** | How confident Matcher is in the proposal, as a percentage with a bar |
| **Status** | **Pending Review**, **Approved**, or **Rejected** |
| **Created** | When Matcher created the suggestion |

Use the **Status** filter to show the suggestions with one status. Use **Items per page** and the page controls below the table to move through the list.

The **Confidence** bar has three bands: high from 90%, medium from 70%, and low below 70%. This value rates the proposal itself. It is not the confidence score of a match.

## Viewing a suggestion

***

Click **View** on a row. The suggestion detail opens below the list. Click **View** again to close it.

The **Proposed rule** panel shows:

| Field | Description |
| - | - |
| **Type** | The strategy of the proposed rule |
| **Priority** | The priority that the proposed rule gets |
| **Status** | The status of the suggestion |
| **Rationale** | A short reason for the proposal |
| **Expected improvement** | A note on the expected effect on automatic matching |
| **Created rule** | The ID of the match rule that Matcher created from the suggestion. It shows only after Matcher creates the rule |

The **Configuration** panel shows the confidence and a plain-language summary of the rule under **Matches when**. Click **Show raw configuration** to see the rule configuration as JSON.

## Approving a suggestion

***

The **Approve** and **Reject** buttons show only on a suggestion with **Pending Review** status.

**Step 1**

Open the suggestion and click **Approve**. The **Approve suggestion** dialog opens.

**Step 2**

Click **Approve**.

When Matcher creates the rule, a message shows the new rule ID, and the suggestion moves to **Approved**. The new rule is on the [Rules](/en/products/matcher/ui/context-rules) tab of the context, at the proposed priority.

## Rejecting a suggestion

***

**Step 1**

Open the suggestion and click **Reject**. The **Reject suggestion** dialog opens.

**Step 2**

Optionally, type a reason in **Reason (optional)**, up to 1000 characters.

**Step 3**

Click **Reject suggestion**.

The suggestion moves to **Rejected**. Matcher creates no rule.


# Uploading reconciliation data
Source: https://docs.lerian.studio/en/products/matcher/ui/uploading-reconciliation-data

Upload a transaction file into one source of the active Matcher context from the New Reconciliation screen, then follow the import job.

A reconciliation run can match only the transactions that you imported. The **New Reconciliation** screen of the Matcher module in Lerian Console uploads transaction files. Each file goes into one source of the active context. The screen then follows the import job on the same page.

## Before you upload

***

* The screen works on the **Active context** that you select in the Matcher sidebar. With no context, the screen asks you to select one first.
* The context must be active. For a context in another status, the screen shows an alert and blocks the upload. Click **Activate this context** to open the context page, then activate the context there. For an archived context, the button is **Restore this context**. See [Managing contexts](/en/products/matcher/ui/managing-contexts).
* The context needs a source to receive the file. See [Context sources](/en/products/matcher/ui/context-sources).

## Uploading a file

***

**Step 1**

Click **Operate → New Reconciliation** in the Matcher sidebar.

**Step 2**

In **Source leg**, select the source that receives the file. Each item shows the source name, its side, and its type.

**Step 3**

Drop a transaction file onto the upload area, or click the area to browse. You can upload one file at a time. The page shows the name and size of the file.

**Step 4**

Check the **Format**. The page fills it from the file name when it can. If it stays empty, select the format.

> [!NOTE]
>
> The **Format** list groups the built-in formats by region. It also lists your layout templates. See [Formats and templates](/en/products/matcher/imports/matcher-import-formats) and [Layout templates](/en/products/matcher/ui/layout-templates).

**Step 5**

Optionally, click **Preview file**. The **File preview** panel shows the columns that Matcher detects and some sample rows. You can preview a file when its format is delimited (CSV), JSON, XML, or camt.053.

**Step 6**

Click **Upload**. A progress bar shows while the file uploads. When Matcher accepts the file, the message **Upload accepted** appears.

> [!NOTE]
>
> The page accepts files up to 100 MB. For a larger file, the page shows a message and keeps **Upload** disabled. Split the file into smaller files and upload each one.

## Tracking the import

***

After the upload, an import panel shows the file name, the job ID, and the job status. While the job runs, the panel checks its status every 1.5 seconds, up to 80 times. Click **Stop watching** to stop the checks. The import continues in Matcher. If the checks stop before the job ends, click **Recheck status** to check again.

When the job ends, the panel shows **Total rows**, **Imported**, and **Failed rows**. Click **Dismiss import** to close the panel.

The **Import jobs** table below the panel lists the imports of the context, newest first. It refreshes while a job is in progress. Click a row to open the import details. The same table is on the **Operational History** screen. For its columns and statuses, see [Operational history](/en/products/matcher/ui/operational-history).

## Next step

***

To match the imported transactions, start a run on **Operate → Reconciliations**. See [Running reconciliations](/en/products/matcher/ui/executing-reconciliation).


# Interfaces
Source: https://docs.lerian.studio/en/interfaces/introduction

Lerian's integrations to payment products, through a Lerian rail or through a partner institution.

An interface is Lerian's integration to a payment product. It gives you the API, the ledger integration, and the operational controls for that product.

The national payment system is different from a Lerian rail. SPI is the Pix system and SPB carries TED. A Lerian rail is software for native messaging, and it can connect an institution to one of those systems. This tab documents the interfaces that reach payment products through a configured provider or a Lerian rail.

Lerian offers seven interfaces:

* [TED Lerian](/en/interfaces/ted-lerian/what-is-ted-lerian)
* [TED JD](/en/interfaces/ted-jd/ted-in-lerian)
* [Pix Lerian](/en/interfaces/pix-lerian)
* [Pix JD](/en/interfaces/pix-jd/direct-pix-via-jd)
* [JD Courier](/en/interfaces/jd-courier/what-is-jd-courier)
* [Pix BTG](/en/interfaces/pix-btg/indirect-pix-overview)
* [Payments BTG](/en/interfaces/payments-btg/boleto-and-bill-payment)

## What runs in production today

***

Pix runs in production through two interfaces. The JD interface connects your institution as a direct participant through a certified PSTI. The BTG interface connects you as an indirect participant. TED runs through JD.

Pix Lerian is an application plugin, not the native Lerian SPI rail. In v1.0.0, Pix Lerian is available for integration and testing with the mock provider adapter.


# What is Pix?
Source: https://docs.lerian.studio/en/interfaces/pix/pix-overview

What Pix is and how Brazil's instant payment system works: 24/7 settlement, Pix keys, QR Codes, SPI, DICT, and Direct or Indirect participant models.

Pix enables instant transfers between individuals, businesses, and financial institutions. Pix operates 24/7, including weekends and holidays.

Transactions typically settle in under 10 seconds. Pix is low-cost, accessible, and secure across the financial system.

# How Pix works

***

Pix supports multiple initiation methods:

* **Pix Keys:** CPF/CNPJ, phone number, email address, or EVP (random key)
* **QR Codes:** Static (reusable) and dynamic (single-use, metadata-rich)
* **Manual entry:** Full banking details (bank, agency, account)

After confirmation, BACEN’s infrastructure settles the transaction between the institutions, and the receiving institution credits the recipient instantly.

# What Pix offers

***

Pix combines speed, accessibility, and regulatory-grade security:

* **Instant settlement**: Routed and cleared in seconds
* **Always available**: 24/7 operation
* **Low cost** or free for individuals
* **Secure and auditable**: Every transaction has an E2E ID
* **User-friendly**: Human-readable identifiers reduce friction and errors

Pix is Brazil’s most widely adopted payment rail. People use it for everyday transfers, merchant payments, and service flows.

# Pix modalities

***

Pix supports several operational flows defined by BACEN:

| Type | Description |
| - | - |
| **Common Pix** | Standard transfer via key or full account details |
| **Pix QR Code** | Static or dynamic EMV-based payment initiation |
| **Pix Saque** | Cash withdrawal at authorized merchants |
| **Pix Troco** | Payment + cash withdrawal in a single operation |
| **Pix Cobrança** | Pix with due dates, penalties, discounts, and reconciliation |
| **Pix Agendado** | Scheduled Pix |
| **Pix Automático** | Recurring payments |

These modalities cover both consumer and business use cases.

# Pix infrastructure: SPI and DICT

***

Pix relies on two core services operated by BACEN:

## SPI (Instant Payment System)

***

The SPI is Pix’s settlement engine.

It handles:

* Transaction routing between institutions
* Real-time clearing
* Final, irrevocable settlement

Institutions connect to SPI through the **SPI Gateway**, which requires strong cryptography, mTLS, and regulated network connectivity.

## DICT (Directory of Transactional Account Identifiers)

***

DICT is the nationwide registry that stores **Pix keys**.

It ensures:

* Key uniqueness
* Lookup of recipient information
* Portability between institutions
* Ownership validation
* Fraud and dispute checks (linked to MED and infractions)

Every Pix operation also includes a **unique End-to-End ID (E2E)** for reconciliation and dispute resolution across all participants.

# Participants in the Pix ecosystem

***

BACEN defines participation models based on how institutions connect to its infrastructure:

### Direct Participants

Institutions that connect directly to SPI and DICT.

They manage:

* Their own Pix messaging and connectivity
* Real-time liquidity
* Full regulatory, operational, and security compliance

This model provides maximum autonomy and control but requires significant infrastructure and governance maturity.

### Indirect Participants

Institutions that access Pix through a direct participant (the “sponsor”).

The sponsor handles:

* Connectivity
* Clearing
* Settlement
* Compliance with BACEN protocols

This reduces operational complexity and speeds up time-to-market.

### A practical way to understand it

| Scenario | Direct participation | Indirect participation |
| - | - | - |
| **Transportation** | Owning an airplane and being a licensed pilot | Flying using a commercial airline |
| **Food service** | Opening your own restaurant with all legal permits | Operating inside a licensed kitchen |
| **Real estate** | Building an entire building | Renting an apartment in a completed building |

In all cases, the goal is the same, but the responsibility and complexity shift. End users see no difference between the two models.

### PSTI (Information Technology Service Provider)

A PSTI is a BACEN-regulated provider authorized to operate the infrastructure required for financial institutions to connect to the RSFN (National Financial System Network).

Using a PSTI allows institutions to:

* Connect to BACEN networks without building full infrastructure
* Rely on certified, secure, and compliant systems
* Maintain control of their ledger and business logic

PSTIs ensure regulated communication, data protection, and high availability for Pix participation.

# Requirements for participation

***

To offer Pix, institutions must follow BACEN’s operational and security standards, which typically include:

* mTLS authentication and ICP-Brasil certificates
* Regulated connection to the RSFN (directly or via PSTI)
* 24/7 availability and redundancy
* Real-time monitoring and SLA adherence
* Fraud prevention and dispute handling (MED)
* Compliance with DICT and SPI message formats
* Timely reporting, logging, and auditability
* Following nightly limit rules and configurable customer limits

> [!TIP]
>
> **Regulatory reference**
>
> For Pix rules, deadlines, and official requirements, always refer to the [official documentation](https://www.bcb.gov.br/estabilidadefinanceira/pix-normas) published by the Central Bank of Brazil (BACEN). This page is a practical overview only.
>
> BACEN’s materials are the authoritative source for Pix regulations. They contain the most complete and current specifications.

# Pix in the Lerian platform

***

Lerian provides **Pix Lerian**, an application plugin for operating Pix through stable application contracts and Midaz ledger integration.

**Lerian SPI** is a separate native Pix rail design, not a connectivity option available through Pix Lerian v1.0.0. This release supports integration and testing with the mock provider adapter. The native SPI messaging connector is still under development and is not available for use as a production rail.

Pix Lerian covers keys and claims, transfers and refunds, collections, and BR Codes. The connectivity provider is configured behind the public contract, so the client integration remains stable.

Key characteristics:

* **One interface, different connectivity providers**: the client application uses the same public contract regardless of the configured provider
* **Provider-adapter boundary**: the client application stays independent of the configured adapter contract
* **Native ecosystem integration**: works with Midaz as the ledger and Access Manager for authentication and authorization

> **[Pix Lerian](/en/interfaces/pix-lerian)**
>
> Understand the interface, its domains, and the recommended integration journey.

> **[Main domains](/en/interfaces/pix/main-domains-overview)**
>
> Explore the core Pix domains: DICT, Transactions, QR Codes, and MED.

> **[Explore the Pix Lerian API](/en/reference/interfaces/pix-lerian/dict/create-entry)**
>
> Browse the client-facing operations for keys, claims, payments, refunds, and collections.


# Best practices
Source: https://docs.lerian.studio/en/platform/access-manager/am-best-practices

Best practices for operating Access Manager securely: manage credentials, lock down environments, and protect identity and authorization at scale.

Access Manager holds the identity, authorization, and credentials for every protected Lerian product. Treat it as critical infrastructure and operate it with the controls below.

## Credentials

***

### Create credentials for calling applications

For machine-to-machine access, the calling application uses its `client_id` and `client_secret` to request a token. The receiving service validates that bearer token. Configure the receiving service to enforce the route. It does not need a second M2M client credential for the same call.

### Protect the deployment environment

Protect the hosts, deployment secrets, and administrator access that support Access Manager. Limit access to the physical or virtual machines and the secret-management systems that deliver its configuration.

### Limit access to credential-management endpoints

Identity management endpoints can expose application data. Restrict access to these endpoints and keep sensitive management operations isolated from general back-office workflows.

## Security recommendations

***

### Use Application-to-Application flows for sensitive endpoints

For critical access such as Ledger automation, use dedicated Applications. This gives you clear control over each integration. Delete an application through the documented Identity API when you no longer need it. Handle any existing tokens or credentials through your environment's incident-response procedure.

### Use user-based credentials for manual actions

When a person needs access for debugging, operations, or support, issue per-user credentials instead of sharing `client_credentials`. You can then manage access and remove permissions for each person separately. End a session only through the normal logout flow with that session's `id_token_hint`. That flow is not an administrator-targeted "log out another user" control. Reserve `client_credentials` for machine-to-machine applications.

Run regular access reviews for applications and permissions. This minimizes exposure and keeps access limited to authorized users.

Always enforce the principle of least privilege for both users and applications. Grant only the exact permissions each one needs.

## Operational changes

***

How you change access depends on what you change: everyday operations or platform data.

### Use the management surfaces after bootstrap

After the environment starts, use Identity APIs or Lerian Console for operational access changes:

* create, update, or remove users
* assign users to groups
* create or delete machine-to-machine applications
* configure providers and MFA.

Bootstrap seed data is not a day-to-day configuration surface. Editing seed files after deployment does not reliably update an existing environment.

### Ship platform permission changes as controlled updates

Built-in resources, actions, roles, groups, and permission sets are platform data. Change them through migrations or an idempotent reconciler so existing environments converge predictably.

Avoid one-off database edits and manual permission changes. They create drift between environments and make access reviews harder to trust.

> [!TIP]
>
> See our [Security Recommendations](/en/products/midaz/security-recommendations) for more guidance on securing your infrastructure.


# How Access Manager works
Source: https://docs.lerian.studio/en/platform/access-manager/am-components

See how Access Manager's Auth, Identity, and product-level enforcement fit together to authenticate subjects and enforce permissions across products.

Access Manager has two services. Each protected Lerian product enforces access control at the route level through the Auth client. Identity provides the management. Together, they cover the three jobs of access control: managing access data, deciding access at runtime, and enforcing those decisions inside each product.

* **Auth** is the runtime decision layer. It issues tokens, verifies MFA, returns user information, and answers permission checks.
* **Identity** is the management layer. It stores users, groups, applications, communication providers, application-provider links, and MFA configuration.
* **Product-level enforcement** is the runtime integration inside protected products. When a product enables its Auth client and configures an Auth address, it calls Auth before product business logic runs. It is not a third Access Manager service.

For example, Identity creates a user and assigns the user to a product group. Auth issues the access token and answers permission checks for that token. A product configured for enforcement applies those decisions on its protected routes before the request reaches the product handler.

> **[Auth service](/en/platform/access-manager/auth-plugin)**
>
> Runtime tokens, MFA verification, user information, permission decisions, and cache.

> **[Identity service](/en/platform/access-manager/identity-plugin)**
>
> Management of users, groups, applications, communication providers, and MFA configuration.

> **[Product-level enforcement](/en/platform/access-manager/product-level-enforcement)**
>
> Route-level checks inside protected Lerian products that call Auth before business logic when their Auth client is enabled and configured.

> [!WARNING]
>
> Auth, Identity, and product-level enforcement do not replace each other. Identity defines access data, Auth makes authentication and authorization decisions, and products with their route-level integration enabled enforce those decisions at runtime.

For day-to-day usage, see [Using Access Manager](/en/platform/access-manager/using-access-manager) for the API workflow and [Access Manager via Lerian Console](/en/platform/access-manager/using-access-manager-with-midaz-console) for the visual flow.


# Access Manager lifecycle stages
Source: https://docs.lerian.studio/en/platform/access-manager/am-lifecycle-stages

The stages of an Access Manager deployment, from installing Auth and Identity to daily operation, and what changes hands at each one.

An Access Manager deployment moves through four stages: Install, Bootstrap, Enable, and Operate. Each stage has its own owner.

> [!NOTE]
>
> Turn enforcement on in a product only after Access Manager runs and reports healthy. A product that enforces access first rejects every protected request.

## Install

***

Deploy the two Access Manager services and connect them to their dependencies. Auth answers access decisions at runtime. Identity holds the users, groups, and applications behind those decisions.

Database schema changes run as a separate migration step. The services never change the schema when they start.

Confirm that both services report healthy and that your products can reach Auth over the network. The platform operator does this once per environment.

## Bootstrap

***

Bootstrap prepares a new environment before any product enforces access.

* **Bootstrap** seeds the base organization, roles, groups, applications, and permission sets that the platform relies on.

> [!WARNING]
>
> The identity backend starts with seeded administrator accounts. Change every seeded administrator password before you expose the deployment.

Bootstrap applies its seed data only during initial setup. After the environment starts, treat that data as read-only.

The platform operator owns this stage, and it runs once per environment.

## Enable

***

Enforcement is a per-product switch. You set the Auth variables in the `.env` file of each Lerian product or plugin where you want access enforced.

Most products and plugins ship with enforcement off and require you to turn it on for production. Streaming Hub rejects enforcement off in production. Check each Brazil rail's environment-variables page for its default.

> [!WARNING]
>
> With enforcement off and `AUTH_REQUIRED` unset, protected routes admit every request without a token. In the products that read `AUTH_REQUIRED`, set it to `true` to make those routes refuse with `503` when the Auth client is disabled or misconfigured. [Product-level enforcement](/en/platform/access-manager/product-level-enforcement) lists these products.

By default a machine-to-machine token acts as the product editor role. Set `AUTH_M2M_INVERSION_ENABLED=true` to use the application's own subject.

Variable names differ by product family. For the per-product table, read [Enabling Access Manager](/en/platform/access-manager/enabling-access-manager). The team that deploys each product repeats this stage once per product.

## Operate

***

Day-to-day work starts after the environment is up. It covers token requests, user and group management, MFA configuration, and calls to protected APIs. Use the Identity APIs or Lerian Console for these tasks.

Access tokens issued to the applications that Identity creates expire after one hour. Applications created outside Identity carry their own lifetime.

Administrators, end users, and integrations share this stage. It continues for the life of the deployment.

## Next steps

***

* [Installing Access Manager](/en/platform/access-manager/installing-access-manager)
* [Enabling Access Manager](/en/platform/access-manager/enabling-access-manager)
* [Using Access Manager](/en/platform/access-manager/using-access-manager)


# Auth service
Source: https://docs.lerian.studio/en/platform/access-manager/auth-plugin

The Auth service issues OAuth2/OIDC tokens, validates sessions, verifies permissions, and handles MFA challenges during user sign-in.

Auth is the runtime access service for Access Manager. It sits between your protected Lerian products and the configured identity provider. It gives products a single interface for token lifecycle, user information, permission checks, logout, and MFA login verification.

Use Auth when you need to:

* request access tokens for human users or machine-to-machine applications.
* refresh an expired access token.
* retrieve OIDC-compatible user information.
* validate whether a subject can perform an action on a resource.
* retrieve the permissions available to the authenticated user.
* end a user session.
* initiate and verify MFA challenges during login.

Auth delegates identity data to the identity provider and caches token, permission, and MFA-related data with Valkey to reduce repeated calls during normal operation.

## Main flows

***

Auth supports the access flows used by Lerian products and integrations.

![Conceptual authentication and authorization flow through the Auth plugin, including token issuance and permission checks](https://mintcdn.com/lerian-49cb71fc/SFzzdxyH5SN7w_fC/images/en/d2/am-auth-flow.svg?fit=max\&auto=format\&n=SFzzdxyH5SN7w_fC\&q=85\&s=dbd54982476146d65ae4e836f578ccfc)

Figure 1. Authentication and Authorization Flow

### Authentication flow

1. **Token request**
   * Human users authenticate with the `password` grant.
   * Service integrations authenticate with the `client_credentials` grant.
   * Auth forwards the request to the identity provider and returns the access token, refresh token, and ID token when applicable.
2. **Token refresh**
   * Clients exchange a refresh token for a new access token.
   * Auth validates the refresh token with the identity provider before issuing the new token.
3. **Token validation**
   * Protected products validate bearer tokens before accepting a request.
   * Auth extracts trusted token claims to identify the subject and tenant context.
   * Auth can cache validation results to reduce repeated identity-provider calls.

### Organization context

On Lerian Cloud, Auth takes the organization from the token. In a BYOC deployment, it uses the configured organization. The product that receives an authorized request owns its own data isolation.

### Browser SSO flow

1. **Start the flow**
   * The browser starts SSO through Auth with an email address, an eligible provider, and an S256 PKCE `code_challenge`. Auth resolves the tenant server-side from the email address and redirects the browser to the upstream identity provider.
2. **Handle the callback**
   * The identity provider redirects the browser to `PLUGIN_AUTH_SSO_CALLBACK_URL`. This absolute callback URL must be registered in the identity provider application's redirect-URI allowlist.
   * The Console submits the provider authorization code, the Auth state, and the matching PKCE `codeVerifier` through Auth's `sso_code` grant. Auth consumes the flow once, relays the code to the identity provider, and returns the token envelope.

Before issuing tokens, Auth verifies that the email returned by the identity provider resolves to the tenant that started the flow. Auth rejects the login if the email is absent or resolves to a different tenant. The rejection uses the same generic SSO failure as other refused relays.

Configure the tenant's OAuth provider and SSO policy through [Identity](/en/platform/access-manager/identity-plugin). The Auth callback URL must match the application's allowed redirect URI.

### MFA login flow

1. **Challenge required**
   * When MFA is required, Auth returns an MFA challenge state instead of completing the login immediately.
2. **Start challenge delivery**
   * For email MFA, the client submits the returned MFA token to request challenge delivery, and Auth sends the challenge code by email.
   * A TOTP application generates its passcode locally, without a delivery request.
3. **Challenge verification**
   * Auth verifies the challenge and returns access tokens when the verification succeeds.
4. **Session controls**
   * MFA challenges expire after the configured TTL.
   * Failed attempts are limited to protect the account from repeated guessing.

### Authorization flow

1. **Enforce access**
   * A protected product asks whether the authenticated subject can perform a specific action on a specific resource.
   * Auth evaluates the request against the configured Access Manager permissions.
   * Auth can cache successful authorization decisions for performance.
2. **Retrieve permissions**
   * A client can retrieve the permissions available to the authenticated user.
   * Auth returns permissions as a map of resources to allowed actions.

### User information flow

1. **Profile request**
   * The client requests user profile information with a bearer token.
   * Auth returns OIDC-compatible user information.

### Logout flow

1. **User logout**
   * The client sends a logout request with the ID token hint.
   * Auth invalidates the session in the identity provider.

## API overview

***

Auth exposes APIs for:

* requesting access tokens with `password` or `client_credentials`.
* refreshing access tokens.
* ending user sessions.
* validating user permissions.
* retrieving user information.
* retrieving user permissions.
* starting, completing, and discovering browser SSO flows.
* initiating an MFA challenge.
* verifying an MFA login challenge.

Auth exposes both credential-bearing entry points and protected operations. Follow the security requirements documented for each endpoint. For technical details on endpoints and usage, check the [Auth APIs](/en/reference/platform/access-manager/am-auth-apis) documentation.

## Permission decisions

***

When a protected product asks Auth whether a subject can perform an action on a resource, Auth resolves the subject (a human user or a machine-to-machine application), looks up the permissions associated with it, and returns an authorized or denied decision.

For human users, Auth evaluates permissions embedded in their identity data, including direct user permissions and applicable roles. For machine-to-machine applications, permissions come from the application's configured permission set. Auth evaluates the data Identity manages and does not invent permissions.

For the full subject/resource/action model, examples, and how routes are protected, see [Product-level enforcement](/en/platform/access-manager/product-level-enforcement). To inspect what the authenticated subject can reach, use [Retrieve User Permissions](/en/reference/platform/access-manager/retrieve-user-permissions).

## Data storage and caching

***

Auth uses structured policy data and cache entries to reduce repeated work:

* **Policy data** stores access-control rules for users, groups, and applications.
* **Token cache** stores token validation results.
* **Permission cache** stores successful authorization decisions.
* **User permissions cache** stores the map of resources and actions available to a user.
* **MFA cache** stores temporary challenge state and attempt counters.


# Caradhras in Access Manager
Source: https://docs.lerian.studio/en/platform/access-manager/caradhras-in-access-manager

See what the Auth and Identity services use Caradhras for, where the identity data lives, and which variables point Access Manager at it.

Access Manager keeps its identity data in Caradhras. Identity and Auth connect to the same backend, each for a different job.

## What each service uses it for

***

* **Identity** stores users, groups, applications, communication providers, application-provider links, and MFA configuration in the backend.
* **Auth** sits between your protected Lerian products and Caradhras. It forwards token requests to the backend and validates refresh tokens with it. It also reads the token claims that identify the subject and the tenant context.
* **Product-level enforcement** depends on the claims that Caradhras issues. A token is internal when it carries the `isInternal` claim with the value `true`. Caradhras issues that claim only for applications that the platform provisions as internal Lerian services.

Caradhras holds the access data. Identity writes it, Auth reads it to decide, and each protected product acts on the decision.

For example, Identity creates a user and puts that user in a product group. Auth then issues the access token and answers the permission checks that follow.

## Where the data lives

***

Caradhras persists this data in the PostgreSQL database that you configure for Access Manager. PostgreSQL backs Caradhras and does not replace it.

Schema changes run as a separate migration step, never when a service starts.

Both services reach the backend at the address you configure. The Access Manager Helm chart deploys the backend alongside the two services.

Valkey caches token, permission, and MFA-related data, so that Auth repeats fewer calls to the backend during normal operation.

## Tokens and keys

***

Access tokens issued to the applications that Identity creates expire after one hour. Applications created outside Identity carry their own lifetime.

`AUTHORIZER_JWT_CERTIFICATE` holds a public key. A fresh identity backend mints its own key pair on first start, and this variable tells Access Manager which public key to trust.

A configured but unusable value stops the service from starting.

## Configuration

***

These variables connect Access Manager to Caradhras.

* `AUTHORIZER_ADDRESS` gives the address of the identity backend. Outside `development`, `staging` and `local`, use an https address with a certificate from a public certificate authority. Read [Installing Access Manager](/en/platform/access-manager/installing-access-manager).
* `AUTHORIZER_JWT_CERTIFICATE` supplies the public key that validates the tokens the identity backend issues. Read the [Access Manager chart README](https://github.com/LerianStudio/helm/tree/main/charts/plugin-access-manager).
* `PLUGIN_AUTH_SSO_STATIC_ORGANIZATION` pins pre-login SSO to one Caradhras organization. Read [Identity service](/en/platform/access-manager/identity-plugin).
* `PLATFORM_INTERNAL_CIDRS` declares the networks that platform services call Caradhras from. When a tenant IP allowlist is active, Auth can deny platform requests from networks not listed here. Caradhras reads its own `PLATFORM_INTERNAL_CIDRS`. Set it to the same value. Read [Tenant IP allowlist](/en/platform/access-manager/product-level-enforcement#tenant-ip-allowlist).


# Identity service
Source: https://docs.lerian.studio/en/platform/access-manager/identity-plugin

The Identity service manages users, groups, roles, applications, providers, SSO configuration, and MFA configuration for Access Manager deployments.

Identity is the management service for Access Manager. It's where administrators define who can access Lerian products: which groups and roles people belong to, which applications can authenticate with machine-to-machine credentials, and which communication or OAuth providers are available.

Identity does not issue access tokens or make runtime authorization decisions. Auth uses the identity data managed here to authenticate subjects and evaluate permissions.

Use Identity when you need to:

* create, update, list, or delete users.
* assign users to product groups or direct permissions.
* create, update, list, or delete groups and inspect their permissions.
* create, update, list, or delete tenant-scoped custom roles and assign their permissions, users, and groups.
* create, list, retrieve, or delete machine-to-machine applications.
* create, update, list, retrieve, or delete communication providers.
* link providers to applications and select the default provider.
* configure the tenant's SSO policy and active OAuth provider.
* initiate, verify, enable, disable, review, or change MFA settings for users.
* reset or update user passwords.

## Users and groups

***

Identity manages human access through users, groups, and direct user permissions. A group represents a permission set for a product or Access Manager area.

For example, you can assign a user to a Midaz viewer group to inspect ledger data without changing it. You can also assign that user to a Reporter contributor group to create report templates. A user can also receive a direct permission without belonging to a group for that product.

Identity exposes user endpoints to list users, create users, retrieve a user, update user information, manage group assignments and direct permissions, delete users, update passwords, and reset passwords. User and group list endpoints use `page` and `limit` for pagination.

On Lerian Cloud, the service returns only the users and groups that belong to your tenant.

When you create or update a user, send the group IDs returned by [List Groups](/en/reference/platform/access-manager/list-groups). The API handles the internal organization prefixing. Clients should not build `organization/group` values manually.

> [!WARNING]
>
> Do not send tenant ownership in user payloads. Identity derives the tenant scope from the bearer token, then applies the requested user and group changes inside that tenant.

### Roles

Access Manager uses role levels as a common convention across products. The effective actions for each role come from the product or application permission set. Identity also supports custom roles scoped to the tenant.

| Role | Typical access |
| - | - |
| Admin | Full access, including administrative operations. |
| Editor | Can read, create, update, and delete resources. |
| Contributor | Typically can read, create, and update resources. Delete access depends on the product permission set. |
| Viewer | Read-only access. |

> [!WARNING]
>
> Role scope is per product or application. A user can be an Editor in Midaz, a Viewer in Reporter, and have no access to Fees.

Access Manager supplies the platform permission catalog. You can create, update, and delete tenant-scoped groups, then use [List Groups](/en/reference/platform/access-manager/list-groups) and [Retrieve Group Details](/en/reference/platform/access-manager/retrieve-group-details) to inspect the groups available in your environment. Identity deletes a group only when it has no members and no subgroups. Otherwise it returns `409` with code `IDE-1058` or `IDE-1059`. Group assignments are one way to grant access. Identity also supports direct user-permission assignment.

You can create custom roles and assign permissions, users, and groups to them. Built-in system roles are immutable: Identity rejects attempts to create, update, or delete them. Use custom roles when the standard role levels do not express the access model you need.

> [!WARNING]
>
> A user without a group for a product can still have access through direct user permissions. Check the user's effective permissions before concluding that they cannot access a product.

For the resource-action model, the action vocabularies used by each product, and how routes are protected at runtime, see [Product-level enforcement](/en/platform/access-manager/product-level-enforcement). For the API workflow that ties users, groups, and tokens together, see [Using Access Manager](/en/platform/access-manager/using-access-manager).

## Applications

***

Applications represent machine-to-machine clients for the `client_credentials` grant. Use them when a service, job, or integration needs to authenticate without a human user.

An application stores the `clientId` and `clientSecret` used by Auth during the `client_credentials` flow. Identity returns the `clientSecret` only in the response to the create request. If you lose the secret, delete the application and create a new one. After creating an application, the integration can request an access token from Auth and call protected Lerian APIs according to its configured permissions.

Identity supports:

* listing applications.
* creating applications.
* retrieving application details.
* deleting applications.

For example, a reconciliation job can use a Bank Transfer application to request a token and call only the endpoints needed for its workflow.

Identity accepts only application names from its catalog when it creates or deletes applications. Application names are product identifiers, such as `midaz` or `reporter`, not UI display labels. [List Available Applications](/en/reference/platform/access-manager/list-available-applications) returns the catalog.

> [!NOTE]
>
> Identity filters internal applications from the public application list. On Lerian Cloud, it also returns only applications of your tenant.

### Tenant scoping

On Lerian Cloud, Identity uses the authenticated context as the tenant boundary for management operations:

* user operations apply to the caller's tenant organization.
* group lists include only permission groups available in that tenant.
* application lists include only machine-to-machine applications bound to that tenant.
* application credentials created for an integration belong to the tenant that created them.

This keeps operational access local to the tenant. An administrator token from one tenant cannot list or mutate another tenant's users, groups, or applications through the public Identity APIs.

## Communication providers

***

Communication providers define delivery services available to applications. Email providers can deliver MFA challenges. Identity manages providers separately from applications so you can reuse and control the same provider consistently.

Identity supports:

* listing providers.
* creating providers.
* retrieving provider details.
* updating providers.
* deleting providers.

Identity also supports application-provider links:

* list providers linked to an application.
* link a provider to an application.
* update a provider link.
* unlink a provider from an application.
* set the default provider for an application.

Use a default provider when an application has more than one linked provider and needs a preferred one.

For SSO, Identity manages one active OAuth provider per tenant. Supported provider types are Google, `AzureAD` (Microsoft Entra ID), Okta, and Custom. The Auth SSO callback URL must be an absolute URL and appear in the application's redirect-URI allowlist, or the authorization-code relay will fail.

Before saving a candidate SSO provider, run its preflight validation. It checks the configuration, OIDC endpoint discovery, client credentials, and the callback redirect URI without creating or changing a provider, application-provider link, or application. The validation result reports a failed check. A malformed or unauthorized request returns an HTTP error.

For a BYOC deployment with one fixed Caradhras organization, set `PLUGIN_AUTH_SSO_STATIC_ORGANIZATION` in Auth. Pre-login SSO then resolves every request to that organization instead of looking up an organization from the user's email.

## MFA management

***

Identity manages MFA configuration for users. Auth uses that configuration during login when MFA is required.

Identity supports:

* initiating MFA setup.
* verifying an MFA passcode during setup.
* enabling MFA after verification.
* disabling MFA.
* retrieving the current MFA status.
* setting the preferred MFA method.

MFA supports an authenticator app or email. Email MFA requires an email provider and a saved email address for the user.

The standard MFA setup and management operations are self-service: the caller's token subject must match the target user. Administrative MFA operations are separate and apply only to the methods supported by those operations.

## Architecture and identity flow

***

![Identity architecture showing how the identity plugin manages user profiles and MFA methods across the authentication flow](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/identity-flow.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=ba2b5eb1102760d9938fa4babab656da)

Figure 1. Identity Flow

1. **Management request**
   * An administrator or authorized client calls an Identity API.
   * When Identity's Auth client is enabled and configured, the request is authenticated and checked against Access Manager permissions. Set `AUTH_REQUIRED=true` when the deployment must refuse management requests if that client is disabled or misconfigured.
2. **Request processing**
   * Identity validates the payload and applies the requested operation.
   * The service updates users, groups, roles, applications, providers, provider links, SSO configuration, or MFA configuration in the configured identity system.
3. **Runtime use**
   * Auth reads the resulting identity data during token, permission, and MFA flows.
   * Protected Lerian products rely on Auth decisions before processing product operations.

## API overview

***

Identity exposes APIs for:

* users.
* groups.
* custom roles and their assignments.
* applications.
* providers.
* application-provider links.
* SSO policy and OAuth-provider configuration.
* MFA setup and management.
* tenant IP allowlist configuration.
* self-service profile and phone management.
* password reset and password update flows.

When its Auth client is enabled and configured, Identity protects management access through Access Manager permissions. For technical details, check the [Identity APIs](/en/reference/platform/access-manager/am-identity-apis) documentation.


# Product-level enforcement
Source: https://docs.lerian.studio/en/platform/access-manager/product-level-enforcement

Understand how protected Lerian products enforce Access Manager decisions at the route level by calling Auth before business logic runs.

Product-level enforcement is the runtime integration inside each protected Lerian product. It is not a third Access Manager service. A product with its Auth client enabled and an Auth address calls Auth from its route-level code. The route-level code then lets the request continue or rejects it before the product handler runs.

Identity defines the access data. Auth decides whether a subject can perform an action on a resource. Product-level enforcement applies those decisions to live traffic.

## What it does

***

For each request on a route with enforcement configured, the product:

* reads the bearer token from the `Authorization` header.
* builds a permission check with the subject derived from token claims, the `resource` configured for the route, and the `action` configured for the route.
* sends that check to Auth.
* continues with the product handler when Auth returns an authorized decision.
* rejects the request with the appropriate HTTP or gRPC error when Auth denies it.
* uses token claims according to the product's own tenant-aware integration when required.

> [!WARNING]
>
> You configure route protection separately in each product. Enable each product's Auth client and set an Auth address. Midaz, Matcher, Reporter, Streaming Hub, Pix Lerian, and Pix Indirect BTG read `AUTH_REQUIRED`: set it to `true` to make protected routes refuse with `503` if the Auth client is disabled or misconfigured. Without it, the middleware passes the request through by default. In Access Manager, `PLUGIN_AUTH_ENABLED` configures Identity's Auth client only. It does not enable enforcement in other Lerian products.

For example, a Midaz route can protect `POST /transactions` with the resource `transactions` and action `post`. Auth decides whether the subject in the bearer token has that permission.

> [!WARNING]
>
> Product-level enforcement does not manage users, issue tokens, or store policy data. It calls Auth and acts on the response.

## Permission model

***

Access Manager evaluates the core permission decision with three values:

| Value | Meaning |
| - | - |
| Subject | The authenticated user, the machine-to-machine application, or the derived `admin/<product>-editor-role` subject in legacy M2M mode. |
| Resource | The protected area of a product, such as `users`, `applications`, `accounts`, `reports`, or `templates`. |
| Action | The operation being requested, such as `get`, `post`, `patch`, `delete`, `read`, or `write`. |

Human authorization evaluates permissions embedded in identity data. Groups can organize permissions, and users can also receive direct user permissions.

For a normal user token, the middleware derives the subject from its `owner` and `sub` claims. Unless the product configures local JWT verification, the middleware parses those claims without signature verification. The authorization round trip to Auth is the trust anchor. Machine-to-machine authorization depends on `AUTH_M2M_INVERSION_ENABLED`. With its default value of `false`, the middleware derives a product-scoped `admin/<product>-editor-role` subject for any non-user token type and does not consult that token's `sub`. With `true`, it uses the application's token `sub` identity and rejects unknown token types.

### Tenant IP allowlist

For the guide to this feature, read [IP allowlist](/en/platform/access-manager/features/ip-allowlist/overview).

Identity stores each tenant's IP allowlist and the surfaces where it applies. A non-empty list applies only on explicitly selected scopes: `console` for human traffic and `api` for machine traffic. With no selected scope, the list remains stored but is inert.

Configure `TRUSTED_PROXIES` in Auth and in each product process listed in [Deployment requirements (BYOC)](/en/platform/access-manager/features/ip-allowlist/deployment). Each process must use the CIDRs of the load balancer or ingress that fronts it. The product resolves the client IP and sends it to Auth as `clientIp`.

The gate runs before Auth's permission cache. Tokens marked as internal bypass it. An empty list does not enforce the gate.

A token is internal when it carries the `isInternal` claim with the value `true`. Caradhras issues that claim only for applications that the platform provisions as internal Lerian services. The client-facing application API cannot set it. The bypass skips only the allowlist gate. Auth still validates the token against Caradhras before it authorizes the request, so a forged internal marker on an invalid token does not grant access.

> [!WARNING]
>
> If Caradhras is unavailable and Auth has a cached policy, Auth serves the last-known-good policy and can still deny. A lookup with no cached policy fails open. An unset `TRUSTED_PROXIES` in Auth also fails open and emits the untrusted-proxy signal. Auth denies a request with a missing client IP when a non-empty list applies. The exception is a request whose transport peer is in `PLATFORM_INTERNAL_CIDRS`. Auth allows that platform-internal forwarding failure, and you must monitor it.

In deployments where platform services call Caradhras from cluster networks, configure the same `PLATFORM_INTERNAL_CIDRS` value in Identity, Auth, and Caradhras with those CIDRs. Each entry must include an explicit prefix. A catch-all prefix is rejected at boot because it would trust every caller and remove every tenant entry from enforcement. Caradhras admits platform callers from its own copy of the value. Auth subtracts them from the tenant policy before enforcement.

### Resource and action names

They must match the values configured for the product route, and the route sends those configured values to Auth.

Most API products use HTTP-method-style actions:

| Example | Meaning |
| - | - |
| `users:get` | Read users. |
| `applications:post` | Create machine-to-machine applications. |
| `reports:patch` | Update reports. |
| `templates:delete` | Delete report templates. |

Some products use semantic actions when an HTTP method does not describe the route well:

| Example | Meaning |
| - | - |
| `transfers:create` | Create a Bank Transfer transfer. |
| `transfers:process` | Process a Bank Transfer transfer. |
| `system_config:read` | Read Bank Transfer system configuration. |
| `workflows:activate` | Activate a Flowker workflow. |

Use [Retrieve User Permissions](/en/reference/platform/access-manager/retrieve-user-permissions) to inspect the effective resources and actions available to the authenticated user.

> [!WARNING]
>
> Do not derive permission strings from endpoint paths by convention. Protected products enforce the resource and action values configured in Access Manager, not values inferred from the URL.

## Request flow

***

1. **Receive the request**
   * The product reads the bearer token from the `Authorization` header.
   * If the token is absent or malformed, the product rejects the request before any permission check.
2. **Build the permission check**
   * The product uses the resource and action configured for the route.
   * In tenant-aware deployments, the product applies its own configured tenant integration. Do not infer a universal `tenantId`-only authorization contract from this route-level flow.
3. **Ask Auth**
   * The product calls Auth with the subject, resource, and action. Depending on its integration, it can also forward product and client-IP context.
   * Auth evaluates the request against the configured Access Manager permissions and may serve the answer from cache.
4. **Apply the decision**
   * On authorized, the product continues to its handler.
   * On denied, the product returns the appropriate HTTP or gRPC error and does not invoke business logic.

## Where this fits

***

When a product configures route-level enforcement, it sits between the network and the product handler. With an enabled and configured Auth client, Auth evaluates authorization before the handler runs. An authorized subject still needs the right resource-action permission to reach a specific operation. A tenant IP allowlist active for that request's scope can still deny it. Auth can serve authorization decisions from cache.

On the management side of this picture, see the [Identity service](/en/platform/access-manager/identity-plugin). The [Auth service](/en/platform/access-manager/auth-plugin) handles the runtime decision side. For the day-to-day workflow against the APIs, see [Using Access Manager](/en/platform/access-manager/using-access-manager).


# Access Manager via Lerian Console
Source: https://docs.lerian.studio/en/platform/access-manager/using-access-manager-with-midaz-console

Manage supported Access Manager operations visually through Lerian Console: users, groups, machine-to-machine applications, and permission assignments.

Lerian Console offers a visual interface for the access tasks most administrators handle day to day. From Lerian Console you can create and manage users, assign permission groups, and set up machine-to-machine applications without touching the Identity APIs.

> [!TIP]
>
> If you need the full API surface, including providers, application-provider links, token flows, or explicit permission checks, use the [Using Access Manager](/en/platform/access-manager/using-access-manager) guide.

## Prerequisites

***

Before using Access Manager features in Lerian Console, make sure you have:

* Access Manager plugin installed and running
* Access Manager [enabled in your environment configuration](/en/platform/access-manager/enabling-access-manager)
* Admin credentials to log into Lerian Console

> [!CAUTION]
>
> After you enable Access Manager, protected API requests must include an `Authorization` header with a valid Bearer access token.
>
> Without this header, protected requests will be rejected, even for endpoints that were previously accessible without authentication.

## Where the Access Manager screens live

***

Lerian Console holds the Access Manager screens in two areas. Settings holds Applications and Security. Authorization holds Users, Roles, Groups, and Permissions, with its own sidebar.

**Step 1**

Log into Lerian Console with your admin credentials.

**Step 2**

Click the gear icon () in the top navigation bar.

**Step 3**

Select **Applications** or **Security** to open Settings. Select **Authorization** to open the Authorization area.

## What you can do

***

> **[Managing Users](/en/platform/console/managing-users)**
>
> Create, edit, and delete user accounts. Manage passwords and assign users to permission groups for human access.

> **[Managing Applications](/en/platform/console/managing-applications)**
>
> Create and review machine-to-machine applications for service integrations. Use generated client credentials for secure service communication.

## What still uses APIs

***

Console covers the common cases. For anything the Console does not cover, use the [Identity APIs](/en/reference/platform/access-manager/am-identity-apis) and [Auth APIs](/en/reference/platform/access-manager/am-auth-apis):

| Area | Use APIs for |
| - | - |
| Providers | Create, update, delete, link, unlink, and set default communication providers for MFA delivery. |
| Token flows | Request tokens, refresh tokens, retrieve user information, and end sessions. |
| Permission checks | Validate a resource-action decision or retrieve the authenticated user's effective permissions. |

> [!NOTE]
>
> Users enroll and manage their own multi-factor authentication methods in the Console, under Settings › Security.

> [!NOTE]
>
> On Lerian Cloud, Console follows the same tenant boundary as the APIs. The logged-in administrator only sees and manages users and applications in their own tenant.

> [!NOTE]
>
> You cannot delete your own user. Another administrator with the delete permission on users can delete a seeded administrator account. A later run of the install step can recreate it with its default password. Change that password before exposing the deployment. Make sure another administrator exists before removing one. You can update its details through the Console.

## Next steps

***

* Learn about [best practices for Access Manager](/en/platform/access-manager/am-best-practices)
* Understand the [technical components](/en/platform/access-manager/am-components) of Access Manager
* Review [API reference](/en/reference/platform/access-manager/am-api-introduction) for programmatic access


# What is Caradhras?
Source: https://docs.lerian.studio/en/platform/access-manager/what-is-caradhras

Caradhras is the identity provider behind Access Manager. It manages users, organizations, and applications, and supports the standard identity protocols.

Caradhras is the identity provider that Access Manager runs on. It is a self-hostable identity and access-management server.

Caradhras holds the objects behind every access decision:

* **Organizations**, the boundary that owns every other object.
* **Users**, the people who sign in.
* **Groups** and **roles**, the two ways to collect subjects.
* **Permissions**, which pair a resource with an action.
* **Applications**, the OAuth clients that machine-to-machine callers use.
* **Certificates**, the key material behind token signatures.

You manage that data through the Identity APIs or Lerian Console.

## Protocols

***

Caradhras supports these protocols and authentication methods:

* OAuth 2.0 and OIDC
* SAML 2.0
* CAS
* SCIM 2.0 for user provisioning
* LDAP: authenticates users against an external directory. Caradhras does not run a directory.
* WebAuthn and passkeys
* TOTP and MFA

## Authorization model

***

Caradhras expresses authorization with Casbin, which supports ACL, RBAC, and ABAC models.

A permission names a resource and an action. Access Manager evaluates that pair against the subject in the token before a product handler runs.

Subjects nest. A group can belong to a parent group. A role can include other roles.

## Your identity provider

***

Your identity provider connects to Caradhras as an upstream provider over OAuth 2.0 and OIDC, SAML 2.0, or LDAP. OIDC providers include Google, Microsoft Entra ID, Okta, or a custom OIDC provider. Your provider does not replace Caradhras.

Your users then authenticate at your provider. Access Manager still reads their identity data from Caradhras, and it still decides what they can reach.

## How it ships

***

Caradhras is part of the Access Manager deployment. You do not install it as a separate product. The [Access Manager Helm chart](https://github.com/LerianStudio/helm/tree/main/charts/plugin-access-manager) deploys Caradhras as the identity backend, and the Auth and Identity services call it.

Caradhras persists its identity data in the PostgreSQL database that you configure for Access Manager.

To see what each Access Manager service uses the backend for, read [Caradhras in Access Manager](/en/platform/access-manager/caradhras-in-access-manager).


# What is Lerian Console?
Source: https://docs.lerian.studio/en/platform/console/about-lerian-console

Manage and operate Lerian products from a single web interface with unified authentication, navigation, and product administration.

The **Lerian Console** is the single web interface for managing and operating Lerian products. You configure, monitor, and administer them from one place.

The Console centralizes navigation, authentication, and product management.

> [!NOTE]
>
> The Console is part of the **Enterprise plan**. It isn't sold separately. See [how Lerian is packaged](/en/products/products-and-plugins) or [talk to our team](https://lerian.studio/contact) for details.

## Architecture

***

The Console has two layers:

* **Platform layer**. Shared capabilities that apply across all products: centralized authentication, product catalog, global navigation, and language and theme preferences.
* **Product layer**. Each Lerian product integrates as an independent module with its own navigation, workflows, and product-specific settings, while sharing the same design patterns.

## Key capabilities

***

* **Single sign-on**: Log in once and access all enabled products without re-authenticating.
* **Role-based access**: Control who can access which products and features based on roles and permissions.
* **Product management**: Enable, disable, and configure products from a central dashboard.
* **Unified experience**: Navigate between products with consistent UI patterns.

## Who uses the Console

***

| Role | Primary activities |
| - | - |
| **Platform administrators** | Enable/disable products, manage users and roles, configure global settings |
| **Product operators** | Access enabled products, perform day-to-day operations, configure product-specific settings |

## Console modules

***

These products have a module in Lerian Console:

> **[Midaz](/en/products/midaz/console/midaz-module)**
>
> Core ledger management: organizations, ledgers, accounts, assets, accounting, and transactions.

> **[Reporter](/en/products/reporter/console/managing-reports)**
>
> Report generation, template management, and regulatory filing for financial and operational data.

> **[Flowker](/en/products/flowker/console/flowker-module)**
>
> Design visual workflows, configure provider integrations, run automated processes, and monitor executions through the Flowker module.

> **[Tracer](/en/products/tracer/console/tracer-module)**
>
> Configure real-time fraud detection rules, set spending limits, and review transaction validations.

> **[Streaming Hub](/en/platform/streaming-hub/streaming-hub-in-lerian-console)**
>
> Browse the event catalog, create webhook and pull subscriptions, and follow delivery on the dashboard.

> **[Matcher](/en/products/matcher/ui/matcher-module)**
>
> Configure reconciliation contexts and rules, run reconciliations, and resolve exceptions and disputes.

## Product versions

***

Some Console screens need a minimum version of the product behind them. The Console reads the version that each product reports. When a product runs an earlier version, a notice replaces the part of the screen that needs that version. The notice names the product and the version, for example *Requires Bank Transfer 3.1.0 or later*. When the Console cannot read the version, it opens the screen.

| Screen | Needs |
| :- | :- |
| The **Ledger activity** section of the Midaz home page | Midaz 4.1.0 or later |
| The Tracer **Dashboard**. With an earlier Tracer, the module opens on a cover page instead. | Tracer 4.1.0 or later |
| The Bank Transfer **Transfers** list, the **Recent Transfers** card, and the transfer detail page | Bank Transfer 3.1.0 or later |
| The **Environments** page | Access Manager 3.11.0 or later |
| In **Settings > Partners**: creating a partner, the **Permissions** and **Scope** tabs of a partner, and creating a partner application | Access Manager 3.11.0 or later |


# About settings
Source: https://docs.lerian.studio/en/platform/console/about-settings

What the Settings area of Lerian Console contains, which sections need Access Manager, and where user and permission management lives.

Open Settings with the gear icon () in the top navigation bar.

## Sections

***

> **[Applications](/en/platform/console/managing-applications)**
>
> The Access Manager applications that authenticate external systems. Create them, view their details, and delete them.

> **[Partners](/en/platform/access-manager/features/partners/console)**
>
> Your own customers that call your platform from their own systems. Create them, choose what each one can reach, and create their applications.

> **[Authorization](/en/platform/console/managing-users)**
>
> Users, roles, groups, and permissions, in an area with its own sidebar.

> **[Security](/en/platform/access-manager/features/ip-allowlist/console)**
>
> Your own multi-factor authentication, plus the single sign-on providers and the IP allowlist when your permissions include them.

> **[Products](/en/platform/console/settings-products)**
>
> Turn Lerian products on or off for your tenant.

> **[System](/en/platform/console/settings-system)**
>
> System preferences, such as the interface language and the theme.

> **[Notification Layer](/en/platform/console/notification-layer)**
>
> Notification delivery by email, SMS, and webhook, in an area with its own sidebar.

## What each section needs

***

Applications, Partners, Authorization, and Security need Access Manager. The Partners entry disappears when [`NEXT_PUBLIC_PARTNERS_ENABLED`](/en/platform/console/console-environment-variables) is `false`. When your account lacks the read permission on applications, the Console hides the Applications entry in the Settings sidebar. It does not show an error. Without the read permission on roles, it also hides the Authorization entry.

Security always appears. Its **MFA** tab is open to every signed-in user. The **Single Sign-On** tab needs the read permission on providers. The **IP allowlist** tab needs the read permission on security. Products and System open without Access Manager and without a permission. With Access Manager, the **Notification Layer** entry needs the read permission on notifications.

## Where users live

***

User, role, group, and permission management lives in a separate area called Authorization, with its own sidebar. Open it from the **Authorization** entry in the Settings sidebar, or from the gear menu in the top bar.

> **[Managing users](/en/platform/console/managing-users)**
>
> Create, edit, and delete user accounts, reset passwords, and read how groups, roles, and permissions give a user access.


# Console environment variables
Source: https://docs.lerian.studio/en/platform/console/console-environment-variables

The environment variables that connect Lerian Console to Midaz, Tracer, and Access Manager, and the ones that switch Console screens on or off.

Console reads these variables when its container starts. After you change one, restart the Console container. You do not need to rebuild the image.

To install or upgrade Console, see the [Console chart README](https://github.com/LerianStudio/helm/tree/main/charts/product-console).

## Product addresses

| Variable | Required | What it does |
| :- | :- | :- |
| `MIDAZ_V2_BASE_PATH` | Yes | The address of the Ledger `/v2` API, ending in `/v2/`. Console reads Fees, Holders, and Alias Accounts from it. Without it, these pages fail. |
| `TRACER_BASE_PATH` | Only with Tracer | The address of the Tracer service, without `/v1`. |

## Secrets

Keep `NEXTAUTH_SECRET`, `MONGODB_PASS`, and `PLUGIN_AUTH_CLIENT_SECRET` in your secret vault. Never put them in a file in your repository or in an image.

## Screens

| Variable | What it controls |
| :- | :- |
| `NEXT_PUBLIC_MIDAZ_CONSOLE_AVATAR_ALLOWED_FORMAT` | The image formats accepted for avatars, separated by commas, for example `jpeg,jpg,png`. |
| `NEXT_PUBLIC_PARTNERS_ENABLED` | The **Partners** entry of Settings and the **Partners** card on the home page. They are on unless the value is `false`. |
| `NEXT_PUBLIC_BANK_TRANSFER_ENABLED` | The Bank Transfer screens of the Midaz module. They are off unless the value is `true`. |


# Environments
Source: https://docs.lerian.studio/en/platform/console/environments

See the environments where you have an account in Lerian Console, and choose your default environment.

The **Environments** page lists the environments where you have an account. Use it to choose your default environment. When you have an account in more than one environment, you sign in to your default environment.

The page needs Access Manager 3.11.0 or later. With an earlier version, a version notice replaces the list. See [Product versions](/en/platform/console/about-lerian-console#product-versions).

## Accessing the Environments page

***

In the top navigation bar, click the name of your current environment. On a narrow screen, open your profile menu and select the environment name.

If the Console cannot read your environments, the navigation bar shows no environment name.

## Your environments

***

The **Your environments** table has one row for each environment:

* **Environment name**: the name of the environment.
* **Environment status**: the **Default** badge marks your default environment. The **Current** badge marks the environment that you use now. An **SSO** badge marks an environment that has single sign-on turned on.

## Changing your default environment

***

**1. Click Make default**

On the row of the environment that you want, click **Make default**. Your default environment has no **Make default** button.

**2. Confirm the change**

In the dialog, click **Make default and sign out**. Make default signs you out.

If the change fails, the Console shows an error message and keeps the dialog open, so you can try again.


# Managing Applications
Source: https://docs.lerian.studio/en/platform/console/managing-applications

Create, inspect, and delete the Access Manager applications that authenticate external systems, from the Applications page of Lerian Console.

An application is an OAuth client: an external system or service that connects to your API through authentication with an identity provider. Each application has its own credentials (client ID and secret) that authorize and authenticate access to the APIs.

On Lerian Cloud, the list shows only the applications of the logged-in administrator's tenant. Console does not expose applications from other tenants.

## The Applications page

***

Click the gear icon () in the top navigation bar, then select **Applications**. The section needs Access Manager and the read permission on applications. Without that permission, Applications does not appear in the Settings sidebar.

The table has five columns:

| Column | What it shows |
| - | - |
| **Name** | The application identifier. |
| **Description** | The description of the application. A dash (—) shows when it has none. |
| **ClientId** | The client identifier for authentication. |
| **Creation Date** | The date on which someone created the application. |
| **Actions** | The row menu, which opens the details panel or deletes the application. |

The default Lerian application is protected: its row shows a lock instead of the actions menu, so you cannot view or delete it here.

The footer gives the number of applications in the list. The list does not paginate.

A **Security Warning** banner stands above the table. It asks you to:

* Keep the client ID and the client secret confidential.
* Store the keys in a secure location.
* Delete an application only when you are sure.
* Rotate the credentials when you suspect a compromise.
* Keep the keys out of frontend code and public repositories.

## Create an application

***

**1. Open the form**

Click **New Application**. The form opens on the right side of the screen.

**2. Choose the application name**

Pick a name in the **Application Name** list. The list comes from the platform. You cannot type a name that is not on it.

**3. Describe the application**

Write a short **Description** of what the application does.

**4. Save**

Click **Save**. This step needs the create permission on applications. The Console answers with the message "Application successfully created".

The new application appears in the list.

The Console shows the client secret once, when you create the application. Store it then. If you lose it, delete the application and create a new one.

## View an application

***

Find the application, open the menu in the **Actions** column, and select **Details**. The **Application Details** panel opens on the right side of the screen with three read-only fields: **Name**, **Description**, and **ClientId**. A copy button sits next to the **ClientId**, in the panel and in the table.

> [!NOTE]
>
> Application details cannot be edited. To change one, delete it and create it again.

## Delete an application

***

> [!WARNING]
>
> Deleting an application **revokes access to all connected services.** It is irreversible and permanently removes the application.

**1. Open the row menu**

Find the application, open the menu in the **Actions** column, and select **Delete**.

**2. Confirm**

A dialog asks "Are you sure you want to delete?". Click **Yes, delete it**. To stop, click **I changed my mind**.

The Console answers with the message "Application successfully deleted".

## What the Console does not expose

***

To set up single sign-on providers, open **Settings** › **Security** › **Single Sign-On**. Use the Identity APIs for other application settings that Console does not expose.


# Managing Users
Source: https://docs.lerian.studio/en/platform/console/managing-users

Create, edit, reset the password of, and delete user accounts, and manage roles, groups, and permissions in the Authorization area of Lerian Console.

Users live in the Authorization area of Lerian Console, next to Roles, Groups, and Permissions. Open Authorization from the **Authorization** entry in the Settings sidebar, or from the gear menu in the top bar.

Roles and permissions control what each user can do.

The Users page needs Access Manager and the read permission on users. Without that permission, the Console shows a not-authorized page instead of the list.

On Lerian Cloud, the list shows only the users of the logged-in administrator's tenant. Console does not expose users from other tenants.

## The Users page

***

The table has six columns:

| Column | What it shows |
| - | - |
| **Name** | The full name of the user, with the user identifier below it. |
| **E-mail** | The e-mail address of the user. |
| **Username** | The login identifier. |
| **Groups** | The first group of the user, and a `+N` badge that lists the rest. |
| **MFA** | The multi-factor authentication status of the user. |
| **Actions** | The row menu. |

You choose which columns the table shows. The list paginates, and the footer gives the range on screen and the total.

The row menu holds three items: **View Details**, **Edit**, and **Delete**. The Console shows **Edit** only to an account with the update permission on users. It shows **Delete** only to an account with the delete permission on users.

## Create a user

***

**1. Open the form**

Click **New User**. The form opens on the right side of the screen.

**2. Fill in the fields**

The form asks for **Name**, **Last Name**, **Username**, **E-mail**, **Password**, **Confirm Password**, and **Groups**.

**3. Save**

Click **Save**. This step needs the create permission on users. The new user appears in the list.

The Console applies these rules:

* **Name** and **Last Name** are required, and **Username** holds at least 3 characters.
* **Username** accepts letters, numbers, hyphens, and underscores.
* **E-mail** holds a valid address.
* **Password** holds at least 12 characters, with one uppercase letter, one lowercase letter, one number, and one special character.
* **Password** rejects two identical characters next to each other, so `aa` and `11` both fail.
* **Groups** accepts one or more groups. At least one is required.

> [!NOTE]
>
> The Console checks these rules before it submits the form. The identity backend can apply further rules.

## Edit a user

***

**1. Open the row menu**

Find the user, open the menu in the **Actions** column, and select **Edit**.

**2. Change the fields**

The panel has two tabs: **Personal Information** and **Password**. On the **Personal Information** tab you change the **Name**, the **Last Name**, the **E-mail**, and the **Groups**. The tab holds no username field, so a user keeps the username they got at creation.

**3. Save**

Click **Save**.

## Reset a user's password

***

**1. Open the Password tab**

Select **Edit** in the row menu, then open the **Password** tab.

**2. Type the new password**

Fill in **New Password** and **Confirm Password**. The new password follows the rules in [Create a user](#create-a-user).

**3. Save and confirm**

Click **Save**. A dialog titled "Password Change" opens. Click **Yes, change password**.

> [!NOTE]
>
> This is an administrator reset. It asks for no current password and sets no temporary password. The user signs in with the new one next time.

> [!NOTE]
>
> To manage your own multi-factor authentication, use **Settings** › **Security**. To reset your own password, use **Forgot my password?** on the sign-in page. The link appears when the deployment sets `ENABLE_FORGOT_PASSWORD` to `true`.

## Delete a user

***

> [!WARNING]
>
> Deleting a user **permanently removes the account.** This action cannot be undone.

Find the user, open the menu in the **Actions** column, and select **Delete**. A dialog titled "Confirm Deletion" states: "You are about to permanently delete this user. This action cannot be undone. Do you wish to continue?" The Console then answers with the message "User successfully deleted".

The Console does not offer **Delete** on your own account.

## Roles, groups, and permissions

***

The Authorization sidebar has five entries: Overview, Users, Roles, Groups, and Permissions.

A permission names a resource and an action. You grant it to a role, or directly to a user. A user gets a role directly or through a group.

**View Details** in the row menu opens a page for one user. That page has six tabs: **Effective Access**, **Roles**, **Groups**, **Direct Permissions**, **Profile**, and **Security**.

## The Roles page

***

The Roles table has six columns: **Name**, **Type**, **Users**, **Groups**, **Status**, and **Actions**. **Type** shows **System** or **Custom**. **Status** shows **Enabled** or **Disabled**.

The platform manages the system roles. A system role has no row menu. Its **Actions** cell reads "This role is managed by the platform and is not editable from the console".

The row menu of a custom role holds **View Details**, **Edit**, and **Delete**. The Console shows **Edit** only to an account with the update permission on roles. It shows **Delete** only to an account with the delete permission on roles.

## Create a role

***

**1. Open the form**

On the Roles page, click **New Role**. The form opens on the right side of the screen.

**2. Fill in the fields**

The form asks for **Name**, **Display Name**, and **Description**.

**3. Save**

Click **Save**. This step needs the create permission on roles. The new role appears in the list.

The Console applies these rules:

* **Name** and **Display Name** are required.
* **Name** holds 2 to 100 characters: letters, numbers, hyphens, and underscores.
* **Display Name** holds at most 100 characters. **Description** holds at most 500.

## Edit a role

***

**1. Open the row menu**

Find the role, open the menu in the **Actions** column, and select **Edit**.

**2. Change the fields**

Change the **Display Name**, the **Description**, or the **Enabled** switch. The **Name** field is read-only, so a role keeps the name it got at creation.

**3. Save**

Click **Save**.

## Assign permissions, users, and groups to a role

***

**View Details** in the row menu opens a page for one role. That page has three tabs: **Permissions**, **Users**, and **Groups**. Each tab lists what the role holds.

**1. Open the tab**

On the role page, open the **Permissions**, **Users**, or **Groups** tab.

**2. Open the panel**

Click **Add Permissions**, **Add Users**, or **Add Groups**. A panel opens with a search box.

**3. Select the items**

Select the items to add. An item that the role already holds shows "Already assigned".

**4. Assign**

Click the button at the bottom of the panel, for example **Assign 2 Permissions**.

The **Add Permissions** panel also filters the list by **Resource**.

To remove one item, use the remove button on its row. To remove more than one, select the rows and click **Remove Selected**. The Console asks you to confirm.

A system role shows the notice "System Role". Its tabs offer no add or remove.

## Create a group

***

**1. Open the form**

On the Groups page, click **New Group**. The form opens on the right side of the screen.

**2. Fill in the fields**

The form asks for **Name**, **Display Name**, and **Contact Email**.

**3. Save**

Click **Save**. This step needs the create permission on groups. The new group appears in the list.

**Name** and **Display Name** follow the same rules as for a role. **Contact Email** is optional. When you fill it in, it holds a valid address.

The Groups table shows **Name**, **Members**, and **Actions**. The row menu holds **View Details**, **Edit**, and **Delete**. The Console shows **Edit** only to an account with the update permission on groups. It shows **Delete** only to an account with the delete permission on groups.

## Edit a group

***

**1. Open the row menu**

Find the group, open the menu in the **Actions** column, and select **Edit**.

**2. Change the fields**

Change the **Display Name** or the **Contact Email**. The **Name** field is read-only.

**3. Save**

Click **Save**.

## Add members and roles to a group

***

**View Details** in the row menu of a group opens a page with two tabs: **Members** and **Roles**.

**1. Open the tab**

On the group page, open the **Members** or **Roles** tab.

**2. Open the panel**

Click **Add Members** or **Add Roles**. A panel opens with a search box.

**3. Select and add**

Select the users or roles. Click the button at the bottom of the panel, for example **Add 2 Members** or **Assign 2 Roles**.

To remove a member or a role from the group, use the same buttons as on a role page.

## Browse permissions

***

The Permissions page shows the permissions grouped by resource. Search by name, or filter by **Resource**. Click a resource name to open or close its table.

Each resource table has six columns:

| Column | What it shows |
| - | - |
| **Name** | The permission name, with the permission identifier below it. |
| **Actions** | The actions that the permission covers. |
| **Effect** | **Allow** or **Deny**. |
| **Roles** | The roles that hold the permission, as links. |
| **Users** | The number of users with the permission. |
| **Groups** | The number of groups with the permission. |


# Plugins in Midaz Module
Source: https://docs.lerian.studio/en/platform/console/mc-console-plugins

The cards the Plugins screen of the Midaz Module shows: Pix Indirect (BTG), Fees Engine, Bank Transfer (TED JD), and Payments.

Plugins are optional capabilities that add features to the Midaz Module on top of Midaz Core. The Plugins screen also holds the Fees Engine card. Fees Engine is part of Midaz, not a plugin.

## What the Plugins screen lists

***

Open the screen from the Midaz Module sidebar, at **Settings** › **Plugins**. This is the Midaz Module's own Settings, not the Console Settings area behind the gear icon. It shows up to four cards. Each card carries a name, a short description, and a toggle.

> **[Pix Indirect (BTG)](/en/interfaces/pix-btg/indirect-pix-overview)**
>
> Connects your institution to Brazil's Pix instant payment system through BTG Pactual, the direct participant.

> **[Fees Engine](/en/products/midaz/fees/fees-engine-overview)**
>
> Adds the Fee Packages, Calculator, Billing Packages, and Billing Runs screens to the Midaz Module sidebar. Fees runs inside Midaz and needs no separate service.

> **Bank Transfer (TED JD)**
>
> Sends and receives TED bank transfers through the JD integration.

> **[Payments](/en/interfaces/payments-btg/boleto-and-bill-payment)**
>
> Issues boletos and pays bills, including DARF tax documents.

> [!NOTE]
>
> To show the Bank Transfer (TED JD) card, set `NEXT_PUBLIC_BANK_TRANSFER_ENABLED` to `true` and restart the Console container. You do not need to rebuild the image.

## How plugins work

***

* **Settings controls availability.** Enable each plugin in [Plugin settings](/en/platform/console/plugin-settings) before its menu item appears in the Midaz Module sidebar.
* **Disabling preserves data.** Turning a plugin off hides its UI. It does not delete configurations you created with it.

Enabling Fees Engine checks that Midaz answers at the `MIDAZ_V2_BASE_PATH` address. Enabling Pix Indirect (BTG) checks that the Pix Indirect service answers when the Console has an address for it. If the check fails, the Console keeps the card off and shows an error. Payments and Bank Transfer (TED JD) turn on without that check.


# Notification Layer
Source: https://docs.lerian.studio/en/platform/console/notification-layer

Follow notification delivery, inspect each notification and its delivery attempts, configure the email, SMS, and webhook delivery profiles, and change the delivery settings in Lerian Console.

The Notification Layer is the Console area for the notifications that the platform sends by email, SMS, and webhook. Use it to:

* Follow the delivery figures on the **Overview** screen.
* Find a notification, read its delivery attempts, and retry or cancel it.
* Configure the delivery profiles that send each channel.
* Change the runtime settings of the delivery service.

## Open the Notification Layer

***

Click the gear icon () in the top navigation bar, then select **Notification Layer**. The same entry is also in the Settings sidebar. The area has its own sidebar with four screens: **Overview**, **Notifications**, **Delivery Profiles**, and **Settings**.

With Access Manager, the entry needs the read permission on notifications. Without that permission, **Notification Layer** does not appear in the gear menu or in the Settings sidebar.

Each screen and action needs its own permission:

| Screen or action | Permission with Access Manager |
| - | - |
| **Overview**, **Notifications**, and the detail of a notification | Read on notifications |
| **Retry delivery** and **Cancel notification** | Create on notifications |
| **Delivery Profiles** and the detail of a profile | Read on delivery profiles |
| **New delivery profile** | Create on delivery profiles |
| **Save changes** and **Edit credentials** on a profile | Update on delivery profiles |
| **Delete** a profile | Delete on delivery profiles |
| **Settings** | Read on systemplane, the resource that holds the runtime settings |
| Save a change on **Settings** | Update on systemplane |

## Overview

***

The **Overview** screen sums up notification delivery across all channels. Six cards stand at the top:

| Card | What it shows |
| - | - |
| **Total** | The number of notifications. |
| **Delivered** | The notifications with the status **Delivered**. |
| **Delivery Rate** | The delivered notifications as a percentage of the delivered and failed ones together. |
| **Failed** | The notifications with the status **Failed** or **Exhausted**. |
| **Pending** | The notifications with the status **Pending** or **Processing**. |
| **p95 Latency** | The 95th percentile of the delivery attempt latency. The 99th percentile shows below it. |

Below the cards:

* **Total Attempts** and **Avg Attempts per Notification** count the delivery attempts.
* **Top Failure Reasons** shows the failures by reason, for example **Invalid recipient** or **Rejected by Twilio**. A reason without a label shows its failure code.
* **Volume by Channel** shows the number of notifications on each channel.
* **Recent Notifications** lists the latest notifications with their **Status**, **Channel**, **Recipient**, **Subject**, **Priority**, and **Created** date.

If the Console cannot read the figures, the screen shows **Could not load notification overview** in place of all of them. Click **Retry** to read them again.

## Notifications

***

The **Notifications** screen lists the notifications of the platform. The table has the columns **Status**, **Channel**, **Subject**, **Recipient**, **Priority**, and **Created**. To open a notification, open the menu in the **Actions** column and select **View**.

### Notification statuses

| Status | Meaning |
| - | - |
| **Pending** | The notification waits for its next delivery attempt. |
| **Processing** | A delivery attempt is in progress. |
| **Delivered** | The provider accepted the message. This status is final. |
| **Failed** | The last attempt failed. |
| **Exhausted** | The service makes no more attempts, because the attempts ran out or the failure is permanent. |
| **Canceled** | Someone canceled the notification. This status is final. |

### Filter the list

Open the **Filters** panel to narrow the list:

* **Status**: click one or more status chips.
* **Channel**: **Email**, **SMS**, or **Webhook**.
* **Recipient**: the exact recipient.
* **Correlation ID**: the correlation identifier of the notification.
* **Failure code**: the failure codes from the overview, the most frequent first.
* **Created from** and **Created to**: the creation date range.

A field with a value shows **Clear** next to its label. **Clear filters** empties every field. **Items per page** sets the page size.

### Notification detail

The **Notification Detail** screen shows one notification in cards:

* The first card shows the status, the channel, **ID**, **Subject**, **Recipient**, **Destination**, **Priority**, and **Correlation ID**.
* **Delivery** shows **Attempts** (used and maximum), **Scheduled at**, **Next attempt at**, **Delivered at**, **Failed at**, **Canceled at**, **Canceled by**, **Provider message ID**, **Failure code**, **Created at**, and **Updated at**.
* **Metadata** and **Failure detail** show as JSON when the notification has them.

**Back to notifications** returns to the list.

### Delivery attempts

The **Delivery attempts** card lists the attempts, oldest first, as **Attempt 1**, **Attempt 2**, and so on. Each attempt shows:

* Its result and the time of the attempt.
* **Provider**: the delivery profile that made the attempt.
* **Response**: the response code, when there is one.
* **Latency**: the duration of the attempt, in milliseconds.
* The error message, when the attempt failed.
* **Response body**: click it to expand the body that the provider returned.

When the notification has no attempt yet, the card shows **No delivery attempts recorded yet.**

### Retry or cancel a notification

**Retry delivery** is available when the status is **Failed** or **Exhausted**. Confirm in the **Retry delivery?** dialog. The notification goes back to **Pending**, and the service attempts delivery again.

**Cancel notification** is available when the status is **Pending**, **Processing**, or **Failed**. Confirm in the **Cancel notification?** dialog. You cannot undo a cancellation. The service makes no new delivery attempt.

## Delivery Profiles

***

A delivery profile connects a channel to a provider and holds the credentials for that provider. The **Delivery Profiles** screen lists the profiles with the columns **Name**, **Channel**, **Provider**, **Status**, **Priority**, **Default**, and **Updated**. The row menu in **Actions** has **View** and **Delete**.

When a channel has more than one active profile, the service uses the profile with the highest priority first. A tie goes to the default profile, then to the oldest profile. The service skips inactive profiles.

### Create a delivery profile

**1. Open the form**

Click **New delivery profile**.

**2. Name the profile**

Type a **Name**.

**3. Choose the channel and the provider**

Select the **Channel**, then the **Provider**. You cannot change either one after you create the profile.

**4. Set the selection fields**

Set the **Status**, the **Priority**, and the **Default for this channel** switch.

**5. Set the limits**

Optionally, type a **Rate limit (per second)** and a **Daily limit**. An empty limit means no limit.

**6. Fill in the provider configuration**

Fill in the fields of the **Provider configuration** section. The fields change with the provider, as the next sections show.

**7. Save**

Click **Save**. The Console returns to the list.

### Email and SMS providers

Each channel has its own providers. An asterisk (\*) marks a required field.

| Channel | Provider | Configuration fields |
| - | - | - |
| **Email** | **SMTP** | **Host**\*, **Port**\*, **From**\*, **Username**, **Password** |
| **Email** | **AWS\_SES** | **AWS region**\*, **Access key ID**\*, **Secret access key**\*, **Session token**, **From**\* |
| **Email** | **SENDGRID** | **API key**\*, **From**\*, **From name** |
| **SMS** | **TWILIO** | **Account SID**\*, **Auth token**\*, **From**\* |
| **SMS** | **ZENVIA** | **API token**\*, **From**\* |
| **SMS** | **INFOBIP** | **API key**\*, **Base URL**\*, **From**\* |

**From** is the sender that recipients see, such as an email address or an approved SMS sender ID. The SMTP **Port** accepts a value from 1 to 65535.

### Webhook provider

The **Webhook** channel has one provider, **HTTP\_WEBHOOK**. The profile does not hold the endpoint address: each webhook notification carries its own address in **Destination**.

The webhook profile has these fields:

* **Signing secret (HMAC)**: optional. The service signs the request body with this secret, so that the destination can verify the sender.
* **Destination auth**: how the service authenticates to the destination. Select **none** for no authentication.
* **Custom headers**: optional name and value pairs that the service sends on every request.

The **Destination auth** value adds its own fields:

| Destination auth | Fields |
| - | - |
| **basic** | **Username**\*, **Password**\* |
| **bearer\_static** | **Token**\* |
| **oauth2\_client\_credentials** | **Auth URL**\*, **Client ID**\*, **Client secret**\*, **Scope**, **Audience** |
| **jwt\_exchange** | **Auth URL**\*, **Token path**\*, **Expires-in path**\*, **HTTP method**, **Custom headers**, **Request body (JSON)** |

For **oauth2\_client\_credentials** and **jwt\_exchange**, **Auth URL** is the token endpoint that the service calls before it delivers the webhook. For **jwt\_exchange**, **Token path** and **Expires-in path** are the JSON paths of the access token and of its lifetime in the response.

### Delivery profile detail

The **Delivery Profile** screen shows the status, the channel, and the provider of the profile at the top. You can change these fields:

* **Name**
* **Status**
* **Priority**
* **Rate limit**
* **Daily limit**
* **Default profile for this channel**

Click **Save changes** to save them. After the priority or a limit has a value, you can change that value, but you cannot clear it.

The **Lifecycle** section shows **ID**, **Channel**, **Provider type**, **Consecutive failures**, **Last success**, **Last failure**, **Created at**, and **Updated at**. **Consecutive failures** goes back to zero after the next successful delivery.

### Replace the credentials

The **Provider configuration & credentials** section does not show the stored credentials. To replace them:

**1. Open the editor**

Click **Edit credentials**.

**2. Fill in every field**

Fill in all the fields you want to keep. Secret fields, such as passwords, API keys, and tokens, open empty.

**3. Save**

Click **Save credentials**. The new values replace the full provider configuration. To stop, click **Cancel**.

### Delete a delivery profile

Click **Delete** on the profile screen, or select **Delete** in the row menu of the list. Then click **Confirm** in the dialog.

## Settings

***

The **Settings** screen shows the runtime settings of the delivery service, by group. Changes apply without a restart. Each row shows the setting, its key, a description, and the allowed values.

| Group | Setting | Allowed values |
| - | - | - |
| **Delivery & Retry** | **Max delivery attempts** | 1 to 20 |
| **Delivery & Retry** | **Retry base delay (s)** | 5 to 300 |
| **Delivery & Retry** | **Retry max delay (s)** | 60 to 86400 |
| **Delivery & Retry** | **Email concurrency** | 1 to 100 |
| **Delivery & Retry** | **SMS concurrency** | 1 to 50 |
| **Delivery & Retry** | **Webhook concurrency** | 1 to 100 |
| **Delivery & Retry** | **Webhook timeout (s)** | 5 to 120 |
| **Circuit Breaker** | **Failure threshold** | 1 to 50 |
| **Circuit Breaker** | **Recovery timeout (s)** | 10 to 600 |
| **Rate Limiting** | **Default max requests**, **Aggressive max requests**, **Relaxed max requests** | 1 to 100000 |
| **Rate Limiting** | **Default window (s)**, **Aggressive window (s)**, **Relaxed window (s)** | 1 to 3600 |
| **M2M Credentials Cache** | **Credential cache TTL (s)** | 30 to 86400 |
| **Logging** | **Log level** | debug, info, warn, error |

To change settings:

**1. Find the setting**

Type in the search box, or select a group in the list next to it. **All groups** shows every group.

**2. Change the value**

Change the value. The screen marks each changed row.

**3. Save**

Click **Save** with the number of changes, for example **Save 2 changes**.

If a value is out of range, the screen saves nothing and asks you to fix the marked fields. If some changes fail, the screen keeps them marked, so you can save them again.

When runtime configuration is off on the delivery service, the screen shows **Runtime configuration plane is disabled**, and you cannot change the settings.


# Plugin settings
Source: https://docs.lerian.studio/en/platform/console/plugin-settings

Enable or disable Midaz Module plugins from the Plugins screen of Midaz Settings.

The **Plugins** screen of **Midaz Settings** is where you enable and disable plugins for the Midaz Module.

> [!NOTE]
>
> Enabling a plugin adds its menu item to the Midaz Module sidebar. Disabling it hides the menu item without deleting any configuration you have already created.

## Plugins

***

The page shows three cards: **Pix Indirect (BTG)**, **Fees Engine**, and **Payments**. A fourth card, **Bank Transfer (TED JD)**, appears only when the deployment turns it on. [Plugins in Midaz Module](/en/platform/console/mc-console-plugins) explains the setting. Each card shows the plugin name, a short description, and a toggle.

### Fees Engine card

Fees Engine is part of Midaz, not a plugin. Its card on this screen turns the Fees screens of the Midaz Module on and off.

> **Fees Engine**
>
> Configure fee packages and billing packages, and estimate the fees charged on a transaction.
>
> **Key features**:
>
> * Create and manage Fee Packages
>
> * Define fee calculation rules (flat, percentage, or maximum between both)
>
> * Run fee estimations before applying to real transactions
>
> * Associate fees with specific ledgers, segments, or transaction routes
>
> * Create billing packages and review billing runs
>
> > **[Learn more about Fees Engine](/en/products/midaz/fees/console/fees-engine-overview)**
> >
> > Complete guide to managing fees through Lerian Console.

## Enabling or disabling a plugin

***

**1. Open Settings**

From the Midaz Module sidebar, click **Settings** > **Plugins**. The entry is available after you select a ledger.

**2. Locate the plugin**

Find the plugin in the list.

**3. Toggle the switch**

Use the toggle on the right side of the plugin card to enable or disable it.


# Products
Source: https://docs.lerian.studio/en/platform/console/settings-products

Enable or disable Lerian product modules from Console Settings to control which capabilities and screens are available to your Console users and operators.

Use the Products page to enable or disable Lerian products for your tenant. This controls which modules are available to users in the Lerian Console.

You can also enable a product from the Console home page. The card of each product that is off has an **Enable** button. With Access Manager, the button needs the update permission on products.

## Accessing the Products page

***

To access the **Products** section:

**Step 1**

Click the gear icon () in the top navigation bar.

**Step 2**

Select **Products** from the sidebar.

**Step 3**

The **Products** page displays all available products with toggle switches to enable or disable each one.

## Available products

***

| Product | Description |
| - | - |
| **Midaz** | Core ledger management module: organizations, ledgers, assets, accounts, portfolios, and transactions. |
| **Reporter** | Report generation module: templates, reports, data sources, and regulatory filing. |
| **Tracer** | Transaction validation module. Provides rule-based validation for financial transactions before they are committed to the ledger. |
| **Flowker** | Workflow orchestration module with visual automation and execution in real time. |
| **Streaming Hub** | Event delivery module. Delivers platform events to your own webhooks and queues. |
| **Matcher** | Reconciliation module: contexts, rules, reconciliations, and exceptions. |

## Enabling or disabling a product

***

To change a product's status with Access Manager, you need the update permission on products. Without it, the toggle switches are disabled.

To change a product's status:

**Step 1**

From the **Products** page, locate the product you want to enable or disable.

**Step 2**

Click the toggle switch next to the product.

**Step 3**

To turn a product on, the Console checks that its service answers and shows "Product enabled". If the service does not answer, the product stays off. To turn a product off, confirm with **Turn off** in the dialog. The Console shows "Product disabled".


# System
Source: https://docs.lerian.studio/en/platform/console/settings-system

Set the language and the theme of the Lerian Console interface.

The System page holds two display preferences: the interface language and the theme.

## Accessing the System page

***

To access the **System** section:

**Step 1**

Click the gear icon () in the top navigation bar.

**Step 2**

Select **System** from the sidebar.

**Step 3**

The page shows the **Language** and **Theme** fields.

## Available settings

***

### Language

Select the display language for the Lerian Console interface. It sets the language of the Console labels and messages.

**Languages available:**

* English - EN-US
* Português - PT-BR

### Theme

Select the appearance theme of the Lerian Console interface.

**Themes available:**

* Light: Uses light backgrounds and dark text.
* Dark: Uses dark backgrounds and light text to reduce visual strain in low-light environments.
* System: Automatically matches the appearance settings defined by your device or operating system.

## Altering system settings

***

To change the settings:

**Step 1**

On the **System** page, open the drop-down list that you wish to change (**Language** or **Theme**).

**Step 2**

Select the option you want.

**Step 3**

Click **Save** in the bar at the bottom of the page. The bar appears after you change a field.

**Step 4**

The interface updates immediately to display the content in the selected option.

> [!TIP]
>
> The Console keeps these preferences in your browser, not in your user account. Another browser or device keeps its own.
>
> If you change the language by mistake, open the **Language** list again. It shows each language in its own name.


# License Manager
Source: https://docs.lerian.studio/en/platform/licensing/license-manager

How a licensed Lerian product validates its license key, what each result allows, and how it behaves when the license service does not answer.

Lerian issues a license key for each Lerian product that requires one. The product validates the key when it starts, and again at a fixed interval. This page describes what you configure, which host the product calls, and what each result allows.

## What a license key is

***

A license key covers one product and the organization identifiers that you declare for it. A product accepts the key only for those organizations, and only for itself. Store the key as a secret, and keep it out of source control.

## What the product reads from the environment

***

| Variable | Content |
| :- | :- |
| `LICENSE_KEY` | The key that Lerian issued for this product. |
| `ORGANIZATION_IDS` | The organization identifiers that the key covers, separated by commas, or `global` when Lerian licenses the whole deployment. Some products, such as Lerian SISBAJUD, accept only `global`. |
| `IS_DEVELOPMENT` | Optional. Set it to `true` to validate against `https://license.dev.lerian.io` instead of the production host. |

In production, most products do not start without `ORGANIZATION_IDS`. Some products, such as the Lerian SISBAJUD executor, do not start without it in any environment.

## How the check runs

***

The product sends its own name, the license key and one organization identifier to `https://license.lerian.io`. Lerian operates that service. Open outbound HTTPS to that host from every workload that runs a licensed product, or every check fails. A workload that sets `IS_DEVELOPMENT` to `true` needs the same rule for `https://license.dev.lerian.io`.

Lerian STA can read a signed license file instead of a key. When `LICENSE_FILE_PATH` is set, Lerian STA verifies the file locally and does not call `https://license.lerian.io`. See the [Lerian STA environment variables](/en/rails/sta/sta-environment-variables).

The product validates at startup, then repeats the check in the background at a fixed interval. One attempt waits up to five seconds for an answer.

## What each result allows

***

| Result | What the product does |
| :- | :- |
| Active | The product runs. It logs a warning 30 days before expiry, and a stronger warning in the last 7 days. |
| Trial | The product runs and logs the days that remain. It logs a warning in the last 2 days. |
| Expired, grace period open | The service grants 14 days of grace from the day it records the expiry. The product runs and logs a warning. |
| Grace period closed | The service suspends the key. The product stops. A Bank Transfer deployment that serves several organizations stops serving only that organization. |
| No valid license at startup | The product stops and writes the reason to the log. |

## When the license service does not answer

***

> [!WARNING]
>
> If the license service stays unreachable, the product can stop serving. A product that starts while it cannot reach the license service stops, at once or within six hours. Monitor the outbound rule and the validation logs.

## Error codes

***

Each failure carries a stable code. The [License Manager error list](/en/platform/licensing/license-manager-error-list) gives the codes and the messages that come with them.


# License Manager error list
Source: https://docs.lerian.studio/en/platform/licensing/license-manager-error-list

The License Manager error codes and their messages, so you can diagnose a license failure on a Lerian product.

A licensed product can return one of these codes when it cannot confirm a valid license. Quote the code when you contact support. [License Manager](/en/platform/licensing/license-manager) describes the environment that the check reads.

```json theme={null}
{ "code": "<error_code>", "title": "<error_title>", "message": "<error_message>" }
```

Bank Transfer answers with its own problem document instead, and carries the LCS code in `refusalCode`. When the license service refused the key, the body can also carry `gatewayCode`, the code that the service returned.

## Errors that the product returns

***

`\<organization-id>` is the identifier that the product reports back to you. During shutdown, a product can answer LCS-0003 or LCS-0013 with a message that reports the shutdown.

| `code` | `message` |
| :- | :- |
| LCS-0001 | The server encountered an unexpected error. Please try again later or contact support. |
| LCS-0003 | No valid licenses were found for any of the configured organizations. Please check your license keys and ensure at least one organization has a valid license. |
| LCS-0010 | The X-Organization-Id header is missing. Please ensure the header is included in the request. |
| LCS-0011 | The organization ID '\<organization-id>' was not found in the list of configured organizations. Please verify you are using a valid organization ID. |
| LCS-0012 | License validation failed for organization ID \<organization-id>. This could be due to network issues, invalid license keys, or server-side problems. Please verify your license key is correct and that you have network connectivity to the license server. |
| LCS-0013 | The license for organization ID '\<organization-id>' is not valid and has no grace period active. Please renew your license or contact support for assistance. |

## Errors that the license service returns

***

The license service returns these codes. A product can pass the code on to the caller.

| `code` | `message` |
| :- | :- |
| LCS-1001 | Could not validate license key. Please try again later or contact your system administrator. |
| LCS-1002 | There is no license for this license key. Please ensure the license key is correct and try again. |
| LCS-1003 | The license key has expired. Please contact your system administrator to renew your license. |
| LCS-1004 | The license key has been suspended due to payment issues or administrative action. Please contact your system administrator. |
| LCS-1005 | The license key or organization IDs are not valid for this license. Please ensure the license key and organization IDs are correct and try again. |
| LCS-1006 | There is no license for this product. Please ensure the license key is correct and try again. |
| LCS-1007 | The license key cannot be empty. Please set the license key in the environment variables. |
| LCS-1008 | The organization IDs cannot be empty. Please set the organization IDs in the environment variables. |
| LCS-1009 | The application name cannot be empty. Please set the application name in the environment variables. |


# Overview
Source: https://docs.lerian.studio/en/platform/lifecycle-management

Lerian installs and operates Lerian products in your Kubernetes cluster through the Lerian BYOC agent, which opens every connection to Lerian from your cluster.

**Lifecycle Management** runs through the Lerian BYOC agent. You install the agent in your Kubernetes cluster. Lerian then installs, upgrades, rolls back, and removes Lerian products in your cluster through the agent.

The agent installs and operates applications. It does not create cloud infrastructure, and it holds no cloud credential.

> [!NOTE]
>
> Lifecycle Management is available to **Enterprise** clients on the [BYOC deployment model](/en/start-here/evaluate-and-deploy/deployment-models). In Lerian Cloud, Lerian runs the deployment and lifecycle operations for you, and you do not need the agent.

## How the agent connects to Lerian

***

* You install one agent in each cluster.
* The agent opens every connection to Lerian. Your cluster needs no inbound access from Lerian.
* The agent connects to Lerian over HTTPS.
* Each agent has its own credential. Lerian identifies your company from that credential, not from data that the agent sends.
* Inside the cluster, the agent serves a health and metrics endpoint.

## What Lerian does through the agent

***

At your request, Lerian runs these operations in your cluster through the agent:

* Install a Lerian product.
* Upgrade a product.
* Roll back a product to an earlier version.
* Remove a product.
* Check that the cluster meets the needs of a product before the install.

If an upgrade fails, the agent rolls the product back to its last working version. The agent does not roll back after a database schema change ran. In that case, the product stays on the failed upgrade.

The agent pulls a product's chart from an allowed registry, by the exact content digest that Lerian names. It refuses a chart that has no digest.

The agent also reports to Lerian the health of the products that Lerian asks it to observe.

Lerian also updates the agent itself. The agent first runs the new build once in your cluster as a test. It replaces itself only when that test passes.

## What you control

***

* **Namespaces**: You create the namespaces where the agent can install products, and you list them when you install the agent. To add a namespace later, upgrade the agent chart.
* **Registries**: You set the registries from which the agent can pull product charts and its own image.
* **Private registry credential**: If your registry needs a credential, the agent sends it only to that registry.
* **Your secret manager**: The agent can use your own secret manager through External Secrets.
* **Network**: You can limit the outbound traffic of the agent, and set a proxy and your own certificate authorities.
* **Removal**: You can uninstall the agent.

For each of these settings, see the [agent chart README](https://github.com/LerianStudio/helm/tree/main/charts/agent).

## What Lerian sees

***

The agent sends information about your cluster and your products to Lerian. For example:

* **At regular intervals**: The status of the agent, and the health of each product that it observes.
* **When a product looks unwell**: The last output of its stopped containers, and the warning events about the product.
* **On request from a Lerian operator**: Product status, an upgrade preview, the computed configuration values, live resource usage, and the cluster check result.

For the full inventory, with when each item leaves and where it lands, see "What leaves your cluster" in the [agent chart README](https://github.com/LerianStudio/helm/tree/main/charts/agent).

## Security

***

* The agent runs as a non-root user, with a read-only file system and no added privileges.
* Across the cluster, the agent reads information such as nodes, pods, and services. It can also create namespaces and manage storage classes.
* In the namespaces that you list, the agent installs products and writes their Secrets.
* Install the agent in a dedicated namespace.

## Get started

***

**1. Ask Lerian support**

Ask Lerian support for the agent credential and the address of the Lerian control plane.

**2. Create the namespaces**

Create the namespaces where Lerian installs products. Each namespace must exist before you install the agent.

**3. Install the agent**

Install the agent with the agent chart, as the [agent chart README](https://github.com/LerianStudio/helm/tree/main/charts/agent) describes. Use the credential, the address, and the namespaces from the previous steps.

## Manage installed products

***

To install, upgrade, roll back, or remove a product, send a request through the [Lerian Support Portal](/en/products/midaz/lerian-support-portal). Lerian runs the operation in your cluster through the agent.

To remove the agent itself, uninstall its chart. See the [agent chart README](https://github.com/LerianStudio/helm/tree/main/charts/agent).

## Related

***

> **[Agent chart README](https://github.com/LerianStudio/helm/tree/main/charts/agent)**
>
> Install, configure, and uninstall the Lerian BYOC agent.

> **[Deployment models](/en/start-here/evaluate-and-deploy/deployment-models)**
>
> Compare Lerian Cloud and BYOC.

> **[Lerian Support Portal](/en/products/midaz/lerian-support-portal)**
>
> Send requests to Lerian support.


# Multi-tenancy
Source: https://docs.lerian.studio/en/platform/multi-tenancy

How Lerian Cloud and supported BYOC products isolate tenants, and how to choose dedicated or shared storage.

Multi-tenancy lets one deployment serve independent institution contexts (**tenants**) while keeping each request and its data within the authenticated tenant's scope.

Lerian operates Lerian Cloud as a multi-tenant environment. In BYOC, multi-tenancy is available only for products and entitlements that support it. A BYOC Single-Tenant deployment is a separate configuration.

Tenant scoping and configuration are product-specific. Use the authentication and configuration guide for the product that you deploy. Do not assume an environment variable, JWT claim, or API behavior documented for one product applies to another.

## Authentication and request scoping

***

Each product validates the caller's identity and derives its tenant context according to that product's authentication contract.

The platform does not define one universal `tenantId` claim or one universal tenant header for every product. A product integration must follow that product's documented claim and routing behavior. Do not add a tenant identifier to a request unless that product explicitly requires it.

> [!NOTE]
>
> Multi-tenancy is an operational capability. It does not mean that every Lerian product has the same authentication middleware or configuration surface.

## Storage isolation

***

* **`dedicated`**: a tenant receives a dedicated PostgreSQL database.
* **`shared`**: tenants share a PostgreSQL database and each receives a dedicated schema.

The database-versus-schema split is specific to PostgreSQL. Other datastores use their own mode-specific routing and provisioning rules. Do not infer PostgreSQL schema behavior for MongoDB or RabbitMQ.

| Dimension | `dedicated` | `shared` |
| :- | :- | :- |
| **PostgreSQL isolation** | Separate database per tenant. | Separate schema in a shared database. |
| **Operational blast radius** | A database-level incident is limited to that tenant's database. | A database-level incident can affect tenants sharing the instance. |
| **Cost and density** | Higher isolation, more infrastructure per tenant. | Higher density, less infrastructure per tenant. |
| **Restore design** | Plan and test restores for the dedicated database. | Plan and test restores against the shared database and its schemas. |

Choose the mode per service according to the service's supported configuration, regulatory obligations, expected workload, and recovery requirements.

## Moving a tenant between modes

***

Moving a tenant from shared to dedicated storage is an operator-planned migration. The platform has no generic automatic workflow for it. Validate the target product's migration path, data-consistency requirements, maintenance window, backup/restore plan, and rollback procedure before changing a tenant's storage mode.

The tenant identity can remain stable, but do not assume every product can move data between modes without an implementation-specific migration.

## Operating each deployment model

***

### Lerian Cloud

Lerian operates the multi-tenant infrastructure. Follow the product's API and authentication documentation. Your token and the product's routing contract determine the request scope.

### BYOC Multi-Tenant

The operator configures the supported products, tenant services, storage mode, backing resources, and authentication. Treat each product's configuration reference as authoritative.

### BYOC Single-Tenant or local development

Multi-tenancy is not automatic. Authentication requirements depend on the product and environment. For Midaz, production and multi-tenant deployments require authentication. A permitted non-production single-tenant deployment can disable it.

## Related pages

***

> **[Use cases](/en/platform/multi-tenancy/use-cases)**
>
> How to choose dedicated or shared PostgreSQL isolation.

> **[Deployment models](/en/start-here/evaluate-and-deploy/deployment-models)**
>
> Compare Lerian Cloud, BYOC Single-Tenant, and supported BYOC Multi-Tenant configurations.

> **[Access Manager](/en/platform/access-manager)**
>
> Understand the supported authentication flows for the products you deploy.


# Multi-tenancy use cases
Source: https://docs.lerian.studio/en/platform/multi-tenancy/use-cases

Choose dedicated or shared PostgreSQL isolation for a supported BYOC tenant service.

Choose an isolation mode per tenant service after you have confirmed that the product supports multi-tenancy. This page uses the isolation modes `dedicated` and `shared` as they apply to PostgreSQL.

## Choose `dedicated` when isolation dominates

***

Use a dedicated PostgreSQL database per tenant when the tenant needs a strong infrastructure boundary. The same applies when the tenant needs independent database maintenance windows, or a recovery plan designed around a dedicated database.

Typical examples include a highly regulated institution, a high-volume tenant, or a tenant whose workload must not share a PostgreSQL instance with other tenants. This choice increases infrastructure and operational cost, so validate the product's connection, backup, and migration design first.

## Choose `shared` when density dominates

***

Use a dedicated schema per tenant in a shared PostgreSQL database when your operating model values density and lower per-tenant infrastructure cost. The supported product must also be able to operate in `shared` mode.

A database-level incident or maintenance action can affect tenants on the shared instance. Plan capacity, backups, recovery, and maintenance around that shared blast radius.

## Treat migration as a product operation

***

Do not rely on a generic automatic promotion from `shared` to `dedicated`. Moving a tenant to dedicated storage requires an operator-planned migration that the target product supports.

Before changing a registration, establish:

1. the target product's supported migration procedure
2. a tested backup, consistency, and rollback plan
3. a maintenance window and communication plan
4. post-migration checks for authentication, routing, and tenant data.

## Decision checklist

***

| Question | Favors `dedicated` | Favors `shared` |
| :- | :- | :- |
| Does the tenant require a dedicated database boundary? | Yes | No |
| Can the tenant share a database-level maintenance and incident domain? | No | Yes |
| Is per-tenant infrastructure cost acceptable? | Yes | No |
| Does the product explicitly support the selected mode? | Required | Required |

## Related pages

***

> **[Multi-tenancy](/en/platform/multi-tenancy)**
>
> Product support, request scoping, and storage concepts.


# Automation and CI
Source: https://docs.lerian.studio/en/platform/narya/automation-and-ci

Run Narya from a pipeline with one command and an exit code, put work on a clock, and orchestrate several agents from a script.

A pipeline drives Narya the way you do: the binary, a prompt, a credential in the environment, and an exit code.

## One turn from a command line

***

`narya -p "<prompt>"` runs one turn and answers on standard output. Its flags:

* `--repo <path>` sets the working repository, and defaults to the working directory.
* `--model <id>` chooses the model.
* `--agent <name>` runs the turn under a named agent.
* `--session <id>` continues an existing session.
* `--style <name>` names a response style you declared as `[styles.<name>]` in `config.toml`. It cannot join `--session`.
* `--instructions <file>` adds an instruction file to the system prompt. Repeat it for more. A run that goes to a running host refuses it.
* `--json` switches the output to a machine shape.

## Exit codes

***

| Code | Meaning |
| - | - |
| `0` | The turn ran to its end. The answer is on standard output. |
| `1` | The turn failed. A key the provider rejected lands here. |
| `2` | Usage, configuration, or a store that another Narya process holds. No credential for the resolved provider lands here. |
| `130` | Interrupted. The transcript survives, and `--session` resumes it. |

The two credential failures carry different codes on purpose. An absent key exits `2`, and a rejected key exits `1`. Retry on `1`. On `2`, read the message first: a held store clears on its own, and a missing credential does not.

> [!WARNING]
>
> A turn that stops early still exits `0`. Two endings do this: an output ceiling and the provider's content filter. The exit code alone cannot tell a cut answer from a complete one. Narya names both on standard error, and `--json` carries each as `stopReason` on the `turn-finished` event.

## The two shapes of `--json`

***

`narya -p --json` streams one event envelope per line on standard output. Each line carries `id`, `type` and `timestamp`. A line adds `sessionId` and `laneId` when the event belongs to a session or a lane. `payload` is `null` when the event carries no body. Plain output carries only the answer to your prompt. The stream carries every lane, so select on `laneId`. These are the same event envelopes the host streams on [its API](/en/platform/narya/the-host-api), so a pipeline and a client read one format.

Every other command answers with one document. The actions share one envelope:

```json theme={null}
{"command":"narya retention run","result":"swept","changed":{},"exitCode":0}
```

`result` is one word to branch on. `changed` appears only on a run that changed something. A non-zero exit carries `reason` instead.

Some commands publish their own document on success and print the envelope only on failure, among them `narya export` and the `narya schedule` verbs. Branch on the exit code for those, never on `result`.

Under `--json`, standard output carries the document or the stream and nothing else. Sentences for a person go to standard error.

## The credential on a runner

***

Put the provider key in your CI secret store and hand it to the step as `<PROVIDER>_API_KEY`.

```yaml theme={null}
name: narya review

on: pull_request

permissions:
  contents: read

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false

      # Add a step here that places your licensed narya binary on PATH.
      - name: Ask Narya
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          # Pass the ref through env, never into the script text. A ref with
          # shell metacharacters would run as script on this runner.
          BASE_REF: ${{ github.base_ref }}
        run: |
          narya -p "Read the changes on this branch against origin/$BASE_REF.
          Name every change that breaks a caller, with the file and why."
```

The step fails when Narya exits non-zero, and the answer lands in the job log.

> [!NOTE]
>
> Narya reads the branch's own history, so check out the full branch.

## Schedules

***

Put work on the host's clock.

* `narya schedule add "<prompt>" --every <duration>` repeats on an interval, and `--at <RFC3339>` fires once.
* Add `--repo <path>`, `--agent <name>` or `--budget <usd>` to either form.
* `narya schedule list` lists what exists, and `narya schedule rm <schedule-id>` cancels one.
* `narya schedule budget <schedule-id> on <usd>` changes what one fire of an existing schedule may spend. `off` stops the schedule from firing until you set a number again.

Narya refuses to create a schedule in a directory nobody trusts. All four verbs talk to the running host.

The spend ceiling is on by default. If you set no `--budget`, the schedule takes the operator's default, `$5.00` per fire, as `[schedules] ceiling_usd`. If you set a number, Narya keeps it. If you set `0`, Narya stores the schedule and refuses to fire it until you set a budget.

## Workflows

***

A workflow is a JavaScript program that orchestrates agents. Start one by path or as inline source, over the host API. Narya refuses an invalid program before anything runs.

A workflow program calls four capabilities:

* `agent(step, agent, task)` runs one agent.
* `agents([...])` runs one wave, read in the order you asked.
* `step(name, value)` records a step.
* `args` hands the program its own run's arguments.

Three ceilings are constants, and no setting changes them: 72 hours per run, 4,096 host calls, and 4 hours per step. Narya snapshots the source at submission, so a resumed run uses the source that was submitted.


# Extending Narya
Source: https://docs.lerian.studio/en/platform/narya/extending-narya

Add tool servers, OpenAPI tool trees, packages, registered extensions, confined scripts, agents, skills, commands and hooks, or drive Narya over its local API.

You extend Narya with resources you declare in files, packages you install, extensions you register, and confined scripts. A client you write drives the host API.

## MCP tool servers

***

Declare a server as `[tool_servers.<name>]` in `config.toml`. Give it exactly one transport. `command` spawns a process and speaks stdio. `url` speaks streamable HTTP over https, or over http on loopback. A declaration with both, or with neither, refuses to load.

```toml theme={null}
[tool_servers.filesystem]
command = ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/repo"]
env = { PATH = "/usr/local/bin:/usr/bin:/bin", HOME = "/home/you" }
```

> [!WARNING]
>
> `env` replaces the child environment. It does not add to it. The child inherits nothing, not even `PATH` and `HOME`. Declare both for any `npx` or `uvx` server, or the child exits before it serves a tool.

The other keys are `dir`, `headers`, `oauth`, `timeout_ms` and `enabled`. Every declared server connects at startup unless you set `enabled = false`.

Narya keeps one long-lived session per server and reconnects with backoff. When a server disconnects, Narya withdraws its tools from the registry, so the model never sees a departed server's tools.

Set `oauth = true` for a remote server that signs in. Narya holds the connection open, prints the authorization URL, and listens on `127.0.0.1:7666` for the callback while the sign-in is open. A sign-in nobody answers costs that one server and nothing else. A one-shot run cannot complete a sign-in, and it says so.

> [!WARNING]
>
> A declared tool server runs under the `tool` rule, which the shipped set allows. Narya's write and secrets rules do not apply to what the server itself reads or writes. Narrow it with `ask tool <name>` or `deny tool <name>`.

## OpenAPI tool trees

***

Declare `[tool_trees.<name>]` to turn an OpenAPI document into a callable tool tree. The keys are `spec`, `base_url`, `headers`, `timeout_ms` and `enabled`. A relative `spec` path resolves against your Narya home. Set `base_url` when the document declares no server of its own. Narya derives the tools once at startup. No server runs, and no session reconnects.

## Confined scripts

***

Narya runs ECMAScript in a confined engine. The engine reaches no filesystem, no network, no environment and no module loader. It has no dynamic evaluation. Call depth stops at 4,096, and source stops at 256 KiB. Three callers use it: the model's `run_program` tool, workflows, and tool discovery.

## The host API

***

The host serves one HTTP API over a Unix socket, and every client drives it. [The host API](/en/platform/narya/the-host-api) describes the transport, the event stream and the envelopes.

## Packages

***

`narya ext add <source>` installs a package from a local path or a Go module reference. `narya ext list`, `remove`, `enable` and `disable` manage what you installed.

A package that declares only resources adds agents, skills, commands and hooks, and installs by copy. A package with Go code compiles into your Narya binary, so it needs a local Go toolchain. Narya asks you to trust a package that carries code or hooks before it installs it. Add `--yes` to skip that question in a script.

## Registered extensions

***

To add an extension that runs as its own HTTPS service, register it with `POST /v1/extensions`. That needs the `extensions:manage` permission. The body needs two fields: `name`, in the form `publisher/extension`, and `endpoint`. The other fields are optional: `description`, `points`, `slots`, `position`, `grants`, `models` and `enabled`.

The endpoint must be an `https://` URL, and this applies to loopback addresses too. The host resolves the address before it stores the registration. It refuses a loopback or private address unless `allow_private_endpoints` in the `[extensions]` table of `config.toml` admits that range. No setting admits any other address outside the public internet, such as a link-local or multicast address.

An exclusive slot holds one extension. A registration that claims an exclusive slot that another extension holds gets `409` with `NRY-0006`. To admit both, name the winner of that slot under `prefer` in the `[extensions]` table.

The response carries the extension's secret, once. No read returns it again. To replace the secret, call `POST /v1/extensions/{publisher}/{name}/secret`. The response carries the new secret and the time when the old one stops working. The host signs each call to the extension under the secret. The extension signs its own calls the same way, and it can call only the event stream.

The extension serves its own operations at its endpoint. The host calls `/transform` at the decision points that the extension sits on. It calls `/models` and `/supply` when the extension supplies models, `/tools` when it publishes tools, and `/invoke` to run a named operation. The host does not follow a redirect from the extension.

A client reaches an extension through the host with `POST /v1/extensions/{name}/invoke`. The token of an ordinary member is enough. The host signs the forwarded call, so the client does not need the secret.

## Agents, skills, commands and hooks

***

Narya reads Claude Code's own formats without any change.

**Agents** are markdown files with YAML frontmatter, and the body is the prompt. The keys are `name`, `description`, `tools` and `model`, and a file with no `name` takes its file name. An agent in your Narya home or in `.narya/agents` also reads `mode`, `hidden` and `permission-policy`. `tools` is an allowlist and never a grant: Narya intersects a child's list with its parent's, so a child agent can lose tools, never gain them.

Narya reads agents from your Narya home, then `~/.claude/agents`, then the `.claude/agents` and `.narya/agents` of a repository you trust. Four agents ship with the binary: `explore`, `general`, `plan` and `review`.

**Skills** follow the Agent Skills standard: a directory that holds a `SKILL.md`. Narya reads the same ladder, `~/.claude/skills` included, and re-reads it on each request. A skill you add mid-session reaches the next turn.

**Commands** come from your Narya home, from `~/.claude/commands`, and from the `.claude/commands` and `.narya/commands` of a repository you trust.

**Hooks** come from the `hooks` table of `~/.claude/settings.json`, and from the same file in a repository you trust. Narya reads them with the stdin keys and exit codes those scripts already use. Four events map: `PreToolUse`, `PostToolUse`, `UserPromptSubmit` and `SessionStart`. Other events, such as `Stop`, `SubagentStop`, `Notification`, `PreCompact` and `SessionEnd`, have no equivalent. Narya skips them and says so in its log.

> [!WARNING]
>
> These differences have no workaround. Narya reads hook output for a verdict only, so `additionalContext` never reaches the model's context. `systemMessage` goes nowhere. A hook read from `settings.json` always fails open: a hook that times out, exits with a code other than `0` or `2`, or prints output Narya cannot read lets the call through, and this format has no field to change that. Its `tool_response` arrives as a string, not an object.

## Narya's own hooks

***

Declare `[[hooks]]` in `config.toml` with `point`, `command`, `timeout_ms`, `fail` and `match`. `fail` carries no default, so state it.

`match` filters tool names at `before-tool-call` and `after-tool-call`. Use a tool name or a Go regular expression that matches the whole name, such as `read|write`. An empty value or `*` matches every tool. Other hook points do not accept a nonempty `match`.

Four points decide, and a hook there can stop what it fronts:

`before-tool-call`, `before-model-request`, `after-tool-call`, `at-permission-ask`.

Eight points observe, and a hook there learns what happened without changing it:

`session-started`, `lane-started`, `lane-finished`, `delegation-created`, `child-asked`, `skill-invoked`, `permission-denied`, `session-compacted`.

A repository's own file cannot declare `at-permission-ask`.

## Delegation

***

Delegation is a tool call. Set its bounds under `[delegation]` in `config.toml`. The `max_depth` key counts the levels below your conversation, and `0` turns delegation off. Set `max_concurrent` to bound how many lanes one conversation runs at any instant.


# Models and credentials
Source: https://docs.lerian.studio/en/platform/narya/models-and-credentials

Choose a model supplier, give Narya your own key, and see exactly what leaves your machine and what it costs.

Narya calls the model supplier you configure, with your own credential. Three suppliers ship with the binary.

## The three suppliers

***

| Provider | Endpoint |
| - | - |
| `anthropic` | `https://api.anthropic.com` |
| `openai` | `https://api.openai.com` |
| `openrouter` | `https://openrouter.ai/api` |

`openrouter` is a gateway to other suppliers.

A fresh installation with no `config.toml` runs on the default model of the provider you signed in to. Override the wire family, the base URL and the default model per provider under `[providers.<name>]` in `config.toml`. Your file wins on any collision with the catalog in the binary.

Run `narya providers` to list the providers, and `narya models` to list the models.

## Where your key comes from

***

Narya spends your organization's key first, when one is stored, and this machine's own key otherwise. A key typed into a client is your organization's: Narya stores it encrypted, and every member's turns spend it. Storing one needs the `keys:manage` permission. `narya auth login` stores this machine's own key.

Narya derives the environment variable name from the provider name, uppercased, plus `_API_KEY`. So `anthropic` reads `ANTHROPIC_API_KEY`, `openai` reads `OPENAI_API_KEY`, and `openrouter` reads `OPENROUTER_API_KEY`.

Narya reads this machine's key from three tiers, in order:

1. The environment variable, which wins on every read.
2. The operating system keychain: macOS Keychain or Linux Secret Service.
3. A per-provider file with `0600` permissions under `credentials` in your Narya home. Narya uses this tier only on a machine with no keychain backend at all.

If the keychain exists but refuses the request, Narya reports the error and does not use the file.

> [!WARNING]
>
> `narya auth login` writes to the keychain even when the environment variable already holds a key for that provider. The environment variable then shadows the stored one on every read, without a message. Unset the variable to use what you stored.

## Sign in

***

Run `narya auth login <provider>` to store a key, and `narya auth logout <provider>` to remove it. Narya probes a typed key against the provider before it stores anything.

Add `--method key` to type a key, or `--method subscription` for a browser sign-in. Browser sign-in works for `anthropic` only, against `claude.ai` and `platform.claude.com`.

## What leaves your machine

***

Narya sends your prompts, the files it reads, and tool results to the model supplier you configure, with the key it spends. Lerian operates no endpoint in that path.

Narya also reaches these hosts:

* `models.dev`, for a model catalog refresh every 12 hours, and each provider you configured, for a `GET /v1/models` listing. Set `NARYA_MODELS_URL=off` to stop both. The refresh never blocks a turn, and a failure goes to the host log alone.
* The two browser sign-in hosts above, during a sign-in.
* The identity provider in your `[identity]` settings.
* The address in `[identity] plane_url`, when you set one. The host reads your organization's settings there every 15 minutes, and a share finds your organization's home there. A session you share goes to that home.
* A release host, on an explicit upgrade command.
* Any host the model names through its `fetch` tool. That call runs under the network rule, which asks first. Narya reads at most 5 MiB and waits at most 30 seconds.
* The supplier's own web search, which runs on the supplier's side under the same key. Narya offers it to the `anthropic` and `openai` providers, and only against the supplier's own endpoint. The network ask does not reach it. `deny network **` turns it off, and a per-host rule narrows `fetch`, never the search. An unattended run searches only where the rules allow every host.
* The tool servers, OpenAPI tool trees and PDF converter you declare. See [Extending Narya](/en/platform/narya/extending-narya).
* Registered extensions and packages. `narya ext add` downloads the package's Go module from the module source.
* The OpenTelemetry collector you name under `[telemetry]` or in `OTEL_EXPORTER_OTLP_ENDPOINT`. Telemetry is off until you name one.

Hooks can receive session data according to their point: `before-model-request` receives a prompt, `before-tool-call` receives tool arguments, and `after-tool-call` receives tool arguments and results. Review an extension's hooks before you enable it.

Shell commands the model runs reach the network under the shell rules, not the network rule.

## Cost

***

Prices come from a `models.dev` snapshot inside the binary, in US dollars per million tokens. A model with no published price reports no cost. It never reports a zero.

Run `narya records usage --from <time> --to <time>` for tokens and cost per group. An incomplete total prints with a `>=` marker.

Narya sets two spending ceilings by default:

* `$5.00` per scheduled fire, as `[schedules] ceiling_usd`.
* `$20.00` per owner per UTC day, as `[schedules] daily_ceiling_usd`.

A scheduled fire on a model Narya cannot price does not run.


# Permissions and trust
Source: https://docs.lerian.studio/en/platform/narya/permissions-and-trust

How Narya asks about a repository, how its permission rules read, what the shipped posture allows, and how to audit every refusal.

Narya checks one gate in front of every tool call. Two things decide the answer: whether you trust the directory, and what the rules say.

## The trust question

***

The client asks **Trust this repository?** one round trip after it opens. It asks only when the directory carries something governed: an instruction file, a resource directory, or a `.narya/config.toml`.

The question names what reaches the model and what runs on this machine.

You have four answers:

* `y` trusts this folder.
* `p` trusts this folder and its parent. The host computes the parent, so no client can widen the scope past what it showed you.
* `n` is a durable no.
* `esc` continues untrusted. Narya stores nothing and asks again at the next launch.

Narya stores one row per canonical path. A lookup walks up the tree, and the nearest trusted or refused ancestor decides. Type `/trust` to reopen the question.

## What trust decides

***

Trust decides which rule set runs. A directory nobody trusts runs under a stricter set, and only where a person can answer. A one-shot run keeps the shipped set. Reads inside the directory stay free, and reads outside it ask. Shell, write, network and tool actions ask. Trust swaps in the shipped set.

Trust also gates the repository's own material: its instruction files, its `.claude/settings.json` hooks, and its `.claude` and `.narya` commands, skills and agents. Narya ignores all of it in an untrusted repository, in any mode.

## How a rule reads

***

A rule is a TOML table with three keys.

```toml theme={null}
[[rule]]
action = "write"
resource = "/etc/**"
effect = "deny"
```

Five actions exist, and no more: `shell`, `read`, `write`, `network` and `tool`. The action decides what Narya matches. A path glob matches `read` and `write`. Command text matches `shell`, after Narya decomposes the line into the commands it really runs. A host matches `network`. A tool name matches `tool`.

Three effects exist: `allow`, `ask` and `deny`.

There is no ordinal field. Position in the file is the precedence. Narya concatenates four scopes in this order: its shipped set, your global rules, the project rules, and the session. **The last match wins.**

An answer you remember becomes a rule: a global one for everywhere, or a project one for this repository. A repository you trust also contributes project rules through the `[[rule]]` blocks of its `.narya/config.toml`. Set `permission_mode = "custom"` in `config.toml` to replace the shipped set with `permissions.toml` in your Narya home.

## The shipped posture

***

Shell commands run. Tool calls run. Reads inside the session's directory run, and reads outside it ask. More than forty shell rules ask first, among them `rm -r`, `sudo`, `git push --force`, `chmod`, `dd` and `kill -9`. Writes inside the repository run, and writes outside it ask. Network actions ask, except the supplier's own web search, which `deny network **` turns off.

The read tool refuses `.env` files, such as `prod.env` and `.env.local`, and reads `.env.example` inside the directory. These rules govern the read tool alone. A `grep` of the directory returns their contents. A shell command reads them under the shell rules. A write to one is allowed.

Narya judges a shell line on the strictest verdict across everything it really runs. A line Narya cannot parse asks, and Narya remembers nothing from it.

> [!WARNING]
>
> A non-interactive run cannot wait for a person to answer a permission ask. `narya -p` runs in that mode. Session-scoped refusal records have the audit limits below.

## Audit

***

Narya writes one row per ask and per refusal that belongs to a session, including refusals that reached no person. A refusal outside a session, or a row the store fails to write, leaves no row. The refusal still stands. Each row carries:

* the action and the resource
* which rules matched, and what a remembered allow would grant
* the status and who decided
* the reason
* the scope of the answer

Rule-derived allows carry no row.

Read the rows back with `narya permissions denied`. Add `--session <id>`, `--since <time>` or `--until <time>` to narrow the range. One page holds 100 rows, and Narya says so when it truncates.

Retention is opt-in per class and keeps everything by default. The `[retention] permission_asks` setting sweeps decided rows and keeps the pending ones.

## Attended and detached sessions

***

Every session records a posture, `attended` or `detached`. A detached session refuses and records the next prompt rather than blocking forever. Run `narya session promote <session-id>` to hand a session to the host as detached. A second run changes nothing. The host refuses it in a directory nobody trusts.

A session recorded detached in a directory nobody trusts drops back to attended at its next gate check. The trust read fails closed.


# Run Narya
Source: https://docs.lerian.studio/en/platform/narya/running-narya

Sign in, start the host, install it as a login service, manage sessions and checkpoints, and check the health of your installation.

Narya splits into a host and its clients. The host owns the store, the sessions and the model connections. A client sends a message and reads the result over the local socket. An interactive client starts a host when no host answers, and then drives it over the same HTTP API as every other client.

## Sign in to your organization

***

Set the `[identity]` table in `config.toml` with the values your organization gives you: `issuer`, `jwks_url`, `auth_url`, `device_url` and `client_id`. A host missing `issuer` or `jwks_url` refuses every request.

* `narya login` prints a URL and a short code. Open the URL on any machine with a browser, and enter the code.
* `narya whoami` reports who this machine is signed in as, with no network call.
* `narya logout` removes the sign-in.

Narya keeps the tokens and refreshes them when they expire. The interactive client and every command that talks to the running host present them. A `narya -p` run with no host running needs no sign-in.

## The host

***

**1. Start the host**

Run `narya host start`. The host takes the store lock and listens on the socket inside your Narya home directory.

**2. Check it**

Run `narya host status`. It reports whether a host runs and the state of each of its tool servers.

**3. Stop it**

Run `narya host stop`.

## Keep the host alive across logins

***

`narya daemon install` writes a login service and loads it: a LaunchAgent on macOS, and a user systemd unit on Linux. Both run `narya host start` and restart it after a failure. Narya writes the unit with `0600` permissions. It sets `NARYA_HOME` inside the unit rather than inheriting the value.

`narya daemon status` answers three questions separately: registered, loaded and serving. `narya daemon uninstall` removes the unit and nothing else. Your sessions, your store and your configuration stay.

The host and every session in it survive a closed terminal. A later `narya -p` attaches to the running host rather than opening the store itself.

> [!NOTE]
>
> `narya daemon install` is the only command that writes a service unit.

## Sessions

***

Each session binds to one repository path. Resume one with `narya -s <session-id>`, or with `narya -p --session <session-id>`.

* `narya session list` lists the sessions in the store.
* `narya export <session-id>` writes one transcript to standard output. Choose `--format markdown` or `--format jsonl`. Add `--reasoning` and `--tool-output` for more detail.
* `narya import <file> --repository <absolute path>` reads a transcript from another tool. Set `--format claudecode` or `--format opencode`.
* `narya session promote <session-id>` hands the session to the running host, so a later permission prompt in it is refused and recorded.
* `narya session share <session-id>` copies the session to your organization's home. Add `sync` to keep sending later entries.

## Share a session

***

A share copies a session to your organization's home, where your team reads it. The host redacts the entries before they leave your machine. You set the redaction rules in the `[sharing.redaction]` table of `config.toml`.

**1. Preview the share**

Call `GET /v1/sessions/{sessionId}/share/preview`. The answer carries each entry as the host would send it, and it names each rule that held something back. A preview sends nothing.

**2. Publish the session**

Call `POST /v1/sessions/{sessionId}/share` with `mode`. `once` copies the entries that exist now. `sync` also sends the entries that come later. The answer carries the new `shareId`.

Two fields of the publish are optional:

* `expiresAt` sets when the share stops. Without it, the window of the host applies. Set that window with `default_expiry` in the `[sharing]` table.
* `recipients` names the colleagues that the share is for. Without it, the share is for the whole organization. Only the owner of the session can name recipients.

A `503` with `NRY-0029` means that the host recorded the share and queued its entries, but the organization's home did not answer. The host sends the entries later. Each publish creates a new share, so a second publish of the same session creates a second share.

* `GET /v1/sessions/{sessionId}/share` lists the live shares of the session that you can change.
* `PUT /v1/shares/{shareId}/recipients` changes who a share is for.
* `DELETE /v1/sessions/{sessionId}/share` revokes every share of the session and deletes the copy at the organization's home. A `503` with `NRY-0029` means that the copy is still there. Send the request again when the home answers.
* `GET /v1/shares` on the organization's home lists the shares that you can read there.

A revoked share does not come back. To share the session again, publish it again, which creates a new share.

## Run a session in an environment

***

An environment is a separate machine that the host provisions for your sessions. A session that names no environment runs on the machine of the host. The host provisions environments only when the `NARYA_SANDBOX_IMAGE` environment variable names the image to run.

* `POST /v1/environments` creates an environment. Only `id` is required. `setupScript` runs once inside the new environment. `repository` names a repository that your organization selected in the Narya GitHub App, as `owner/name`, and the host clones it into the environment.
* `GET /v1/environments` lists your environments, and `GET /v1/environments/{environmentId}` reads one.
* `DELETE /v1/environments/{environmentId}` destroys an environment.

To run a session in an environment, put the environment id in the `environment` field of `POST /v1/sessions`.

A create is idempotent on `id`. When you send an `id` that you already created, the host answers `200` with that environment. It provisions nothing and runs no setup script.

When the setup script fails or runs past the time limit of the host, the environment is `unusable`. Its `setup` field carries the outcome and the output of the script. A session cannot run in an `unusable` environment. Destroy it, then create it again with a corrected script.

## Checkpoints and rewinds

***

Narya records restore points of your working tree in a shadow git repository beside your checkout. Your own git history never changes. No timer removes a checkpoint.

A rewind moves a session back across the conversation, the files, or both. Name the scope, because it has no default.

## Health and repair

***

`narya doctor` walks the installation and reports what it finds:

* the home directory and the configuration
* the host and the store
* the sessions, the package jobs and the tool servers
* the credentials
* the binary and the terminal

It repairs nothing. Each finding names the command that fixes it.

`narya repair <session-id>` is the way out of a quarantine. At start, Narya recovers each session an unclean shutdown left running, and quarantines one it cannot replay. This command retries that recovery. Add `--retire` to archive the session instead, with its transcript kept.

## Retention

***

Narya keeps everything until you say otherwise. Set a maximum age per class under `[retention]` in `config.toml`.

* `narya retention status` reports what a sweep would remove.
* `narya retention run` performs the sweep.
* `narya purge <session-id> --yes` removes one session and everything under it.

`narya repair`, `narya retention` and `narya purge` open the store themselves, so they refuse while a host runs. Stop it first with `narya host stop`.


# The host API
Source: https://docs.lerian.studio/en/platform/narya/the-host-api

One host, one HTTP contract over a Unix socket. Every Narya client drives the same API, and you can write your own against it.

Narya runs coding agents behind one HTTP API. One long-lived host on your machine does the work, and every client drives that one API. The API has an OpenAPI 3.1 document. Lerian generates the host's server and its own Go client from this document.

Three kinds of client speak it. The terminal client that Lerian ships opens an interactive session. The one-shot command `narya -p` runs one turn for a pipeline. A client you write drives the same operations with a token of its own.

## What the host owns

***

* **Sessions**: durable conversations, each bound to one repository path.
* **Lanes**: the parallel tracks inside a session.
* **Checkpoints and rewinds**: restore points of your working tree, and the moves back to them.
* **The store**: the database that holds the sessions and the decisions. The host takes its lock.
* **Model connections**: the host calls the model supplier with your credential.
* **Schedules**: prompts on the host's clock, under a spend ceiling.
* **Workflows**: JavaScript programs that orchestrate agents.
* **Monitors**: long-running commands beside a session, whose output reaches the conversation.
* **Permission asks**: the questions in front of a tool call, and the answers you give back.

## Reach the host

***

The host listens on a Unix socket in your Narya home. Narya creates the socket owner-only, and the socket carries no TLS.

Every request carries a bearer token from the identity provider in your `[identity]` settings. The host checks the signature, the issuer, the expiry, and the person and organization the token names. A request with no valid token gets `401` with `NRY-0011`. A caller whose role lacks the permission an operation needs gets `403` with `NRY-0028`. An operation that declares another security scheme also accepts that credential: the event stream accepts a registered extension's signed request.

The shipped clients present the token that `narya login` stored.

The socket is `narya.sock` inside your Narya home, which is `~/.config/narya` by default. Set `NARYA_HOME` to move it. Over that socket the host speaks HTTP/1.1 and answers JSON with camelCase fields. The authority in the URL carries nothing, so any name works there.

```bash theme={null}
TOKEN="an-access-token-from-your-identity-provider"
curl --unix-socket ~/.config/narya/narya.sock \
  -H "Authorization: Bearer $TOKEN" \
  http://narya/v1/host
# Answers one JSON object about the running host.
```

When a host runs, the one-shot command is itself a client of this API. A one-shot run that finds no host opens the store itself, when no other Narya process holds it.

## Results arrive on the event stream

***

A message answers `202` with a turn id. Everything that turn produces reaches you on `GET /v1/events` as server-sent events.

The `data` line carries one JSON envelope. Its `type` field says which event this is: a text delta, a tool call, a permission ask, a finished turn. A client reads one shape and branches on `type`.

Send a `Last-Event-ID` header to resume where you stopped. A cursor that names an event newer than the store answers `409`. A consumer too slow to keep up loses its own connection, and every other client keeps streaming.

Two query parameters narrow the stream. `sessionId` keeps one session. `hostEvents=true` adds the events that belong to no session, and it applies only beside `sessionId`.

`narya -p --json` prints these same envelopes, one per line. A pipeline and a client read one format. See [Automation and CI](/en/platform/narya/automation-and-ci).

## One shape for lists and errors

***

A paged list answers a cursor envelope: `items`, `limit` and a `nextCursor` when more remains. Cursors are opaque, and the API offers no offset paging. The store is append-heavy, so an offset shifts under a concurrent write.

One error envelope: `code`, `title` and `message`. A code is `NRY-` and four digits. The [error list](/en/reference/platform/narya/host-api-error-list) names each code and what to do about it.

## Read the reference

***

> **[Narya host API overview](/en/reference/platform/narya/host-api-overview)**
>
> Narya host API overview: transport, streaming, envelopes, and every operation.

> **[Narya host API error list](/en/reference/platform/narya/host-api-error-list)**
>
> Every code the host answers with, what triggers it, and the way out.


# What is Narya?
Source: https://docs.lerian.studio/en/platform/narya/what-is-narya

Narya runs coding agents behind one HTTP API. One host on your machine owns the sessions and the store, and every client drives the same contract.

Narya runs coding agents behind one HTTP API. One long-lived host on your machine owns the sessions, the store and the model connections. The terminal client and the one-shot command that Lerian ships drive that API. A client you write drives the same one.

The host owns every session. Clients reach it over a Unix socket inside your Narya home directory. Each request carries a token from the identity provider you configure, and `narya login` gets you one. A session you share is copied to your organization's home.

## Sessions, lanes, checkpoints and rewinds

***

A **session** is a durable conversation bound to one repository path. It outlives the process that opened it. An archived session takes no new work, and nothing moves it back. The transcript stays queryable and exportable.

A **lane** is a parallel track inside a session. The main lane carries your own conversation. Other lanes carry delegated work and side conversations. Plain output carries only the answer to your prompt. The `--json` output carries every lane and tags each line with its lane id.

A **checkpoint** is a restore point of your working tree. Narya keeps checkpoints in a shadow git repository beside your checkout, never in your own history. Checkpoints are permanent, and no timer removes them.

A **rewind** moves a session back across the conversation, the files, or both. The scope has no default, so you must state which of the three you mean.

## The clients Lerian ships

***

Run `narya` with no arguments to open the interactive client. The client needs a terminal on both standard input and standard output. Add `--tui` for the full-screen layout or `--no-tui` for the inline layout. Add `-s <session-id>` to resume a session.

Run `narya -p "<prompt>"` for one turn and one answer. This is the shape a pipeline uses.

Every command accepts `--json`.

## One API, any client

***

Both shipped clients drive one HTTP API. The host serves it over a Unix socket in your Narya home, and it carries the work: sessions, lanes, messages, permissions, schedules and workflows. The terminal client drives it. The one-shot command drives it too, whenever a host answers on the socket. A client you write against the same contract reaches the same operations.

[The host API](/en/platform/narya/the-host-api) describes the transport, the event stream and the envelopes.

## Where Narya keeps your data

***

Narya writes to `~/.config/narya` by default, or to `$XDG_CONFIG_HOME/narya` when that variable is set. Set `NARYA_HOME` to move that root anywhere else. Narya creates the directory with `0700` permissions.

The root holds the SQLite store, the local socket, your `config.toml` and your permission rules. It also holds the credentials directory, the identity directory, the spill and media directories, and the log file.

## What Narya reads from your existing setup

***

Narya reads Claude Code's own formats without any change: agents, skills and commands under `~/.claude`, and the `hooks` table of `~/.claude/settings.json`. It reads the same resources from a repository you trust.

MCP tool servers plug in through `config.toml`.

## How you get Narya

***

Lerian delivers Narya to licensed institutions. Contact your Lerian account team for access.

## Read next

***

> **[Run Narya](/en/platform/narya/running-narya)**
>
> Sign-in, the host, the login service, sessions and the health commands.

> **[Models and credentials](/en/platform/narya/models-and-credentials)**
>
> The three model suppliers, where your key comes from, and what leaves your machine.

> **[Permissions and trust](/en/platform/narya/permissions-and-trust)**
>
> The trust question, the rule format, and the audit you read back.

> **[Automation and CI](/en/platform/narya/automation-and-ci)**
>
> One-shot runs, exit codes, schedules and workflows.

> **[Extending Narya](/en/platform/narya/extending-narya)**
>
> Tool servers, confined scripts, the host API, agents and hooks.

> **[The host API](/en/platform/narya/the-host-api)**
>
> One contract for every client: socket, event stream, envelopes.


# About Observability
Source: https://docs.lerian.studio/en/platform/observability

Send Midaz telemetry to an OpenTelemetry collector.

Midaz exports traces, logs, and metrics through OpenTelemetry (OTLP). Run a collector, then point Midaz at it.

## 1. Run a collector

***

Use your own OpenTelemetry collector, or Alloy Lerian, the Lerian collection agent, which exports the telemetry to Lerian's central telemetry backend.

To install it, see the [Alloy Lerian chart README](https://github.com/LerianStudio/helm/tree/main/charts/alloy-lerian).

## 2. Point Midaz at the collector

***

Set `OTEL_EXPORTER_OTLP_ENDPOINT` to the collector address on the Ledger, and on Tracer when you run it.

An endpoint without `https://` is plaintext. When `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` is `production`, the Ledger does not start with a plaintext exporter unless `ALLOW_INSECURE_OTEL` names a reason, for example `ALLOW_INSECURE_OTEL="node-local collector"`.

For how the Midaz chart sets these variables, see the [Midaz chart README](https://github.com/LerianStudio/helm/tree/main/charts/midaz).

For the telemetry variables of the other Lerian services, see [BYOC configuration essentials](/en/reference/byoc-configuration#observability).


# Consuming events
Source: https://docs.lerian.studio/en/platform/streaming-hub/consuming-events

Consume events from Streaming Hub: verify webhook HMAC signatures, handle rotation, read X-Lerian headers, deduplicate deliveries, and pull with cursor ack.

Streaming Hub delivers events two ways. **Push** sinks (`webhook`, `sqs`, `rabbitmq`, `eventbridge`) send each matched event to a destination you own. A **pull** sink holds events on a server-side cursor that your consumer reads on its own schedule. This page covers what your consumer must do in each case.

## Verifying a webhook signature

***

Streaming Hub signs every webhook delivery with an HMAC over the request timestamp and the exact request body. The signature proves that the request came from Streaming Hub, and that it was not tampered with or replayed. Two headers carry the signature:

| Header | Value |
| - | - |
| `X-Webhook-Signature` | The signature, in the form `v1,sha256=<hex>`. |
| `X-Webhook-Timestamp` | The Unix-seconds timestamp folded into the signature. |

The signature formula is:

```
signature_input = "v1:" + X-Webhook-Timestamp + "." + <raw request body>
X-Webhook-Signature = "v1,sha256=" + hex( HMAC-SHA256(key = signing_secret, message = signature_input) )
```

To verify a delivery:

1. **Read the raw body and the timestamp**: verify before parsing the body, over the exact bytes received. Any re-serialization changes the bytes and breaks the signature.
2. **Check freshness**: reject the request if `X-Webhook-Timestamp` is more than 5 minutes from now. This is the replay-protection window.
3. **Recompute the signature**: build `signature_input` as above with your signing secret and hex-encode the HMAC-SHA256.
4. **Compare in constant time**: compare your `v1,sha256=<hex>` against the received `X-Webhook-Signature` with a constant-time (timing-safe) comparison. Reject on mismatch.
5. **Respond**: return `2xx` only after the signature and freshness both pass.

You receive the signing secret when you create the subscription, or when you last rotate it. Streaming Hub never sends the secret in a header. The header carries only the derived signature. See [creating a webhook subscription](/en/platform/streaming-hub/managing-subscriptions) for where the secret comes from.

## Handling two signatures during rotation

***

When you [rotate a signing secret](/en/platform/streaming-hub/managing-subscriptions), the hub runs a **24-hour dual-sign overlap**. During the overlap each delivery carries two `X-Webhook-Signature` headers, one signed with the new secret and one with the previous secret. The hub sends them as repeated headers, so you can migrate to the new secret without dropping any delivery.

Verify against both: recompute the expected signature with each secret you currently hold, and accept the request if either received signature matches. Once you have deployed and confirmed the new secret, retire the old one.

> [!WARNING]
>
> Read `X-Webhook-Signature` as a list of repeated header values using your framework's multi-value header accessor (or its raw-headers view). Do not split a single joined string on commas: the signature value itself contains a comma (`v1,sha256=…`), so a naive comma-split corrupts it. Some HTTP stacks join repeated headers with `", "` by default. Use the list accessor to get each value intact.

## Correlation headers

***

Every webhook delivery also carries a set of `X-Lerian-*` context headers:

| Header | Carries |
| - | - |
| `X-Lerian-Event-Id` | The stable event id (the CloudEvents `ce-id`). It is the deduplication key and stays constant across redeliveries of the same event. |
| `X-Lerian-Event-Type` | The event type, as the bare `<resource>.<event>` tail (for example, `transaction.created`). |
| `X-Lerian-Tenant-Id` | The owning tenant id (attribution only). |
| `X-Lerian-Delivery-Id` | The per-attempt id. It changes on every retry of the same event. |
| `X-Lerian-Schema-Version` | The payload schema version. |

> [!WARNING]
>
> Webhook delivery carries no producer-source header. `X-Lerian-Event-Type` is deliberately source-free, so a consumer cannot distinguish two producers that emit the same key unless the subscription pins `origin`. Create one origin-pinned subscription per producer when source identity matters.

## Deduplicating deliveries

***

Delivery is **at-least-once**: the hub may deliver the same event more than once, through retries or a redelivery after a worker restart. Deduplicate on `X-Lerian-Event-Id`. It is stable across every redelivery of the same event, while `X-Lerian-Delivery-Id` differs per attempt. Treat a `X-Lerian-Event-Id` you have already processed as a duplicate: acknowledge it with a `2xx` and do not reprocess. Keep your handler idempotent.

## Responding quickly

***

Return a `2xx` as soon as you have verified and durably accepted the event. Then do the real work asynchronously. The hub treats a failing response, or one slower than the subscription's attempt timeout (10 seconds by default), as a failed delivery. A failed delivery triggers the [retry curve](/en/platform/streaming-hub/how-streaming-hub-works). If the destination stays broken long enough, the hub eventually [auto-disables](/en/platform/streaming-hub/how-streaming-hub-works) the subscription.

## Pulling events

***

A `pull` subscription receives no push. Instead, your consumer reads a page of its events with:

```
GET /v1/events?subscription_id=<uuid>
```

The events come back in ascending arrival order, each with its `seq`, its `ceId` (for dedup), its type, and its payload. The response includes a `next_cursor`.

**The read is the acknowledgment (cursor-as-ack).** Fetching a page advances the subscription's durable cursor to the highest `seq` returned. There is no separate ack call. Reading a page acknowledges it. This is monotonic, so it never moves backward.

To page through normally, resume from the server's `next_cursor` and stop when a short page (fewer than your `limit`) returns `null`. Two behaviors to keep in mind:

* **A forward `?after=` seek can forfeit the gap.** When you pass `?after=N` greater than your current cursor and the read returns events, the cursor advances past everything up to `N`. A later read without `?after=` does not return the skipped events. This can only happen with a hand-crafted forward seek, never through normal `next_cursor` pagination.
* **A backward `?after=` seek never rewinds.** A stale or lower `?after=` that reads an older page does not move the cursor back, because the cursor only ever advances.

The pull read is rate-limited per tenant. A denied read returns `429` with the code `rate_limited`: wait the `Retry-After` seconds, then retry. A `503` means the hub could not check the allowance, or Access Manager returned no verdict. Retry with backoff. Deduplicate pulled events on `ceId`, just as a webhook consumer deduplicates on `X-Lerian-Event-Id`.

## Next steps

***

> **[Managing subscriptions](/en/platform/streaming-hub/managing-subscriptions)**
>
> Create subscriptions, rotate secrets, and recover disabled destinations.

> **[Operating Streaming Hub](/en/platform/streaming-hub/operating-streaming-hub)**
>
> Deploy, configure, and observe the hub.


# How Streaming Hub works
Source: https://docs.lerian.studio/en/platform/streaming-hub/how-streaming-hub-works

The path an event takes through Streaming Hub: ingest, classification, consume-once deduplication, subscription matching, dispatch, retries, and dead-letters.

An event moves through Streaming Hub in three stages. The hub **ingests** it from the internal stream, **matches** it against your subscriptions, and **dispatches** it to each matched destination. This page walks through each stage and the delivery guarantees that fall out of it.

## Ingesting events from the stream

***

Streaming Hub consumes the platform stream as **CloudEvents 1.0** messages in **binary content mode**. The CloudEvents context attributes travel in Kafka record headers (each prefixed `ce-`). The event body is the record value. The hub reads routing and identity from the headers.

The hub subscribes only to v3 **application fact topics**:

```
lerian.streaming.<ce-source>
```

`ce-source` is one lowercase, dot-free segment. It uses letters, digits, underscores, or hyphens. The topic carries no resource, event, or schema-major suffix. The hub dispatches by CloudEvents headers. The follow set excludes command topics (`.commands`) and dead-letter topics (`.dlq`).

A second consumer reads the `.dlq` topics that producers write. That consumer serves observability only. The follow-set grammar excludes a trailing `.dlq`, so a dead-letter record never becomes a delivery to one of your subscriptions. Operators read those records through `GET /admin/dlq`. See [DLQ forensics](/en/platform/streaming-hub/operating-streaming-hub).

Every record the hub accepts must carry this context set:

| Header | Requirement |
| - | - |
| `ce-specversion` | The CloudEvents spec version. |
| `ce-id` | A unique event id. It must be a UUIDv7. It is the deduplication and correlation key. This tightens the [shared envelope contract](/en/reference/events/overview), where `ce-id` is opaque: the hub quarantines a record whose id is not a UUIDv7, and it deduplicates ids within a tenant. |
| `ce-source` | The producing service. |
| `ce-type` | The event type, exactly `studio.lerian.<source>.<resource>.<event>`; `<source>` must equal `ce-source`. |
| `ce-time` | The emission timestamp. |
| `ce-schemaversion` | The payload schema version. |
| `ce-resourcetype` | The resource segment (for example, `account`). |
| `ce-eventtype` | The event segment (for example, `created`). |
| `ce-tenantid` | The owning tenant, and the only source of tenant identity at ingest. A record missing it is quarantined. |

For each record the hub returns one of three **verdicts**:

| Verdict | When | Outcome |
| - | - | - |
| **Accept** | A well-formed event with a non-empty tenant id. | Persisted to the event inbox and matched against subscriptions for that same tenant. |
| **Drop** | A system event. | Counted and skipped; the stream position still advances. No event is stored. |
| **Quarantine** | A malformed event, or one missing its tenant. | Not retried. A malformed record never becomes valid on replay. |

The tenant admitted at ingest comes only from the validated `ce-tenantid` attribute the parser extracted. Ingest has no tenant-roster drop gate. Stored events match only subscriptions with the same tenant id.

> [!NOTE]
>
> Three related strings look alike but are distinct. Never conflate them:
>
> * **`ce-type`** is the source-qualified CloudEvents type: `studio.lerian.<source>.<resource>.<event>` (for example, `studio.lerian.lender.loan_application.approved`).
> * **Kafka topic** is one v3 fact topic per application: `lerian.streaming.<source>` (for example, `lerian.streaming.lender`). Resource, event, and schema major do not appear in the topic.
> * **`X-Lerian-Event-Type`** is the bare `<resource>.<event>` key on a delivered webhook (`loan_application.approved`). It intentionally omits the producer. Use a subscription `origin` pin when the same key can come from more than one application.
>
> See the [event streaming overview](/en/reference/events/overview) for the full wire contract.

## Consume-once deduplication

***

The internal stream is at-least-once, so the same record can arrive more than once. On the way into the event inbox the hub deduplicates on `ce-id`. A duplicate id writes nothing and counts as a dedup drop. The hub persists records per Kafka partition in one transaction. It commits the stream position for a partition only after that partition's write commits. A failure on one partition therefore never loses or double-commits events on another.

## Subscription matching

***

Matching admits a subscription only when it is both `enabled` and in `verification_state = active`. These are two independent conditions, and matching requires both. See [the subscription model](/en/platform/streaming-hub/managing-subscriptions).

An event no subscription wants produces zero deliveries. That is a correct outcome, not an error.

## Dispatching to your destinations

***

For every match, the hub creates a delivery job and hands it to a worker pool (eight workers by default). Workers claim due jobs atomically with a short lease and interleave across tenants, so no single tenant's backlog starves the others. Each worker loads the stored payload, decrypts the destination's signing secret or credential in memory, and makes exactly one delivery attempt to the sink.

Delivery is **at-least-once**: the hub may deliver the same event more than once (through retries or redeliveries after a worker restart). See [Consuming events](/en/platform/streaming-hub/consuming-events) for the consumer side of this contract.

## Retries and back-off

***

When an attempt fails, the hub schedules the next one on a fixed back-off curve with full jitter:

```
0 · 5s · 5m · 30m · 2h · 5h · 10h · 10h
```

The curve spans roughly 28 hours across its eight steps.

## Dead-lettering

***

The hub **dead-letters** an event that exhausts its retries. The hub stops attempting it and records the terminal outcome. The hub reclaims a job that instead keeps crashing a worker mid-attempt and never records an outcome. The reclaim limit is five by default. The hub then dead-letters it as poison, so a single toxic job can never occupy a worker forever.

## Circuit breaker

***

Each `(tenant, destination)` pair has a circuit breaker. When a destination fails repeatedly, its breaker opens. Further jobs for that destination are **shed** (rescheduled without an attempt). A single broken endpoint does not burn worker capacity or hammer a struggling target. The breaker recovers on its own once the destination starts succeeding again.

## Auto-disabling a broken destination

***

The hub automatically disables a destination that stays broken for a long time. Auto-disable trips only when the open failure span is both:

* **sustained**: it lasts at least the failure window (120 hours by default), and
* **spread**: at least 12 hours separate the first and last failure in the span.

Both gates must hold, and a single successful delivery clears the span, so a brief blip never accumulates toward the verdict. When auto-disable trips it flips the subscription's `enabled` flag to `false`. It never touches `verification_state`. Delivery stops (matching requires `enabled`), and the hub records why.

You recover an auto-disabled subscription with `POST /v1/subscriptions/:id/verify`, which re-probes the destination and, on success, re-enables it in place. An operator can turn auto-disable off with `STREAMING_HUB_AUTODISABLE_ENABLED`. See [recovering an auto-disabled subscription](/en/platform/streaming-hub/managing-subscriptions).

## Ordering guarantees

***

Producers partition the stream by tenant, so one tenant's events normally ride a single partition. The hub stores them in that order and gives each one an arrival sequence (`seq`). A pull consumer reads events in `seq` order.

Push delivery does not keep that order. Workers deliver in parallel, and a retry sends a failed event after the events that followed it.

The hub attributes and deduplicates on the CloudEvents headers, not the Kafka record key. A producer that spreads (salts) a hot tenant across several partitions keeps attribution correct, but `seq` then reflects the order events *arrived* at the hub, not the order they were *produced*.

## Next steps

***

> **[Managing subscriptions](/en/platform/streaming-hub/managing-subscriptions)**
>
> The subscription model, onboarding flows, and secret rotation.

> **[Consuming events](/en/platform/streaming-hub/consuming-events)**
>
> Verify signatures, deduplicate, and pull events.


# Managing subscriptions
Source: https://docs.lerian.studio/en/platform/streaming-hub/managing-subscriptions

Create webhook and queue subscriptions in Streaming Hub, wire an AWS delegated grant, rotate signing secrets, recover auto-disabled destinations, and re-pin.

A **subscription** tells Streaming Hub which events go to which destination for your tenant. You manage subscriptions through the `/v1` control-plane API, authenticated with an Access Manager token. This page covers the model and the onboarding flows. The API reference has the exact request and response shapes (start from the [reference introduction](/en/reference/introduction)).

## The subscription model

***

A subscription records:

* **`name`**: a human label (required, non-blank). A subscription that is not deleted and already holds the name makes the create return `409 subscription_name_taken`.
* **`sink_kind`**: one of `webhook`, `pull`, `sqs`, `rabbitmq`, `eventbridge`.
* **`endpoint`**: where deliveries go, in a shape that depends on the sink kind (see below).
* **`event_types`**: the keys to deliver. Take each key from the `eventKey` field of `GET /v1/catalog`, exactly as served. The hub accepts any well-formed key, so a catalog gap never stalls onboarding. A key that no producer emits matches nothing. Omit the field to receive every event type.
* **`schema_major`**: the payload major version the subscription follows. Omit it to follow major version 1.
* **`timeout_ms`**: for a webhook only, the per-attempt delivery timeout, from 1000 to 20000 milliseconds. The default is 10000.
* **`plan_tier`**: the delivery tier the subscription runs under.

The endpoint format follows the sink kind:

| Sink kind | Endpoint |
| - | - |
| `webhook` | An `https://` URL, no embedded userinfo. |
| `pull` | Omitted. The server synthesizes `pull://<id>`. |
| `sqs` | The `https://` SQS queue URL. |
| `rabbitmq` | `<exchange>/<routingKey>` (exchange required, routing key optional). The broker host lives in the encrypted credential. |
| `eventbridge` | The EventBridge event-bus name. `DetailType` is derived from the matched event type. The region lives in the encrypted credential. |

> [!WARNING]
>
> Queue delivery does not preserve the canonical source-qualified `ce-type`. SQS and RabbitMQ set `ce-type` to the bare `<resource>.<event>` key. EventBridge uses that bare key for `DetailType` and `Detail.type`, and its `source` identifies the hub rather than the producer. Pin `origin` and keep the subscription identity alongside the delivery when producer identity matters.

### Two orthogonal status fields

***

Every subscription carries two independent status fields. Confusing them is the most common source of "why did delivery stop" questions, so keep them separate:

* **`verification_state`** is **proof** that the destination can receive events. It moves through `pending_verification` → `active` → `degraded`, driven by probes. Only an `active` subscription is deliverable.
* **`enabled`** is the **deliverability switch**. It is what auto-disable flips off, and what a re-enable turns back on.

Subscription matching requires both: a subscription delivers only when `enabled` and `verification_state = active`. Auto-disable lives entirely in `enabled` and never changes `verification_state`, so an auto-disabled subscription reads as `enabled = false, verification_state = active`. See [auto-disabling a broken destination](/en/platform/streaming-hub/how-streaming-hub-works) for how the two interact.

## Creating a webhook subscription

***

A webhook subscription is the simplest to onboard. It needs no credential, only one probe:

1. **Create**: `POST /v1/subscriptions` with `sink_kind: "webhook"` and your `https://` endpoint. Send a unique `X-Idempotency` header: the hub rejects a create that omits it, before any write. The hub validates the destination URL against private, loopback, and cloud-metadata address ranges before any write. The response returns the new subscription in `pending_verification`, and the signing secret.
2. **Save the signing secret**: no read route returns it. A retry with the same `X-Idempotency` key returns the same response. The hub stores the secret only as ciphertext. If you lose it, you can only rotate to a new one.
3. **Activate the destination**: `POST /v1/subscriptions/:id/ping` sends a synthetic, signed probe through the real delivery path and reports the classified outcome. A successful probe moves the subscription to `active`, and that is what makes it deliverable. Deploy your endpoint before you ping: it must answer `2xx`.

After the probe succeeds, matching admits the webhook subscription and it starts to receive events. For the full walkthrough from create to a first confirmed delivery, see the [quick start](/en/platform/streaming-hub/streaming-hub-quick-start). See [Consuming events](/en/platform/streaming-hub/consuming-events) for how to verify the signature on each delivery.

## Onboarding a queue subscription

***

Queue subscriptions (`sqs`, `rabbitmq`, `eventbridge`) are born `pending_verification` and deliver nothing until a probe verifies their destination. How you verify depends on the kind:

* **RabbitMQ**: supply a broker credential, verified on write (below).
* **SQS and EventBridge**: either supply an outbound credential, verified on write (below), or [wire an AWS delegated grant](#wiring-an-aws-delegated-grant) (next section) without storing a credential.

For any queue kind, the outbound-credential flow is three steps:

1. **Create**: `POST /v1/subscriptions` with the queue `sink_kind` and its endpoint, and no inline credential (the hub rejects an inline `sink_config` or `credential`). Send a unique `X-Idempotency` header, as for any create. The hub stores the subscription `pending_verification`. Matching excludes it, so it produces no delivery jobs yet.
2. **Supply the credential**: `PUT /v1/subscriptions/:id/credential` with the write-only outbound credential. The hub holds it in memory, probes it immediately (connect and authenticate against the destination), and persists it as ciphertext only if the probe succeeds. A failed probe stores nothing. The hub validates destination addresses against blocked ranges before storage. A successful probe moves the subscription to `active`.
3. **Active**: once `active`, matching admits the subscription and it begins receiving events.

The credential is **write-only**: you supply it here and no read path ever returns it, not even masked. To change it, `PUT` a new one. The same probe-on-write applies.

## Wiring an AWS delegated grant

***

For the credentialless AWS path (`sqs`, `eventbridge`), the hub delivers by assuming a role in your AWS account. You wire that trust instead of supplying an outbound credential:

1. **Fetch the setup artifacts**: `GET /v1/subscriptions/:id/setup-artifacts` returns a cross-account IAM **trust policy**, a CloudFormation **quick-create link**, and a non-secret **`ExternalId`** the hub mints for this subscription.
2. **Apply them in your AWS account**: create the delivery role from the trust policy (the quick-create link scaffolds it). The role trusts the hub's principal *only* under the minted `ExternalId` condition. That condition closes the confused-deputy gap. A trust policy that omits it fails verification, and never counts as verified.
3. **Register the grant**: `PUT /v1/subscriptions/:id/delegated-grant` with the delivery role ARN, region, and destination. This records non-secret coordinates only. It runs no probe and does not change `verification_state`.
4. **Verify**: `POST /v1/subscriptions/:id/verify` runs the hardened role-assumption probe and, on success, flips the subscription to `active`.

No AWS credential crosses these requests. The hub reaches your account by assuming your role under the `ExternalId`.

## Rotating a signing secret

***

`POST /v1/subscriptions/:id/secret/rotate` mints a new webhook signing secret, returns it, and starts a **24-hour dual-sign overlap**. During the overlap the hub signs each delivery with both the new and the previous secret and sends two signature headers. Your consumer can therefore switch to the new secret at any point in the window without dropping deliveries.

Rotate cleanly like this:

1. Call rotate and save the new secret from the response (alongside the `overlapUntil` timestamp).
2. Deploy the new secret to your consumer within the overlap window. While your verifier holds both secrets, it accepts a delivery if either signature validates.
3. After the overlap, retire the old secret.

Only a webhook subscription has a signing secret. The hub rejects rotation for every other sink kind. See [handling two signatures during rotation](/en/platform/streaming-hub/consuming-events) for the consumer-side verification.

## Recovering an auto-disabled subscription

***

When a destination stays broken long enough, the hub [auto-disables](/en/platform/streaming-hub/how-streaming-hub-works) the subscription by flipping `enabled = false`. To recover it:

1. Fix the destination (the endpoint, the queue, or the grant).
2. Call `POST /v1/subscriptions/:id/verify`. It re-probes the destination. On a successful probe, it re-enables the subscription and clears the auto-disable mark, in place and with the same id and signing secret.

A failed re-probe does not re-enable the subscription, and it moves an `active` verification state to `degraded`. Call `GET /v1/subscriptions/:id/health` for the delivery-health rollup (recent outcomes, dead-letter counts, and the auto-disable verdict). Use it to confirm the destination is healthy before and after.

## Changing the schema pin and the timeout

***

`PATCH /v1/subscriptions/:id` changes two fields. Every body must carry `schema_major`:

* `{"schema_major": 2}` pins the subscription to that major version.
* `{"schema_major": null}` clears the pin, so the subscription follows major version 1.
* On a webhook, add `"timeout_ms"` to change the per-attempt timeout, or send `0` to return to the 10000 default. Send the current `schema_major` with it to keep the pin.

The hub rejects any other field, a body without `schema_major`, or a `schema_major` below `1`. It never silently ignores them, so you can never believe a forbidden change took effect. The `event_types` and `origin` fields are immutable. Create a new subscription when either filter must change.

A `PATCH` never changes the endpoint, the sink kind, or the secret. It does not reset `verification_state` and echoes no secret.

## Idempotency

***

The mutating routes (create, delete, `PATCH`, secret rotate, and delegated-grant registration) require an idempotency key:

```
X-Idempotency: <your-unique-key>
```

The hub rejects a mutation sent without it before any write, with `400 missing_idempotency_key`. The store is **fail-closed**: if the idempotency store is unreachable, the request fails rather than risking a double write. That guarantees a replayed create or rotate returns the original secret instead of minting a new one.

* Replaying a committed key within its retention window (24 hours by default) returns the original response byte-for-byte, with `X-Idempotency-Replayed: true`.
* Reusing a key while its first request still runs, or with a *different* request body, returns `409 idempotency_conflict`. Mint a new key for a corrected request.

The verification routes (`ping`, `verify`, `PUT /credential`, `GET /setup-artifacts`) are naturally idempotent and require no key. See the platform-wide guidance on [retries and idempotency](/en/reference/retries-idempotency).

## Next steps

***

> **[Consuming events](/en/platform/streaming-hub/consuming-events)**
>
> Verify webhook signatures, deduplicate deliveries, and pull events.

> **[How Streaming Hub works](/en/platform/streaming-hub/how-streaming-hub-works)**
>
> Matching, dispatch, retries, and auto-disable in detail.


# Operating Streaming Hub
Source: https://docs.lerian.studio/en/platform/streaming-hub/operating-streaming-hub

Deploy Streaming Hub with Helm in BYOC, run out-of-band migrations, wire liveness and readiness probes, set essential config, and observe the hub via OTLP.

This page is for operators who run Streaming Hub in their own infrastructure (BYOC). It covers deployment, the configuration that matters, the health and shutdown contract, and how to observe the service.

## Deploying with Helm

***

Streaming Hub ships as a dedicated Helm chart, `streaming-hub-helm`, separate from any other Lerian product chart. The chart runs the hub in one of two shapes:

* **`all`**: a single deployment that runs every background worker. This is the default and the simplest to operate.
* **`split`**: separate **ingest** and **delivery** deployments that scale independently: ingest replicas share one Kafka consumer group, while delivery replicas work delivery jobs from Postgres.

The split shape is driven per process by `STREAMING_HUB_ROLE` (`all` | `ingest` | `delivery`). The role gates which background workers run and which Kafka clients dial. It does not gate which HTTP routes mount. Every role serves the full control-plane API and the `/readyz` endpoint your orchestrator depends on. There is one image and one binary.

## Running database migrations

***

Streaming Hub uses a single hub-owned PostgreSQL database, version 15 or later, and it never migrates itself. Schema migrations run out of band: the chart runs them in a Helm pre-install and pre-upgrade Job before the hub starts. The hub only *checks* that the database is at the schema version it expects. A replica whose schema does not match reports `Down` on `/readyz`.

The hub creates its own weekly table partitions ahead of time as a background task. This routine task is not a schema migration and needs no operator action. Partition retention is off by default (`STREAMING_HUB_PARTITION_RETENTION_ENABLED=false`), so the hub keeps stored events until you turn it on. When you turn it on, `STREAMING_HUB_PARTITION_RETENTION_HORIZON` sets the retention window (default `2160h`, 90 days). The horizon must be at least `STREAMING_HUB_PARTITION_FUTURE_BUFFER_WEEKS` × 7 days, or boot fails. The shortest horizon is therefore 7 days (`168h` with a 1-week buffer).

## Health and graceful shutdown

***

Streaming Hub exposes two distinct probe endpoints. Wire each to the matching Kubernetes probe:

| Endpoint | Probe | Behavior |
| - | - | - |
| `/healthz` | Liveness | Returns `200` unconditionally once the process is serving, independent of Postgres, Kafka, or application-ingest consumer health. A failing liveness restarts the pod, so it must not depend on dependencies. |
| `/readyz` | Readiness | Folds the full probe set for the role. `Healthy` or `Degraded` → `200` (kept in rotation); `Down` → `503` (pulled from rotation). A `Degraded` replica keeps serving. |

`/readyz` distinguishes two failure classes. A **runtime-probe** failure (Postgres unreachable, consumer dead) takes the replica **Down** and out of rotation. A **degrader** (high latency, consumer lag, a thin partition buffer) clamps the replica to **Degraded** but keeps it serving. An impaired replica should not refuse traffic. The probe set is role-aware. A missing ingest consumer never makes a delivery-role pod unready.

On `SIGTERM` the hub drains gracefully. It flips `/readyz` to `NotReady` first, before it stops serving. It then waits a bounded pre-stop window, so the orchestrator can pull the pod from the service before connection teardown. The `/healthz` endpoint stays `200` throughout, so the orchestrator does not kill the pod mid-drain. It then stops its components in dependency order.

> [!WARNING]
>
> Set the deployment's `terminationGracePeriodSeconds` at or above the hub's drain ceiling, not a fixed number. The ceiling is the pre-stop window, plus the shutdown timeout, plus the shutdown timeout again, plus 15 seconds of fixed margin. At the defaults (a 5-second pre-stop window and a 30-second shutdown timeout) it is 80 seconds.
>
> A grace period below the ceiling risks a `SIGKILL` of a still-draining replica. That is safe for correctness, but it forfeits the clean drain. The hub reclaims and redelivers in-flight jobs, and the consumer deduplicates them.

`/version` (build identity) and `/runtime` (a cheap Go-runtime snapshot) round out the unauthenticated operational surface for incident triage.

## Essential configuration

***

Streaming Hub reads its configuration from `STREAMING_HUB_*` environment variables, plus shared `PLUGIN_AUTH_*`, `RATE_LIMIT_*`, and `OTEL_*` variables and the unprefixed `ENV_NAME` and `ALLOW_RATELIMIT_FAIL_OPEN`. The variables you set most often:

| Variable | Default | Purpose |
| - | - | - |
| `STREAMING_HUB_ENV` | `local` | Deployment environment (`local` \| `staging` \| `production`). `staging` and `production` refuse the development bypass flags. |
| `STREAMING_HUB_ROLE` | `all` | Deployable slice: `all` \| `ingest` \| `delivery`. Gates workers and Kafka clients, never routes. |
| `STREAMING_HUB_HTTP_LISTEN_ADDR` | `:8080` | The single control-plane bind address. |
| `STREAMING_HUB_POSTGRES_DSN` | *(required)* | The hub-owned PostgreSQL DSN. Boot fails if empty. |
| `STREAMING_HUB_KAFKA_BROKERS` | *(empty)* | Bootstrap broker list for the internal stream. |
| `STREAMING_HUB_REDIS_ADDRESS` | *(required)* | `host:port` of the Redis or Valkey that counts the per-tenant rate limits. Every role needs it. Boot fails if empty. TLS is on by default (`STREAMING_HUB_REDIS_TLS`). |
| `RATE_LIMIT_ENABLED` | `false` | Must be `true`. Boot fails otherwise. |
| `ALLOW_RATELIMIT_FAIL_OPEN` | `false` | `true` serves the rate-limited routes unmetered while Redis is unreachable. `false` answers them `503`. |
| `STREAMING_HUB_DASHBOARD_CURSOR_HMAC_KEY` | *(required)* | Standard base64 of exactly 32 random bytes. It signs the dashboard page cursor. Boot fails if it is empty or malformed. |
| `STREAMING_HUB_TENANT_ID` | *(required)* | The tenant every control-plane request acts as. Boot fails if empty. See the warning below. |
| `STREAMING_HUB_MANIFEST_SOURCES` | *(empty)* | Comma-separated producer base URLs whose manifests populate the catalog in BYOC mode. Invalid URLs fail boot. |
| `STREAMING_HUB_MANIFEST_CLIENT_ID` | *(empty)* | Optional client id used to fetch BYOC producer manifests. Set it together with `STREAMING_HUB_MANIFEST_CLIENT_SECRET`; leaving both empty uses anonymous fetches. |
| `STREAMING_HUB_MANIFEST_CLIENT_SECRET` | *(empty)* | Optional client secret for manifest fetches. Setting only one manifest credential fails boot. |
| `STREAMING_HUB_KEK_SOURCE` | `env` | Key-encryption-key provider (`env` \| `secretsmanager`). |
| `STREAMING_HUB_KEK_REF` | *(required in `staging` and `production`)* | The **name** of the env var holding the KEK material, never the material itself. |
| `PLUGIN_AUTH_ADDRESS` | `http://localhost:4000` | The Access Manager authorization base URL for control-plane requests. |
| `PLUGIN_AUTH_ENABLED` | `true` | Master auth switch. `false` is a local bypass, refused in `staging` and `production`. |
| `STREAMING_HUB_AUTODISABLE_ENABLED` | `true` | `false` turns auto-disable off. |
| `STREAMING_HUB_SHUTDOWN_TIMEOUT` | `30s` | Graceful-drain window. It must be below `35s`, or boot fails. |
| `STREAMING_HUB_AWS_HUB_PRINCIPAL_ARN` | *(empty)* | The hub's public IAM principal embedded in AWS setup artifacts. Required for AWS sinks. |
| `STREAMING_HUB_AWS_SETUP_TEMPLATE_URL` | *(empty)* | The public CloudFormation template URL for the AWS quick-create link. |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | *(empty)* | The OTLP collector endpoint telemetry exports to (no `STREAMING_HUB_` prefix). |

When Access Manager returns no verdict on a request, the hub answers `503` with the code `service_unavailable` on every authorized route, `GET /admin/dlq` included. Retry with backoff.

Removing a URL from `STREAMING_HUB_MANIFEST_SOURCES` stops future refreshes from that producer but keeps its last-known-good catalog rows. Manifest refresh is control-plane discovery only. A producer outage does not block event ingest or delivery matching.

Secret **values** never belong in committed configuration. You reference the KEK by the *name* of the env var that the deploy layer injects it into (`STREAMING_HUB_KEK_REF`). The hub reads the material from that named variable and never logs it. Deployment-level Kafka SASL and TLS material, the dashboard cursor key, and Redis credentials must come from your secret store.

> [!WARNING]
>
> **`STREAMING_HUB_TENANT_ID` must match the `ce-tenantid` your producers stamp.** Ingest stores each event under its `ce-tenantid`. Subscriptions created through `/v1` belong to `STREAMING_HUB_TENANT_ID`. When the two differ, creates succeed and events are stored, but no producer event matches a subscription or reaches a pull read. The hub reports no error. A value other than `default` emits one startup warning.
>
> Access Manager is the only authorization gate: every principal it grants the Streaming Hub `subscriptions` permission acts on this tenant. Grant it only to this tenant's principals.

## DLQ forensics

***

`GET /admin/dlq` is the operator forensics surface for dead-letter observations. It is cross-tenant by design. Access Manager authorizes it on the `admin_dlq` resource with the `get` action, and it returns records across all tenants. It is therefore not part of the `/v1` API.

The dead-letter observations it reads are observability only. They come from upstream producers' dead-letter topics, and the hub never re-delivers them. Use it to investigate why records failed upstream. It does not replay them.

## Topic reconciler

***

The topic reconciler is a read-only drift detector, enabled by default (`STREAMING_HUB_RECONCILER_ENABLED`). On each pass it compares the live broker topics, the event catalog, and the distinct subscription targets. It flags three kinds of drift:

* **ghost topics**: a followed topic with no catalog entry.
* **dead subscriptions**: a subscribed event type and major with no live catalog entry.
* **lag-versus-retention** breaches.

It detects, never corrects. It emits count-only gauges and structured logs, and writes no broker or database state. Disabling it removes an operational alarm and never affects delivery.

## Observability

***

Streaming Hub exports its metrics, traces, and logs through OTLP, pointed at the collector in `OTEL_EXPORTER_OTLP_ENDPOINT`. That is where the real `streaming_hub_*` metrics live.

> [!NOTE]
>
> The `/metrics` endpoint is almost empty by design: it serves only the static `streaming_hub_build_info` gauge. Scrape the hub's real metrics from your OTLP collector, not from `/metrics`.

Tenant identity is never a metric label. It lives on span attributes and log fields, so the metric cardinality stays bounded no matter how many tenants a deployment serves.

## Next steps

***

> **[How Streaming Hub works](/en/platform/streaming-hub/how-streaming-hub-works)**
>
> The delivery internals behind the operational surfaces above.

> **[Managing subscriptions](/en/platform/streaming-hub/managing-subscriptions)**
>
> The control-plane operations your tenants use.


# Streaming Hub in Lerian Console
Source: https://docs.lerian.studio/en/platform/streaming-hub/streaming-hub-in-lerian-console

Open the Streaming Hub module in Lerian Console: follow event delivery on the dashboard, search the event catalog, and create and manage subscriptions.

The **Streaming Hub** module in Lerian Console shows how the Hub delivers your events. Use it to follow delivery, read the event catalog, and manage subscriptions. [Managing subscriptions](/en/platform/streaming-hub/managing-subscriptions) covers the same subscription tasks through the API.

## Accessing Streaming Hub

***

The module works only when Streaming Hub is on for your organization. An administrator turns it on in **Settings** > **Products**. See [Products](/en/platform/console/settings-products).

Open the product launcher in Lerian Console and select **Streaming Hub**. The sidebar has three entries: **Dashboard**, **Event Catalog**, and **Subscriptions**.

When Streaming Hub is off, the module pages show a notice that points to this setting.

## Dashboard

***

The module opens on the **Dashboard**. It shows event delivery, as the Hub measured it.

Select the period at the top: **1h**, **6h**, **24h**, or **48h**. The default is 24 hours. For a different window, choose **Custom**, then set a **Start** and a **Duration**. The start must be in the past.

The dashboard shows:

* **Current state**: the subscriptions at the moment of the snapshot, counted by switch, by verification state, by destination kind, and by channel.
* **Events received**: the events the Hub received in the period, with a chart per hour or per UTC day. This is not a delivery count.
* **Push delivery**: the delivery jobs created, and the delivery attempts by outcome, such as **Delivered** or **Failed**.
* **Push backlog**: the delivery jobs waiting, and how long the oldest one has waited.
* **Pull eligibility**: the events that pull consumers had the right to read, and the eligible subscription matches. The Hub does not report what a consumer read.

Under them, **Needs attention** lists the subscriptions that need an operator's attention in the period. Each row shows the destination, the verification, the state, the last success and failure, and the attempt counts. The **Reasons** column says why the row is there, for example **Automatically disabled** or **Destination not verified**.

## Event catalog

***

**Event Catalog** lists the events that producers advertise, and how current each one is. The page groups the events by topic. Each event shows its event key, its schema version, a description, its resource, and its source.

The event key is the value that a subscription takes as an event type.

Each topic shows a freshness badge for each producer, such as **Refreshed** or **Out of date**.

Use **Search the catalog** to filter by event key, description, topic, or producer.

**Producers advertising no events** lists the producers that the Hub sweeps but holds no events from.

## Subscriptions

***

**Subscriptions** lists where the Hub delivers your events. The table shows **Name**, **Destination**, **Type**, **State**, **Verification**, and **Created**. Filter the list by **Destination kind**, **Delivery**, and **Verification**.

The Console shows each destination without its path, its query, and any account identifier. The Streaming Hub holds the full address.

To open a subscription, click its name.

### Create a subscription

**1. Open the form**

On the **Subscriptions** page, click **New subscription**.

**2. Name the subscription**

Type a **Name**. The list shows this name.

**3. Choose the destination kind**

Choose **Webhook** if the Hub posts to your endpoint, or **Pull** if your service reads from the Hub.

**4. Type the endpoint**

For a webhook, type the **Endpoint**: an `https` address that the Streaming Hub can reach.

**5. Choose the event types**

Choose every event type, including the ones published later. Or choose only the event types that you select from the catalog.

**6. Set the optional fields**

Leave **Producing application** empty to receive from every producer. Leave **Schema major version** empty to follow the version that the Hub publishes.

**7. Create**

Click **Create subscription**.

For a webhook, the **Subscription created** dialog shows the signing secret. The Streaming Hub returns it exactly once. Copy it, then select **I have copied the signing secret and stored it safely**. Then click **Verify now** to send one signed request to your endpoint, or **Verify later**. The Streaming Hub delivers nothing to the destination until one signed request reaches it and succeeds.

For a pull subscription, the **Pull subscription created** dialog shows the subscription ID. A pull subscription has no signing secret: your consumer authenticates with its own token. See [Consuming events](/en/platform/streaming-hub/consuming-events).

### The subscription page

The subscription page has these cards:

* **Destination**: the address, the destination kind, the delivery state, and the verification state.
* **Delivery**: the switch, the event types, the producer, the schema version, the signature scheme, the plan, the creation date, and the date of the last change.
* **Credential**: the credential kind, such as **Cross-account role** or **Stored queue credential**, and the last time that the signing secret changed. The Hub never returns secret material on a read, so the card cannot show it.
* **How to consume this subscription**: for a pull subscription, how your service reads it.
* **Delivery health**: the success rate per attempt, the last success and failure, the dead-lettered attempts, the quarantined events, the consumer lag, and the attempt outcomes.
* **Actions**: the actions for this subscription.

A subscription that waits for verification shows **Pending verification** at the top.

### Verify, rotate, or delete a subscription

* **Verify now** sends one real signed request to your endpoint. The Console does not offer it when the subscription is active and its switch is on. It is the only action that lifts an automatic shutdown.
* **Rotate signing secret** is for a webhook that holds a signing secret. The **Rotate the signing secret** dialog issues a new secret and shows it once. The Hub signs each delivery with both secrets until the deadline that the dialog shows. Click **Rotate the secret** to confirm.
* **Delete subscription** stops delivery. Type the subscription name to confirm, then click **Delete it**. If you create a webhook subscription again, it receives a new signing secret. A pull subscription loses the position that your consumer has read up to.

## Next steps

***

> **[Managing subscriptions](/en/platform/streaming-hub/managing-subscriptions)**
>
> Create and manage subscriptions through the API.

> **[Consuming events](/en/platform/streaming-hub/consuming-events)**
>
> Verify signatures, deduplicate deliveries, and pull events.


# Quick start
Source: https://docs.lerian.studio/en/platform/streaming-hub/streaming-hub-quick-start

Create a webhook subscription, activate it, receive the hub.destination.verified lifecycle event, and confirm delivery.

This path needs four hub calls. It subscribes to the hub's own `hub.destination.verified` lifecycle fact, so you do not need a separate product producer for the first end-to-end check.

Every `/v1` call sends the `Authorization: Bearer TOKEN` header and `Content-Type: application/json`. The hub never takes the tenant from a request body, path, or query.

## Before you start

***

You need:

* A running hub and a token with the Streaming Hub `subscriptions` `get` and `post` permissions. The catalog read also needs `catalog` `get`.
* A public `https://` endpoint you control. The hub rejects private, loopback, and cloud-metadata addresses.

## The four calls

***

```
1. GET  /v1/catalog                    → find hub.destination.verified
2. POST /v1/subscriptions              → id + signingSecret
3. POST /v1/subscriptions/{id}/ping    → activate and emit the lifecycle fact
4. GET  /v1/subscriptions/{id}/health  → confirm one successful delivery
```

## 1. Find the matching key and origin

***

`GET /v1/catalog`

Find the entry whose `eventKey` is `hub.destination.verified`. Its `source` is `streaming-hub`.

Put `eventKey` in `event_types` exactly as the catalog serves it. Do not build it from `resourceType` and `eventType`. Put `source` in `origin`.

## 2. Create the subscription

***

`POST /v1/subscriptions`

Send `X-Idempotency` with a unique value.

```json theme={null}
{
  "name": "quick-start",
  "sink_kind": "webhook",
  "endpoint": "https://hooks.example.com/lerian",
  "event_types": ["hub.destination.verified"],
  "origin": "streaming-hub"
}
```

`event_types` takes catalog `eventKey` values, not full CloudEvents types. `origin` pins the subscription to one `ce-source`. Omit it only when you intentionally want the same key from any producer. Both fields are immutable after creation. `schema_major` is optional. `plan_tier` defaults to `standard`.

The `201` response carries the new `subscription` with its `id`, and the plaintext `signingSecret`. Save the secret now. No read route returns it. A retry with the same `X-Idempotency` key returns the same response.

## 3. Activate the destination and emit the test fact

***

`POST /v1/subscriptions/{id}/ping`

A new webhook starts in `pending_verification`. The ping sends a signed probe through the production delivery path. Your endpoint must answer with `2xx`.

```json theme={null}
{ "outcome": "ok", "statusCode": 200, "errorClass": "" }
```

`outcome: "ok"` moves the subscription to `active`. After that state change commits, the hub attempts to emit `hub.destination.verified` with `ce-source: streaming-hub`. If that best-effort emission succeeds, the subscription you just created matches the fact and receives it. Repeating the ping for an already-active subscription probes the endpoint again but does not re-emit the lifecycle event.

## 4. Confirm the delivery

***

Your endpoint receives a signed `POST` with `X-Lerian-Event-Id`, `X-Lerian-Event-Type`, and `X-Lerian-Delivery-Id`. Verify the HMAC before trusting the body and deduplicate on `X-Lerian-Event-Id`.

Then call `GET /v1/subscriptions/{id}/health`. A fresh `last_success_at` and a `delivered` count in `delivery_outcomes` confirm the path works end to end.

A `pull` subscription needs no endpoint or ping. Create it with `sink_kind: "pull"`, then read `GET /v1/events?subscription_id=<id>`.

See [Managing subscriptions](/en/platform/streaming-hub/managing-subscriptions) and [Consuming events](/en/platform/streaming-hub/consuming-events) for lifecycle, signatures, retries, and cursors.


# What is Streaming Hub?
Source: https://docs.lerian.studio/en/platform/streaming-hub/what-is-streaming-hub

Streaming Hub is Lerian's managed delivery edge. It consumes the platform's internal event stream and fans events out to webhook, queue, and pull consumers.

**Streaming Hub** is Lerian's event-delivery service. It sits at the edge between the platform's internal event stream and the systems you run outside it. It delivers each event you care about to a destination you own: a webhook, a cloud queue, or a cursor you pull.

Lerian products publish domain events (past-tense business facts such as an account being created or a transaction being posted) onto a shared streaming backbone. Streaming Hub subscribes to that backbone on your behalf, matches the events against the subscriptions you register, and delivers them. You describe *which events go where*. The hub owns the consume, match, and deliver loop.

## Streaming Hub in the Lerian platform

***

The platform's event backbone is a shared, [CloudEvents-based stream](/en/reference/events/overview) carried on Kafka/Redpanda. Delivery on that stream is at-least-once, and every tenant's events ride the same topics. To consume it directly, you must run your own Kafka consumer. That consumer tracks offsets, filters event types, deduplicates, retries failed deliveries, and signs outbound requests.

Streaming Hub does that work once, as a managed edge. It consumes the internal stream and never produces onto it. It turns a raw event feed into per-destination delivery you configure through a single API.

Because the hub is the delivery edge, the guarantees you build against are the hub's delivery contract, not the raw stream. Your webhook endpoint verifies a signature, deduplicates on a stable event id, and returns quickly. See [How Streaming Hub works](/en/platform/streaming-hub/how-streaming-hub-works) for the full path an event takes.

## Sink kinds

***

A subscription delivers to exactly one destination, called a **sink**. Streaming Hub supports five sink kinds:

| Sink kind | Delivery | Destination |
| - | - | - |
| `webhook` | Push | An `https://` endpoint you own. Each request is HMAC-signed and carries CloudEvents correlation headers. |
| `pull` | Pull | A server-side cursor. Your consumer reads a page of events with `GET /v1/events`; the read doubles as the acknowledgment. |
| `sqs` | Push | An Amazon SQS queue, reached through a verified outbound credential or an AWS delegated grant. |
| `rabbitmq` | Push | A RabbitMQ exchange and routing key. |
| `eventbridge` | Push | An Amazon EventBridge event bus, reached through a verified outbound credential or an AWS delegated grant. |

Push sinks (`webhook`, `sqs`, `rabbitmq`, `eventbridge`) deliver events to you as they match. The `pull` sink inverts that: the hub holds events on a cursor and your consumer fetches them on its own schedule.

A webhook subscription becomes deliverable after one signed probe confirms your endpoint answers. RabbitMQ subscriptions require a broker credential that the hub probes before activation. SQS and EventBridge can activate with an outbound credential that the hub probes, or with a delegated AWS grant that stores no credential. See [Managing subscriptions](/en/platform/streaming-hub/managing-subscriptions).

## Deployment model

***

Streaming Hub runs BYOC by default: you deploy it into your own infrastructure as a single-tenant service, with one configured control-plane tenant and no dependency on Lerian-hosted tenant management.

On Lerian Cloud, subscriptions, events, and cursors stay isolated by tenant. See [Operating Streaming Hub](/en/platform/streaming-hub/operating-streaming-hub) for the deployment details.

## The control-plane API

***

You manage subscriptions through the `/v1` control-plane API. Every route requires an Access Manager token (`Authorization: Bearer <token>`). The hub never takes the tenant from a request body, path, or query. Through it you:

* create, list, read, and delete subscriptions.
* verify a destination (`ping` / `verify`) and supply queue credentials.
* rotate a webhook signing secret.
* read a subscription's delivery health.
* read the operational dashboard of your subscriptions.
* pull events (`GET /v1/events`) for `pull` sinks.
* browse the event [catalog](/en/reference/events/overview) the hub sees.

The full operation set, request shapes, and error tokens live in the API reference. Start from the [reference introduction](/en/reference/introduction).

## Next steps

***

> **[How Streaming Hub works](/en/platform/streaming-hub/how-streaming-hub-works)**
>
> The path an event takes: ingest, match, dispatch, retry, and auto-disable.

> **[Managing subscriptions](/en/platform/streaming-hub/managing-subscriptions)**
>
> Create webhook and queue subscriptions, wire AWS grants, and rotate secrets.

> **[Consuming events](/en/platform/streaming-hub/consuming-events)**
>
> Verify webhook signatures, deduplicate deliveries, and pull events.

> **[Event streaming overview](/en/reference/events/overview)**
>
> The shared CloudEvents contract every Lerian event follows.


# Environment variables
Source: https://docs.lerian.studio/en/rails/bc-correios/bc-correios-environment-variables

Deploy-time environment variables for Lerian BC Correios: runtime posture, datastores, the BC Correio connection, encryption keys, AI, and audit settings.

Lerian BC Correios reads its configuration from the process environment at startup. You set these variables at deploy time. A service restart makes them take effect. [BYOC configuration essentials](/en/reference/byoc-configuration) documents the backbone every Lerian Go service shares.

To install or upgrade Lerian BC Correios, see the [Lerian BC Correios chart README](https://github.com/LerianStudio/helm/tree/main/charts/plugin-bc-correios).

In the tables below, the **Default / Required** column shows the value the service applies when you leave the variable unset. A bold qualifier marks a variable you must set, such as **Required** or **Required outside development**. "Outside development" means an `ENV_NAME` other than `development`. `—` means the service applies no default. A variable flagged `Sensitive.` carries credential or key material. Inject it from your secret manager at deploy time. Never commit a value.

> [!NOTE]
>
> Where a value in the shipped example file differs from the value the code applies, this page publishes the code value.

## Service and runtime

| Variable | Default / Required | Description |
| - | - | - |
| `ENV_NAME` | `development` | Deployment environment. Any value other than `development` turns on the stricter startup checks on this page. With `production`, the service refuses `LOG_LEVEL=debug`. |
| `DEPLOYMENT_MODE` | `local` | Operational posture: `local`, `byoc`, or `saas`. In `saas`, every configured dependency must use TLS. Another value stops the boot. |
| `APP_NAME` | `br-correios` | Application name. |
| `LOG_LEVEL` | `info` | Log level: `debug`, `info`, `warn`, or `error`. |
| `SERVER_PORT` | `8080` | HTTP listen port, from 1 to 65535. |
| `SERVER_READ_TIMEOUT_SEC` | `30` | HTTP read timeout, in seconds. |
| `SERVER_WRITE_TIMEOUT_SEC` | `30` | HTTP write timeout, in seconds. |
| `SERVER_SHUTDOWN_TIMEOUT_SEC` | `30` | Time the service waits for open requests at shutdown, in seconds. |
| `DEFAULT_TENANT_ID` | `00000000-0000-0000-0000-000000000001` | Tenant for a token without a tenant claim, in single-tenant mode. Takes a UUID. |
| `STREAMING_CLOUDEVENTS_SOURCE` | `—` | Leave it unset, or set it to exactly `br-correios`. Another value stops the boot. |

## License

| Variable | Default / Required | Description |
| - | - | - |
| `LICENSE_KEY` | **Required** | License credential issued by Lerian. Every environment needs it. `Sensitive.` |
| `ORGANIZATION_IDS` | `global` | Organization scope the license covers. |
| `READYZ_LICENSE_TIMEOUT_SECONDS` | `5` | Time budget of the license check in `/readyz`, in seconds. |

## CORS and proxies

| Variable | Default / Required | Description |
| - | - | - |
| `ALLOWED_ORIGINS` | `*` in development. **Required outside development** | Comma-separated list of allowed browser origins. Outside development, the service refuses `*`. |
| `TRUSTED_PROXIES` | `127.0.0.1,::1` | Comma-separated list of proxy addresses whose `X-Forwarded-For` header the service trusts. |

## PostgreSQL

| Variable | Default / Required | Description |
| - | - | - |
| `POSTGRES_HOST` | `localhost` | Database host. |
| `POSTGRES_PORT` | `5432` | Database port. |
| `POSTGRES_USER` | **Required outside development** | Database user. |
| `POSTGRES_PASSWORD` | `—` | Database password. `Sensitive.` |
| `POSTGRES_NAME` | **Required outside development** | Database name. |
| `POSTGRES_SSLMODE` | `disable` | Database TLS mode. Outside development, the service refuses `disable`. |
| `POSTGRES_MAX_CONNS` | `50` | Maximum connections in the pool. |
| `POSTGRES_MIN_CONNS` | `5` | Minimum connections in the pool. |

## Cache (Valkey)

The cache holds idempotency keys, rate-limit counters, the shared BACEN request quota, and the attachment download budget.

| Variable | Default / Required | Description |
| - | - | - |
| `CACHE_ADDR` | `localhost:6379` | Cache address as `host:port`. |
| `CACHE_PASSWORD` | `—` | Cache password. `Sensitive.` |
| `CACHE_DB` | `0` | Cache logical database number. |
| `CACHE_TLS` | `false` | Uses TLS for the cache connection. |
| `CACHE_CA_CERT` | `—` | Custom CA certificate for the cache TLS connection, as PEM or base64-encoded PEM. Without it, the service uses the system trust store. |
| `CACHE_TTL_SEC` | `60` | Time the service keeps tenant settings in the cache, in seconds. |
| `CACHE_POOL_SIZE` | `10` | Cache connection pool size. |
| `CACHE_MAX_ACTIVE_CONNS` | `20` | Maximum active cache connections. |

## RabbitMQ (audit pipeline)

| Variable | Default / Required | Description |
| - | - | - |
| `RABBITMQ_URL` | `amqp://guest:guest@localhost:5672/` | Broker URL. Outside development, the service refuses the `guest:guest` credentials, and a failed connection stops the boot. `Sensitive.` |

## Encryption and idempotency

| Variable | Default / Required | Description |
| - | - | - |
| `ENCRYPTION_KEY` | **Required outside development** | AES-256-GCM key for the stored BC Correio credentials, AI API keys, and idempotency answers. Exactly 32 bytes. `Sensitive.` |
| `AMQP_SIGNING_KEY` | Derived from `ENCRYPTION_KEY` | Key that signs the audit messages on RabbitMQ. When set, exactly 32 bytes and different from `ENCRYPTION_KEY`. `Sensitive.` |
| `IDEMPOTENCY_TTL_SEC` | `86400` | Time the service keeps an `X-Idempotency` key, in seconds, from 90 to 86400. |

## BC Correio connection

| Variable | Default / Required | Description |
| - | - | - |
| `BC_CORREIO_ENVIRONMENT` | `—` | BACEN environment: `homologation` or `production`. It selects the BC Correio host. |
| `BC_CORREIO_ENDPOINT_URL` | From `BC_CORREIO_ENVIRONMENT` | Full BC Correio endpoint URL. When set, it wins over `BC_CORREIO_ENVIRONMENT`. |
| `BC_CORREIO_TLS_MIN_VERSION` | `TLSv1.2` | Minimum TLS version for BC Correio. |
| `BC_CORREIO_CONNECT_TIMEOUT_SEC` | `30` | Timeout of a call to BC Correio, in seconds, from 1 to 300. |
| `BC_CORREIO_RATE_LIMIT_PER_MINUTE` | `50` | Maximum calls to BC Correio per minute for each Sisbacen credential, from 1 to 60. |
| `BC_CORREIO_RATE_LIMIT_PER_HOUR` | `2700` | Maximum calls to BC Correio per hour for each Sisbacen credential, from 1 to 3000. |
| `BC_CORREIO_RATE_LIMIT_MAX_WAIT_SEC` | `90` | Maximum wait of a call for a free quota slot, in seconds, from 1 to 300. |

## Object storage

| Variable | Default / Required | Description |
| - | - | - |
| `OBJECT_STORAGE_PROVIDER` | `s3` | Attachment storage: `s3` for S3-compatible object storage, or `local` for the local filesystem. |
| `OBJECT_STORAGE_ENDPOINT` | `—` | S3-compatible endpoint URL. |
| `OBJECT_STORAGE_REGION` | `us-east-1` | Storage region. |
| `OBJECT_STORAGE_BUCKET` | `bc-correios-attachments` | Bucket for attachments. |
| `OBJECT_STORAGE_ACCESS_KEY` | `—` | Storage access key. `Sensitive.` |
| `OBJECT_STORAGE_SECRET_KEY` | `—` | Storage secret key. `Sensitive.` |
| `OBJECT_STORAGE_PATH_STYLE` | `false` | Uses path-style S3 addresses. |
| `OBJECT_STORAGE_LOCAL_PATH` | `/data/bc-correios/storage` | Base directory for the `local` provider. |

## Multi-tenancy

| Variable | Default / Required | Description |
| - | - | - |
| `MULTI_TENANT_ENABLED` | `false` | Turns on multi-tenant mode. It needs `PLUGIN_AUTH_ENABLED=true` and an `ENV_NAME` of `staging` or `production`. |
| `MULTI_TENANT_URL` | **Required in multi-tenant mode** | Tenant Manager URL. It must use `https://` unless `MULTI_TENANT_ALLOW_INSECURE_HTTP` is `true`. |
| `MULTI_TENANT_SERVICE_API_KEY` | **Required in multi-tenant mode** | API key for the Tenant Manager. `Sensitive.` |
| `MULTI_TENANT_REDIS_HOST` | **Required in multi-tenant mode** | Host of the Redis that carries tenant events. |
| `MULTI_TENANT_REDIS_PORT` | `6379` | Port of the tenant-event Redis. |
| `MULTI_TENANT_REDIS_PASSWORD` | `—` | Password of the tenant-event Redis. `Sensitive.` |
| `MULTI_TENANT_REDIS_TLS` | `false` | Uses TLS for the tenant-event Redis. |
| `MULTI_TENANT_REDIS_CA_CERT` | `—` | Custom CA certificate for the tenant-event Redis, as PEM or base64-encoded PEM. |
| `MULTI_TENANT_EVENT_CHANNEL` | **Required in multi-tenant mode** | Redis channel for tenant events. |
| `MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD` | `5` | Failures before the Tenant Manager circuit breaker opens. |
| `MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC` | `30` | Time before the Tenant Manager circuit breaker tries again, in seconds. |
| `MULTI_TENANT_MAX_TENANT_POOLS` | `100` | Maximum number of tenant database pools. |
| `MULTI_TENANT_IDLE_TIMEOUT_SEC` | `300` | Idle time before the service closes a tenant pool, in seconds. |
| `MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC` | `30` | Interval between checks of idle tenant connections, in seconds. |
| `MULTI_TENANT_MAX_OPEN_CONNS_PER_TENANT` | `0` | Maximum open connections in each tenant pool. `0` keeps the library default. |
| `MULTI_TENANT_MAX_IDLE_CONNS_PER_TENANT` | `0` | Maximum idle connections in each tenant pool. `0` keeps the library default. |
| `MULTI_TENANT_ALLOW_INSECURE_HTTP` | `false` | Allows `http://` addresses for the Tenant Manager and Access Manager in multi-tenant mode. |
| `STREAMING_OUTBOX_MULTI_TENANT_ENABLED` | `false` | Must be `true` when `MULTI_TENANT_ENABLED` is `true`, or the service does not start. |

## AI

| Variable | Default / Required | Description |
| - | - | - |
| `FEATURE_AI_INSIGHTS_ENABLED` | `true` | Turns AI analysis of mail on or off. |
| `AI_DEFAULT_MODEL_OPENAI` | `gpt-4o-mini` | Model for a tenant that uses `openai` and sets no model. |
| `AI_DEFAULT_MODEL_ANTHROPIC` | `claude-sonnet-4-20250514` | Model for a tenant that uses `anthropic` and sets no model. |
| `AI_DEFAULT_MODEL_GEMINI` | `gemini-2.0-flash` | Model for a tenant that uses `gemini` and sets no model. |
| `AI_DEFAULT_SYSTEM_PROMPT` | Built-in prompt | Default system prompt for the AI analysis. |
| `AI_TENANT_RATE_LIMIT_PER_MIN` | `50` | Maximum AI calls per minute for each tenant. |
| `AI_CIRCUIT_BREAKER_THRESHOLD` | `5` | Failures in a row before the AI circuit breaker of a tenant and provider opens. |
| `AI_CIRCUIT_BREAKER_HALF_OPEN_SEC` | `30` | Time before an open AI circuit breaker tries one call again, in seconds. |
| `AI_TENANT_MAX_CONCURRENT` | `3` | Maximum concurrent AI calls for each tenant. |
| `AI_GLOBAL_MAX_CONCURRENT` | `15` | Maximum concurrent AI calls for the whole instance. |
| `AI_ACQUIRE_TIMEOUT_SEC` | `30` | Maximum wait of a background AI call for a free slot, in seconds. |
| `AI_HTTP_ACQUIRE_TIMEOUT_SEC` | `5` | Maximum wait of a reanalyze request for a free slot, in seconds. After it, the request answers `202`. |
| `AI_INLINE_PROVIDER_TIMEOUT_SEC` | `15` | Timeout of one AI call during the polling cycle, in seconds. |
| `AI_BODY_INLINE_THRESHOLD` | `200` | Minimum body length, in characters, for an analysis during the polling cycle. |

## Transmission

| Variable | Default / Required | Description |
| - | - | - |
| `TRANSMISSION_PENDING_GRACE_SEC` | `30` | Grace window for a `PENDING` send, in seconds, from 5 to 300. When a repeat finds a `PENDING` send older than this, the send becomes `AMBIGUOUS`. |
| `TRANSMISSION_RETRY_MAX_ATTEMPTS` | `3` | Attempts to record a send that BC Correio accepted, from 1 to 10. |
| `TRANSMISSION_METRICS_QUERY_TIMEOUT_SEC` | `2` | Time budget of the database query behind the pending-send metric, in seconds, from 1 to 8. |

## Audit

| Variable | Default / Required | Description |
| - | - | - |
| `FEATURE_AUDIT_ENABLED` | `true` | Turns the audit pipeline on or off. Outside development, the service refuses `false`. |
| `AUDIT_OUTBOX_POLL_INTERVAL_SEC` | `2` | Interval between audit outbox reads, in seconds, from 1 to 300. |
| `AUDIT_OUTBOX_BATCH_LIMIT` | `50` | Maximum audit events in one read for each tenant, from 1 to 1000. |
| `AUDIT_OUTBOX_MAX_ATTEMPTS` | `50` | Attempts to publish one audit event, from 1 to 1000. |
| `AUDIT_OUTBOX_RETENTION_DAYS` | `7` | Days before the service deletes a published outbox row, from 1 to 90. |

## Authentication

| Variable | Default / Required | Description |
| - | - | - |
| `PLUGIN_AUTH_ENABLED` | **Required** | `true` or `false`. A blank value stops the boot. `false` needs an `ENV_NAME` of `development`, `develop`, `dev`, `local`, or `test`, and never works with `DEPLOYMENT_MODE=saas`. With `false`, requests still need a bearer token. |
| `PLUGIN_AUTH_ADDRESS` | **Required when `PLUGIN_AUTH_ENABLED` is `true`** | Lerian Access Manager address. In multi-tenant mode, it must use `https://` unless `MULTI_TENANT_ALLOW_INSECURE_HTTP` is `true`. |

## Telemetry and metrics

| Variable | Default / Required | Description |
| - | - | - |
| `TRACING_ENABLED` | `false` | Exports traces over OTLP. |
| `METRICS_ENABLED` | `false` | Exports metrics over OTLP. |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `—` | OTLP collector endpoint. |
| `OTEL_SERVICE_NAME` | `br-correios` | Service name in telemetry. |
| `OTEL_LIBRARY_NAME` | `br-correios` | Instrumentation library name in telemetry. |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | Value of `ENV_NAME` | Deployment environment in telemetry. |
| `METRICS_PROMETHEUS_ENABLED` | `false` | Opens a separate listener for a Prometheus scrape. |
| `METRICS_PROMETHEUS_ADDRESS` | `127.0.0.1:9076` | Address of the Prometheus listener. |

## Rate limits

| Variable | Default / Required | Description |
| - | - | - |
| `RATE_LIMIT_ENABLED` | `false` | Turns on the request budgets per tenant and operation. |
| `RATE_LIMIT_REDIS_TIMEOUT_MS` | `500` | Timeout of a rate-limit counter call to the cache, in milliseconds. |
| `ATTACHMENT_BANDWIDTH_BUDGET_MB_PER_MIN` | `500` | Attachment download budget per tenant, in megabytes per minute, from 1 to 102400. |


# Integrating with Lerian BC Correios
Source: https://docs.lerian.studio/en/rails/bc-correios/bc-correios-integration

Integrating with Lerian BC Correios: tenant settings, the connection test, Access Manager groups, idempotency, errors, and request limits.

The business endpoints below use the `/api/v1/correios` base path. The operator systemplane uses `/v1/system`. The [API Reference](/en/reference/rails/bc-correios/list-or-search-mails) documents each operation, with its request and response.

## Before you start

***

A tenant needs settings before Lerian BC Correios can poll BC Correio or send a message.

1. Create the settings with `POST /settings`. Send the Sisbacen user and password in `bcbUsername` and `bcbPassword`.
2. Test the connection with `POST /settings/test-connection`. It calls BC Correio with the stored credentials.

A second `POST /settings` for the same tenant returns `409` `BCC-0006`. Change existing settings with `PATCH /settings`, and the retention period with `PATCH /settings/retention`.

`GET /settings` does not return credential values. It returns `hasBcbCredentials` and `hasAiApiKey` instead.

## Authentication and permissions

***

Every operation needs a bearer token from [Lerian Access Manager](/en/platform/access-manager). Lerian BC Correios reads the tenant from the `tenant_id` claim of the token.

Access Manager grants access through three groups:

| Group | Access |
| - | - |
| `plugin-bc-correios-viewer-group` | Read mail, attachments, settings, the audit trail, and the dashboard. Mark a mail as read. |
| `plugin-bc-correios-contributor-group` | Viewer access. Also send messages, ask for an AI analysis, and archive or restore mail. |
| `plugin-bc-correios-editor-group` | Contributor access. Also create and change settings, and test the BC Correio and AI connections. |

The Access Manager administrator group has the same access as the editor group.

## Idempotency

***

`POST /mails/send` needs an `X-Idempotency` header. A request without it returns `422`. A request with an empty value returns `400` `BCC-0001`.

`POST /mails/{id}/reanalyze` also needs the header. A request without it, or with an empty value, returns `400` `BCC-0001`.

On every operation that takes the header, these rules apply:

* A repeat while the first request still runs returns `409` `BCC-0012` with a `Retry-After` header.
* A key longer than 128 bytes returns `400` `BCC-0001`.

## Errors

***

Errors follow RFC 9457 problem details. Branch on the `code` field, not on the `detail` text. The [BC Correios error list](/en/reference/rails/bc-correios/bc-correios-error-list) gives each code, its meaning, and its HTTP status.

## Integration conventions

***

* **Send limits.** `keywords` takes at most 10 entries of at most 100 characters each. A request body larger than 8 MB returns `413` `BCC-4003`.
* **Mail count.** `GET /mails/count` can return a count up to 60 seconds old.
* **Rate limits.** When `RATE_LIMIT_ENABLED` is `true`, each tenant has a request budget per operation in a 60-second window. Past it, the answer is `429` `BCC-0007` with a `Retry-After` header.
* **Attachment downloads.** Each tenant can download `ATTACHMENT_BANDWIDTH_BUDGET_MB_PER_MIN` megabytes of attachments per minute, 500 by default. Past it, the answer is `429` `BANDWIDTH_LIMIT_EXCEEDED`.

| Operation | Requests per 60 seconds |
| - | - |
| Get a mail, mark it as read, archive, restore, AI status | 500 |
| List or search mail, download an attachment | 100 |
| Settings, except the AI connection test | 60 |
| Dashboard | 60 |
| Audit trail and export | 50 |
| Count mail | 30 |
| Send a message | 10 |
| Ask for an AI analysis | 10 |
| Test the AI connection | 5 |


# Operating Lerian BC Correios
Source: https://docs.lerian.studio/en/rails/bc-correios/bc-correios-operations

Readiness probes, the BACEN request quota, credentials and keys, storage and retention, metrics, and the production posture of Lerian BC Correios.

Lerian BC Correios carries your official correspondence with BACEN, so an instance that is not ready is an operational event.

## Health and readiness

***

`GET /health` reports liveness. It answers `200` while the process runs, and it does not check dependencies.

`GET /readyz` runs the dependency checks. It answers `200` when the service can take traffic, and `503` when it cannot or while it shuts down. It reuses a result for 250 milliseconds.

| Check | What it probes |
| - | - |
| `postgres` | The PostgreSQL database. |
| `cache` | The Valkey or Redis cache. |
| `rabbitmq` | The RabbitMQ broker. |
| `storage` | The object storage for attachments. |
| `license_client` | The Lerian license server. |
| `startup_self_probe` | The startup self-check of the service. |
| `systemplane` | The runtime configuration store, when present. |

In multi-tenant mode, `/readyz` also checks the Tenant Manager and its event Redis.

`/readyz` does not call BC Correio, because each tenant has its own credentials. To check the link to BC Correio for a tenant, call `POST /settings/test-connection`.

`GET /version` returns the build version of the service.

## BACEN request quota and circuit breaker

***

Lerian BC Correios limits its calls to BC Correio per Sisbacen credential:

* `BC_CORREIO_RATE_LIMIT_PER_MINUTE` calls per minute, 50 by default.
* `BC_CORREIO_RATE_LIMIT_PER_HOUR` calls per hour, 2700 by default.

The service refuses a value above 60 per minute or 3000 per hour. When the cache is available, all replicas share one count per credential. A call waits up to `BC_CORREIO_RATE_LIMIT_MAX_WAIT_SEC` seconds for a free slot, 90 by default.

Each tenant has its own circuit breaker for BC Correio. Five failures in a row open it.

## Credentials and keys

***

`ENCRYPTION_KEY` holds the AES-256-GCM key that encrypts the BC Correio credentials, the AI API keys, and the stored idempotency answers. It takes exactly 32 bytes. Outside the `development` environment, the service does not start without it.

`AMQP_SIGNING_KEY` holds the key that signs the audit messages on RabbitMQ. Without it, the service derives a separate key from `ENCRYPTION_KEY`. When you set it, it takes exactly 32 bytes and must differ from `ENCRYPTION_KEY`.

## Storage, outbox and retention

***

Lerian BC Correios stores mail in PostgreSQL. It stores attachments in S3-compatible object storage, or on the local filesystem when `OBJECT_STORAGE_PROVIDER` is `local`.

User actions reach the audit trail through an outbox table and RabbitMQ. The outbox tries each event up to `AUDIT_OUTBOX_MAX_ATTEMPTS` times, 50 by default. The retention worker deletes published outbox rows after `AUDIT_OUTBOX_RETENTION_DAYS` days, 7 by default.

The retention worker runs once every 24 hours and applies the retention period of each tenant.

The service does not apply its own database schema. A separate migration step applies it before the service starts.

## Metrics and tracing

***

Set `TRACING_ENABLED=true` to export traces, and `METRICS_ENABLED=true` to export metrics, over OTLP to `OTEL_EXPORTER_OTLP_ENDPOINT`.

Set `METRICS_PROMETHEUS_ENABLED=true` to open a separate listener for a Prometheus scrape, on `METRICS_PROMETHEUS_ADDRESS`. The default address is `127.0.0.1:9076`. The main port has no metrics endpoint.

See [Observability](/en/platform/observability) for the platform view.

## Deployment posture

***

`DEPLOYMENT_MODE` takes `local`, `byoc`, or `saas`. In `saas`, every configured dependency must use TLS, or the service does not start.

`ENV_NAME` decides how strict the startup checks are. With any value other than `development`, the service also requires:

* `POSTGRES_USER` and `POSTGRES_NAME`, with a `POSTGRES_SSLMODE` other than `disable`.
* `RABBITMQ_URL`, without the `guest:guest` credentials. The service does not start if it cannot connect to RabbitMQ.
* `ENCRYPTION_KEY`, with exactly 32 bytes.
* `ALLOWED_ORIGINS`, with a value other than `*`.
* `FEATURE_AUDIT_ENABLED` not set to `false`.

Every environment needs `LICENSE_KEY` and an explicit `true` or `false` in `PLUGIN_AUTH_ENABLED`. A missing or invalid value stops the boot.


# How Lerian BC Correios works
Source: https://docs.lerian.studio/en/rails/bc-correios/how-bc-correios-works

How Lerian BC Correios collects mail from BC Correio, stores mail and attachments, sends messages to BACEN, analyzes mail with AI, and applies retention.

Lerian BC Correios runs one polling worker per tenant. Each cycle asks BC Correio for the folders and the mail of the tenant's Sisbacen user, and stores what is new.

## Polling cycle

***

Each cycle runs these steps:

1. Lists the BC Correio folders that the Sisbacen user can see.
2. Reads each folder page by page, until a page comes back empty.
3. Reads each new mail and fetches its attachments, then stores them.
4. For a mail that it already stores, fetches the attachments that failed in an earlier cycle.

An error on one folder or one mail does not stop the cycle. The next cycle tries that work again.

## Folders

***

When Lerian BC Correios stores a new mail, it puts the mail in the local folder that matches its BC Correio folder:

| BC Correio folder | Local folder |
| - | - |
| `CaixaEntrada` | `INBOX` |
| `Transmitidos` | `SENT` |
| `Arquivados` | `ARCHIVED` |
| `Cancelados` | `CANCELLED` |
| `Destinados`, `Reservados`, `Setor` | `INBOX` |

A later move of the mail in BC Correio does not change its local folder. You cannot restore a mail from `CANCELLED`.

## Initial synchronization

***

The first cycle of a tenant stores the mail that already exists in BC Correio. Lerian BC Correios does not send that backlog to the AI provider. You can still ask for an analysis of a mail from it.

A cycle that fails to read a folder does not complete the initial synchronization. The next cycle runs it again.

## Storing mail and attachments

***

Lerian BC Correios stores each mail in PostgreSQL. It stores attachments in S3-compatible object storage or on the local filesystem, with the SHA-256 checksum of each file.

When you download an attachment, the service checks the file against its checksum.

## Sending a message

***

`POST /mails/send` sends a text message to a BACEN department through BC Correio. The message goes to the destination in the request. Without one, it goes to the default destination of the tenant. Without both, it goes to `DEINF`.

The tenant needs stored BC Correio credentials. Without them, the request returns `401` `BCC-2001`, and Lerian BC Correios stores nothing.

Lerian BC Correios records the message as `PENDING` before it calls BC Correio. The outcome then decides the status and the answer:

| Outcome | Stored status | Answer |
| - | - | - |
| BC Correio accepts the message. | `CONFIRMED` | `201`, with the protocol number in `bcbConfirmationId`. |
| The service cannot tell whether BC Correio received the message, for example after a timeout. | `AMBIGUOUS` | `409` `BCC-2010` |
| BC Correio refuses the message, or the service does not send it. | `FAILED` | `503` `BCC-2002` |

A repeat of the request with the same `X-Idempotency` key does not send the message again. While the first request runs, the repeat can return `409` `BCC-0012` with a `Retry-After` header. Otherwise the stored status of the first request decides the answer:

| Status of the first request | Answer |
| - | - |
| `CONFIRMED` | The original `201` answer. |
| `PENDING`, inside the grace window | `409` `BCC-2009`. Wait, then retry with the same key. |
| `PENDING`, after the grace window | The status changes to `AMBIGUOUS`, and the answer is `409` `BCC-2010`. |
| `AMBIGUOUS` | `409` `BCC-2010` |
| `FAILED` | `409` `BCC-2011`. Send the message again with a new key. |

`TRANSMISSION_PENDING_GRACE_SEC` sets the grace window, 30 seconds by default.

Do not send a message again after `BCC-2010`. BC Correio can already hold it. Confirm with BACEN through its manual channel that the message did not arrive, and only then send it with a new key.

Lerian BC Correios does not retry a send by itself.

## Local mail actions

***

Mark as read, archive, and restore change your local copy of a mail. Lerian BC Correios does not send these actions to BC Correio.

A restore of a mail in the `CANCELLED` or `SENT` folder returns `409` `BCC-0014`.

## AI insight

***

A tenant can configure an AI provider: `openai`, `anthropic`, or `gemini`, with its own API key. Lerian BC Correios sends the mail body to that provider, together with the text it extracts from TXT, CSV, XML, PDF, and DOCX attachments.

When automatic AI analysis is enabled and the tenant has configured an AI provider, Lerian BC Correios analyzes a mail with no attachments and a body of at least `AI_BODY_INLINE_THRESHOLD` in the polling cycle. A background worker analyzes the other mail.

`POST /mails/{id}/reanalyze` waits up to 20 seconds for the analysis. A successful completion returns `200` with the insight. If the analysis is still running at that deadline, it returns `202` with a pending status; poll `GET /mails/{id}/ai-status` for the result.

## Retention

***

Each tenant sets a retention period between 1825 and 36500 days in its settings.

A retention worker runs once every 24 hours. For mail that passes the retention period, it deletes the attachment files from storage and hides the mail. It then deletes the mail records from the database.

## Audit trail

***

The audit trail records these actions:

| Action | When |
| - | - |
| `VIEW_MAIL` | A user reads the detail of a mail. |
| `MAIL_READ` | A user marks a mail as read. |
| `DOWNLOAD_ATTACHMENT` | A user downloads an attachment. |
| `SEND_MESSAGE` | A user sends a message to BACEN. |
| `MAIL_ARCHIVED` | A user archives a mail. |
| `MAIL_RESTORED` | A user restores a mail. |
| `SETTINGS_UPDATED` | A user creates or changes the tenant settings. |
| `RETENTION_POLICY_APPLIED` | A retention run deletes mail. |

`GET /audit` lists the entries. `GET /audit/export` exports them as CSV. Send `Accept: application/pdf` to get a PDF.


# What is Lerian BC Correios?
Source: https://docs.lerian.studio/en/rails/bc-correios/what-is-lerian-bc-correios

Lerian BC Correios connects your institution to BC Correio, BACEN's electronic correspondence system. It collects your mail, keeps it with an audit trail, and sends your messages to BACEN departments.

**Lerian BC Correios** is the Lerian service for **BC Correio**, the electronic correspondence system of the Central Bank of Brazil (BACEN). Supervised institutions receive official mail from BACEN in BC Correio, such as resolutions, circulars, and communications. They also use it to send messages to BACEN departments.

BC Correio is a BACEN web service on the internet. It does not use the RSFN. Each request carries the Sisbacen user and password of your institution.

BACEN does not push mail to your institution. Lerian BC Correios asks BC Correio for new mail on a schedule that you choose, stores each mail, and gives your teams one API to read it.

Lerian BC Correios keeps the data of each tenant apart. It reads the tenant from the `tenant_id` claim of the bearer token.

## What Lerian BC Correios does and does not do

***

**Lerian BC Correios does:**

* Collects the mail of every BC Correio folder your Sisbacen user can see, with its attachments.
* Stores each mail and its attachments, and checks the SHA-256 checksum of an attachment when you download it.
* Sends a text message to a BACEN department and keeps the protocol number that BC Correio returns.
* Marks a mail as read, archives it, or restores it in your local mailbox.
* Applies the retention period of each tenant, and deletes mail that passes it.
* Records who read, downloaded, sent, archived, or restored a mail in an audit trail that you can export.
* Analyzes mail with an AI provider that you configure, with your own API key.

**Lerian BC Correios does not:**

* **Send attachments to BACEN.** A message that you send is text, with no attachment.
* **Transfer files with BACEN.** [Lerian STA](/en/rails/sta/what-is-lerian-sta) is the rail for file exchange with BACEN.
* **Change the state of a mail in BC Correio.** Read, archive, and restore change your local copy only.
* **Read BACEN normative documents.** Lerian BC Correios reads the mail folders of BC Correio.

## Who it serves

***

Lerian BC Correios serves supervised institutions that receive BACEN mail in BC Correio. Your compliance and back-office teams read that mail and answer BACEN through one API, with an audit trail.

One deployment can serve several tenants. Each tenant keeps its own settings, BC Correio credentials, and mail.

## Glossary

***

| Term | Meaning |
| - | - |
| **BC Correio** | BACEN's electronic correspondence system for supervised institutions. |
| **Sisbacen** | The BACEN access system. Your Sisbacen user and password give access to BC Correio. |
| **Folder** | A BC Correio mailbox, such as the inbox or the sent folder. Lerian BC Correios maps each folder to a local folder. |
| **Destination** | The code of the BACEN department that receives a message you send, for example `DEINF`. |
| **Protocol number** | The number BC Correio returns for a message that it accepts. The API returns it as `bcbConfirmationId`. |
| **Mail type** | The class of a mail: `RESOLUTION`, `CIRCULAR`, `COMMUNICATION`, or `OTHER`. |
| **Retention period** | The number of days a tenant keeps its mail before Lerian BC Correios deletes it. |
| **AI insight** | The analysis of a mail that the AI provider of the tenant returns. |

See also [Native messaging and partner interfaces](/en/rails/native-messaging).


# Environment variables
Source: https://docs.lerian.studio/en/rails/ccs/ccs-environment-variables

Deploy-time environment variables for Lerian CCS: runtime posture, datastores, the STA and Reporter upstreams, encryption keys, and regulatory settings.

Lerian CCS reads its configuration from the process environment at startup. You set these variables at deploy time. A service restart makes them take effect. [BYOC configuration essentials](/en/reference/byoc-configuration) documents the backbone every Lerian Go service shares.

In the tables below, the **Default / Required** column shows the value the service applies when you leave the variable unset. A bold qualifier marks a variable you must set, such as **Required** or **Required in production**. `—` means the service applies no default. A variable flagged `Sensitive.` carries credential or key material. Inject it from your secret manager at deploy time. Never commit a value.

Where a value in the shipped example file differs from the value the code applies, this page publishes the code value.

## Service and runtime

| Variable | Default / Required | Description |
| - | - | - |
| `APPLICATION_NAME` | Service name | Process application name that appears in logs and telemetry. |
| `ENV_NAME` | `—` | Deployment environment label, folded to lower case. The value `production` arms every production gate on this page. |
| `LOG_LEVEL` | `info` | Structured logger level: `debug`, `info`, `warn`, or `error`. |
| `DEPLOYMENT_MODE` | `local` | Operational posture: `local`, `byoc`, or `saas`. Another value stops the boot. |
| `CCS_RUN_MODE` | `all` | Selects the subsystems this process runs: `manager` for the HTTP API only, `worker` for background workers only, or `all` for both. An invalid value stops the boot. |
| `SERVER_ADDRESS` | `—` | Main HTTP listen address. An unset value makes the server bind a port the operating system assigns, so deployments set it. |
| `HTTP_BODY_LIMIT_BYTES` | `104857600` | Maximum inbound request body size, in bytes. |
| `DEFAULT_TENANT_ID` | `—` | Fallback tenant identifier for paths with no per-request tenant context. |
| `MIGRATIONS_PATH` | `—` | Filesystem path to the SQL migration files. The migration binaries read it directly. The service never applies migrations itself. |
| `INFRA_CONNECT_TIMEOUT_SEC` | `30` | Overall infrastructure dial budget in seconds. The service clamps a value of zero or less to 30 seconds. |

## License

| Variable | Default / Required | Description |
| - | - | - |
| `LICENSE_KEY` | **Required** | License credential issued by Lerian. `Sensitive.` |
| `ORGANIZATION_IDS` | **Required** | Organization scope the license covers. Lerian CCS runs the license library in global mode, so the value is the literal `global`. |

## CORS, TLS, and proxies

| Variable | Default / Required | Description |
| - | - | - |
| `CORS_ALLOWED_ORIGINS` | **Required in production** | Comma-separated list of allowed browser origins. A production boot refuses an empty list and refuses a wildcard. |
| `CORS_ALLOWED_METHODS` | `—` | Comma-separated list of allowed HTTP methods. |
| `CORS_ALLOWED_HEADERS` | `—` | Comma-separated list of allowed request headers. |
| `CORS_EXPOSE_HEADERS` | `—` | Comma-separated list of response headers the browser can read. |
| `CORS_ALLOW_CREDENTIALS` | `false` | Allows credentialed cross-origin requests. |
| `ALLOW_CORS_WILDCARD` | `false` | Applies when `CORS_ALLOWED_ORIGINS` is empty or `*`: `true` allows any origin without credentials, and `false` refuses every cross-origin request. |
| `SERVER_TLS_CERT_FILE` | `—` | Path to the TLS certificate when the service terminates TLS itself. Set it together with the key file. |
| `SERVER_TLS_KEY_FILE` | `—` | Path to the TLS private key. Set it together with the certificate file. |
| `TLS_TERMINATED_UPSTREAM` | `false` | Marks the request path as TLS-terminated by a proxy in front of the service. |
| `TRUSTED_PROXIES` | **Required in production** | Comma-separated CIDR ranges of the layer-7 proxies whose `X-Forwarded-For` header the service honours. A production boot refuses an empty list and refuses a wildcard range. |

## PostgreSQL

| Variable | Default / Required | Description |
| - | - | - |
| `POSTGRES_HOST` | `—` | Primary database host. The connection identity carries no defaults, so an incomplete block fails the dial at boot. |
| `POSTGRES_PORT` | `—` | Primary database port. |
| `POSTGRES_USER` | `—` | Primary database user. |
| `POSTGRES_PASSWORD` | **Required in production** | Primary database password. `Sensitive.` |
| `POSTGRES_NAME` | `—` | Primary database name. |
| `POSTGRES_SSLMODE` | **Required** | Primary database TLS mode. A production boot refuses the value `disable`. |
| `POSTGRES_REPLICA_HOST` | `—` | Read-replica host for query scaling. Each other replica field falls back to its primary value when unset. |
| `POSTGRES_REPLICA_PORT` | `—` | Read-replica port. |
| `POSTGRES_REPLICA_USER` | `—` | Read-replica user. |
| `POSTGRES_REPLICA_PASSWORD` | `—` | Read-replica password. `Sensitive.` |
| `POSTGRES_REPLICA_NAME` | `—` | Read-replica database name. |
| `POSTGRES_REPLICA_SSLMODE` | `—` | Read-replica TLS mode. A production boot refuses the value `disable`. |
| `POSTGRES_MAX_OPEN_CONNS` | `25` | Maximum open connections per pool. |
| `POSTGRES_MAX_IDLE_CONNS` | `—` | Maximum idle connections per pool. The service applies no default here. |
| `POSTGRES_CONN_MAX_LIFETIME_MINS` | `30` | Maximum connection lifetime in minutes. |
| `POSTGRES_CONN_MAX_IDLE_TIME_MINS` | `5` | Maximum connection idle time in minutes. |
| `POSTGRES_CONNECT_TIMEOUT_SEC` | `—` | Dial timeout in seconds. |
| `POSTGRES_POOL_FANOUT_ACK` | `—` | Operator consent to exceed the safe connection fan-out across the connection pools. Accepts `true`, `1`, `yes`, or `on`. Without it the boot refuses an oversized fan-out. |

## Redis

| Variable | Default / Required | Description |
| - | - | - |
| `REDIS_HOST` | `localhost:6379` | Redis address as `host:port`. A non-empty value also arms the TLS posture gate in `saas` mode. |
| `REDIS_MASTER_NAME` | `—` | Sentinel master name when the deployment uses Redis Sentinel. |
| `REDIS_PASSWORD` | `—` | Redis password. `Sensitive.` |
| `REDIS_DB` | `0` | Redis logical database number. |
| `REDIS_PROTOCOL` | `3` | Redis wire-protocol version. |
| `REDIS_TLS` | `false` | Turns on TLS for the Redis client. |
| `REDIS_CA_CERT` | `—` | Base64-encoded PEM certificate authority for the Redis handshake. The client reads it only when `REDIS_TLS=true`. |
| `REDIS_POOL_SIZE` | `10` | Maximum Redis pool size. The client clamps a value above 1000. |
| `REDIS_MIN_IDLE_CONNS` | `—` | Minimum idle Redis connections kept warm. The client pre-warms none by default. |
| `REDIS_READ_TIMEOUT` | `3` | Redis read timeout in seconds. |
| `REDIS_WRITE_TIMEOUT` | `3` | Redis write timeout in seconds. |
| `REDIS_DIAL_TIMEOUT` | `5` | Redis dial timeout in seconds. |
| `REDIS_POOL_TIMEOUT` | `2` | Redis pool checkout timeout in seconds. |
| `REDIS_MAX_RETRIES` | `3` | Redis command retry budget. |
| `REDIS_MIN_RETRY_BACKOFF` | `8` | Minimum Redis retry backoff in milliseconds. |
| `REDIS_MAX_RETRY_BACKOFF` | `1` | Maximum Redis retry backoff in seconds. |

## Messaging and circuit breaker

| Variable | Default / Required | Description |
| - | - | - |
| `CIRCUIT_BREAKER_ENABLED` | `false` (**Required** as `true`) | Wires the circuit-breaker manager. The Reporter integration and the object-storage adapters both need it, so the boot refuses a value of `false`. |
| `RABBITMQ_ENABLED` | `false` | Turns on the message-broker wiring. |
| `RABBITMQ_URL` | `—` | Full broker connection URL. `Sensitive.` Set this or the host, because the boot refuses both empty when the broker is on. |
| `RABBITMQ_HOST` | `—` | Broker host. |
| `RABBITMQ_PORT_AMQP` | `—` | Broker message port. |
| `RABBITMQ_DEFAULT_USER` | `—` | Broker username. |
| `RABBITMQ_DEFAULT_PASS` | `—` | Broker password. `Sensitive.` |
| `RABBITMQ_VHOST` | `—` | Broker virtual host. |
| `RABBITMQ_QUEUE` | `—` | Default queue name. |
| `RABBITMQ_EXCHANGE` | **Required** with the broker on | Business-events exchange. The service declares it on the broker, which refuses a blank name. |
| `RABBITMQ_HEALTH_CHECK_URL` | `—` | HTTP endpoint the readiness probe calls to check the broker. |
| `RABBITMQ_HEALTH_CHECK_ALLOWED_HOSTS` | `—` | Comma-separated allow-list of hosts the health probe can target. |
| `RABBITMQ_REQUIRE_HEALTH_ALLOWED_HOSTS` | `false` | Forces the health-probe allow-list to be non-empty. |
| `RABBITMQ_ALLOW_INSECURE_HEALTH_CHECK` | `false` | `true` lets the broker health check send the broker credentials to an `http://` `RABBITMQ_HEALTH_CHECK_URL`, and limits the check only by `RABBITMQ_HEALTH_CHECK_ALLOWED_HOSTS`. A production boot refuses `true`. |
| `RABBITMQ_PUBLISHER_CONFIRM_TIMEOUT_MS` | `5000` | Publisher confirm timeout in milliseconds. |
| `RABBITMQ_PUBLISHER_RECOVERY_INITIAL_MS` | `1000` | First publisher recovery backoff in milliseconds. |
| `RABBITMQ_PUBLISHER_RECOVERY_MAX_MS` | `30000` | Maximum publisher recovery backoff in milliseconds. |
| `RABBITMQ_PUBLISHER_MAX_RECOVERIES` | `10` | Maximum publisher recovery attempts before the publisher gives up. |
| `CCS_CONSUMER_MAX_REDELIVERIES` | `5` | Maximum retry cycles a transiently failed message can take before the consumer moves it to the terminal dead-letter queue. |

## Outbox

Lerian CCS writes outbound work to a transactional outbox in the same database transaction as the state change. The `OUTBOX_` family below configures the dispatcher that the shared platform library runs.

| Variable | Default / Required | Description |
| - | - | - |
| `OUTBOX_ENABLED` | `false` (**Required** as `true`) | Turns on the outbox worker. The Reporter integration needs it, so the boot refuses `false`. |
| `OUTBOX_TABLE_NAME` | `—` | Outbox table name. The boot refuses an empty value when the outbox is on. |
| `OUTBOX_DISPATCH_INTERVAL_SEC` | `2` | Interval in seconds between dispatch cycles. |
| `OUTBOX_BATCH_SIZE` | `50` | Maximum events drained per dispatch cycle. |
| `OUTBOX_PUBLISH_MAX_ATTEMPTS` | `3` | Maximum publish attempts per event within one cycle. |
| `OUTBOX_PUBLISH_BACKOFF_MS` | `200` | Publish retry backoff in milliseconds. |
| `OUTBOX_RETRY_WINDOW_SEC` | `300` | Minimum age in seconds before a failed event becomes eligible for a retry. |
| `OUTBOX_MAX_DISPATCH_ATTEMPTS` | `10` | Maximum dispatch attempts per event before the dispatcher stops retrying it. |
| `OUTBOX_PROCESSING_TIMEOUT_SEC` | `600` | Timeout in seconds after which the dispatcher reclaims a stuck event. |
| `OUTBOX_MAX_FAILED_PER_BATCH` | `25` | Maximum failed events the dispatcher reclaims for a retry in one cycle. |
| `OUTBOX_INCLUDE_TENANT_METRICS` | `false` | Adds per-tenant labels to the outbox metrics. |
| `OUTBOX_PRIORITY_EVENT_TYPES` | `—` | Comma-separated event types the dispatcher sends first. |
| `OUTBOX_ALLOW_EMPTY_TENANT` | `false` | Accepts an event with no tenant context. |

## CCS outbox overrides

| Variable | Default / Required | Description |
| - | - | - |
| `CCS_OUTBOX_OVERRIDES_ENABLED` | `false` | Applies the three overrides below. While it is `false`, the service ignores them. |
| `CCS_OUTBOX_DISPATCH_INTERVAL_MS` | `1000` | Dispatch interval in milliseconds. It takes precedence over the seconds-based interval, which preserves sub-second precision. |
| `CCS_OUTBOX_BATCH_SIZE` | `50` | Maximum events the registered handlers process per cycle. |
| `CCS_OUTBOX_MAX_ATTEMPTS` | `10` | Maximum dispatch attempts before the dispatcher marks an event permanently undeliverable. |

## Streaming

The Lerian streaming library reads the `STREAMING_` family, not the service configuration. [Lerian Streaming Hub](/en/platform/streaming-hub/what-is-streaming-hub) delivers the published events.

| Variable | Default / Required | Description |
| - | - | - |
| `STREAMING_ENABLED` | `false` | Master switch for business-event emission. While it is off, the service wires a no-operation emitter and publishes nothing. It also needs `OUTBOX_ENABLED=true`. |
| `STREAMING_BROKERS` | **Required** when streaming is on | Comma-separated broker bootstrap list. An enabled configuration with an empty list refuses to boot. |
| `STREAMING_CLOUDEVENTS_SOURCE` | Fixed | This service's CloudEvents source. It sets the topic namespace and the event-type prefix. Leave it unset. Any value other than the built-in source refuses the boot, even when streaming is off. |
| `STREAMING_CLIENT_ID` | The service's target name | Broker client identifier used for broker-side diagnostics. |
| `STREAMING_CB_FAILURE_RATIO` | `0.5` | Failure ratio that opens the producer circuit breaker. |
| `STREAMING_CB_MIN_REQUESTS` | `10` | Minimum requests before the producer circuit breaker evaluates the failure ratio. |
| `STREAMING_CB_TIMEOUT_S` | `30` | Open-state cooldown in seconds for the producer circuit breaker. |
| `STREAMING_CLOSE_TIMEOUT_S` | `30` | Maximum drain and flush window in seconds when the producer closes. |
| `STREAMING_TLS_ENABLED` | `false` (**Required** as `true` in `saas`) | Turns on TLS for the broker dial. The minimum version is TLS 1.2. In `saas` mode a plaintext broker dial refuses the boot. |
| `STREAMING_TLS_CA_CERT` | `—` | Base64-encoded PEM certificate authority for a private or on-premises broker. An empty value uses the host trust store. A malformed value refuses the boot. |
| `STREAMING_SASL_MECHANISM` | `—` | Broker authentication mechanism: `PLAIN`, `SCRAM-SHA-256`, or `SCRAM-SHA-512`. An empty value disables broker authentication. A mechanism without its credentials refuses the boot. |
| `STREAMING_SASL_USERNAME` | `—` | Broker authentication username. |
| `STREAMING_SASL_PASSWORD` | `—` | Broker authentication password. `Sensitive.` |
| `STREAMING_SASL_ALLOW_PLAINTEXT` | `false` | Allows broker authentication over a plaintext connection, which sends the credentials in the clear. The service refuses that combination unless you set this flag. |

## STA integration

Lerian CCS sends every outbound file to BACEN through [Lerian STA](/en/rails/sta/what-is-lerian-sta) and receives the answers back from it.

| Variable | Default / Required | Description |
| - | - | - |
| `STA_ENABLED` | `false` | Wires the STA client, the submission handler, and the STA readiness probe. It also needs `STA_BASE_URL`, `CIRCUIT_BREAKER_ENABLED=true` and `OUTBOX_ENABLED=true`. |
| `STA_BASE_URL` | **Required** when STA is on | Base URL of the STA service. An empty value refuses the boot. |
| `STA_HTTP_TIMEOUT_SEC` | `30` | Per-request timeout in seconds on the STA client. The service falls back to 30 seconds for a value of zero or less. |
| `STA_FILE_HASH_VERIFY_ENABLED` | `false` | Verifies the SHA-256 digest of a downloaded inbound file against the digest on the file event. |
| `STA_EVENT_HMAC_VERIFY_ENABLED` | `false` | Authenticates inbound STA business events against the shared signature scheme. A boot with verification on and an incomplete key catalogue fails loudly. |
| `STA_EVENT_HMAC_MASTER_KEYS` | `—` | Catalogue of `version:hex` master keys shared with the STA service. `Sensitive.` |
| `STA_EVENT_HMAC_MASTER_KEY_VERSION` | `—` | Catalogue version the verifier treats as active. |
| `STA_EVENT_HMAC_TOLERANCE_SECONDS` | `300` | Window in seconds outside which an authentic event is logged as late or early. |

## Reporter integration

Lerian Reporter renders the daily ACCS001 file, so it is a mandatory upstream. The readiness probe treats it as a hard dependency. Start Lerian Reporter before you expect Lerian CCS to become ready.

| Variable | Default / Required | Description |
| - | - | - |
| `REPORTER_URL` | **Required** | Base URL of the Reporter service. An empty value refuses the boot. |
| `REPORTER_HTTP_TIMEOUT_SEC` | `30` | Per-request timeout in seconds on the Reporter client. The service falls back to 30 seconds for a value of zero or less. |
| `REPORTER_TEMPLATE_ID_ACCS001` | `—` | Identifier of the Reporter template the ACCS001 render targets. The Reporter mints this identifier per environment when you register the template. An empty identifier together with an empty template name refuses the batch approval with error `MYS-0008` and HTTP 503. |
| `REPORTER_TEMPLATE_NAME_ACCS001` | `—` | Description of the ACCS001 template in the Reporter. The service resolves the template by this description when you leave the identifier unset. |
| `DETAIL_RENDER_MODE` | `inline` | Render path for a detail response. Only `inline` starts the service. Every other value refuses the boot. |
| `CCS_REPORTER_POLL_INITIAL_DELAY_MS` | `2000` | First backoff delay in milliseconds on the render poll loop. |
| `CCS_REPORTER_POLL_MAX_DELAY_MS` | `30000` | Maximum backoff delay in milliseconds on the render poll loop. |
| `CCS_REPORTER_POLL_TOTAL_TIMEOUT_SEC` | `1800` | Total poll budget in seconds. A render older than this budget ends as a timeout. |
| `CCS_REPORTER_POLL_BACKOFF_MULTIPLIER` | `2.0` | Multiplier applied to the delay after each poll. The boot refuses a value below `1.0`. |

## Authentication

| Variable | Default / Required | Description |
| - | - | - |
| `PLUGIN_AUTH_ENABLED` | **Required**: `true` or `false`. A blank or other value stops the boot. A development `ENV_NAME` is `development`, `develop`, `dev`, `local` or `test` | `true` sends each gated `/v1` request to Lerian Access Manager for a decision. `false` skips that call; a bearer token that names a principal is still required. Only a development `ENV_NAME` outside `saas` accepts `false`. The value also decides whether the service mints outbound tokens. |
| `PLUGIN_AUTH_HOST` | **Required** when authentication is on | Base URL of [Lerian Access Manager](/en/platform/access-manager). |
| `AUTH_JWT_VERIFY_CERT` | `—` | One or more PEM RSA public keys or X.509 certificates, separated by newlines. With a loaded certificate, the service checks the RS256 signature and the expiry of each bearer token before it calls Access Manager, and answers 401 when the check fails. It takes precedence over `AUTH_JWT_VERIFY_CERT_PATH`. It takes effect only with `PLUGIN_AUTH_ENABLED=true`. |
| `AUTH_JWT_VERIFY_CERT_PATH` | `—` | Path to a file with the same content. The service reads it only when `AUTH_JWT_VERIFY_CERT` is empty. |
| `AUTH_JWT_ISSUER` | `—` | With a loaded certificate, the service answers 401 to any token whose `iss` claim differs from this value. |

## Machine-to-machine credentials

Lerian CCS mints an outbound token per upstream through Lerian Access Manager. Each upstream carries its own credential pair.

| Variable | Default / Required | Description |
| - | - | - |
| `REPORTER_CLIENT_ID` | **Required** when authentication is on outside `saas` | Client identifier for the Reporter upstream. |
| `REPORTER_CLIENT_SECRET` | **Required** when authentication is on outside `saas` | Client secret for the Reporter upstream. `Sensitive.` |
| `STA_CLIENT_ID` | **Required** when authentication is on outside `saas` | Client identifier for the STA upstream. |
| `STA_CLIENT_SECRET` | **Required** when authentication is on outside `saas` | Client secret for the STA upstream. `Sensitive.` |
| `REPORTER_M2M_TARGET_SERVICE` | `—` | Metrics label for the Reporter upstream. An empty value falls back to the canonical upstream name. |
| `STA_M2M_TARGET_SERVICE` | `—` | Metrics label for the STA upstream. An empty value falls back to the canonical upstream name. |

## Encryption and idempotency

| Variable | Default / Required | Description |
| - | - | - |
| `CCS_CRYPTO_MASTER_KEY` | **Required** | Hex-encoded 32-byte AES-256 master key that encrypts the document values the service keeps encrypted. `Sensitive.` The boot fails when the value is absent, shorter or longer than 64 hexadecimal characters, or not hexadecimal. |
| `IDEMPOTENCY_KEY_PREFIX` | `idempotency:` | Base prefix on every idempotency cache key. |
| `IDEMPOTENCY_KEY_TTL_HRS` | `168` | Retention window in hours for a cached response. |

## API documentation

| Variable | Default / Required | Description |
| - | - | - |
| `SWAGGER_ENABLED` | `false` | Mounts the interactive API-documentation route. Production keeps it off. |
| `SWAGGER_TITLE` | Service name | Title rendered in the API specification. |
| `SWAGGER_DESCRIPTION` | `—` | Description rendered in the API specification. |
| `SWAGGER_VERSION` | `1.0.0` | API version label rendered in the specification. |
| `SWAGGER_HOST` | `—` | Host override for the API specification. |
| `SWAGGER_SCHEMES` | `https` | Comma-separated URL schemes the specification accepts. |

## Telemetry and metrics

| Variable | Default / Required | Description |
| - | - | - |
| `ENABLE_TELEMETRY` | `false` | Wires the OpenTelemetry exporter. See [Observability](/en/platform/observability) for the platform view. |
| `OTEL_LIBRARY_NAME` | `—` | Instrumentation library name. |
| `OTEL_RESOURCE_SERVICE_NAME` | Service name | Service name resource attribute. |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | `—` | Deployment environment resource attribute. |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `—` | Collector address for the OpenTelemetry exporter. |

## Rate limits

Lerian CCS applies three rate-limit tiers to the `/v1` routes: the default tier, the aggressive tier on mutating requests, and the export tier on heavy reads such as audit queries.

| Variable | Default / Required | Description |
| - | - | - |
| `RATE_LIMIT_ENABLED` | `false` | Turns on the rate-limit subsystem. Production forces it to `true`. |
| `RATE_LIMIT_MAX` | `500` | Default tier request ceiling per window. |
| `RATE_LIMIT_WINDOW_SEC` | `60` | Default tier window in seconds. |
| `AGGRESSIVE_RATE_LIMIT_MAX` | `100` | Aggressive tier request ceiling per window. |
| `AGGRESSIVE_RATE_LIMIT_WINDOW_SEC` | `60` | Aggressive tier window in seconds. |
| `EXPORT_RATE_LIMIT_MAX` | `60` | Export tier request ceiling per window. |
| `EXPORT_RATE_LIMIT_WINDOW_SEC` | `60` | Export tier window in seconds. |

## Health endpoints

> [!NOTE]
>
> Lerian CCS exposes `GET /health` for liveness and `GET /readyz` for readiness on the main port, plus `GET /version` and `GET /metrics`. See [Health and readiness](/en/reference/health-and-readiness) for the probe contract and [Operating Lerian CCS](/en/rails/ccs/ccs-operations) for the probe list.

## Object storage

Lerian CCS reads inbound files from one bucket and writes outbound files to another. Both accept any S3-compatible store. An empty bucket name marks the matching readiness check as skipped.

| Variable | Default / Required | Description |
| - | - | - |
| `OBJECT_STORAGE_STA_ENDPOINT` | `—` | Endpoint of the inbound bucket. An empty value selects the default cloud endpoint. |
| `OBJECT_STORAGE_STA_REGION` | `us-east-1` | Region of the inbound bucket. |
| `OBJECT_STORAGE_STA_BUCKET` | `—` | Name of the read-only inbound bucket. |
| `OBJECT_STORAGE_STA_ACCESS_KEY` | `—` | Access key for the inbound bucket. `Sensitive.` Leave it unset when an attached cloud role supplies the credentials. |
| `OBJECT_STORAGE_STA_SECRET_KEY` | `—` | Secret key for the inbound bucket. `Sensitive.` |
| `OBJECT_STORAGE_STA_USE_PATH_STYLE` | `false` | Uses path-style addressing on the inbound bucket. |
| `OBJECT_STORAGE_STA_DISABLE_SSL` | `false` | Disables TLS on the inbound bucket connection. |
| `OBJECT_STORAGE_STA_MAX_OBJECT_BYTES` | `536870912` | Maximum size of one inbound object, in bytes. |
| `OBJECT_STORAGE_STA_SSE_ALGORITHM` | **Required** when the inbound bucket is set | Encryption at rest for the inbound bucket: `AES256`, `aws:kms` or `none`. A blank or other value stops the boot. `none` boots only with a development `ENV_NAME` outside `saas`. |
| `OBJECT_STORAGE_STA_SSE_KMS_KEY_ID` | **Required** with `aws:kms` | Key identifier for `aws:kms` on the inbound bucket. |
| `OBJECT_STORAGE_CCS_ENDPOINT` | `—` | Endpoint of the outbound bucket. An empty value selects the default cloud endpoint. |
| `OBJECT_STORAGE_CCS_REGION` | `us-east-1` | Region of the outbound bucket. |
| `OBJECT_STORAGE_CCS_BUCKET` | `—` | Name of the outbound bucket that holds the rendered regulatory files. |
| `OBJECT_STORAGE_CCS_ACCESS_KEY` | `—` | Access key for the outbound bucket. `Sensitive.` Leave it unset when an attached cloud role supplies the credentials. |
| `OBJECT_STORAGE_CCS_SECRET_KEY` | `—` | Secret key for the outbound bucket. `Sensitive.` |
| `OBJECT_STORAGE_CCS_USE_PATH_STYLE` | `false` | Uses path-style addressing on the outbound bucket. |
| `OBJECT_STORAGE_CCS_DISABLE_SSL` | `false` | Disables TLS on the outbound bucket connection. |
| `OBJECT_STORAGE_CCS_SSE_ALGORITHM` | **Required** when the outbound bucket is set | Encryption at rest for the outbound bucket: `AES256`, `aws:kms` or `none`. A blank or other value stops the boot. `none` boots only with a development `ENV_NAME` outside `saas`. |
| `OBJECT_STORAGE_CCS_SSE_KMS_KEY_ID` | **Required** with `aws:kms` | Key identifier for `aws:kms` on the outbound bucket. |

## Retention and regulatory settings

| Variable | Default / Required | Description |
| - | - | - |
| `CCS_OUTBOUND_RETENTION_DAYS` | `30` | Lifetime in days of an uploaded outbound file in the bucket. The service applies 30 days for a value of zero or less. |
| `CCS_ACCS009_RETENTION_DAYS` | `30` | Lifetime in days of a stored ACCS009 penalty report. |
| `CCS_NON_SUBMISSION_SCAN_INTERVAL_SEC` | `3600` | Interval in seconds between non-submission scans. The boot refuses a value of zero or less and a value above 86400. |
| `CCS_BACEN_DESTINATARIO_CNPJ_BASE` | `00000000` | Eight-digit BACEN recipient stamped on the file envelope. Set the real value before you go live. |
| `CCS_ACCS010_DTFIM_MODE` | `transfer_date` | Rule that resolves the mandatory end date on a relationship transfer. |

[Integrating with Lerian CCS](/en/rails/ccs/ccs-integration) covers the API surface, the error codes, and the published events.


# Integrating with Lerian CCS
Source: https://docs.lerian.studio/en/rails/ccs/ccs-integration

The Lerian CCS API surface, its authentication and tenancy model, idempotency, error contract, and the events it publishes.

Lerian CCS exposes one REST API under `/v1`. Every business route needs a bearer token.

## API surface

***

| Area | Operation | Purpose |
| - | - | - |
| Configuration | `GET /v1/configurations` | Read the current configuration. |
| Configuration | `POST /v1/configurations` | Create a configuration. |
| Configuration | `GET /v1/configurations/{id}` | Read one configuration. |
| Configuration | `PATCH /v1/configurations/{id}` | Update one configuration. |
| Configuration | `POST /v1/configs/{configId}/conglomerate-members` | Add a member. |
| Configuration | `GET /v1/configs/{configId}/conglomerate-members` | List members. |
| Configuration | `DELETE /v1/configs/{configId}/conglomerate-members/{memberId}` | Remove a member. |
| Batch | `POST /v1/batches` | Generate the batch for a movement date. |
| Batch | `GET /v1/batches` | List batches. |
| Batch | `GET /v1/batches/{id}` | Read one batch. |
| Batch | `POST /v1/batches/{id}/approve` | Approve and start the render. |
| Batch | `POST /v1/batches/{id}/submit` | Alias of approve. |
| Batch | `POST /v1/batches/{id}/reject` | Reject a batch under review. |
| Batch | `GET /v1/batches/{id}/items` | List line items. |
| Batch | `GET /v1/batches/{id}/items/{itemId}/errors` | List item errors. |
| Batch | `POST /v1/batches/resend` | Resend from a terminal batch. |
| Batch | `POST /v1/batches/{id}/reprocess-last-event` | Admin. Re-fire the last event. |
| Batch | `POST /v1/batches/{id}/drain-parked-response` | Admin. Apply a parked ACCS003. |
| Batch | `POST /v1/batches/reconcile-partial-applies` | Admin. Repair a contradicted verdict. |
| Batch | `POST /v1/batches/recompute-mirror` | Admin. Recompute the mirror. |
| Batch | `POST /v1/batches/backfill-sta-transfer-id` | Admin. Restore a lost identity. |
| Requisition | `POST /v1/pending-requisition-queries` | Ask BACEN for the unanswered requisitions. |
| Requisition | `GET /v1/pending-requisition-queries/gaps` | List the unanswered requisitions. |
| Injunction | `POST /v1/injunctions` | Record a block or unblock. |
| Injunction | `GET /v1/injunctions` | List injunctions. |
| Injunction | `GET /v1/injunctions/{id}` | Read one injunction. |
| Injunction | `POST /v1/injunctions/{id}/revoke` | Revoke an injunction. |
| Reconciliation | `POST /v1/reconciliations` | Start a run against an ACCS004. |
| Reconciliation | `GET /v1/reconciliations` | List runs. |
| Reconciliation | `GET /v1/reconciliations/{id}` | Read one run. |
| Reconciliation | `GET /v1/reconciliations/{id}/divergences` | List divergences. |
| Transfer | `POST /v1/transfers` | Create a transfer. |
| Transfer | `GET /v1/transfers` | List transfers. |
| Transfer | `GET /v1/transfers/{id}` | Read one transfer with its legs. |
| Transfer | `GET /v1/transfers-in` | List received transfers. |
| Transfer | `GET /v1/transfers-in/{id}` | Read one received transfer. |
| Transfer | `POST /v1/transfers-in/{id}/confirm` | Confirm a received transfer. |
| Audit | `GET /v1/audit/entries` | List audit entries. |
| Audit | `POST /v1/audit/verify-chain` | Verify the audit chain. |
| Streaming | `GET /v1/streaming/manifest` | Read the event manifest. With streaming off, the route is not mounted. |

Operator endpoints sit outside `/v1`.

| Endpoint | Purpose |
| - | - |
| `GET /health` | Liveness. |
| `GET /readyz` | Readiness of every dependency. |
| `GET /readyz/tenant/{id}` | Readiness of one institution. |
| `GET /version` | Build version. |
| `GET /metrics` | Readiness metrics, Prometheus text. |
| `/swagger/*` | The API specification, when `SWAGGER_ENABLED=true` outside production. |

## Authentication and tenancy

***

Every `/v1` route takes an OAuth2 bearer token from [Lerian Access Manager](/en/platform/access-manager). With `PLUGIN_AUTH_ENABLED=true` and `PLUGIN_AUTH_HOST`, Lerian Access Manager authorizes each request. Only a development `ENV_NAME` outside `saas` accepts `false`.

Each institution keeps its own database schema.

## Idempotency

***

Lerian CCS accepts an optional `X-Idempotency` header on most mutating routes. A middleware caches the first response and replays it for a repeat of the same key. A repeat with a different body answers 422, and a repeat while the first request runs answers 409. Keys belong to one institution, and the default retention is 7 days.

## Errors

***

A business error answers an RFC 9457 problem document, with the media type `application/problem+json` and a product code. The code values are frozen contract, so a client matches on the code, not the message text.

| Code | Status | When |
| - | - | - |
| `CCS-0001` | 409 | A configuration already exists. |
| `CCS-0004` | 404 | The configuration does not exist. |
| `CCS-0010` | 409 | A non-terminal batch holds that movement date. |
| `CCS-0012` | 400 | The movement date is outside the window. |
| `CCS-0020` | 404 | The batch does not exist. |
| `CCS-0024` | 422 | The batch refuses that transition. |
| `CCS-0050` | 400 | The transfer names the institution itself. |
| `CCS-0061` | 409 | An injunction already covers that document. |
| `CCS-0074` | 409 | A reconciliation is already in progress. |
| `MYS-0008` | 503 | An upstream or the template is unavailable. |

## Events

***

Lerian CCS publishes one business event on its own topic, with a matching dead-letter topic. The topic and the event type follow the [Streaming Hub naming rule](/en/platform/streaming-hub/how-streaming-hub-works), with this service's CloudEvents source as the namespace.

| Event | Meaning |
| - | - |
| Batch submitted | The ACCS001 batch went to Lerian STA. |

It carries the critical delivery posture. The service writes it to the transactional outbox in the same transaction as the state change. Streaming is off by default. While it is off, the service wires a no-operation emitter and publishes nothing. [Lerian Streaming Hub](/en/platform/streaming-hub/what-is-streaming-hub) is the delivery layer.

With `RABBITMQ_ENABLED=true`, Lerian CCS also publishes notifications on the exchange named by `RABBITMQ_EXCHANGE`.

| Routing key | Meaning |
| - | - |
| `ccs.events.batch` | A batch finished generation and waits for review. |
| `ccs.events.batch.generation_failed` | Batch generation failed. |
| `ccs.events.reconciliation.divergence` | A run found a divergence. |

Documents in those payloads are masked.

## Integration conventions

***

* **Headers.** While `CORS_ALLOWED_HEADERS` stays unset, a fixed default list applies, and it does not include `X-Idempotency`. A value you set replaces that list, so name every header your browser client sends.
* **Pagination.** Each list route caps its own page size. A page size of 100 or less stays within every route's cap.
* **Rate limits.** The limiter covers `/v1` only. Mutating requests and heavy reads such as audit queries carry tighter tiers.
* **File references.** The regulatory XML stays in object storage. The API and the broker messages carry file references only.

[How Lerian CCS works](/en/rails/ccs/how-ccs-works) covers these flows.


# Operating Lerian CCS
Source: https://docs.lerian.studio/en/rails/ccs/ccs-operations

Readiness probes, credentials and keys, storage and retention, parked responses, and the production posture of Lerian CCS.

Lerian CCS carries a daily regulatory obligation, so an unready instance is an operational event.

## Health and readiness

***

`GET /health` reports liveness. `GET /readyz` runs every dependency probe and reports one status.

| Check | What it probes | When it fails |
| - | - | - |
| `postgres` | The primary database. | It does not answer. |
| `redis` | The Redis or Valkey instance. | It does not answer. |
| `rabbitmq` | The message broker. | It does not answer. Reports `skipped` while the broker is off. |
| `sta_http_client` | The Lerian STA endpoint. | It does not answer. Reports `skipped` while the integration is off. |
| `reporter` | The Lerian Reporter endpoint. | The Reporter is unreachable. Always active. |
| `storage_sta` | The inbound storage bucket. | It is unreachable. Reports `skipped` while the bucket is unset. |
| `storage_ccs` | The outbound storage bucket. | It is unreachable. Reports `skipped` while the bucket is unset. |
| `movement_window` | The effective transmission window. | Never. It reports the posture in place. |
| `st_consumer` | The single-institution consumer. | Never. It reports the consumer count. |
| `startup_self_probe` | The boot self-probe. | It has not passed yet. |

`GET /readyz/tenant/{id}` reports `postgres`, `redis` and `rabbitmq` for one institution.

An unreachable Reporter removes the instance from service. Start the Reporter first.

## Credentials and keys

***

`PLUGIN_AUTH_ENABLED=true` with `PLUGIN_AUTH_HOST` makes Access Manager authorize each API request. The same pair mints the outbound tokens.

Each upstream carries its own credential. Lerian STA uses `STA_CLIENT_ID` and `STA_CLIENT_SECRET`. Lerian Reporter uses `REPORTER_CLIENT_ID` and `REPORTER_CLIENT_SECRET`.

Lerian CCS mints a token through OAuth2 client credentials for each outbound call. Outside `saas`, with the gate on, a missing pair stops the boot and names the exact variable. In `saas`, Lerian manages each institution's credential, and the rail caches the credential for `M2M_CREDENTIAL_CACHE_TTL_SEC` seconds, 300 by default.

`CCS_CRYPTO_MASTER_KEY` holds the AES-256-GCM master key for data encrypted at rest. It takes 64 hexadecimal characters. An empty value stops the boot.

Lerian CCS can verify a signature on each inbound event from Lerian STA. Set `STA_EVENT_HMAC_VERIFY_ENABLED=true`, load the key catalogue into `STA_EVENT_HMAC_MASTER_KEYS`, and name the active version in `STA_EVENT_HMAC_MASTER_KEY_VERSION`. Load the catalogue first. The service refuses an event whose signature does not match.

## Storage, outbox and retention

***

Two object-storage buckets hold the regulatory XML: `OBJECT_STORAGE_STA_BUCKET` inbound and `OBJECT_STORAGE_CCS_BUCKET` outbound. The API and the broker messages carry file references only.

Outbound work leaves through a transactional outbox table, so the service needs `OUTBOX_ENABLED=true` to start. The dispatcher reads it every `OUTBOX_DISPATCH_INTERVAL_SEC` seconds, 2 by default, in batches of `OUTBOX_BATCH_SIZE`, 50 by default, and gives up on an event after `OUTBOX_MAX_DISPATCH_ATTEMPTS` attempts, 10 by default. Set `CCS_OUTBOX_OVERRIDES_ENABLED=true` to move the dispatcher onto the `CCS_OUTBOX_*` interval, batch size and attempt budget instead. When an ACCS001 hand-off exhausts its attempt budget, its batch moves to `SUBMIT_FAILED`.

`CCS_OUTBOUND_RETENTION_DAYS` and `CCS_ACCS009_RETENTION_DAYS` both default to 30 days. A monitor scans for a missing remittance every `CCS_NON_SUBMISSION_SCAN_INTERVAL_SEC` seconds, 3600 by default.

The service never applies its own database schema. A separate migration job applies it before startup.

## Parked STA responses

***

When Lerian CCS cannot apply an inbound file, it parks the file event in a dead-letter queue. The file stays in the inbound bucket. It is often the only copy of a BACEN fact, so it needs an alert and a human decision.

`POST /v1/batches/{id}/drain-parked-response` applies a late ACCS003 to a batch that already reached a terminal state. The caller supplies identifiers only. Lerian CCS re-fetches the file, re-derives the verdicts, and refuses when the named batch does not match. It writes an audit entry in the same transaction.

Do not drain when two batches match one file, or when the correlation contradicts itself. Establish which batch produced the file first. Treat the disagreement as the finding.

## Metrics and tracing

***

`GET /metrics` serves the readiness metrics in Prometheus text format. Set `ENABLE_TELEMETRY=true` to export traces and metrics over OTLP to `OTEL_EXPORTER_OTLP_ENDPOINT`. See [Observability](/en/platform/observability) for the platform view.

## Deployment posture

***

`DEPLOYMENT_MODE` takes `local`, `byoc` or `saas`. `CCS_RUN_MODE` takes `manager`, `worker` or `all`, and selects which subsystems run.

Production adds these requirements.

* `PLUGIN_AUTH_ENABLED=true` with `PLUGIN_AUTH_HOST`.

Every environment needs `LICENSE_KEY`, `ORGANIZATION_IDS`, `REPORTER_URL`, `CCS_CRYPTO_MASTER_KEY`, `CIRCUIT_BREAKER_ENABLED=true` and `OUTBOX_ENABLED=true`.

Startup validation checks the license and the TLS posture. A failed check stops the boot.


# How Lerian CCS works
Source: https://docs.lerian.studio/en/rails/ccs/how-ccs-works

How Lerian CCS builds the daily ACCS001 batch, submits it through Lerian STA, records transfers, and reconciles the accepted position.

Lerian CCS runs one regulatory cycle per **movement date** and per **configuration**. Every file that leaves or reaches Lerian CCS travels through [Lerian STA](/en/rails/sta/what-is-lerian-sta).

## Where the customer data comes from

***

Lerian CCS keeps no copy of your customer base. **Lerian Reporter** renders the daily ACCS001 file from your customer data against a registered template. Lerian CCS reads the rendered bytes and creates one batch line item per operation in the file.

The Reporter is a mandatory upstream. Lerian CCS refuses to start without the Reporter address, and an unreachable Reporter takes Lerian CCS out of the ready state. With neither the ACCS001 template identifier nor its name set, the approval fails with `MYS-0008`.

## Reporting (ACCS001)

***

A batch belongs to one movement date. One rule answers which movement date the institution may transmit now, and whether a supplied date is acceptable. A date outside the rule fails with `CCS-0012`.

The batch then walks a state machine:

| State | What it means |
| - | - |
| `GENERATING` → `GENERATED` | Lerian CCS builds the batch and validates it. |
| `PENDING_REVIEW` | The batch waits for an operator decision. |
| `AWAITING_RENDER` | An operator approved the batch, and the render is in flight. |
| `SUBMITTED` | The rendered file is queued for Lerian STA. |
| `ACCEPTED` | BACEN accepted the remittance. |
| `PARTIALLY_REJECTED` | BACEN took the file and refused some records. |
| `FORMAT_REJECTED` | BACEN refused the file. |
| `REJECTED` | An operator rejected the batch. |
| `GENERATION_FAILED`, `RENDER_FAILED`, `SUBMIT_FAILED` | The build, the render, or the hand-off to Lerian STA failed. A transfer that Lerian STA cancels also ends in `GENERATION_FAILED`. |

Every state from `ACCEPTED` down is terminal. Approve and reject are the operator decisions on a batch under review. A generate request can also approve the batch at once, with a written reason. Approve dispatches the render and parks the batch, so no synchronous path reaches the hand-off. A render that gives up ends in `RENDER_FAILED`, and recovery is a fresh batch.

BACEN answers on the inbound file channel. An ACCS002 carries the file-level verdict. An ACCS003 carries one verdict per record, and Lerian CCS matches each verdict to its line item by the regulatory tuple. A verdict that matches no line item fails closed rather than dropping in silence. An accepted record promotes its relationship into the accepted position. A refused record leaves an error row your operators can read.

After `FORMAT_REJECTED` or `PARTIALLY_REJECTED`, an operator can create a resend batch from that batch.

A background monitor asks, per configuration and movement date, whether BACEN acknowledged a remittance dated on that date. It answers `PRESENT`, `MISSING` or `UNDETERMINED`. The obligation holds even with no movement, so `MISSING` is a regulatory omission. `UNDETERMINED` says the control could not answer.

## Pending requisitions and penalty reports (CCS0009 and ACCS009)

***

An operator can ask BACEN which requisitions the institution has not answered (CCS0009). Lerian CCS lists each gap that BACEN reports.

BACEN sends penalty reports as ACCS009. That document is a columnar text report with no XML layout. Lerian CCS parses it and stores the occurrence.

## Transfers (ACCS010 and CCS0010)

***

An operator records an outbound transfer as a draft, with the receiving institution's CNPJ root and the legs it covers. Your operators list transfers newest first, up to 200 per page, and read any transfer with its legs.

Another institution can also transfer relationships to yours. Lerian CCS reads the sender's ACCS010 copy and records the transfer as `RECEIVED`. An operator confirms it, and Lerian CCS sends a CCS0010. BACEN's answer moves the transfer to `ACKNOWLEDGED` or `REFUSED`.

## Compliance and injunctions (ACCS004)

***

BACEN publishes the position it holds for the institution as an ACCS004. Lerian CCS parses that report and runs a reconciliation against the accepted position it keeps. Only one run per configuration may be in progress. A run ends as `COMPLETED` with its match and divergence counts, or as `FAILED` with a diagnostic. Your operators list the divergences of a run, with each document masked to its last four characters.

The comparison keys on a keyed hash of the document.

An injunction records a judicial `BLOCK` or `UNBLOCK` against one document for one configuration, under LC 105/2001. A block holds that identity out of the remittance. An operator can revoke an active injunction, and the revocation is soft.

## Audit trail and events

***

Each entry carries the SHA-256 of the previous entry combined with the canonical form of the record, so the entries form one chain per institution. An operator can ask the service to verify a chain end to end.

Lerian CCS also publishes a business event when the ACCS001 batch goes to Lerian STA. It writes the event through a transactional outbox, so the event and the state change it reports commit together. Event publication over the streaming topic stays off until an operator turns it on.


# What is Lerian CCS?
Source: https://docs.lerian.studio/en/rails/ccs/what-is-lerian-ccs

Lerian CCS is your integration to the BACEN CCS register, from the daily remittance to position reconciliation and judicial injunctions.

**Lerian CCS** is the Lerian service for the **BACEN CCS** regulatory integration. CCS is the *Cadastro de Clientes do Sistema Financeiro Nacional*, the BACEN customer register of the National Financial System.

Lerian CCS covers three areas of that obligation:

* **Reporting (ACCS001).** Lerian Reporter renders your daily remittance file, and Lerian CCS submits it to BACEN through [Lerian STA](/en/rails/sta/what-is-lerian-sta).
* **Compliance (ACCS004).** Lerian CCS reconciles the position BACEN reports against the accepted position it holds, and records judicial block and unblock orders.
* **Transfers (ACCS010 and CCS0010).** Lerian CCS records a transfer that another institution sends, and confirms it. It also records an outbound transfer as a draft.

All BACEN XML passes through one codec. Files carry the CCSDOC, BCARQ and SISARQ envelopes, and messages carry the BCMSG and SISMSG envelopes. The codec uses UTF-16BE with a byte-order mark. The regulatory XML stays in object storage, and the API and the broker messages carry file references only.

Lerian CCS isolates each institution in its own database schema.

## What Lerian CCS does and does not do

***

**Lerian CCS does:**

* Builds the daily ACCS001 batch and submits it through Lerian STA.
* Records judicial injunctions as blocks and unblocks, and lets an operator revoke one.
* Records the transfers other institutions send, and confirms them.

**Lerian CCS does not:**

* **Connect to BACEN directly.** [Lerian STA](/en/rails/sta/what-is-lerian-sta) owns the BACEN leg. Lerian CCS submits each file to Lerian STA over HTTP, and BACEN's answers return over the message broker.
* **Render the ACCS001 file.** Lerian Reporter renders it from your customer data, and Lerian CCS then builds the batch line items from the rendered bytes. The Reporter is a mandatory upstream.
* **Apply its own database schema.** A separate migration job applies the schema before the service starts.

## Who it serves

***

Lerian CCS serves financial institutions that carry the daily CCS reporting obligation. That obligation stands even on a day with no movement, so a missing remittance is a regulatory omission. Lerian CCS grades that question per configuration and movement date, and raises a signal when it cannot confirm that the remittance arrived.

One deployment can serve several institutions. Each keeps its own schema, configuration, and conglomerate members.

## Glossary

***

| Term | Meaning |
| - | - |
| **CCS** | *Cadastro de Clientes do Sistema Financeiro Nacional*, the BACEN register of customer relationships. |
| **Lerian STA** | Lerian's integration to BACEN's file-exchange hub. It carries every CCS file both ways. |
| **Configuration** | The per-institution settings a batch, a reconciliation, and an injunction belong to. |
| **Conglomerate member** | A participant institution registered under one configuration. |
| **Movement date** | The date the ACCS001 file itself carries. One rule decides which date the institution may transmit now. |
| **Accepted position** | The local mirror of the relationships BACEN has accepted. |
| **ACCS001** | The daily remittance the institution sends to BACEN. |
| **ACCS002 and ACCS003** | BACEN's file-level verdict and per-record verdicts on an ACCS001. |
| **ACCS004** | The position report BACEN publishes for reconciliation. |
| **ACCS009** | The BACEN penalty report, a columnar text file with no XML layout. |
| **ACCS010, ACCS011, ACCS012** | The relationship-transfer file family. |
| **CCS0009** | The query that asks BACEN which requisitions the institution has not answered. |
| **CCS0010** | The confirmation of a relationship transfer that another institution sent. |
| **CCSDOC, BCARQ, SISARQ** | The BACEN envelope elements of a CCS file. |
| **BCMSG, SISMSG** | The BACEN envelope elements of a CCS message. |
| **Injunction (*liminar*)** | A judicial block or unblock recorded against one CPF or CNPJ under LC 105/2001. |
| **LC 105/2001** | The Brazilian bank-secrecy law that governs what an institution may disclose. |

See also [Native messaging and partner interfaces](/en/rails/native-messaging).


# Environment variables
Source: https://docs.lerian.studio/en/rails/consignado/consignado-environment-variables

Consignado-specific deployment variables for Dataprev connectivity, workers, auctions, credentials, artifacts, pacing, and operational windows.

Set these variables at deployment time. Unless stated otherwise, changing one requires a restart. The [BYOC configuration reference](/en/reference/byoc-configuration) covers the shared Lerian runtime: server, datastores, telemetry, authentication, streaming, outbox, and licensing. This page lists Consignado-specific settings and the few shared settings that materially change its rail behavior.

`—` means no default. Variables carrying certificates, private keys, OAuth secrets, or HMAC keys are sensitive and must come from a secret manager.

A deployment is managed when `DEPLOYMENT_MODE` is `byoc` or `saas`, or when `ENV_NAME` is `production`.

## Service and tenant mode

| Variable | Default | Purpose |
| - | - | - |
| `SERVER_ADDRESS` | `:8080` | Main HTTP listener for the API and probes. |
| `DEPLOYMENT_MODE` | `local` | `local`, `byoc`, or `saas`. Startup refuses any other value. `byoc` and `saas` make the deployment managed. |
| `ENV_NAME` | `development` | Environment label. `production` makes the deployment managed. |
| `SYSTEMPLANE_ENABLED` | `false` | Enables runtime configuration under `/system`. |
| `DEFAULT_TENANT_ID` | `default` | Tenant the deployment serves. |
| `OUTBOX_ENABLED` | `true` | Must be `true`; startup refuses a deployment that cannot durably record rail facts. |
| `STREAMING_ENABLED` | `true` | Must be `true`; the streaming relay is the only publisher for outbox facts. |
| `STREAMING_BROKERS` | — | Required broker list. Startup refuses a relay with no destination. |
| `STREAMING_CLOUDEVENTS_SOURCE` | — | Must be exactly `consignado-gw`. Startup refuses any other value; a wrong source means no fact ever reaches a consumer. |
| `STREAMING_KAFKA_TLS_ENABLED` | `false` | Connects to the brokers over TLS. Startup requires `true` unless `STREAMING_KAFKA_ALLOW_PLAINTEXT` is `true`. |
| `STREAMING_KAFKA_ALLOW_PLAINTEXT` | `false` | Permits a plaintext broker connection when `ENV_NAME` is `development`, `local`, or `test`. A managed deployment refuses it. |
| `STREAMING_KAFKA_SASL_MECHANISM` | — | `plain`, `scram-sha-256`, or `scram-sha-512`. A managed deployment requires one of the two SCRAM values. |
| `STREAMING_KAFKA_SASL_USERNAME_FILE` | — | Path to the file that holds the broker user name. Required with a SASL mechanism and in a managed deployment. |
| `STREAMING_KAFKA_SASL_PASSWORD_FILE` | — | Path to the file that holds the broker password. Required with a SASL mechanism and in a managed deployment. Sensitive. |
| `SUBSCRIPTIONS_HUB_ENABLED` | `false` | A managed deployment requires `true` and refuses to start without it. |
| `SUBSCRIPTIONS_HUB_BASE_URL` | — | Streaming Hub base URL. A managed deployment refuses to start without it. |

## Dataprev client and authentication

| Variable | Default | Purpose |
| - | - | - |
| `DATAPREV_ENABLED` | `false` | Master switch for the Dataprev rail runtime. |
| `DATAPREV_BASE_URL` | — | Base URL for the main Dataprev API. HTTPS is required in managed deployments; a non-managed deployment permits HTTP only for loopback hosts. |
| `DATAPREV_TOMBAMENTO_BASE_URL` | — | Separate endpoint for tombamento operations. Empty keeps those operations unavailable. It follows the same HTTPS/loopback policy. |
| `DATAPREV_OAUTH_TOKEN_URL` | — | OAuth2 token endpoint. HTTPS is required in managed deployments; a non-managed deployment permits HTTP only for loopback hosts. |
| `DATAPREV_OAUTH_CLIENT_ID` | — | OAuth client ID. Sensitive. |
| `DATAPREV_OAUTH_CLIENT_SECRET` | — | OAuth client secret. Sensitive. |
| `DATAPREV_OAUTH_SCOPES` | — | Comma-separated OAuth scopes requested from Dataprev. |
| `DATAPREV_CERT_FILE` | — | Local ICP-Brasil certificate path for non-managed development. Sensitive. |
| `DATAPREV_KEY_FILE` | — | Local private-key path paired with `DATAPREV_CERT_FILE`. Sensitive. |
| `DATAPREV_CODIGO_SOLICITANTE` | — | Three-digit requester code. |
| `DATAPREV_REQUEST_TIMEOUT_SEC` | `30` | Timeout for one Dataprev request. |
| `DATAPREV_REQUESTS_PER_SECOND` | `25` | Rail rate, from 0 to 25, for requests that carry no tenant identity. With the Systemplane enabled, the stored value applies instead. |
| `DATAPREV_CONSENT_CACHE_HMAC_KEY` | — | HMAC key for worker-consent records and cache entries. Worker margin and FGTS reads refuse without it, and startup refuses a Redis deployment without it. Sensitive. |

Managed deployments must use tenant credential custody. They fail closed instead of falling back to an unauthenticated or non-mTLS client.

## Contract and portability windows

| Variable | Default | Purpose |
| - | - | - |
| `DATAPREV_AVERBACAO_ENABLED` | `false` | Enables averbação, CCB and rail artifact storage, and contract corrections. |
| `DATAPREV_PORTABILIDADE_SOLICITACAO_WINDOW_HOURS` | `72` | Lookback window for portability proposals. |
| `DATAPREV_PORTABILIDADE_INCLUSAO_GARANTIAS_PATH` | — | Override for the Dataprev portability-guarantee submission path. |
| `DATAPREV_PORTABILIDADE_AVERBACAO_WINDOW_DAYS` | `20` | Calendar days from the origin exclusion date a request names to register an inbound portability. |
| `DATAPREV_REFINANCIAMENTO_REVERSAO_WINDOW_BUSINESS_DAYS` | `7` | Business-day window for refinancing reversal. |
| `DATAPREV_SALDO_DEVEDOR_CLOCK_INTERVAL_SEC` | `86400` | Cadence for outstanding-balance obligations and month-end fallback. |
| `DATAPREV_SALDO_DEVEDOR_REENVIO_INTERVAL_SEC` | `60` | Cadence of the resend of outstanding-balance reports that a competência turnover held back. |

## Reconciliation and employment feeds

| Variable | Default | Purpose |
| - | - | - |
| `DATAPREV_RECONCILIATION_ENABLED` | `false` | Enables payroll bookkeeping and repasse reconciliation. |
| `DATAPREV_RECONCILIATION_INTERVAL_SEC` | `3600` | Reconciliation cadence. |
| `DATAPREV_RECONCILIATION_LOOKBACK_MONTHS` | `1` | Previous payroll competences included in each pass. |
| `DATAPREV_RECONCILIATION_CNPJS` | — | Comma-separated employer scopes; empty reads the rail-wide feed. |
| `DATAPREV_RECONCILIATION_TENANT_ID` | — | Tenant the reconciliation poller runs for. The employment feed and exclusion recovery also require it. |
| `DATAPREV_EMPLOYMENT_REPORT_ENABLED` | `false` | Enables the employment-termination feed. |
| `DATAPREV_EMPLOYMENT_REPORT_ADAPTER` | `disabled` | `dataprev` for the real adapter; `fake` is local-only. |
| `DATAPREV_EMPLOYMENT_REPORT_INTERVAL_SEC` | `3600` | Employment-report cadence. |
| `DATAPREV_EMPLOYMENT_REPORT_PAGE_SIZE` | `100` | Records requested per page. |
| `DATAPREV_EMPLOYMENT_REPORT_CONCURRENCY` | `4` | Concurrent tenant workers. |
| `DATAPREV_EMPLOYMENT_REPORT_TENANT_TIMEOUT_SEC` | `300` | Maximum processing time for one tenant in a pass. |

## Exclusion and redirection

| Variable | Default | Purpose |
| - | - | - |
| `DATAPREV_EXCLUSION_ENABLED` | `false` | Enables exclusion admission and recovery. |
| `DATAPREV_EXCLUSION_PROVIDER_TIMEOUT_SEC` | `30` | Timeout for one exclusion provider call. |
| `DATAPREV_EXCLUSION_CLAIM_DWELL_SEC` | `60` | Minimum dwell before claimed work can be retried. |
| `DATAPREV_EXCLUSION_STATUS_CHECK_LEASE_SEC` | `60` | Lease for exclusion status checks. |
| `DATAPREV_EXCLUSION_RECOVERY_INTERVAL_SEC` | `30` | Recovery-loop cadence. |
| `DATAPREV_EXCLUSION_RECOVERY_BATCH` | `50` | Operations claimed per pass. |
| `DATAPREV_EXCLUSION_RECOVERY_CONCURRENCY` | `4` | Concurrent recovery workers. |
| `DATAPREV_EXCLUSION_RECOVERY_TENANT_TIMEOUT_SEC` | `60` | Maximum processing time for one tenant in a pass. |

Leave `DATAPREV_EXCLUSION_ADAPTER` and `DATAPREV_EXCLUSION_FAKE_BASE_URL` unset.

## Outcome recovery

A rail command can end with its outcome unestablished: the process died mid-call, or Dataprev never answered. Two recovery loops converge that state against the rail's own registry. A third loop resends a bid whose rail answer was lost. The three loops are off by default. Enable them in any deployment that submits averbações, rail commands, or bids. Otherwise nothing converges an unestablished outcome automatically.

| Variable | Default | Purpose |
| - | - | - |
| `DATAPREV_AVERBACAO_RECOVERY_ENABLED` | `false` | Enables averbação outcome convergence. |
| `DATAPREV_AVERBACAO_RECOVERY_INTERVAL_SEC` | `60` | Convergence cadence. |
| `DATAPREV_AVERBACAO_RECOVERY_BATCH` | `50` | Records claimed per pass. |
| `DATAPREV_AVERBACAO_RECOVERY_CONCURRENCY` | `4` | Concurrent tenant workers. |
| `DATAPREV_AVERBACAO_RECOVERY_TENANT_TIMEOUT_SEC` | `60` | Maximum processing time for one tenant in a pass. |
| `DATAPREV_AVERBACAO_RECOVERY_MINIMUM_DWELL_SEC` | `300` | Minimum age before an unestablished outcome is reconciled. |
| `DATAPREV_AVERBACAO_RECOVERY_PROVIDER_TIMEOUT_SEC` | `30` | Timeout for one registry read. |
| `DATAPREV_RAIL_COMMAND_RECOVERY_ENABLED` | `false` | Enables convergence for refinancing, reversal, renegotiation, and origin-side portability exclusion. |
| `DATAPREV_RAIL_COMMAND_RECOVERY_INTERVAL_SEC` | `60` | Convergence cadence. |
| `DATAPREV_RAIL_COMMAND_RECOVERY_BATCH` | `50` | Records claimed per pass. |
| `DATAPREV_RAIL_COMMAND_RECOVERY_CONCURRENCY` | `4` | Concurrent tenant workers. |
| `DATAPREV_RAIL_COMMAND_RECOVERY_TENANT_TIMEOUT_SEC` | `60` | Maximum processing time for one tenant in a pass. |
| `DATAPREV_RAIL_COMMAND_RECOVERY_MINIMUM_DWELL_SEC` | `300` | Minimum age before an unestablished outcome is reconciled. |
| `DATAPREV_RAIL_COMMAND_RECOVERY_PROVIDER_TIMEOUT_SEC` | `30` | Timeout for one registry read. |
| `CONSIGNADO_BID_RECONDUCTION_ENABLED` | `false` | Enables the resend of bids whose rail answer was lost, under the original proposal number. |
| `CONSIGNADO_BID_RECONDUCTION_INTERVAL_SEC` | `15` | Resend cadence. |
| `CONSIGNADO_BID_RECONDUCTION_BATCH_SIZE` | `20` | Bids resent in one pass. |

## Auctions and client bids

| Variable | Default | Purpose |
| - | - | - |
| `LEILAO_ENABLED` | `false` | Enables scheduled discovery of open loan requests. |
| `LEILAO_CLIENT_BID_ENABLED` | `false` | Enables the authenticated client bid command surface. |
| `LEILAO_INTERVAL_SEC` | `3600` | Auction-discovery cadence. |
| `LEILAO_TENANT_ID` | — | Tenant that auction discovery and portability discovery run for. Both require it. |
| `LEILAO_PORTAL_BASE_URL` | — | Optional worker portal base URL. Leaving it unset is a valid deployment: bids then travel with the client's own contacts. A value that is set is validated at boot and an unsafe one fails the boot closed. |
| `LEILAO_DISCOVERY_LOOKBACK_HOURS` | `48` | Width of each discovery window. It must be wider than `LEILAO_INTERVAL_SEC` plus `LEILAO_DISCOVERY_CLOCK_SKEW_SEC`, or startup fails. |
| `LEILAO_DISCOVERY_CLOCK_SKEW_SEC` | `300` | Clock-skew overlap applied to discovery windows. |
| `LEILAO_FAST_LANE_ENABLED` | `false` | Enables a second discovery pass over the last 60 seconds of open requests, once per second by default. It starts only with `LEILAO_ENABLED=true`. |
| `LEILAO_PORTABILITY_ENABLED` | `false` | Enables portability discovery. This is independent from `LEILAO_ENABLED`. |
| `LEILAO_PORTABILITY_INTERVAL_SEC` | `3600` | Cadence of the portability-discovery pass. |

Portability discovery requires `LEILAO_PORTABILITY_ENABLED=true`, `LEILAO_TENANT_ID`, `DATAPREV_ENABLED=true`, `STREAMING_ENABLED=true`, a primary database, and the canonical outbox. It does not require `LEILAO_ENABLED=true`. The portability listing window is 72 hours by default (`DATAPREV_PORTABILIDADE_SOLICITACAO_WINDOW_HOURS`). The service refuses to boot unless that window is wider than `LEILAO_PORTABILITY_INTERVAL_SEC` plus the 300-second `LEILAO_DISCOVERY_CLOCK_SKEW_SEC` margin.

## Credential custody and artifacts

| Variable | Default | Purpose |
| - | - | - |
| `CREDENTIALS_STORE_ENABLED` | `false` | Enables Dataprev credential custody. A managed deployment requires it. |
| `CREDENTIALS_CLEANUP_INTERVAL_SEC` | `30` | Credential-cleanup cadence. |
| `CREDENTIALS_CLEANUP_BATCH_SIZE` | `50` | Credentials claimed per cleanup pass. |
| `CREDENTIALS_CLEANUP_CONCURRENCY` | `4` | Concurrent cleanup workers. |
| `CREDENTIALS_CLEANUP_LEASE_SEC` | `60` | Cleanup lease. |
| `CREDENTIALS_CLEANUP_PERSISTENCE_TIMEOUT_SEC` | `5` | Persistence timeout for one cleanup operation. |
| `AVERBACAO_ARTIFACTS_BUCKET` | — | Private object-store bucket for CCB and rail artifacts. Required when `DATAPREV_AVERBACAO_ENABLED=true`. |
| `AVERBACAO_ARTIFACTS_ENDPOINT_URL` | — | S3-compatible endpoint override for local or private object stores. |
| `AVERBACAO_ARTIFACTS_USE_PATH_STYLE` | `false` | Uses path-style S3 addressing when enabled. |
| `AWS_REGION` | — | Region used by credential custody and artifact storage. Deliberately has no default: an unset value lets the AWS SDK resolve the institution's own region, and a hardcoded one would override it. Set it explicitly for the region your data must stay in. |
| `AWS_ENDPOINT_URL` | — | AWS-compatible endpoint override for local development. Do not set it in managed AWS production. |

> [!NOTE]
>
> Consignado has no non-event-driven startup mode: outbox, streaming, and brokers are mandatory even though the platform shares those settings. Keep the CloudEvent source pinned to `consignado-gw`.


# Integrate with Lerian Consignado — Dataprev
Source: https://docs.lerian.studio/en/rails/consignado/consignado-integration

Integrate through the authenticated HTTP API, the Lender command stream, Consignado business facts, and event-delivery subscriptions.

Use the HTTP API for the complete client-facing Consignado surface. Use CloudEvents to consume immutable business facts and, when integrating through Lender, to send the supported commands. The two interfaces are complementary. The event stream is not the authority for every rail operation.

## HTTP API

The API covers tenant credentials, margin and worker data, auctions and bids, registration and import, documents, and disbursement. It also covers contract corrections, contract lifecycle, portability in both directions, refinancing, renegotiation, and guarantees. The remaining operations cover reconciliation, outstanding balances, funds, originadores, assignments, usage, throughput, and delivery subscriptions.

Start with [fetch worker margin](/en/reference/rails/consignado/fetch-consignado-worker-margin), then use the API Reference navigation to find the remaining operation families.

## Lender commands consumed

The gateway reads one application command stream and dispatches by CloudEvent source and event key. Selection is by key, never by topic name. The gateway quarantines a key it does not handle to its own dead-letter queue instead of skipping it.

| Event key | Runtime behavior |
| - | - |
| `consignado_margin.requested` | Performs the worker margin read against the rail. The consumer itself runs only where both the Dataprev rail and streaming are enabled. |
| `consignado_exclusao.requested` | Uses the same idempotent exclusion service as the HTTP operation when the runtime is available; otherwise returns a named unavailability error. |
| `consignado_redirecionamento.requested` | Returns a named refusal. The gateway quarantines the command to its own dead-letter queue. |

Averbação is not a Lender command. Submit it through the authenticated HTTP operation.

## Declared and operational business facts

There is no per-fact toggle. The published fact set is a projection of the runtime catalog. A deployment either emits a fact or does not run the flow that produces it.

Configuration decides what a deployment emits, never the fact. Inbound portability discovery is off by default. The `consignado.portability_proposal.received` fact appears only where that flow is enabled. It is committed atomically with its durable marker when the scheduled portability-discovery poller finds a live offer. The same holds for any rail command a deployment does not run. The operational facts cover:

* auction requests and inbound portability proposals
* margin, employment, and absence reports
* proposal acceptance, contract registration (`consignado.contract.registered`, including signed CCB artifact evidence), disbursement, and correction availability
* averbação, exclusion, and origin-side portability outcomes
* reconciliation, repasse exceptions, and calendars
* assignment and throughput changes
* rail pause and resume for a tenant during the Dataprev competência turnover, on Lerian Cloud

See [Consignado events](/en/reference/events/consignado) for the full catalog and the exact CloudEvent resource/event mapping.

## Application streams

The gateway uses one topic per application:

* facts go to `lerian.streaming.consignado-gw`
* the gateway reads Lender commands from `lerian.streaming.lender.commands`
* fact types use `studio.lerian.consignado-gw.<resource>.<event>`
* command types use `studio.lerian.lender.<resource>.<event>`

Route by CloudEvent source, resource type, and event type. Do not infer an event from a topic name alone.

## Delivery subscriptions

Use the subscription API to register a delivery destination, read its delivery health, rotate its signing secret, test delivery, or revoke it. Only the create and rotate answers carry the signing secret. No read returns it. Reads show a masked destination. Only the admin role can read the full destination, because a webhook path can carry a callback token.

A successful test proves delivery to the configured endpoint. It does not change the at-least-once semantics of business events.

## Reliability contract

* Business facts enter a transactional outbox before publication.
* Delivery is at least once.
* Deduplicate by `(ce-source, ce-id)`.
* Monetary values travel as decimal strings, never binary floating point.
* Payload fields use `snake_case`. Timestamps use UTC RFC 3339.
* A missing required business identifier is terminal and goes to the consumer DLQ rather than to Dataprev.


# Operate Lerian Consignado — Dataprev
Source: https://docs.lerian.studio/en/rails/consignado/consignado-operations

Operational guidance for Consignado: workers, idempotency, rail windows, throughput, reconciliation, credentials, and failure recovery.

Operate Lerian Consignado as a tenant-isolated rail, not as a stateless proxy. Commands, background reads, the outbox, and recovery state all participate in the contract.

## Command and read surfaces

Use the authenticated HTTP API for client commands and queries. The API separates commands from reads. Each client operation requires an authorization action and runs in the caller's tenant. Follow the operation's idempotency requirements. Retries after timeouts are normal and must reuse the same business identity.

A mounted operation is not proof that a specific deployment wires its Dataprev adapter. An unavailable rail integration returns `501 Not Implemented` for that request instead of disappearing from the API. The capabilities operation reports which operation families your deployment reaches.

The Lender command stream remains available for the supported integration commands. It is not a replacement for the complete HTTP surface. See [Consignado events](/en/reference/events/consignado).

## Scheduled workers

The gateway runs fourteen scheduled loops. They share delayed first execution, stable per-replica staggering, panic isolation, and graceful shutdown. Every loop except the auction fast lane also runs non-overlapping passes with positive jitter.

| Worker | Purpose | Default cadence |
| - | - | - |
| Reconciliation poller | Reads bookkeeping and repasse data and evaluates expected settlement. | 1 hour |
| Auction discovery poller | Lists open loan requests and publishes each new one. | 1 hour |
| Auction fast lane | Lists the last 60 seconds of open loan requests and publishes each new one. Off by default. | 1 second |
| Portability discovery poller | Lists open inbound portability requests and relays each one with its own expiry. | 1 hour |
| Employment report poller | Reads employment termination data per tenant. | 1 hour |
| Exclusion recovery | Drives admitted exclusions to a terminal state. | 30 seconds |
| Averbação recovery | Converges averbações whose outcome was never established against the rail registry. | 1 minute |
| Rail-command recovery | Converges refinancing, reversal, renegotiation, and portability-exclusion commands whose outcome was never established. | 1 minute |
| Bid reconduction | Resends a bid whose rail answer was lost, under its original proposal number. | 15 seconds |
| Credential cleanup | Expires stale tenant credentials under a lease. | 30 seconds |
| Bid payload cleanup | Removes retained bid payloads after their retention window. | 1 minute |
| Proposal witness | Confirms accepted proposal terms against the durable client bid. | 5 seconds |
| Outstanding-balance clock | Evaluates missed-installment and month-end balance obligations. | 24 hours |
| Outstanding-balance resend | Sends the outstanding-balance reports that a competência turnover held back. | 1 minute |

Eleven of the fourteen take their cadence from environment configuration and need a restart to change. The auction fast lane, bid payload cleanup, and proposal witness read their cadence through the Systemplane and take effect on the next delay.

Averbação recovery and rail-command recovery exist because a rail command can leave its outcome unestablished: the process died mid-call, or the rail never answered. They converge that state against the rail's own registry instead of losing it. Bid reconduction resends a bid whose rail answer was lost, under its original proposal number, and each resend uses the tenant's rail budget. The three loops are off by default. Enable the two recovery loops in any deployment that submits averbações or rail commands.

Once a month, Dataprev closes for its competência turnover and refuses requests. When a background loop meets that refusal, the loops that poll Dataprev for that tenant pause for 5 minutes, then 15, then 30 for each later refusal. Client requests still reach Dataprev and receive its refusal. The scheduled-jobs report shows `paused_until` for a paused loop. On Lerian Cloud, the gateway publishes `consignado.rail.paused` once per turnover and `consignado.rail.resumed` when Dataprev answers again.

## Rail windows

Rail defaults and constraints include:

* a 24-hour loan-auction validity window that Dataprev supplies and the gateway does not configure
* a 72-hour portability-request lookback
* 20 calendar days from the origin exclusion to register an inbound portability, when the request names the exclusion date
* 7 business days to reverse refinancing
* a 48-hour auction-discovery window, with a five-minute clock-skew allowance

Treat these as rail constraints, not internal timeouts. Configure only settings exposed by the gateway when the Dataprev contract for the target environment requires a different value. The gateway does not let you change fixed values that Dataprev supplies, including the loan-auction validity window.

## Throughput and pacing

Dataprev traffic is paced per tenant. The throughput API sets the tenant's rate, from 0 to 25 requests per second, and no setting raises that ceiling. A tenant with no stored rate runs at 3 requests per second. A stored value of `0` pauses rail traffic for that tenant.

## Reconciliation safety

Bookkeeping and repasse reads are independent. One failing source must not suppress the other. Expected repasses can emit three states:

* `consignado.repasse.overdue`: the expected movement is late
* `consignado.repasse.resolved`: the movement arrived after an overdue alarm
* `consignado.repasse.unobserved`: the gateway cannot currently prove presence or absence

Changing the configured employer-CNPJ scope while expectations remain open can strand those expectations under the old scope. Drain or migrate them in the same maintenance window. The repasse-expectation list counts open expectations by employer scope and marks each scope this deployment no longer reads. Read its freshness state first: an empty list proves nothing unless the state is `fresh`.

## Credentials and artifacts

Rotate the tenant certificate, OAuth secret, requester code, and portal URL through the credentials API. Local certificate-file variables are a development fallback, not a substitute for tenant custody in managed deployments.

Registering a worker portal base URL is optional, for the tenant and for each originador. See [Discover auctions and submit proposals](/en/rails/consignado/how-consignado-works#3-discover-auctions-and-submit-proposals) for the order in which the gateway selects a portal.

CCB and rail artifacts use the configured object store. Keep the bucket private and deliver content only through the authenticated artifact operation.

The averbação and the CCB attachment accept a signed CCB whose base64 text is up to 8 MiB. A contract correction accepts a corrected resource whose base64 text is up to 8 MiB.

## Failure behavior

The rail fails closed on missing tenant identity, malformed command identifiers, and Dataprev endpoints outside the deployment policy: HTTPS in a managed deployment, loopback HTTP only otherwise. A managed deployment also fails closed on missing credentials and on unsupported adapters. Business facts are written through the outbox and delivered at least once. Consumers must deduplicate by CloudEvent source and ID.


# How Lerian Consignado — Dataprev works
Source: https://docs.lerian.studio/en/rails/consignado/how-consignado-works

The end-to-end Consignado flow on Dataprev: tenant setup, worker margin, auctions, registration, servicing, portability, guarantees, and reconciliation.

Lerian Consignado combines synchronous HTTP commands with asynchronous facts and scheduled Dataprev reads. The HTTP API admits work and answers queries. The outbox publishes business facts. Background workers discover or recover state that Dataprev exposes as feeds rather than callbacks.

## 1. Configure a tenant

Before a tenant can call the rail, register:

* an ICP-Brasil A1 client certificate and private key
* OAuth2 client credentials
* the tenant's three-digit Dataprev requester code
* optionally, the worker portal base URL offered as a formalization contact in bid proposals

Credential status returns presence, certificate fingerprint, and expiry metadata. It never returns the certificate, private key, or OAuth secret. In a [managed deployment](/en/rails/consignado/consignado-environment-variables), a rail operation for a tenant without the certificate, the OAuth credentials, or the requester code answers `DATAPREV_CREDENTIAL_REQUIRED`.

When partners originate loans in the tenant's name, register each one as an originador. When the tenant assigns credits to funds, register each fund. A deactivated originador cannot place bids, and the gateway keeps its record.

## 2. Read worker data and margin

The margin endpoint authenticates the tenant, obtains the worker's Dataprev authorization context, and returns the rail response without turning it into an underwriting decision. When Dataprev returns them, the answer also carries the worker, employment, and employer records. The API also exposes new employment links, termination reports, authorized FGTS records, and FGTS balance reads.

## 3. Discover auctions and submit proposals

A scheduled discovery loop lists open loan requests and publishes each new one. An optional fast lane repeats that listing every second. A client can then submit a bid through the authenticated HTTP API. The gateway retains the durable bid payload needed to prove what the client sent and later publishes the accepted-proposal witness.

A bid can name an originador. The gateway refuses a bid for an unknown or deactivated originador. An originador that authenticates with its own credential bids under its own reference.

Every proposal must reach the worker through at least one contact. The gateway adds a formalization portal as a contact when it finds one: on the bid first, then on the named originador, then on the tenant. When none of the three has a portal, each proposal must carry a client contact. Otherwise the gateway refuses the bid before it calls Dataprev.

Portability auctions use a separate response operation and a bounded Dataprev request window.

## 4. Register and fund the contract

The registration flow:

1. registers the contract with Dataprev
2. attaches the CCB document when required
3. exposes registration status and rail documents
4. records the client's disbursement confirmation
5. publishes immutable booking and payment facts through the outbox

A downstream lender or ledger decides what those facts mean for its own books. The gateway does not post directly to the ledger.

Import a contract that is already registered on the rail outside this gateway. The import reads the contract from Dataprev and moves no money. Only an active or suspended contract can be imported. A contract the tenant already holds answers `CONTRACT_ALREADY_REGISTERED`.

Record a correction against the registered contract when something the client already asserted turns out to be wrong. Examples are the wrong CCB file and a disbursement confirmation with the wrong evidence. A correction crosses no government boundary: the rail's own rectification fields are retired, so the client remains the only authority. The gateway takes custody of the corrected bytes, publishes the fact that names them, and serves them back under authentication. Corrections chain: each one supersedes the event before it.

## 5. Service the contract

The API covers the rail lifecycle after registration: suspension, reactivation, term changes, installment anticipation and reversal, and exclusion. It also covers refinancing and reversal, renegotiation, portability registration, and legacy-contract operations.

Portability runs in both directions. As the proponent institution, register the inbound portability. As the origin institution, exclude the contract the worker moved away. The gateway accepts that only for a contract it registered itself. It refuses anything else before it calls the rail.

Reversing a refinancing works the same way. You can reverse a refinancing through this gateway only if the gateway registered it. The 7-business-day window is judged against the gateway's own record of when that refinancing committed.

The gateway reports the outstanding balance (saldo devedor) to Dataprev for the contracts it registers through averbação and the contracts it imports. The reported balance is the present value of the unpaid installments still ahead, on the Brasília date of the report. The gateway discounts each installment at the contract's monthly rate and assumes payment on the due date. It sends a report when the debt changes, when an installment falls due without payment, and on the last business day of a month with no report.

Exclusion is a recoverable operation. The initial authenticated command records the intent, and a scheduled recovery loop drives admitted work to a terminal rail state. Repeating the same idempotent command does not create a second exclusion. Refinancing, reversal, renegotiation, and origin-side portability exclusion have a recovery loop of their own for the same reason. The loop converges a command whose outcome nobody established against the rail registry instead of losing it.

## 6. Reconcile payroll and repasse

The reconciliation worker reads two independent Dataprev sources:

* **bookkeeping records**, keyed by the payroll competence and contract context
* **CEF repasse records**, which represent the settlement movement

The gateway emits one reconciliation fact per source record and tracks expected repasses. A repasse can become overdue, later resolve, or become unobservable when the gateway cannot establish a current rail view. Consumers must not treat silence as settlement.

## 7. Operate portfolios and guarantees

Additional API families cover operational calendars, employment terminations, FGTS guarantee execution, funds, originadores, assigned credits, assignments, per-tenant throughput, usage, and event-delivery subscriptions.

> [!NOTE]
>
> Use the API reference operation page for exact required headers, idempotency rules, validation ranges, and response schemas.


# What is Lerian Consignado — Dataprev?
Source: https://docs.lerian.studio/en/rails/consignado/what-is-lerian-consignado

Lerian Consignado connects a credit journey to Dataprev's Crédito do Trabalhador, from worker margin and auctions through contract lifecycle, guarantees, and reconciliation.

**Lerian Consignado — Dataprev** is the native Brazil rail that connects the Lerian platform to Dataprev's **Crédito do Trabalhador** program for private-sector payroll loans under Brazilian employment law. It is not the traditional INSS payroll-loan rail.

The rail isolates every financial institution as a tenant. Each tenant uses its own Dataprev requester code, OAuth credentials, ICP-Brasil client certificate, operational limits, and data partition.

## What the rail covers

Lerian Consignado implements the integration lifecycle around a payroll loan:

* worker authorization, employment data, eligible FGTS records, and available payroll margin
* loan and portability auctions, bid submission, and proposal evidence
* contract registration, import of a contract registered outside the gateway, CCB attachment, rail document retrieval, and disbursement confirmation
* corrections to a registered contract's CCB or disbursement evidence
* suspension, reactivation, term changes, installment anticipation, and exclusion
* refinancing, reversal, renegotiation, inbound and origin-side portability, and legacy-contract migration
* outstanding-balance (saldo devedor) reporting to Dataprev
* FGTS guarantee execution
* payroll bookkeeping, CEF repasse reconciliation, employment termination, and operational calendars
* fund and originador registration, assigned-credit visibility, assignment registration, throughput, usage, and delivery subscriptions

The [Consignado API reference](/en/reference/rails/consignado/fetch-consignado-worker-margin) is the source of truth for request and response schemas.

## Responsibility boundary

Lerian Consignado owns the Dataprev boundary. It authenticates with the rail, validates and sends rail commands, reads Dataprev feeds, preserves rail identifiers, and publishes business facts.

The credit engine remains responsible for underwriting, pricing, approval policy, the loan product, and customer communication. Downstream systems remain responsible for ledger postings and accounting decisions. The rail never invents a rate or silently converts a Dataprev result into a credit decision.

FGTS guarantee execution is the exception at this boundary: it is an irreversible remote money-path command. The gateway submits it to the configured rail, but downstream systems still own ledger posting and accounting.

## Interfaces

The product exposes three complementary interfaces:

* an **authenticated HTTP API** for commands and queries
* **CloudEvents** for business facts and the supported Lender command channel
* **scheduled workers** for Dataprev feeds, reconciliation, recovery, and proposal evidence

Every mutating path except the runtime configuration API under `/system` is tenant-scoped. No read operation returns the Dataprev certificate, private key, or OAuth secret.

> **[How Consignado works](/en/rails/consignado/how-consignado-works)**
>
> Follow the journey from credentials and margin to registration, servicing, and reconciliation.

> **[Consignado events](/en/reference/events/consignado)**
>
> See the emitted and consumed CloudEvents and delivery semantics.


# Native messaging and partner interfaces
Source: https://docs.lerian.studio/en/rails/native-messaging

The two ways the Lerian platform reaches Brazil's payment system: Lerian-owned messaging straight to BACEN, and adapters for connectivity partners such as JD and BTG.

The Lerian platform reaches Brazil's payment system in two ways, and both run side by side.

**Native messaging** is Lerian's own connectivity layer. It gives you direct, non-intermediated links to the Central Bank of Brazil (BACEN) networks and the market infrastructures under its supervision. Lerian owns and operates these connections, rather than adapting them from a third-party provider.

A **partner interface** reaches the same rail through a connectivity provider's systems. Brazil Rails and Interfaces are separate tabs in this documentation.

## What "native" means

***

A provider interface reaches a rail through another institution's infrastructure. Your traffic rides on a connectivity provider's systems. A native connection removes that intermediary.

Your institution's messages travel on Lerian-owned software straight to BACEN and the market infrastructures that clear and settle Brazilian payments. The link to BACEN depends on the rail. Lerian SPB, Lerian SPI, and Lerian SRC use the RSFN. Lerian BC Correios uses BC Correio, a BACEN web service on the internet. A native connection has one less dependency in the money path, and it follows the platform principle that clients own their stack.

## The native family

***

Native messaging reaches the rails below. Each service speaks the messaging contract of a specific Brazilian settlement, clearing, or regulatory system:

| Rail | System | What it moves |
| - | - | - |
| **Lerian SPB** | Sistema de Pagamentos Brasileiro | TED and STR messaging (large-value interbank transfers settled in real time) |
| **Lerian SPI** | Sistema de Pagamentos Instantâneos | Pix (instant payments settled directly in BACEN's instant-payment system) |
| **Lerian SILOC** | Sistema de Liquidação Diferida (Núclea) | Deferred net settlement of interbank credit orders (boleto and card flows) |
| **Lerian SLC** | Serviço de Liquidação Centralizada (Núclea) | Centralized settlement of the Brazilian card arrangement between acquirers, sub-acquirers, and settlement institutions |
| **Lerian STA** | Sistema de Transferência de Arquivos | File exchange with BACEN over HTTPS on the internet (regulatory and operational file transfer) |
| **Lerian SISBAJUD** | Sistema de Busca de Ativos do Poder Judiciário | Court-ordered asset searches, balance queries, and blocking and unblocking orders |
| **Lerian Consignado — Dataprev** | Dataprev | Payroll-deductible (consignado) credit operations exchanged with Dataprev |
| **Lerian CCS** | Cadastro de Clientes do Sistema Financeiro Nacional | Customer-relationship reporting to BACEN and relationship transfers between institutions |
| **Lerian SCR** | Sistema de Informações de Crédito | Consolidated credit-position consultations of a client, read from BACEN |
| **Lerian BC Correios** | BC Correio | Official correspondence with BACEN: received mail and messages to BACEN departments |
| **Lerian SRC** | BC Protege+ | Restriction consultations sent to BACEN before an institution opens an account or changes the ownership of a relationship |

## How the two models coexist

***

* A **native rail** connects your institution directly, on Lerian-owned software, with no connectivity partner between you and BACEN. Lerian SPI is the native Pix messaging design and covers the full SPI messaging contract. Its native connector is not available for Pix Lerian v1.0.0. Lerian SPB carries TED and the currently supported SPB messaging flows.
* A **partner interface** connects your institution through a connectivity partner: Pix through JD and BTG, TED through JD, boletos and bill payment through BTG. The partner absorbs the mechanics of the BACEN link. Your integration with the Lerian platform stays the same.

Both models preserve your ledger, accounts, and business logic regardless of how a message reaches the rail. They do not require a particular ledger. The rail emits settlement facts for your ledger consumer.

In the navigation, [Brazil Rails](/en/rails/what-are-brazil-rails) holds one anchor per rail. [Interfaces](/en/interfaces/introduction) holds one anchor per interface. That tab also lists the paths that run in production today.


# How Lerian SCR works
Source: https://docs.lerian.studio/en/rails/scr/how-scr-works

How Lerian SCR runs a consultation: request, credential and channel protections, result cache and tariff, code decoding, and the fail-closed audit.

A consultation runs in one request. Lerian SCR serves what the cache already holds and calls BACEN for the rest. It then decodes the answer and audits the outcome before it replies.

## Consultation request

***

A consumer posts a consultation with the borrower document, the client type, and a range of reference dates. The request also declares the holder's authorization under LC 105/2001. That declaration is a required flag, and the consent record stays with the institution.

The call is synchronous. The decoded result arrives in the response body of the same request, and there is no create-then-poll flow. The response carries an identifier for a later re-read.

BACEN charges per client and per reference date, so a narrow range costs less. Each request carries an idempotency key, and a retry that replays a stored outcome pays no second tariff.

## Credential resolution and channel protections

***

Lerian SCR resolves the institution's channel credential before it opens the circuit breaker path. A credential failure is a local failure, and a vault outage never trips the channel breaker.

The adapter then issues an HTTPS `GET` to BACEN's `/wsscr2n/cliente/resumo` operation and sets HTTP Basic on the request. The channel authenticates the server only, through the host system certificate pool, with TLS 1.2 as the floor and no client certificate.

Three guards stand in front of the call, in this order. Single-flight coalescing merges identical concurrent consultations into one upstream call. A per-institution circuit breaker then decides whether the call proceeds. Inside the breaker, a semaphore caps concurrent connections at two per institution. By default, the breaker trips after five consecutive failures, or after a failure ratio of 0.5 over at least ten requests. It then cools down for 30 seconds.

A transport failure, a BACEN platform error, or an answer the service cannot read trips the breaker. A "no position" answer and a client-side rejection do not. An open breaker returns `SCR-1002` at once and does not call BACEN.

## Result cache and tariff

***

Lerian SCR reads a Redis cache before it calls BACEN. The cache holds one entry per reference month under the key `scr:pos:{tenantID}:{blindIndexHex}:{AAAAMM}`. The institution comes first, and the borrower appears only as a blind index. Each value carries the same AES-256-GCM at-rest envelope as the audit row.

A full hit skips the BACEN call and the tariff, and it still audits and emits. A partial hit fetches one range that covers every missing month, so a cached month inside that range is fetched and billed again. A request that asks for fresh data skips the read and pays the tariff.

By default an entry for the current month lives four hours, and an entry for a closed month lives 720 hours. A month that BACEN omits becomes a no-position marker, so a repeat of the same range does not pay for that month again.

An unreadable entry counts as a miss. A cache write is best-effort and never fails a consultation. A deployment without Redis refuses consultations with `SCR-9002`.

## Decoding

***

BACEN answers with codes for modality, funding source, indexer, currency variation, creditor segment, guarantee type, and additional-information type. Lerian SCR resolves each code against the SCR annex tables, which ship inside the service, and returns a `{ code, description }` pair.

An unknown code keeps the code, returns a null description, and increments an unknown-code metric. It never fails the consultation. An empty code returns an empty code with no description and fires no metric.

The decoder reads domain codes only. It never sees the borrower document.

## Audit and events

***

Every terminal outcome writes one audit row. The row and its outbox event commit in one transaction, so no consultation leaves without its trail.

A failed write fails the consultation with `SCR-9001`, a retryable 503. The consumer never receives an un-audited credit position. The row keeps its personal data under AES-256-GCM encryption and an HMAC-SHA256 blind index, with two independent keys.

The outbox carries two event types: `studio.lerian.br-scr.consulta.completed` for a served consultation, and `studio.lerian.br-scr.consulta.failed` for a failed one. The dispatcher publishes both on the topic `lerian.streaming.br-scr`, with `lerian.streaming.br-scr.dlq` for poison messages.

An operator can turn emission off. The rows then stay pending in the outbox, and they ship after emission is back on and the service restarts.


# Environment variables
Source: https://docs.lerian.studio/en/rails/scr/scr-environment-variables

Deploy-time environment variables for Lerian SCR: the BACEN consultation channel, the datastores, event streaming, the secret store, and the at-rest keys.

Lerian SCR is the Lerian-owned rail that consults borrower positions at BACEN. You set these variables at deploy time. A service restart makes them take effect. The system plane holds a second set of knobs an operator changes after deployment. See [Operations](/en/rails/scr/scr-operations) and [System plane](/en/reference/platform/systemplane/overview).

In the tables below, the **Default / Required** column shows the default value. `—` means no default. A bold qualifier marks a value you must set. A row marked `Sensitive.` carries credential or key material. Inject it from your secret manager at deploy time, and never commit a value.

The strict posture covers a production environment name and the `saas` deployment mode. **Required in production** marks a value that the strict posture demands. A missing or insecure value there refuses the boot.

## Service and runtime

***

| Variable | Default / Required | Description |
| - | - | - |
| `SERVICE_NAME` | `br-scr` | Service identity stamped on logs and telemetry. |
| `ENV_NAME` | `development` | Deployment environment. The values `production` and `prod` select the strict posture. |
| `LOG_LEVEL` | `info` | Minimum log level. One of `debug`, `info`, `warn`, `error`. Another value refuses the boot. |
| `SERVER_PORT` | `3003` | Inbound HTTP listen port. |
| `DEPLOYMENT_MODE` | `local`, **Required in production** | TLS posture. One of `local`, `byoc`, `saas`. The value `saas` selects the strict posture, and it also needs `ENV_NAME` set to `production`, `prod`, or `staging`. The strict posture demands an explicit value. |
| `TRUSTED_PROXIES` | — | Comma-separated proxy addresses or CIDR ranges whose forwarded client IP the service trusts. Empty trusts no proxy and reads the direct peer. A wildcard range refuses a strict boot. |
| `PROXY_HEADER` | `X-Forwarded-For` | Header the service reads the client IP from. It applies only when the trusted proxy list is set. |
| `READYZ_DRAIN_DELAY` | `3s` | Window held open after readiness reports 503 on shutdown, before the listener closes. A `0` disables the wait. An invalid or a negative value falls back to the default. The service caps the window at a third of the shutdown budget. |

> [!NOTE]
>
> Lerian SCR exposes `/health`, `/readyz`, and `/version` on the main port. See [Health and readiness](/en/reference/health-and-readiness) for the probe contract, and [Operations](/en/rails/scr/scr-operations) for the readiness checks.

## Postgres

***

Postgres holds the audit trail, the credential metadata, and the outbox. An operator applies the schema before the first start. The service reads the schema and never creates it.

| Variable | Default / Required | Description |
| - | - | - |
| `POSTGRES_HOST` | **Required in production** | Database host. |
| `POSTGRES_PORT` | `5432` | Database port. |
| `POSTGRES_USER` | **Required in production** | Database user. |
| `POSTGRES_PASSWORD` | — | Password for that user. Sensitive. |
| `POSTGRES_DB` | **Required in production** | Database name. |
| `POSTGRES_SSLMODE` | `disable`, **Required in production** | Connection TLS mode. The strict posture accepts only `require`, `verify-ca`, or `verify-full`. |
| `POSTGRES_MAX_OPEN_CONNS` | `25` | Maximum open connections in the pool. A value of `0` or less restores the default. |
| `POSTGRES_MAX_IDLE_CONNS` | `10` | Maximum idle connections in the pool. A value of `0` or less restores the default. |
| `POSTGRES_CONN_LIFETIME` | `30m` | Maximum lifetime of a pooled connection. An unparseable value falls back to the default. |
| `POSTGRES_CONN_IDLE_TIME` | `5m` | Maximum idle time of a pooled connection. An unparseable value falls back to the default. |

## Redis

***

Redis backs the result cache, the idempotency window, and the inbound rate limit.

| Variable | Default / Required | Description |
| - | - | - |
| `REDIS_HOST` | **Required** | Cache host. Every deployment mode requires it, unless the operator states the opt-out below. A blank host otherwise refuses the boot. |
| `REDIS_PORT` | `6379` | Cache port. |
| `REDIS_PASSWORD` | — | Cache password. Sensitive. |
| `REDIS_TLS_ENABLED` | `false`, **Required in production** | The strict posture demands `true` when Redis is configured. |
| `SCR_REDIS_DISABLED` | `false` | The value `true` is the explicit statement that this deployment runs without Redis. The consultation and the credential update then answer `SCR-9002`. |
| `RATE_LIMIT_ENABLED` | `false` | The value `true` turns on the inbound rate limit that `scr.rate_limit` configures. |

## Streaming

***

The outbox dispatcher publishes the consultation events. No variable sets the topic, because the service derives it from the event source. The first five variables belong to Lerian SCR. The rest belong to the streaming library, which applies the broker TLS and the SASL credentials to the dial.

| Variable | Default / Required | Description |
| - | - | - |
| `SCR_STREAMING_BROKERS` | **Required** | Comma-separated broker addresses. Every deployment mode requires them, unless the operator states the opt-out below. A blank list otherwise refuses the boot. |
| `SCR_STREAMING_CLIENT_ID` | `br-scr` | Producer client identifier. |
| `SCR_STREAMING_SOURCE` | `br-scr` | CloudEvents source, and the origin of the topic name. The boot refuses any other value. The service compares the raw value, so padding also refuses the boot. |
| `SCR_STREAMING_TLS` | `false`, **Required in production** | The strict posture demands `true` when brokers are configured. A `true` here also demands `STREAMING_TLS_ENABLED=true`. |
| `SCR_STREAMING_EMISSION_DISABLED` | `false` | The value `true` stops the dispatcher. The events stay as pending outbox rows, and they ship after emission is back on and the service restarts. |
| `STREAMING_TLS_ENABLED` | `false` | Enables the TLS dial to the broker. |
| `STREAMING_TLS_CA_CERT` | — | Base64-encoded PEM certificate authority. A broker behind a private authority needs it. Without it only a publicly trusted broker certificate validates. |
| `STREAMING_SASL_MECHANISM` | — | SASL mechanism for the producer. Without a mechanism the producer connects anonymously and presents no principal for the write grant. |
| `STREAMING_SASL_USERNAME` | — | SASL user. |
| `STREAMING_SASL_PASSWORD` | — | SASL password. Sensitive. |
| `STREAMING_SASL_ALLOW_PLAINTEXT` | `false` | The value `true` puts the SASL credentials on the wire in the clear. Keep it `false`. |

## Authentication

***

| Variable | Default / Required | Description |
| - | - | - |
| `PLUGIN_AUTH_ENABLED` | `—`, **Required** | `true` sends each gated request to Lerian Access Manager. `false` skips only that call; a bearer token is still required. Only a development `ENV_NAME` outside `saas` accepts `false`. |
| `PLUGIN_AUTH_ADDRESS` | **Required in production** | Authorization server base URL. The strict posture demands an `https` scheme. |

## BACEN channel

***

The outbound channel reaches the BACEN consultation web service over HTTPS with HTTP Basic credentials. The service reads the two credential variables only when the secret store kind is the environment.

| Variable | Default / Required | Description |
| - | - | - |
| `SCR_WSSCR2N_BASE_URL` | **Required in production** | Full base URL, including the BACEN context path. The adapter appends only the operation path. The homologation host is `www9.bcb.gov.br` and the production host is `scr.bcb.gov.br`. The strict posture demands an `https` scheme. |
| `SCR_WSSCR2N_BASIC_USER` | **Required in production with the environment secret store** | The institution's virtual service user, in BACEN's `UUUUUDDDD.OPERADOR` format. It is not the name of the Sisbacen transaction. |
| `SCR_WSSCR2N_BASIC_PASSWORD` | **Required in production with the environment secret store** | Password for that service user. Sensitive. |

## Secret store

***

The secret store resolves the BACEN channel credential.

| Variable | Default / Required | Description |
| - | - | - |
| `SECRET_STORE_KIND` | `env` | Credential backing. The value `env` reads the credential from the environment. The value `aws` reads it per institution from the managed vault, and it mounts the credential operations. Another value refuses the boot. |
| `AWS_REGION` | **Required in production with the managed vault** | Region the managed vault client resolves its endpoint from. |
| `SECRET_STORE_PREFIX` | `scr` | Vault path prefix for the per-institution credentials. Not a secret. |

## At-rest encryption

***

The audit trail encrypts the borrower data and indexes it blind. Two independent keys do that work. One key for both would leak the relation between the ciphertext and the index. Outside the strict posture the service falls back to well-known development keys, which must never reach a regulated runtime.

| Variable | Default / Required | Description |
| - | - | - |
| `SCR_ATREST_ENCRYPTION_KEY` | **Required in production** | AES-256 envelope key, as base64 or as 32 raw bytes. Sensitive. |
| `SCR_ATREST_BLIND_INDEX_KEY` | **Required in production** | HMAC key for the searchable document index. It must hold at least 32 characters, and it must differ from the envelope key. Sensitive. |

## Telemetry and metrics

***

| Variable | Default / Required | Description |
| - | - | - |
| `ENABLE_TELEMETRY` | `false` | The value `true` wires the OpenTelemetry providers. |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | — | Collector endpoint. With telemetry on, the strict posture demands an `https` scheme. |
| `METRICS_PROMETHEUS_ENABLED` | `false` | The value `true` opts into a dedicated Prometheus scrape listener. |
| `METRICS_PROMETHEUS_ADDRESS` | `127.0.0.1:9075` | Bind address of that listener. The application port carries no `/metrics` route. |


# Integrating with Lerian SCR
Source: https://docs.lerian.studio/en/rails/scr/scr-integration

Integrating with Lerian SCR: the operation surface, token scopes, idempotency, the error catalog, the consulta events, and the request conventions.

Lerian SCR exposes one REST surface. The institution comes from the token.

## API surface

***

| Operation | Scope | Purpose |
| - | - | - |
| `POST /v1/scr/consultations` | `scr:consultation:write` | Consult a borrower position. Tariffed. |
| `GET /v1/scr/consultations/{id}` | `scr:audit:read` | Re-read a consultation, untariffed. |
| `GET /v1/scr/audit` | `scr:audit:read` | List the audit trail. |
| `GET /v1/scr/credential` | `scr:credential:read` | Read credential status, never the secret. |
| `PUT /v1/scr/credential` | `scr:credential:write` | Set or rotate the credential. |
| `GET /v1/scr/operations/summary` | `scr:dashboard:read` | Aggregate summary, no personal data. |
| `/v1/system/{namespace}/{key}` | `scr:system:write` | Read or change runtime configuration. |
| `GET /v1/streaming/manifest` | `scr:streaming:read` | The event manifest. |
| `GET /health` | None | Liveness probe. |
| `GET /readyz` | None | Readiness probe, per dependency. |
| `GET /version` | None | Build stamp. |

The credential operations exist only when a writable vault backs the deployment. Otherwise the credential comes from the environment.

## Authentication and tenancy

***

A consumer authenticates with an OAuth2 client-credentials token in `Authorization: Bearer`. With `PLUGIN_AUTH_ENABLED=true`, the authorization server decides every gated request. A scope has the shape `scr:<resource>:<action>`. See [Access Manager](/en/platform/access-manager).

The institution comes from the token claims, never from a body field, header, path, or query. A dedicated deployment fixes it per instance.

A missing token answers `SCR-0201`, and a missing scope `SCR-0202`. An unreachable authorization server answers `SCR-1002`, because the gate fails closed.

## Idempotency

***

The two effectful operations require an `X-Idempotency` header, and a request without it answers `SCR-0004`. A retry inside a five-minute window replays a 2xx or 4xx outcome and pays no second tariff. After a 5xx outcome the key is free, and a retry runs the operation again. A key reused with a different body answers `SCR-0003`. Without Redis both operations answer `SCR-9002`.

## Errors

***

A failure answers `application/problem+json` under RFC 9457, with the code and the status.

| Code | Status | When |
| - | - | - |
| `SCR-0001` | 400 | Malformed body or query parameters. |
| `SCR-0002` | 422 | Invalid document, date range, or authorization declaration. |
| `SCR-0003` | 409 | `X-Idempotency` reused with a different body. |
| `SCR-0004` | 422 | `X-Idempotency` missing. |
| `SCR-0201` | 401 | Missing or invalid access token. |
| `SCR-0202` | 403 | Scope missing for the action. |
| `SCR-0301` | 404 | No such consultation or audit record. |
| `SCR-0401` | 429 | Rate limited. `Retry-After` gives the wait. |
| `SCR-1001` | 502 | BACEN platform error, passed through in `details.upstreamViolations`. |
| `SCR-1002` | 503 | Channel unavailable, breaker open, or vault unreachable. |
| `SCR-1003` | 504 | Upstream timeout. |
| `SCR-9000` | 500 | Unexpected internal error. |
| `SCR-9001` | 503 | The audit write did not commit. |
| `SCR-9002` | 503 | The idempotency store is unavailable, and the operation did not run. |

## Events

***

Lerian SCR emits one event per terminal consultation through a transactional outbox. The audit row and the event commit together.

* `studio.lerian.br-scr.consulta.completed`: the consultation returned an answer, a position or none.
* `studio.lerian.br-scr.consulta.failed`: the consultation returned no answer.

Both types travel on the topic `lerian.streaming.br-scr`, and poison messages on `lerian.streaming.br-scr.dlq`. No variable sets the topic, so provision both. See [Streaming Hub](/en/platform/streaming-hub/what-is-streaming-hub).

When an operator turns emission off, the dispatcher does not start. The rows stay pending, and they ship after emission is back on and the service restarts.

## Integration conventions

***

* **Correlation.** `X-Request-ID` carries a UUID through logs and traces.
* **Reference dates.** Consultation ranges and audit filters use `AAAAMM`, a six-digit year and month. The operational summary takes a date-time range instead.
* **Filters.** The document filter takes 8 to 14 digits, matched through the blind index. Client type `1` is an individual, `2` a company.
* **Pagination.** The audit list takes an opaque `cursor` and a `limit` from 1 to 200, default 50.


# Operating Lerian SCR
Source: https://docs.lerian.studio/en/rails/scr/scr-operations

Operating Lerian SCR: readiness checks, runtime configuration namespaces, credential rotation, cache and retention, metrics, and the strict posture.

Lerian SCR runs on a tariffed regulatory channel, and its operational surface protects it.

## Health and readiness

***

`GET /health` answers liveness. `GET /readyz` answers one entry per dependency.

| Check | What it probes | When it fails |
| - | - | - |
| `postgres` | A ping on the primary pool. | Unreachable: down. |
| `redis` | A ping on the cache client. | Unreachable: down. Absent: skipped. |
| `scr_endpoint` | A limited TLS handshake to BACEN. No query, no credential. | Broken chain: down. Dial timeout: degraded. |
| `vault` | A reachability call on the credential store. | Unreachable: degraded. |
| `plugin-access-manager` | A GET on the Access Manager `/health`, with no token. | Unreachable, or an error status other than 401 or 403: down. A blank `PLUGIN_AUTH_ADDRESS`: down. Authentication off: skipped. |
| `event_emission` | The declared emission posture. | Never. It reports only. |
| `systemplane_schema` | The runtime-configuration schema in Postgres. | An outdated or partly applied schema: down. |

The handshake result serves for 20 seconds, so readiness never dials BACEN per request. The pod-level breaker opens only when every per-institution breaker is open.

On shutdown `/readyz` turns 503 first, and the listener stays open three seconds. `READYZ_DRAIN_DELAY` overrides it.

## Runtime configuration

***

Eight namespaces reach an operator at `/v1/system`, under the `scr:system:write` scope. The table lists the seven the service reads. `scr.postgres` also exists in the catalog, and the service takes its connection-pool settings from the [environment variables](/en/rails/scr/scr-environment-variables).

A log-level change takes effect at once. A retention change takes effect at the next purge sweep. The service reads every other namespace when it starts, so a change there takes effect at the next restart. See [System plane](/en/reference/platform/systemplane/overview).

| Namespace | What it controls | Defaults |
| - | - | - |
| `scr.app` | Log level. | Boot configuration. |
| `scr.rate_limit` | Inbound limit per IP, with `RATE_LIMIT_ENABLED=true`. | 100 per 60 seconds. |
| `scr.outbox` | Interval, batch size, publish attempts. | `2s`, 50, 3. |
| `scr.wsscr2n` | Request deadline, connections per institution. | `25s`, 2. |
| `scr.cache` | Entry lifetimes. | `4h`, `720h`. |
| `scr.circuit_breaker` | Trip thresholds, cool-down. | 5 failures, ratio 0.5, minimum 10, `30s`. |
| `scr.retention` | Purge window, sweep cadence. | Empty. Purge off. |

The configured consultation deadline must be below 28 seconds. Audit persistence has a separate timeout. The connection cap accepts 1 or 2.

## Credentials and rotation

***

The secret-store kind picks the credential source. The environment kind reads the user and password from the deployment environment. The managed-vault kind resolves them per institution, and the database holds only a reference.

The managed-vault kind also mounts `PUT /v1/scr/credential`. It writes the vault first and the metadata second, so a retry reuses the reference.

The password never reaches a log, a span, or an error. The status operation returns a masked user name. A vault outage answers `SCR-1002` and never trips the channel breaker.

## Cache and retention

***

The result cache holds one entry per institution, borrower blind index, and reference month. Each value carries the audit row's at-rest envelope. A current-month entry lives four hours, a closed-month entry 720 hours. An unreadable entry counts as a miss.

The audit purge stays off until an operator sets a window. An empty window deletes nothing. With a window, a sweep deletes older rows in bounded batches, and never archives them.

## Metrics and tracing

***

With `ENABLE_TELEMETRY=true`, metrics leave by OTLP push. A Prometheus scrape listener is opt-in on a loopback address, `127.0.0.1:9075` by default. The application port has no `/metrics` route.

Two histograms measure a consultation: end to end, and the overhead without the BACEN call. Their labels carry the institution, the cache-hit flag, and the outcome, never the borrower. Counters cover unknown decode codes, unreadable cache entries, and purged rows.

## Deployment posture

***

A production environment name or the SaaS deployment mode selects the strict posture. Strict boot demands an explicit deployment mode, the Postgres host, database and user, and authorization over an https address. It demands the channel base URL over https, and TLS on Postgres and any configured Redis or broker. It demands two distinct at-rest keys and a region for the managed vault, and it forbids a wildcard proxy range.

A blank broker list or Redis host refuses the boot, unless an operator states the opt-out. The boot log and `/readyz` then name the degraded protections.

An operator applies the schema outside the runtime process. The service reads it and never creates it.


# What is Lerian SCR?
Source: https://docs.lerian.studio/en/rails/scr/what-is-lerian-scr

Lerian SCR is a REST facade over BACEN's wsscr2n SCR3 consultation channel. It returns a client's consolidated credit position and audits every query.

**Lerian SCR** is a REST facade over BACEN's **wsscr2n** web service, the SCR3 consultation channel. SCR is the *Sistema de Informações de Crédito*, the BACEN credit information system.

A consumer authenticates with a machine-to-machine token and asks Lerian SCR for a client's consolidated credit position. The service consults wsscr2n for the institution, decodes the result, audits the query, and returns it.

Each consultation writes an audit row. The audit write is fail-closed: a failed audit write fails the consultation, and the consumer gets no result.

A result cache, a per-institution concurrency limit, single-flight coalescing of identical queries, and a per-institution circuit breaker protect the channel.

## What Lerian SCR does and does not do

***

**Lerian SCR does:**

* **Call the wsscr2n channel.** It issues an HTTPS `GET` to BACEN's `/wsscr2n/cliente/resumo` operation with HTTP Basic authentication, over TLS 1.2 or later.
* **Audit every query.** One consultation writes one audit row. Its personal data carries AES-256-GCM encryption at rest and an HMAC-SHA256 blind index for search.
* **Protect the tariffed channel.** A result cache, a two-connection cap per institution, single-flight coalescing, and a per-institution circuit breaker sit in front of BACEN.

**Lerian SCR does not:**

* **Use mTLS.** The channel authenticates the server only and puts HTTP Basic on top. Lerian SCR sends no client certificate.
* **Log the borrower document.** No log line, span, or error message carries it.
* **Hold the consent trail.** The request declares the holder's authorization under LC 105/2001. The consent record itself stays with the institution.
* **Create its database schema.** An operator applies the schema out of band before the service starts.

## Who it serves

***

Lerian SCR serves the internal consumers of a financial institution, such as a scoring consumer that needs a borrower's consolidated credit position.

## Glossary

***

| Term | Meaning |
| - | - |
| **SCR** | *Sistema de Informações de Crédito*, the BACEN credit information system. |
| **SCR3** | The SCR consultation contract that the wsscr2n web service serves. |
| **wsscr2n** | BACEN's web service for the SCR3 consultation. Lerian SCR is the facade over it. |
| **WSCR0001** | The Sisbacen transaction that grants an institution access to the consultation web service. The channel credential is the institution's virtual service user, not this name. |
| **IF** | *Instituição financeira*, the financial institution. One tenant of Lerian SCR. |
| **Reference date (`AAAAMM`)** | One SCR month, as a six-digit year-and-month integer. BACEN also calls it the *data-base*. |
| **Position** | A borrower's consolidated credit picture for one reference date. An empty result means no position, not an error. |
| **Tariff** | The BACEN charge for a consultation, per client and per reference date. |
| **Blind index** | The deterministic HMAC of a borrower document. It makes a row searchable and keeps the document out of the clear. |
| **Single-flight** | The coalescing of identical concurrent consultations into one call to BACEN. |
| **Circuit breaker** | The per-institution guard that stops calls to BACEN after repeated channel failures. |

For how Lerian SCR sits alongside the other native rails and the partner interfaces, see [Native messaging and partner interfaces](/en/rails/native-messaging).


# How Lerian SILOC works
Source: https://docs.lerian.studio/en/rails/siloc/how-siloc-works

Gateway connection lifecycle, MQ-configured SFN processing, supported-message dispatch, at-least-once delivery with durable deduplication, outbound requests, and certificate handling.

Lerian SILOC exposes typed operations over the `/api/v1/siloc` surface. Over one connection to Núclea, it receives SILOC messages and routes each one, and it sends the institution's own requests. The service also keeps the participant, certificate, and coverage records that support this work.

## Gateway connection lifecycle

***

A complete SILOC MQ connection descriptor activates inbound SFN processing. The service then opens and maintains one messaging-gateway connection to Núclea's SILOC over the national financial-system network. Four guards protect the connection:

* a **circuit breaker** that trips on repeated failure,
* **automatic reconnect** with a capped backoff,
* a **credential-disabled stop** that halts the gateway after a certificate revocation, and
* a **readiness probe** that reports the gateway's connection and health.

Without the descriptor, the service starts with no live SILOC connectivity, and a partial descriptor prevents the service from starting. See [Environment variables](/en/rails/siloc/siloc-environment-variables). With the complete descriptor configured, the service decrypts and decodes inbound messages from the regulated envelope before it routes them.

## Inbound SFN dispatch

***

After decoding, the ingress selects a route from a closed **(`CodProdt`, `CodMsg`)** policy:

| Messages | Product | Route |
| - | - | - |
| **PAG0102**, **LDL0021**, **PAG0103** | SLC | Relay to Lerian SLC |
| **PAG0101** | OT or SLC | Participant status, per product |
| **PAG0102**, **LDL0021**, **PAG0103** | OT | Cycle opening, deposit instruction, and cycle close |
| **LDL0024**, **LDL0028** to **LDL0031** | OT | Schedule grid and câmara session notices |
| **LDL0001**, **LDL0007**, **LDL0010**, **LDL0013**, **LDL1018**, **LDL1026**, **LDL1027** | None | Câmara advices |
| **LDL1001**, **LDL1011**, **LDL1014** | None | Collateral advisories |
| **LTR0001**, **LTR0007**, **LTR0012** | None | Card-route notices, relayed to Lerian SLC |
| **PAG0200** | None | Bilateral balances |
| The `R2` notice of a PAG transfer | None | Transfer credit notice |
| **GEN0015** | None | File-available notice |
| An answer or refusal to a request the institution sent | The product of the request | Answer to the request |

The SLC relay acts on arrival. The service parks every other routed message and applies it later: `PAG0101` when `STATUS_REPLAY_ENABLED=true`, and the rest when `OT_REPLAY_ENABLED=true`. `LDL0020`, `LDL0006`, and every other product/code pair fail closed to an operator exception, and the service never relays them as settlement funding. A message with a blank `BCMSG.NUOp` follows the same fail-closed path.

## At-least-once dispatch with durable deduplication

***

The source can redeliver a message, so the SLC relay is **at-least-once**. For a successfully decoded SLC funding frame with a nonblank `BCMSG.NUOp`, the service checks durable deduplication by **`BCMSG.NUOp`** before relay. The policy treats that operation number as globally unique. The service does not use a message-ID-only key.

The service writes the processed-message record only after a successful relay and before it acknowledges the source. It creates no such record for an undecoded or unsupported message. A failure before the service writes that record can leave the message eligible for another delivery. Do not treat this behavior as an unconditional end-to-end exactly-once guarantee.

## Failure outcomes

***

* A **retryable** failure, such as a datastore outage, returns the frame to the receive queue, and the service receives it again after `MQ_BACKOUT_DELAY`. A frame refused more than `MQ_BACKOUT_THRESHOLD` times moves to `MQ_BACKOUT_QUEUE`. The service records it for an operator and raises `INBOUND_QUARANTINED`.
* A **non-retryable** failure, such as an unsupported (`CodProdt`, `CodMsg`) pair, fails closed to a durable operator exception. The service acknowledges the message only after that exception record commits.
* When the relay to Lerian SLC is down, the service parks the funding frame as a relay failure and raises `RELAY_DOWN`. An operator replays it after the relay recovers.
* Before it applies a parked message, the service validates it against the official XSD. The service never applies a message that the schema refuses, and it raises `INBOUND_SEMANTIC_REJECTED`. While the validator gives no answer, the message waits and the service raises `XSD_VALIDATOR_DOWN`.
* The processed-message record protects only the successfully decoded and supported messages described above. It does not promise retention of every frame or exactly-once effects across every downstream system.

## Ingestion observability

***

* **List relayed messages**: the audit feed of the funding messages that the service relayed to Lerian SLC.
* **Read relay status**: the relay's health (`HEALTHY`, `DEGRADED`, or `DOWN`), whether card settlement is blocked, and the last-relayed timestamp.

## Outbound requests

***

The service sends the institution's own requests to Núclea: transfers, collateral movements, queries, confirmations, and participant status changes. A request still `DISPATCHED` after its answer deadline raises `UNANSWERED_REQUEST`.

After the gateway accepts a queued outbound message, Lerian SILOC records its transition from `SUBMITTED` to `DISPATCHED` in the database. A retryable dispatch failure leaves it `SUBMITTED` for another attempt.

## Participant directory

***

Lerian SILOC keeps a directory of the SILOC participants it settles for. You **register**, **list**, **get**, and **update** a participant, and read a participant's **status**. Each participant carries its ISPB and its role. The service keeps a participant's operational status per product, and the câmara's `PAG0101` messages set it.

Registering or updating a participant, or a change to its status, emits a participant fact. Registration writes are idempotent through the `X-Idempotency` header, so a retried registration does not create a duplicate.

| Role | Meaning |
| - | - |
| **Direct** | A direct SILOC participant. |
| **Indirect** | A participant that settles through another institution. |
| **Settling institution** | The institution that settles on behalf of indirect participants. |

The operational status uses SILOC's seven-value status domain:

| Value | Status |
| - | - |
| 1 | Participating |
| 2 | Excluded from the cycle |
| 3 | Excluded from SILOC |
| 6 | In cycle, excluded from SILOC |
| 7 | Suspended |
| 8 | Suspended, excluded from the cycle |
| 9 | Inoperative (special regime) |

## Regulated certificates

***

The service holds the connection's regulated certificates as references, not as secrets. You **register** a public certificate together with an **external custody reference**. The service parses the certificate for its subject, serial, and validity window, and stores no private key. You then **list**, **get**, and **revoke** certificates over the same surface.

## Capability coverage

***

A read-only **capability listing** describes the settlement-coverage capabilities as a transparency surface. For each message type, it reports the direction, the implementation state, and the disposition.


# Environment variables
Source: https://docs.lerian.studio/en/rails/siloc/siloc-environment-variables

Deploy-time environment variables for Lerian SILOC: runtime, SILOC settlement-queue connectivity, persistence, authentication, and certificates.

Lerian SILOC is Lerian's native messaging integration for SILOC, the deferred-net settlement system that Núclea operates for boleto and card flows. You set these variables at deploy time. A change takes effect only after you restart the service. For the knobs that behave the same across every Lerian Go service (deployment posture, telemetry, and datastore conventions), see [BYOC configuration essentials](/en/reference/byoc-configuration).

In the tables below, **Required** marks a variable you must set, globally or under the stated condition. `—` means no default.

## Runtime and server

| Variable | Description | Default | Required |
| - | - | - | - |
| `SERVICE_NAME` | Service identifier used in logs and telemetry. | Service default | No |
| `ENV_NAME` | Runtime environment label. `production` or `prod` arms the stricter authentication and TLS gates below. | `development` | No |
| `DEPLOYMENT_MODE` | TLS-enforcement posture (`local`, `byoc`, `saas`). `saas` makes TLS mandatory, requires a production `ENV_NAME`, and refuses to start without them. See [Deployment mode and TLS](/en/reference/byoc-configuration#deployment-mode-and-tls). | — | No |
| `LOG_LEVEL` | Log verbosity (`debug`, `info`, `warn`, `error`). | `info` | No |
| `SERVER_PORT` | HTTP listen port. The liveness and readiness probes bind this same port. | `9820` | No |
| `IDEMPOTENCY_RESPONSE_ENCRYPTION_KEY` | AES-256 key that encrypts the responses the service keeps for `X-Idempotency` replays: 32 raw bytes, or their base64 form. Sensitive. | — | Yes |

## Authentication

Lerian SILOC authorizes protected routes through Access Manager. `AUTH_ENABLED` has no default, so the service refuses to start until you set it.

| Variable | Description | Default | Required |
| - | - | - | - |
| `AUTH_ENABLED` | Require Access Manager authorization on protected routes: `true` or `false`. The service accepts `false` only when you set `ENV_NAME` to `development`, `develop`, `dev`, `local`, or `test`, and never with `DEPLOYMENT_MODE=saas`. With `false`, the service skips the Access Manager call but still requires a bearer token. | — | Yes |
| `AUTH_ADDRESS` | Access Manager service address. Must be a valid `https://` URL in production and SaaS. With authorization on and no address, protected routes answer 503. | — | In production and SaaS |

## PostgreSQL

The replica falls back to the primary host when you leave `DB_REPLICA_HOST` empty (single-node default).

| Variable | Description | Default | Required |
| - | - | - | - |
| `DB_HOST` | PostgreSQL host. | — | Yes (live) |
| `DB_PORT` | PostgreSQL port. | `5432` | No |
| `DB_USER` | Database user. | — | Yes (live) |
| `DB_PASSWORD` | Database password. Sensitive. Inject it at deploy time and never commit it. | — | Yes (live) |
| `DB_NAME` | Database name. | — | Yes (live) |
| `DB_SSLMODE` | libpq TLS mode. A mode other than `require`, `verify-ca`, or `verify-full` needs `ALLOW_INSECURE_TLS=true`. | `disable` | No |
| `DB_REPLICA_HOST` | Optional read-replica host. Falls back to `DB_HOST` when unset. | — | No |

## Redis

| Variable | Description | Default | Required |
| - | - | - | - |
| `REDIS_ADDRESS` | Redis/Valkey host and port. The `X-Idempotency` gate keeps its keys here, so state-changing requests and readiness need it. | — | Yes (live) |
| `REDIS_PASSWORD` | Redis password. Sensitive. | — | No |
| `REDIS_DB` | Redis database number. | `0` | No |
| `REDIS_TLS` | Sets the TLS posture reported by the Redis readiness check. It does not configure TLS for the Redis transport. `DEPLOYMENT_MODE=saas` requires `true`. | `false` | No |
| `ALLOW_INSECURE_TLS` | Set true to let the service open PostgreSQL and Redis connections without TLS. The service logs a warning while this override is on. | — | No |

## SILOC settlement connectivity

Lerian SILOC maintains a single IBM MQ connection to the Núclea SILOC settlement queue manager. Setting `MQ_HOST`, `MQ_CHANNEL`, `MQ_QUEUE_MANAGER`, `MQ_SEND_QUEUE`, or `MQ_RECEIVE_QUEUE` makes the service validate the whole connection descriptor fail-closed at startup. The other `MQ_*` variables alone do not activate that validation.

| Variable | Description | Default | Required |
| - | - | - | - |
| `LOCAL_FI_ISPB` | This institution's 8-digit ISPB. Every OT message is authorized against it. With MQ configured, it must match the ISPB in `MQ_CHANNEL`. | — | Yes |
| `MQ_HOST` | Queue-manager host. | — | Yes (live SILOC) |
| `MQ_PORT` | Queue-manager listener port. | — | Yes (live SILOC) |
| `MQ_QUEUE_MANAGER` | Queue-manager name. Must be the Núclea SILOC settlement queue manager. | — | Yes (live SILOC) |
| `MQ_CHANNEL` | Server-connection channel. Must match the Núclea SILOC channel pattern `C02992335.<ISPB>.1`, where `<ISPB>` is the participant's 8-digit ISPB. | — | Yes (live SILOC) |
| `MQ_SEND_QUEUE` | Outbound send queue. | — | Yes (live SILOC) |
| `MQ_RECEIVE_QUEUE` | Inbound receive queue. | — | Yes (live SILOC) |
| `MQ_BACKOUT_QUEUE` | Queue that receives an inbound frame the service refused more than `MQ_BACKOUT_THRESHOLD` times. At most 48 characters, and different from `MQ_SEND_QUEUE` and `MQ_RECEIVE_QUEUE`. | — | Yes (live SILOC) |
| `MQ_BACKOUT_THRESHOLD` | How many times the service can refuse an inbound frame before it moves the frame to `MQ_BACKOUT_QUEUE`. An integer from 1 to 1000. | — | Yes (live SILOC) |
| `MQ_BACKOUT_DELAY` | Pause before a refused frame is delivered again, as a duration with a unit, from `100ms` to `1m` (for example, `2s`). | — | Yes (live SILOC) |
| `MQ_TLS_ENABLED` | Enable mutual TLS on the MQ channel. Must be `true` in production and SaaS. | `false` | In production and SaaS |
| `MQ_SSL_KEY_REPOSITORY` | Path to the GSKit key repository (`MQSSLKEYR`) backing MQ TLS. The private key lives here, never in an environment variable. Required when `MQ_TLS_ENABLED=true`. | — | If TLS enabled |
| `CAMARA_PAG_ISPB` | The SILOC câmara's 8-digit ISPB. Every inbound settlement message is authorized against this sender before it has any semantic effect. It matches the settlement channel prefix, so override it only for a test câmara. A value that is not 8 digits refuses to start. | `02992335` | No |

## Outbound messages

The service sends the institution's requests to Núclea only when both certificate identifiers and `MQ_SEND_QUEUE` are set. Set both identifiers or neither: one without the other refuses to start.

| Variable | Description | Default | Required |
| - | - | - | - |
| `SFN_OUTBOUND_SIGNER_CERT_ID` | The certificate that signs outbound messages, as `<authority>:<64 hex>`. The custody provider holds its key. | — | To send |
| `SFN_CAMARA_CERT_ID` | The câmara certificate, from the trust manifest, that outbound messages are encrypted to, in the same form. | — | To send |
| `OT_OUTBOUND_DISPATCH_INTERVAL` | How often the dispatcher puts submitted messages on the send queue. | `5s` | No |
| `UNANSWERED_REQUEST_DEADLINES` | How long a dispatched request waits for its answer before the service raises `UNANSWERED_REQUEST`, as `default=<duration>,<COD_MSG>=<duration>`. Unset, queries wait 2 minutes, confirmations 5, and commands 15. The minimum is 1 second. | — | No |
| `UNANSWERED_REQUEST_SWEEP_INTERVAL` | How often the service checks for unanswered requests, from `1s` to `10m`. | `30s` | No |

## Message validation

The service validates the inbound frames it applies and the outbound messages it sends against the official XSD schemas, through a validator sidecar.

| Variable | Description | Default | Required |
| - | - | - | - |
| `XSD_VALIDATOR_URL` | Base URL of the validator sidecar. | — | Yes (live SILOC) |
| `XSD_VALIDATOR_TIMEOUT_SEC` | Timeout of one validation request, in seconds. | `10` | No |

The sidecar listens on `XSD_VALIDATOR_ADDR` (default `127.0.0.1:9091`), and its own `AUTH_ENABLED` has no default. The service sends no bearer token to the sidecar, so run the sidecar with `AUTH_ENABLED=false` on a literal loopback address.

## Certificates

| Variable | Description | Default | Required |
| - | - | - | - |
| `CERT_READINESS_MIN_DAYS` | Days-to-expiry threshold below which a currently valid certificate logs a warning and raises a `CERTIFICATE_EXPIRY` alert. It does not degrade readiness solely because the certificate is near expiry. Must be greater than 0. | `30` | No |

## Trust and custody

| Variable | Description | Default | Required |
| - | - | - | - |
| `SFN_TRUST_MANIFEST_PATH` | Path to the SFN trust manifest used to validate regulated-message trust material. Without it, the service reports not ready. | — | Yes (live SILOC) |
| `SFN_CUSTODY_CONFIG_PATH` | Path to the custody-provider configuration. Without it, the service reports not ready. | — | Yes (live SILOC) |
| `SFN_CUSTODY_CACHE_ENTRIES` | Maximum number of custody entries kept in the in-memory cache. | `16` | No |

## Background processing

| Variable | Description | Default | Required |
| - | - | - | - |
| `OT_REPLAY_ENABLED` | Apply the parked inbound messages other than `PAG0101`: OT cycle messages, câmara advices and notices, and answers to the institution's requests. | `false` | No |
| `OT_REPLAY_INTERVAL` | How often the OT replay runs. | `10s` | No |
| `STATUS_REPLAY_ENABLED` | Apply the parked `PAG0101` participant-status messages. | `false` | No |
| `STATUS_REPLAY_INTERVAL` | How often the status replay runs. | `10s` | No |
| `RECONCILE_ENABLED` | Reconcile OT cycles against their final ROC, and settle a cycle whose ROC matches its settled instruction. | `false` | No |
| `RECONCILE_INTERVAL` | How often reconciliation runs. | `10s` | No |
| `LDL_FACT_CONSUMER_ENABLED` | Consume the SPB LDL settlement facts. Each fact records the outcome of the instruction it names. A failed start is logged and the service keeps running. Disabled, its readiness check reports `skipped`; running, the check does not gate readiness. | `false` | No |
| `CARD_COMMAND_CONSUMER_ENABLED` | Consume card commands from Lerian SLC and send them to Núclea. | `false` | No |
| `CARD_ROUTE_TENANT_ID` | The one tenant whose card commands this installation accepts, or `single-tenant`. | — | With card commands |

## Permission declaration

The service can publish its own permission set to Access Manager at startup. Only `IDP_DECLARATION_ENABLED=true` turns this on. With it on, a missing variable below refuses to start.

| Variable | Description | Default | Required |
| - | - | - | - |
| `IDP_DECLARATION_ENABLED` | Publish the permission set at startup. | `false` | No |
| `IDP_HOST` | Access Manager base URL the set is published to. Must be `https://` outside local and development environments. | — | With declaration |
| `IDP_M2M_CLIENT_ID` | Client ID of the service's machine-to-machine application, whose name must be `siloc`. | — | With declaration |
| `IDP_M2M_CLIENT_SECRET` | Client secret of that application. Sensitive. | — | With declaration |
| `PLUGIN_AUTH_ENABLED` | Must be `true` so the service can obtain the token the publication uses. It does not control route authorization, which `AUTH_ENABLED` does. | — | With declaration |
| `PLUGIN_AUTH_HOST` | Access Manager address for that token. | — | With declaration |

## Observability

| Variable | Description | Default | Required |
| - | - | - | - |
| `ENABLE_TELEMETRY` | Enable OpenTelemetry instrumentation. | `false` | No |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector endpoint. | — | If telemetry enabled |
| `STREAMING_BROKERS` | Broker addresses for the mandatory SILOC fact dispatcher. Streaming has no disabled mode: missing or invalid broker configuration prevents startup rather than leaving facts as `PENDING`. Configure the shared `STREAMING_*` settings as described in [Streaming and outbox](/en/reference/byoc-configuration#streaming-and-outbox). | — | Yes |
| `STREAMING_CLOUDEVENTS_SOURCE` | CloudEvents source identity. Must be exactly `br-siloc`. A different value, including leading or trailing whitespace, prevents startup; the service uses that identity to derive its broker topics and access-control scope. | — | Yes |

## Health and readiness

Lerian SILOC exposes `GET /health` (liveness), `GET /readyz` (readiness), and `GET /version` on the main HTTP port. The service boots and serves these probes even before its datastores and settlement connection are reachable. `/readyz` reports the health of each dependency. See [Health and readiness](/en/reference/health-and-readiness) for the probe contract.


# Integrating with Lerian SILOC
Source: https://docs.lerian.studio/en/rails/siloc/siloc-integration

Integrating with Lerian SILOC: MQ-configured SFN processing, supported-message dispatch, SILOC CloudEvents, and API conventions.

Lerian SILOC is event-driven at its edges. With a configured SILOC MQ connection, it consumes supported SFN messages from Núclea and emits facts onto the platform. It has no client-facing webhook consumers. Downstream systems subscribe to the streaming topics rather than receive callbacks.

## What it consumes

***

* **SFN messages from Núclea.** With the complete SILOC MQ connection descriptor configured, Lerian SILOC decrypts and decodes each inbound message from the regulated envelope, then routes it by a closed **(`CodProdt`, `CodMsg`)** policy. `LDL0020`, `LDL0006`, and every other unsupported pair fail closed to an operator exception. See [How Lerian SILOC works](/en/rails/siloc/how-siloc-works) for the routes.
* **SPB LDL settlement facts**, when `LDL_FACT_CONSUMER_ENABLED=true`. Each fact records the outcome of the instruction it names.
* **Card commands from Lerian SLC**, when `CARD_COMMAND_CONSUMER_ENABLED=true`. The service sends each command to Núclea and publishes its outcome.

## Ingestion and delivery semantics

***

* SLC relay is **at-least-once**. For a successfully decoded SLC funding frame with a nonblank `BCMSG.NUOp`, the durable deduplication key is **`BCMSG.NUOp`**, not a message ID alone.
* The service writes that processed-message record only after a successful relay. It creates no processed-message record for an undecoded or unsupported message. A failure before the record is written can result in another delivery, so this behavior is not an unconditional end-to-end exactly-once guarantee.

## What it emits

***

* **Participant facts.** Lerian SILOC publishes `studio.lerian.br-siloc.siloc_participant.registered`, `studio.lerian.br-siloc.siloc_participant.updated`, and `studio.lerian.br-siloc.siloc_participant.status-changed` as CloudEvents on the platform's streaming backbone. Downstream systems track the participant directory without polling.
* **Operational facts.** Alert transitions (`studio.lerian.br-siloc.siloc_alert.raised`, `studio.lerian.br-siloc.siloc_alert.cleared`, and `studio.lerian.br-siloc.siloc_alert.acknowledged`), schedule changes, câmara advices and notices, answers to the institution's requests, and OT cycle settlement facts.

## No Midaz touchpoint

***

Lerian SILOC has no direct ledger integration. It holds no accounting position. It routes bytes and emits facts. This rail does not book money. The settlement of the net position happens at SILOC and the STR. Any ledger posting lives with the service that owns the money movement.

## Money-path boundary

***

The separate STR rail, [Lerian SPB](/en/rails/spb/what-is-lerian-spb), executes the **STR deposit leg**, the monetary settlement at BACEN. SILOC does not. Lerian SILOC carries the SILOC messages and administers the connection. It never moves money. It sends the institution's transfer and withdrawal requests to Núclea, which executes them.

## API conventions

***

* **Base path** is `/api/v1/siloc`, and errors follow the RFC 9457 problem-detail format.
* **Auth** follows the platform's standard bearer-token scheme.
* **Idempotency.** A state-changing request needs an `X-Idempotency` header of up to 255 characters. Within 24 hours, a retry of the same request with the same key returns the stored response instead of running the command again. A request refused with a 4xx does not spend its key.
* **Certificates are references, not secrets.** A registered certificate carries a public certificate and an external custody reference. It stores or returns no private key.


# Operating Lerian SILOC
Source: https://docs.lerian.studio/en/rails/siloc/siloc-operations

Operate Lerian SILOC: BACEN settlement windows, ICP-Brasil certificates, MQ-configured SFN processing, durable deduplication, monitoring, alerts, and audit.

SILOC settles on a deferred-net, business-day basis. With its SILOC MQ connection configured, the service keeps the gateway connection open and dispatches its supported messages. It holds no accounting position.

## Settlement windows

***

SILOC settles on a deferred multilateral net basis, on business days. Núclea defines the daily settlement windows for boleto and card products. Lerian SILOC records and applies the transfer-order messages that open, advance, reconcile, and close its cycle state. It does not calculate the monetary net position.

## Regulated certificates

***

You register the gateway's certificates as a public certificate plus an external custody reference. The service holds no private key. When you register a certificate, the service parses its subject, serial, and validity window. You revoke the certificate over the API when you retire it. A **credential-disabled** state halts the gateway. A disabled or revoked certificate fail-closes the connection instead of running on invalid credentials.

## Contingency and recovery

***

The SFN ingestion path has defined outcomes under failure. It does not promise to retain every frame. It also does not promise that every operation has a single end-to-end effect:

* A decoded message without a nonblank `BCMSG.NUOp`, or an unsupported **(`CodProdt`, `CodMsg`)** pair fails closed to an operator exception. The service does not support `LDL0020` and `LDL0006`, and never relays them as settlement funding.
* SLC relay is **at-least-once**. For a successfully decoded SLC funding frame, the service checks durable deduplication by **`BCMSG.NUOp`** before relay and writes the processed-message record only after relay succeeds. This is not message-ID-only deduplication and is not an unconditional end-to-end exactly-once guarantee.
* **Parked and refused messages.** [`GET /api/v1/siloc/dlq/deferred`](/en/reference/rails/siloc/list-parked-deferred-inbound-messages) lists the inbound messages parked for replay. Filter with `status=SEMANTIC_REJECTED` for the messages the service refused on their content and never applies.
* **Quarantined frames.** [`GET /api/v1/siloc/dlq/quarantine`](/en/reference/rails/siloc/list-quarantined-inbound-frames) lists the frames moved to the backout queue. After you deal with the copy on that queue, [resolve the frame](/en/reference/rails/siloc/resolve-a-quarantined-inbound-frame). The service does not feed it again, and it clears `INBOUND_QUARANTINED` when no unresolved frame remains.
* **Relay failures.** [`GET /api/v1/siloc/dlq/relay-failures`](/en/reference/rails/siloc/list-relay-failures) lists the funding frames parked during a relay outage. [Replay a frame](/en/reference/rails/siloc/replay-relay-failure) after the relay recovers. A replay of a `BCMSG.NUOp` already relayed resolves the frame without a second relay.

## Reconciliation

***

Reconciliation runs at several grains:

* **Processed-message dedup ledger.** For successfully decoded SLC funding frames with a nonblank NUOp, the ledger uses `BCMSG.NUOp` and records it only after a successful relay. Undecoded and unsupported messages do not receive a processed-message record.
* **Relay audit feed.** The relay feed lists the funding messages that the service relayed to Lerian SLC.
* **Per-participant status and status history.** Each participant carries its operational status per product. The service records each status change as a status-event history entry.
* **OT cycle reconciliation.** With `RECONCILE_ENABLED=true`, the service compares each cycle with its final ROC and settles a cycle whose ROC matches its settled instruction.

## Monitoring, alerts, and audit

***

Lerian SILOC exposes an operator surface for watching OT settlement cycles, connection and relay health, outbound requests, and participant status. The cycle and reconciliation surfaces report recorded state and reconciliation sets. They do not calculate aggregate position figures on read.

* **OT settlement cycles.** [`GET /api/v1/siloc/cycles`](/en/reference/rails/siloc/list-cycles) and [`GET /api/v1/siloc/cycles/{cycleId}`](/en/reference/rails/siloc/get-cycle) list and inspect cycles. [`GET /api/v1/siloc/cycles/{cycleId}/reconciliation`](/en/reference/rails/siloc/get-cycle-reconciliation) returns the reconciliation result, and [`GET /api/v1/siloc/cycles/{cycleId}/recalculations`](/en/reference/rails/siloc/get-cycle-recalculations) returns the cycle's recálculo round chain, including each round's complement/deposit window closure.
* **Settlement instructions.** [`GET /api/v1/siloc/settlement-instructions`](/en/reference/rails/siloc/list-settlement-instructions) and [`GET /api/v1/siloc/settlement-instructions/{instructionId}`](/en/reference/rails/siloc/get-settlement-instruction) return each cycle's obligation legs. [`POST /api/v1/siloc/rocs`](/en/reference/rails/siloc/ingest-roc) ingests a semantic ROC revision. It accepts the rail's semantic ROC format, not a Núclea ROC file, and a revision supersedes prior values for the cycle.
* **Outbound requests.** [`GET /api/v1/siloc/outbound/messages`](/en/reference/rails/siloc/list-outbound-messages-of-every-code) lists the requests the institution sent, newest first. Filter by `status`: the service cannot deliver a `FAILED` request as stored, and that request needs an operator. A `REFUSED` request came back from Núclea with an error.
* **Operational alerts.** [`GET /api/v1/siloc/alerts`](/en/reference/rails/siloc/list-alerts) returns an active-only, keyset-paged feed. Pass `activeOnly=false` to include deactivated alerts as history. The alert types are:
  * Settlement cycle: `WINDOW_CLOSING` (a deposit/complement deadline approaches), `RECALCULATION` (a cycle is in a recálculo round), and `SCHEDULE_CHANGE` (an operator recorded a contingency schedule announcement).
  * Connection and workers: `CONNECTION_DOWN`, `RELAY_DOWN`, `CERTIFICATE_EXPIRY`, `OUTBOUND_DISPATCHER_DOWN`, `OT_REPLAY_DOWN`, and `XSD_VALIDATOR_DOWN`.
  * Câmara notices: `CAMARA_CLOSED`, `CAMARA_INTERRUPTED`, `COLLATERAL_REQUIRED`, `COLLATERAL_SUBSTITUTION`, and `ELIGIBLE_ASSETS_CHANGED`.
  * Inbound messages and requests: `INBOUND_QUARANTINED`, `INBOUND_SEMANTIC_REJECTED`, `FOREIGN_TENANT_COMMAND`, and `UNANSWERED_REQUEST`.
* **Alert acknowledgement.** [`POST /api/v1/siloc/alerts/{id}/acknowledge`](/en/reference/rails/siloc/acknowledge-an-operational-alert) records that an operator saw the alert, with an optional note of up to 500 characters, and moves the alert to history. It does not end the condition. When the service checks an alert on a schedule, such as `RELAY_DOWN`, it raises the alert again while its condition holds. An alert that is already inactive answers 409. `INBOUND_SEMANTIC_REJECTED` and `FOREIGN_TENANT_COMMAND` close only by acknowledgement. A condition alert, such as `RELAY_DOWN` or `RECALCULATION`, also clears when its condition resolves. For example, a cycle that settles clears its `RECALCULATION` alert on the settle path.
* **Homologation scenarios.** [`GET /api/v1/siloc/homologation/scenarios`](/en/reference/rails/siloc/list-homologation-scenarios) lists the certification scenarios and the status of each. [Running a scenario](/en/reference/rails/siloc/run-a-homologation-scenario) checks its pass criterion against the rail's own state and records the evidence. It sends nothing to Núclea.
* **Audit trail.** [`GET /api/v1/siloc/audit-records`](/en/reference/rails/siloc/list-audit-records) returns a paged, verbatim read of the audit trail, for example to export the record of an operator action or a participant status change. Bounds `from` and `to` are RFC3339 instants (the service rejects date-only values).

## Schedule and contingency

***

The canonical OT window grid and the business-day calendar are compiled artifacts on the service. The service projects verbatim the schedule grids and session notices that Núclea sends.

* **Calendar and windows.** [`GET /api/v1/siloc/schedule/calendar`](/en/reference/rails/siloc/get-business-day-calendar) returns the business-day calendar, and [`GET /api/v1/siloc/schedule/windows`](/en/reference/rails/siloc/list-schedule-windows) returns the compiled canonical OT window grid. The grid is a static artifact, not a per-day read, and the service returns it even when the datastore is down.
* **Câmara grids and session.** [`GET /api/v1/siloc/schedule/grids`](/en/reference/rails/siloc/list-schedule-grids) returns the schedule grids Núclea sent, from its change advices and from the answers to the institution's schedule queries. [`GET /api/v1/siloc/schedule/camara-session`](/en/reference/rails/siloc/get-the-camara-s-last-session-announcements) returns the latest opening, closing, interruption, and resumption notices.
* **Contingency schedule changes.** [`POST /api/v1/siloc/schedule/changes`](/en/reference/rails/siloc/record-schedule-change) records a contingency announcement the operator received out of band from Núclea. The body carries `reason` (≤500 chars), `origin` (the announcing channel or upstream reference, ≤256 chars), `effectiveAt`, the announced RFC 3339 instant the change takes effect, and an optional `windowSeq` naming the affected canonical window. With `windowSeq`, `effectiveAt` becomes that window's deposit close for `WINDOW_CLOSING`. The record is **append-only**: a later announcement never rewrites an earlier one. The newest announcement does become the single active `SCHEDULE_CHANGE` alert. Recording one clears the prior alert and raises a new one whose deadline is `effectiveAt` verbatim. [`GET /api/v1/siloc/schedule/changes`](/en/reference/rails/siloc/list-schedule-changes) returns the recorded changes, newest first.

Record a contingency schedule change:

```bash theme={null}
curl -X POST https://siloc.example.com/api/v1/siloc/schedule/changes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency: 2026-07-22-window-2-extension" \
  -d '{
    "reason": "Núclea extended the OT window by 30 minutes",
    "origin": "Núclea e-mail ref 2026-07-22/01",
    "effectiveAt": "2026-07-22T16:20:00-03:00",
    "windowSeq": 2
  }'
```


# What is Lerian SILOC?
Source: https://docs.lerian.studio/en/rails/siloc/what-is-lerian-siloc

Lerian SILOC is your participant connectivity to BACEN's SILOC deferred net settlement via Núclea: gateway link, card-domain relay to SLC, OT cycle tracking, outbound requests, and certificates.

**Lerian SILOC** is a financial institution's participant-side connectivity to **SILOC**. SILOC is the deferred multilateral net settlement system of the Central Bank of Brazil (BACEN). The clearinghouse **Núclea** operates it. SILOC nets many interbank credit-order transactions. Two products settle through SILOC: **boleto** (Cobrança) and **cards**.

Lerian SILOC gives an institution one direct path to SILOC. It owns the single messaging-gateway connection to Núclea over the national financial-system network. It relays the card-domain settlement traffic to **Lerian SLC**, Lerian's card-settlement service. It tracks the OT settlement cycles that Núclea runs, and it sends the institution's own requests to Núclea. It also keeps the participant directory, the regulated certificate references, and a settlement-coverage view.

## What Lerian SILOC does and does not do

***

Lerian SILOC carries messages and administers the participant's connection. It holds no position and executes no transfer. It sends the institution's transfer and withdrawal requests to Núclea, which executes them.

* SILOC and Núclea perform the netting and the final settlement of the net position, not Lerian SILOC.
* The separate STR rail, [Lerian SPB](/en/rails/spb/what-is-lerian-spb), executes the STR deposit leg, the monetary settlement at BACEN. SILOC does not.
* Lerian SILOC computes no net position. It carries messages and records settlement facts.

The service is single-institution: it connects one financial institution to SILOC.

## Who it serves

***

Lerian SILOC serves financial institutions that are **direct or indirect SILOC participants** under their own **ISPB**. The service opens and maintains their gateway connection to Núclea. It relays the card-domain settlement family to Lerian SLC. It keeps a directory of the participants it settles for. It holds the regulated certificate references the connection requires.

## Glossary

***

| Term | Meaning |
| - | - |
| **Lerian SILOC** | A financial institution's native, participant-side connectivity to SILOC: gateway connection, card-domain relay, and administration. |
| **SILOC** (Sistema de Liquidação Diferida das Transferências Interbancárias de Ordens de Crédito) | BACEN's deferred multilateral net settlement system, operated by Núclea. |
| **Núclea** | The clearinghouse that operates SILOC and settles its net position at the STR/BACEN. |
| **LDL** (Liquidação Diferida Líquida) | Deferred multilateral net settlement, SILOC's settlement model. |
| **Deferred net settlement** | Settling only the net position of many transactions at fixed daily cycle times, rather than each transaction individually. |
| **STR** (Sistema de Transferência de Reservas) | BACEN's Reserve Transfer System, where SILOC's net position is finally settled; the deposit leg is executed by the separate STR rail. |
| **Participant** | An institution in SILOC, classified as direct, indirect, or settling institution. |
| **ISPB** | BACEN's 8-character alphanumeric participant identifier. |
| **NUOp** (Número Único da Operação) | BACEN's globally unique per-operation identifier, used as the deduplication key. |
| **Boleto (Cobrança) and Cards** | The two products that settle through SILOC; card settlement is handled by the sibling Lerian SLC service. |

For how Lerian SILOC sits alongside the other native rails and the partner interfaces, see [Native messaging and partner interfaces](/en/rails/native-messaging).


# How Lerian SISBAJUD works
Source: https://docs.lerian.studio/en/rails/sisbajud/how-sisbajud-works

How a judicial order moves through Lerian SISBAJUD: file intake through Lerian STA, release to the executor, execution on Midaz, and BACEN response files.

BACEN delivers every judicial order as a **remittance file**. The **Mensageria** receives the file through Lerian STA, records the orders, and releases them one at a time. The **executor** runs each order on the **Midaz** ledger and reports the result. The Mensageria then writes the response file and submits it to BACEN through Lerian STA.

## Order flow

***

![Lerian SISBAJUD order flow](https://mintcdn.com/lerian-49cb71fc/pdfpHj06Qv6abx_7/images/en/d2/sisbajud-order-flow.svg?fit=max\&auto=format\&n=pdfpHj06Qv6abx_7\&q=85\&s=dc936fc0535e48c9c8fede0c99bc3dbe)

| # | From | To | Message | What happens |
| - | - | - | - | - |
| 1 | STA (BACEN) | Lerian STA | Remittance file | BACEN makes a remittance file (`5301`) or an information request (`5308`) available. Lerian STA downloads it. |
| 2 | Lerian STA | Mensageria | Event: file downloaded | Lerian STA publishes the event on `lerian.streaming.br-sta`. The Mensageria reads the file from the inbound bucket. |
| 3 | Mensageria | Mensageria | Note | The Mensageria parses the file, records the orders, and releases the next order of each subject. |
| 4 | Mensageria | Streaming Hub | Event: execution notice | The Mensageria publishes `judicial_order.execution_requested` on `lerian.streaming.br-sisbajud`. |
| 5 | Streaming Hub | Executor | Webhook: execution notice | The Streaming Hub delivers the notice by webhook. The executor can also read it from an Amazon SQS queue. |
| 6 | Executor | Mensageria | GET order | `GET /v1/sisbajud/execution/orders/{orderId}` returns the order. |
| 7 | Executor | Midaz | Block or unblock | The executor writes the order on the Midaz ledger. |
| 8 | Executor | Mensageria | POST execution result | `POST /v1/sisbajud/execution/orders/{orderId}/execution-results` records the outcome. |
| 9 | Mensageria | Lerian STA | POST transfer | The Mensageria puts the response file in the shared bucket and calls `POST /v1/transfers` on Lerian STA. |
| 10 | Lerian STA | STA (BACEN) | Response file | Lerian STA sends the response file (`5302` or `5309`) to BACEN. |
| 11 | Lerian STA | Mensageria | Event: transfer result | Lerian STA reports the outcome of the transfer on `lerian.streaming.br-sta`. |

## Order intake

***

Lerian STA events are the only way an order file enters the Mensageria. The Mensageria consumes the topic `lerian.streaming.br-sta` in the consumer group `br-sisbajud-sta-intake-v1`. It keeps the events whose source product matches its `STA_SOURCE_PRODUCT` setting and ignores the others.

Before the Mensageria downloads a file, it compares the file size with `STA_MAX_INBOUND_SIZE_BYTES`. After the download, it compares the SHA-256 digest of the file with the digest in the event. A mismatch rejects the file.

| Production code | Homologation code | File | What the Mensageria does |
| - | - | - | - |
| `5301` | `5311` | Remittance of judicial orders | Parses the orders. |
| `5308` | `5318` | Information request | Parses the orders. |
| `5303` | `5313` | BACEN syntax verdict on a block response file | Stores the file and applies the verdict to the response file. |
| `5310` | `5320` | BACEN syntax verdict on an information response file | Stores the file. |

The Mensageria reads the environment, production or homologation, from the file header.

The block remittance file is fixed-width text in ISO-8859-1. The 2026 layout has 684-character records. The CNJ v1.11 layout has 410-character records. `SISBAJUD_REMITTANCE_LAYOUTS` lists the layouts that the Mensageria accepts. The default is `v111,v2026`. The Mensageria rejects a file in a layout that is not on the list.

## Order record

***

The Mensageria turns each file into judicial orders. It records these order types:

* `BLOQUEIO` (block)
* `DESBLOQUEIO` (unblock)
* `REQUISICAO_INFORMACAO` (information request)
* `REITERACAO` (reiteration)

An order moves through the statuses `PENDING`, `PROCESSING`, `MONITORING`, `COMPLETED`, and `FAILED`.

The Mensageria encrypts sensitive fields with a data key for each operation. The institution's key-encryption key wraps that data key. The key manager is HashiCorp Vault Transit or AWS KMS.

### Permanent block

In the 2026 layout, each block record carries a permanent-block indicator. The value `P` or `D` marks a permanent block, and `D` also carries a deadline date. Any other value marks a block that is not permanent. In the CNJ v1.11 layout, these positions are a spacer, and the Mensageria ignores them.

## Release to the executor

***

The Mensageria releases the orders of a subject one at a time. A subject is the CPF or CNPJ that an order targets, inside one institution. The next order of a subject is released after the previous order is settled. A result from the executor can settle it.

The Mensageria writes the release and its execution notice in the same database transaction. The database, not the broker, keeps the order of releases for a subject.

## Execution on Midaz

***

For each execution notice, the executor:

1. Gets the order from the Mensageria.
2. Checks that the order's institution is registered on this executor as its own. For any other institution, it writes nothing.
3. Writes the block or unblock on Midaz. Each write carries an idempotency key built from the order ID and the order revision.
4. Reports the result to the Mensageria.

For an information request, the executor reads the subject's balances and writes nothing on the ledger. When the executor cannot finish an order alone, it hands the order to an operator as a human decision. [How the Lerian SISBAJUD executor runs orders](/en/rails/sisbajud/sisbajud-executor) describes each operation.

## Response files

***

The Mensageria generates two kinds of response file:

* A **block response** file: `5302` in production, `5312` in homologation.
* An **information response** file: `5309` in production, `5319` in homologation. It answers information requests.

A scan at a configured interval picks up finished orders that have no response yet. `RETURN_FILE_GENERATION_ENABLED` turns on the block responses, and `INFORMATION_RETURN_FILE_GENERATION_ENABLED` turns on the information responses. A response file takes the environment, production or homologation, of the remittance that its orders answer. `RETURN_FILE_ENVIRONMENT` applies only when no remittance backs the orders. The default is `HOMOLOGATION`. `SISBAJUD_RESPONSE_LAYOUT` set to `auto`, the default, answers in the layout of the original remittance. The values `v111` and `v2026` force one layout.

With `STA_TRANSFERS_ENABLED` on, the Mensageria submits each response file. It writes the file to the shared bucket, then calls `POST /v1/transfers` on Lerian STA.

| Status | Meaning |
| - | - |
| `GENERATING` | The Mensageria is writing the file. |
| `GENERATED` | The file is ready to submit. |
| `TRANSMITTING` | The Mensageria is submitting the file to Lerian STA. |
| `TRANSMITTED` | Lerian STA accepted the transfer. This does not prove that BACEN received the file. |
| `DELIVERED` | Lerian STA reported that BACEN received the file, with a protocol number. |
| `FAILED` | The file did not reach BACEN. |
| `REJECTED` | The file reached BACEN, and BACEN refused it on syntax in a `5303` or `5313` verdict. |

The file-exchange transport itself is the client-owned integration that [Lerian STA](/en/rails/sta/what-is-lerian-sta) describes. Lerian SISBAJUD is one of its downstream source products.


# Lerian SISBAJUD Mensageria environment variables
Source: https://docs.lerian.studio/en/rails/sisbajud/sisbajud-environment-variables

Environment variables of the Lerian SISBAJUD Mensageria: runtime, authentication, license, key management, execution API, event streaming, response files, object storage, and Lerian STA.

This page lists the environment variables of the **Mensageria**. [Lerian SISBAJUD executor environment variables](/en/rails/sisbajud/sisbajud-executor-environment-variables) lists the variables of the executor. [BYOC configuration essentials](/en/reference/byoc-configuration) documents the variables that every Lerian Go service shares: server, datastores, telemetry, and plugin authentication.

In the tables below, the **Default / Required** column shows the default value. A bold qualifier (for example **Required**) marks the variables you must set. `—` means no default. A variable marked **Sensitive** holds a credential or key material. Inject it from your secret manager at deploy time. Do not commit its value.

## Service and runtime

| Variable | Default / Required | Description |
| - | - | - |
| `SERVER_ADDRESS` | `:4031` | Listen address of the main API. `/health`, `/readyz`, and `/version` use this port. |
| `ENVIRONMENT_NAME` | — | Runtime environment. `ENV_NAME` is an alternative name. `local`, `development`, `staging`, `e2e`, and `test` are non-production values. Any other value, and no value, runs the production checks. |
| `DEPLOYMENT_MODE` | `local` | `local`, `byoc`, or `saas`. Any other value refuses the boot. With `saas`, the boot refuses a PostgreSQL, Redis, or Tenant Manager connection without TLS. |
| `DEFAULT_TENANT_ID` | `11111111-1111-1111-1111-111111111111` | Tenant of a single-tenant deployment. One tenant can hold many institutions. |
| `SYSTEMPLANE_ENABLED` | `false` | Serve the [Systemplane](/en/reference/platform/systemplane/overview) admin API under `/system` on the main port. |

> [!NOTE]
>
> The production checks require `POSTGRES_PASSWORD`, refuse `POSTGRES_SSLMODE=disable`, and require the license variables. With `STREAMING_ENABLED=true`, they also require `STREAMING_TLS_ENABLED=true`.

## Authentication

| Variable | Default / Required | Description |
| - | - | - |
| `PLUGIN_AUTH_ENABLED` | **Required** | `true` or `false`. A blank value or any other value refuses the boot. The Mensageria accepts `false` only when `ENV_NAME` is `development`, `develop`, `dev`, `local`, or `test`, and `DEPLOYMENT_MODE` is not `saas`. With `false`, protected operations still require a bearer token. |
| `PLUGIN_AUTH_HOST` | **Required if `PLUGIN_AUTH_ENABLED` or `STA_TRANSFERS_ENABLED` is `true`** | Address of the Access Manager. The Lerian STA submission gets its M2M token from this address. |
| `AUTH_JWT_VERIFY_CERT` | **Required, or `AUTH_JWT_VERIFY_CERT_PATH`** | PEM public keys or certificates that verify the signature of bearer tokens. This value takes precedence over `AUTH_JWT_VERIFY_CERT_PATH`. |
| `AUTH_JWT_VERIFY_CERT_PATH` | **Required, or `AUTH_JWT_VERIFY_CERT`** | Path of a file that holds the same PEM content. |
| `AUTH_JWT_ISSUER` | **Required** | The `iss` value that bearer tokens must carry. |

The boot accepts a missing verification key and a missing issuer only when all three conditions are true: `PLUGIN_AUTH_ENABLED` is `true`, `DEPLOYMENT_MODE` is `local` or unset, and `ENV_NAME` is `local`.

## License

[License Manager](/en/platform/licensing/license-manager) describes how the product checks the license.

| Variable | Default / Required | Description |
| - | - | - |
| `LICENSE_KEY` | **Required in production** | The license key that Lerian issued for Lerian SISBAJUD. |
| `ORGANIZATION_IDS` | **Required in production** | License scope. Set it to `global`. Any other value refuses the boot. |

"In production" means that `ENVIRONMENT_NAME` is not a non-production value.

## Key management

| Variable | Default / Required | Description |
| - | - | - |
| `KMS_PROVIDER` | **Required when `ENVIRONMENT_NAME` is `production`** | Key manager for envelope encryption: `vault` (HashiCorp Vault Transit) or `aws` (AWS KMS). Any other value refuses the boot. With any other environment, an unset value means `vault`. |
| `AWS_REGION` | **Required with `aws`** | Region of AWS KMS. |
| `SISBAJUD_DEK_CACHE_TTL` | `5m` | Time that an unwrapped data key stays in the memory cache. Go duration. |
| `KEK_REWRAP_BACKFILL_ENABLED` | `false` | Run the background job that re-wraps data keys under the new KEK version after a rotation. |
| `KEK_REWRAP_BACKFILL_SCAN_INTERVAL` | `300` | Interval of the re-wrap job, in seconds. |
| `KEK_REWRAP_BACKFILL_BATCH_SIZE` | `100` | Maximum number of data keys, per table, that one pass of the re-wrap job processes. |

### Vault (when `KMS_PROVIDER=vault`)

| Variable | Default / Required | Description |
| - | - | - |
| `VAULT_ADDR` | **Required** | Address of your Vault. |
| `VAULT_AUTH_METHOD` | `token` | `token` or `approle`. Any other value refuses the boot. |
| `VAULT_TOKEN` | **Required for `token` when `ENVIRONMENT_NAME` is `production`** | Vault token. Sensitive. |
| `VAULT_APPROLE_ROLE_ID` | **Required for `approle`** | AppRole role ID. Sensitive. |
| `VAULT_APPROLE_SECRET_ID` | **Required for `approle`** | AppRole secret ID. Sensitive. |
| `VAULT_TRANSIT_MOUNT_PATH` | `transit` | Mount path of the Transit engine. |
| `VAULT_TIMEOUT_SEC` | `15` | Timeout of each Vault request, in seconds. |
| `VAULT_TOKEN_RENEW_ENABLED` | `true` | Renew the Vault token in the background. |
| `VAULT_TOKEN_RENEW_MIN_INTERVAL_SEC` | `60` | Minimum time between two renewals, in seconds. |

## Execution API and sweeper

The executor reads orders and reports results through the execution API. [Integrating with Lerian SISBAJUD](/en/rails/sisbajud/sisbajud-integration#execution-api) describes it.

| Variable | Default / Required | Description |
| - | - | - |
| `SISBAJUD_EXECUTION_ADDRESS` | `:4032` | Listen address of the execution API. This listener accepts TLS only. |
| `SISBAJUD_EXECUTION_TLS_CERT_FILE` | **Required** | Path of the server certificate of the execution API. |
| `SISBAJUD_EXECUTION_TLS_KEY_FILE` | **Required** | Path of the private key of that certificate. Sensitive. |
| `SISBAJUD_EXECUTION_MTLS_ENABLED` | `false` | `true` makes the listener require a client certificate. Any value other than `true`, `false`, or blank refuses the boot. |
| `SISBAJUD_EXECUTION_CLIENT_CA_FILE` | **Required if `SISBAJUD_EXECUTION_MTLS_ENABLED=true`** | Path of the CA bundle that verifies client certificates. |
| `RESPONSE_DEADLINE_MARGIN` | **Required** | Go duration greater than 0, for example `2h`. For an order that waits behind an earlier revision with an uncertain result, the sweeper keeps this margin before the response deadline. |
| `EXECUTION_DRAINED_HEAD_ALARM_AFTER` | **Required** | Go duration greater than 0, for example `30m`. How long a parked order can block its subject before the sweeper raises an alarm. |
| `EXECUTION_SWEEP_INTERVAL_SEC` | `60` | Interval of the execution sweeper, in seconds. |
| `EXECUTION_DEADLINE_MARGIN_SEC` | `RETURN_FILE_GENERATION_SCAN_INTERVAL` | Time, in seconds, between the `deadlineAt` of an order and its response deadline. It must be greater than 0 and less than `21600`. |
| `EXECUTION_CANARY_INTERVAL_SEC` | `300` | Interval of the canary probe, in seconds. Each run sends one probe for each enabled institution. |

## Event streaming

| Variable | Default / Required | Description |
| - | - | - |
| `STREAMING_ENABLED` | **Required: `true`** | Publish events. The default is `false`, and `false` refuses the boot: the execution notices need a real publisher. |
| `STREAMING_BROKERS` | **Required** | Comma-separated list of Kafka brokers for the events that the Mensageria publishes. |
| `STREAMING_CLOUDEVENTS_SOURCE` | **Required** | Set it to `br-sisbajud`. Any other value refuses the boot. |
| `STREAMING_TLS_ENABLED` | `false` · **`true` in production** | Connect to the brokers over TLS. |
| `STREAMING_SASL_MECHANISM` | — | SASL mechanism of the brokers. With a mechanism and no TLS, the boot refuses unless `STREAMING_SASL_ALLOW_PLAINTEXT` is `true`. |
| `OUTBOX_ENABLED` | `true` | Durable delivery path of events. `STREAMING_ENABLED=true` requires it. |

## Response files and workers

| Variable | Default / Required | Description |
| - | - | - |
| `RETURN_FILE_GENERATION_ENABLED` | `false` | Generate block response files for the finished orders that have no response file. |
| `RETURN_FILE_GENERATION_SCAN_INTERVAL` | `3600` | Interval of block response-file generation, in seconds. |
| `RETURN_FILE_GENERATION_LIMIT` | `500` | Number of orders that one generation pass processes. |
| `INFORMATION_RETURN_FILE_GENERATION_ENABLED` | `false` | Generate information response files (AJUD309). |
| `INFORMATION_RETURN_FILE_GENERATION_SCAN_INTERVAL` | `3600` | Interval of information response-file generation, in seconds. |
| `INFORMATION_RETURN_FILE_GENERATION_LIMIT` | `500` | Number of orders that one information generation pass processes. |
| `RETURN_FILE_ENVIRONMENT` | `HOMOLOGATION` | `PRODUCTION` or `HOMOLOGATION`. A response file takes the environment of the remittance file behind its orders. This value applies only when no remittance file backs them. An invalid value turns off response-file generation. |
| `SISBAJUD_REMITTANCE_LAYOUTS` | `v111,v2026` | Comma-separated remittance layouts that the Mensageria accepts: `v111` and `v2026`. Reception rejects a file in any other layout. An invalid value refuses the boot. |
| `SISBAJUD_RESPONSE_LAYOUT` | `auto` | Layout of the block response. `auto` answers each remittance in the layout it arrived in. `v111` or `v2026` forces one layout. An invalid value refuses the boot. |
| `SLA_ALERT_ENABLED` | `false` | Classify the active orders by SLA-risk band and publish the bands as metrics. |
| `SLA_ALERT_SCAN_INTERVAL` | `60` | Interval of the SLA classification, in seconds. |
| `PROCESSING_LOCK_REAPER_ENABLED` | `true` | Delete expired processing locks in the background. |
| `PROCESSING_LOCK_REAPER_INTERVAL_SEC` | `300` | Interval of the lock cleanup, in seconds. |

## Object storage

| Variable | Default / Required | Description |
| - | - | - |
| `SEAWEEDFS_S3_ENDPOINT` | `http://localhost:8333` | Endpoint of the S3-compatible object store. |
| `SEAWEEDFS_BUCKET` | `sisbajud` | Bucket for the encrypted files of the Mensageria. |
| `SEAWEEDFS_REGION` | `us-east-1` | S3 region. |
| `SEAWEEDFS_CREDENTIALS_SOURCE` | `static` | `static` signs with the two keys below, or sends unsigned requests when both are blank. `default-chain` uses the AWS SDK credential chain, and then both keys must be blank. |
| `SEAWEEDFS_ACCESS_KEY` | — | Access key of the object store. Sensitive. |
| `SEAWEEDFS_SECRET_KEY` | — | Secret key of the object store. Sensitive. |
| `STA_INBOUND_BUCKET` | **Required** | Bucket that holds the remittance files that Lerian STA delivers. It uses the same endpoint as `SEAWEEDFS_S3_ENDPOINT`. |
| `STA_FILE_LOCK_TTL` | `5` | Lifetime of the processing lock of one file, in minutes. |

## Lerian STA consumer

The Mensageria receives remittance files only from the events that [Lerian STA](/en/rails/sta/what-is-lerian-sta) publishes. The consumer uses its own broker settings, `STA_STREAM_*`. It does not read the `STREAMING_*` variables.

| Variable | Default / Required | Description |
| - | - | - |
| `STA_CONSUMER_ENABLED` | `false` | Receive remittance files from Lerian STA events. |
| `STA_STREAM_BROKERS` | **Required if the consumer is on** | Comma-separated list of the Kafka brokers of Lerian STA. |
| `STA_STREAM_SASL_MECHANISM` | **Required if the consumer is on** | `PLAIN`, `SCRAM-SHA-256`, or `SCRAM-SHA-512`. |
| `STA_STREAM_SASL_USERNAME` | **Required if the consumer is on** | SASL user name. |
| `STA_STREAM_SASL_PASSWORD` | **Required if the consumer is on** | SASL password. Sensitive. |
| `STA_STREAM_TLS_ENABLED` | `false` | Connect to the brokers over TLS. With the consumer on, `false` requires `STA_STREAM_SASL_ALLOW_PLAINTEXT=true`. |
| `STA_STREAM_TLS_CA_CERT` | **Required if TLS is on** | Base64-encoded PEM CA certificate of the brokers. |
| `STA_STREAM_SASL_ALLOW_PLAINTEXT` | `false` | Accept SASL without TLS. Production refuses `true`. |
| `STA_CONSUMER_RETRY_BUDGET` | `3` | Number of retries of a transient failure inside one delivery. |
| `STA_SOURCE_PRODUCT` | **Required if the consumer or the submission is on** | Product name that Lerian STA records for this rail. The Mensageria keeps only the events with this name. The example configuration uses `br-sisbajud`. |
| `STA_BACEN_SYSTEM_CODE` | **Required if the consumer is on** | The example configuration uses `JUD`. |
| `STA_EXPECTED_TENANT_ST` | **Required if the consumer is on** | Tenant that Lerian STA writes on its events. Set the `DEFAULT_TENANT_ID` of your Lerian STA. A single-tenant Mensageria refuses an empty value. |
| `STA_MAX_INBOUND_SIZE_BYTES` | **Required if the consumer is on** | Largest remittance file, in bytes, that the consumer downloads. It must be greater than 0. The example configuration uses `52428800`. |
| `STA_OBJECT_STORAGE_ENDPOINT` | **Required if the consumer or the submission is on** | Object-store endpoint of Lerian STA. It must name the same store as `SEAWEEDFS_S3_ENDPOINT`. A different store refuses the boot. |

## Lerian STA submission

| Variable | Default / Required | Description |
| - | - | - |
| `STA_TRANSFERS_ENABLED` | `false` | Submit the response files to Lerian STA. It requires `PLUGIN_AUTH_HOST`. |
| `STA_TRANSFERS_BASE_URL` | **Required if the submission is on** | Base URL of the Lerian STA API. |
| `STA_DOCUMENT_TYPE_AJUD302` | **Required if the submission is on** | Lerian STA document type of the block response. The example configuration uses `AJUD302`. |
| `STA_DOCUMENT_TYPE_AJUD309` | **Required if the submission is on** | Lerian STA document type of the information response. The example configuration uses `AJUD309`. |
| `TRANSFER_OBJECT_STORAGE_BUCKET` | **Required if the submission is on** | Bucket shared with Lerian STA for the response files. It must name the same bucket as `STA_INBOUND_BUCKET`. A different bucket refuses the boot. |
| `STA_CLIENT_ID` | **Required if the submission is on** | OAuth client ID that gets the token for Lerian STA. |
| `STA_CLIENT_SECRET` | **Required if the submission is on** | OAuth client secret for Lerian STA. Sensitive. |

## Values that must match the executor

* **`RESPONSE_DEADLINE_MARGIN`.** The executor reads the same variable. Set the same value on both components.
* **Mutual TLS.** The executor has its own switch, `MENSAGERIA_MTLS_ENABLED`. Set it to the same value as `SISBAJUD_EXECUTION_MTLS_ENABLED`. With mutual TLS on the Mensageria and off on the executor, the TLS handshake fails.
* **Executor identity.** The M2M client of the executor holds the role `br-sisbajud-executor-role`. [Integrating with Lerian SISBAJUD](/en/rails/sisbajud/sisbajud-integration#execution-api) describes its permissions.


# How the Lerian SISBAJUD executor runs orders
Source: https://docs.lerian.studio/en/rails/sisbajud/sisbajud-executor

How the Lerian SISBAJUD executor receives execution notices, runs blocks, unblocks, and information requests on Midaz, and reports each result to the Mensageria.

The **executor** runs the judicial orders of the Mensageria on the client's Midaz ledger. This page describes how the executor receives an order, what each operation writes, and how the executor reports the result. [Operating the Lerian SISBAJUD executor](/en/rails/sisbajud/sisbajud-executor-operations) describes the setup.

## Order lifecycle

***

1. **Notice.** The Streaming Hub posts an execution notice to the webhook listener of the executor. The notice carries the order ID and the order revision, not the order.
2. **Verification.** The executor verifies the HMAC signature of the delivery. It stores each signed notice before it answers.
3. **Fetch.** The executor gets the order with `GET /v1/sisbajud/execution/orders/{orderId}` on the execution API of the Mensageria.
4. **Owner check.** Before its first write, the executor checks that it owns the institution of the order.
5. **Execution.** On its next cycle, the executor runs the operation on Midaz.
6. **Result.** The executor posts the result with `POST /v1/sisbajud/execution/orders/{orderId}/execution-results`.

### Webhook answers

| Delivery | Answer |
| - | - |
| The body is larger than 1 MiB. | `413`. The executor stores nothing. |
| The HMAC signature is missing or invalid. | `401`. The executor does not store the delivery. |
| The signature verifies, but the body is not a usable notice. | `200`. The executor parks the delivery and raises an alarm. |
| The Mensageria or a database fails. | `503`. The Streaming Hub retries the delivery. |
| The executor accepts the notice. | `200`. The executor runs the order on its next cycle. |

The executor accepts a delivery with a timestamp outside `EXECUTOR_HUB_WEBHOOK_MAX_SKEW_SEC`, and logs a warning.

### Fetch answers

| Answer of the Mensageria | What the executor does |
| - | - |
| `200` | Runs the order. |
| `404` or `410` | Treats the order as withdrawn. It writes nothing on the ledger. |
| `401`, `429`, a `5xx` status, or a network error | Retries the request. |
| Any other `4xx` status | Parks the delivery and raises an alarm. |

### Owner check

The executor writes on the ledger only for the institutions that it owns. When it creates an institution, it records its own M2M subject (`EXECUTOR_M2M_SUBJECT`) as the owner.

* If another identity owns the institution, the executor writes nothing and raises an alarm.
* If the institution has no configuration on this executor, the order goes to a human decision.

### Execution cycle

The executor runs one cycle every `EXECUTOR_TICK_EVERY`. The default is `30s`. Each cycle runs four steps in this order:

1. **Ingest.** Runs the accepted notices.
2. **Orphan check.** Looks for operations on the block accounts that the executor did not write.
3. **Monitor.** Sends a heartbeat for each write that has no known outcome.
4. **Drain.** Posts the results that wait in the outbox.

A failed step does not stop the other steps.

### Results

The executor stores each result in an outbox before it posts it. Each post carries the `X-Idempotency` header. When a post fails with a transient error, the executor posts the same result again on a later cycle.

| Field | Values |
| - | - |
| `executionState` | `ACCEPTED`, `EXECUTING`, `MONITORING`, `RESOLVED`, `INDETERMINATE`, `AWAITING_RECONCILIATION` |
| `effect` | `NONE`, `FULL`, `PARTIAL`, `INDETERMINATE` |

The `reasonCode` of each operation is in the sections below.

## Operations

***

The block and the unblock write on Midaz. The information request only reads.

### Block (BLOQUEIO)

1. The executor reads the active accounts of the subject. A subject with no active account gets `NONE` with `NO_CLIENT`.
2. It applies the branch and account restriction of the order.
3. It blocks a salary account only when the order allows salary accounts.
4. It blocks own funds only. An account in overdraft counts as 0.
5. It sends one write to Midaz. The write has one leg for each source account, and all legs go into the block account of the order.

| Outcome | `effect` | `reasonCode` |
| - | - | - |
| The block covers the amount still open on the order. | `FULL` | `BLOCKED_TOTAL` |
| The block covers less than that amount. | `PARTIAL` | `BLOCKED_PARTIAL` |
| No funds are available. | `NONE` | `NO_BALANCE` |

### Unblock (DESBLOQUEIO)

The unblock releases funds of a parent block order, identified by `parentOrderId`. The executor uses the parent block's recorded origin account as the release destination. If it cannot safely determine one destination, it requires a human decision rather than guessing.

* Without a parent, the result is `NONE` with `PARENT_UNRESOLVED`, and the executor writes nothing.
* When the parent has no known effect yet, the executor waits.
* The executor reads the block account of the parent when it runs the order. It releases the smallest of three amounts: the amount that the order asks, the remaining balance of the parent, and the balance of the block account.
* When the release amount is 0, the result is `NOTHING_TO_RELEASE`.
* When a subject account is a salary account, the order goes to a human decision.

### Information request (REQUISICAO\_INFORMACAO)

The executor reads the balances of the subject and writes nothing on the ledger. If the subject is a client but does not own the specified account, the executor requires a human decision rather than reporting that the subject is not a client.

* A subject with at least one active account gets `FULL` with `INFO_FULFILLED`.
* A subject with no active account gets `NONE` with `INFO_NON_CLIENT`.
* An order that names a branch goes to a human decision.

## Ledger semantics

***

### Block account

Each block order has its own block account in Midaz. The alias of the block account has the prefix `@block_sisbajud_` and then the 32 lowercase hexadecimal digits of the block order ID. An unblock finds the account through its `parentOrderId`.

The account type of a block account is `sisbajud_block`. If your ledger validates account types, register `sisbajud_block` as an account type.

### Directions

* A block decreases the subject accounts and increases the block account.
* An unblock decreases the block account. Its write has one source leg: the block account. It releases funds to the recorded origin account, or requires a human decision when one safe destination cannot be determined.

A block moves the amount from the available balance of each subject account to the available balance of the block account.

### Idempotency

Each write carries the `X-Idempotency` header and `X-TTL: 604800`, which is seven days. Midaz keeps the idempotency key of a write for that time. A redelivery of the same order revision sends the same key.

## Uncertain writes

***

When Midaz answers a write without proof of its effect, the outcome is `INDETERMINATE`. The executor reads the ledger again before each heartbeat. It sends a heartbeat result to the Mensageria every `EXECUTOR_HEARTBEAT_EVERY`.

The order goes to a human decision at the first of two limits:

* `EXECUTOR_HUMAN_DECISION_AFTER_BEATS` heartbeats without a change. The default is 3.
* The order deadline minus `RESPONSE_DEADLINE_MARGIN`.

The executor then records a human decision. In the human-decisions list it has `humanDisposition` `HELD_MONEY_MOVED`. The heartbeats continue, with `executionState` and `effect` both `INDETERMINATE`.

### Operations that the executor did not write

The orphan check reads the operations of each block account over `EXECUTOR_ORPHAN_RECONCILE_WINDOW`. The default is `48h`. The executor reports an operation as an orphan when its transaction has no `metadata.code`, or has a code that the executor did not record. This step only detects. It changes nothing on the ledger.

## Accounting routes

***

Accounting routes are optional, per organization. The executor reads them from the tenant documents `routing.organizations` and `routing.ledger_bindings` in the Systemplane. With `SYSTEMPLANE_ENABLED` off, the executor writes without routes.

When a write cannot go out because of its configuration, the executor defers it. Midaz has applied nothing, so the order waits, and a later delivery sends the same write with the same idempotency key. These conditions defer a write:

* The executor cannot resolve the accounting routes of the write.
* Midaz refuses the accounting routes of the write: `422` with code `0113`, `0114`, `0116`, `0117`, `0118`, `0119`, `0152`, or `0157`, or `404` with code `0105`.

Fix the configuration before the order deadline. `GET /v1/admin/ledger-routing/preflight` checks the configuration before you turn on routes.

## Midaz calls

***

The executor calls the Midaz ledger at the `baseUrl` of each institution, with the token of that institution. Give the credentials of the institution access to these operations:

| Purpose | Midaz operation |
| - | - |
| Block | `POST /v1/organizations/{organizationId}/ledgers/{ledgerId}/transactions/block` |
| Unblock | `POST /v1/organizations/{organizationId}/ledgers/{ledgerId}/transactions/unblock` |
| Create a block account | `POST /v1/organizations/{organizationId}/ledgers/{ledgerId}/accounts` |
| Find an account by alias | `GET /v1/organizations/{organizationId}/ledgers/{ledgerId}/accounts?alias=` |
| Read an account | `GET /v1/organizations/{organizationId}/ledgers/{ledgerId}/accounts/{accountId}` |
| Read the balances of an alias | `GET /v1/organizations/{organizationId}/ledgers/{ledgerId}/accounts/alias/{alias}/balances` |
| Read the operations of a block account | `GET /v1/organizations/{organizationId}/ledgers/{ledgerId}/accounts/{accountId}/operations` |
| Read a transaction | `GET /v1/organizations/{organizationId}/ledgers/{ledgerId}/transactions/{transactionId}` |
| Find the transactions of a write | `GET /v1/organizations/{organizationId}/ledgers/{ledgerId}/transactions?metadata.code=` |

The executor finds the accounts of a subject through the Midaz CRM. With `crmMode` `legacy`, it calls `GET /v1/aliases?document=` at `crmBaseUrl`. With `crmMode` `embedded`, it calls `GET /v2/organizations/{organizationId}/instruments?document=` at `baseUrl`.


# Lerian SISBAJUD executor environment variables
Source: https://docs.lerian.studio/en/rails/sisbajud/sisbajud-executor-environment-variables

Environment variables of the Lerian SISBAJUD executor: runtime, authentication, license, key management, the Mensageria connection, execution timing, the webhook listener, Midaz, and event streaming.

This page lists the environment variables of the **executor**. [Lerian SISBAJUD Mensageria environment variables](/en/rails/sisbajud/sisbajud-environment-variables) lists the variables of the Mensageria. [BYOC configuration essentials](/en/reference/byoc-configuration) documents the variables that every Lerian Go service shares: server, datastores, telemetry, and plugin authentication.

In the tables below, the **Default / Required** column shows the default value. A bold qualifier (for example **Required**) marks the variables you must set. `—` means no default. A variable marked **Sensitive** holds a credential or key material. Inject it from your secret manager at deploy time. Do not commit its value.

`MENSAGERIA_BASE_URL` turns on the executor. The executor requirements below apply when it is set.

## Service and runtime

| Variable | Default / Required | Description |
| - | - | - |
| `SERVER_ADDRESS` | **Set it to `:4029`** | Listen address of the main API. The image exposes port 4029. `/health`, `/readyz`, and `/version` use this port. |
| `ENVIRONMENT_NAME` | — | Runtime environment. `local`, `development`, `staging`, `e2e`, and `test` are non-production values. Any other value, and no value, runs the production checks. |
| `DEPLOYMENT_MODE` | `local` | `local`, `byoc`, or `saas`. With `saas`, the boot refuses a PostgreSQL or Redis connection without TLS. Outside `local`, the webhook listener needs TLS. |
| `DEFAULT_TENANT_ID` | `11111111-1111-1111-1111-111111111111` | Tenant of a single-tenant deployment. It must be a UUID. |
| `SYSTEMPLANE_ENABLED` | `false` | Serve the [Systemplane](/en/reference/platform/systemplane/overview) admin API under `/system`, and the accounting-route documents under `/tenant-system`. |

> [!NOTE]
>
> The production checks require `POSTGRES_PASSWORD` and refuse `POSTGRES_SSLMODE=disable`. With `STREAMING_ENABLED=true`, they also require `STREAMING_TLS_ENABLED=true`.

## Authentication

| Variable | Default / Required | Description |
| - | - | - |
| `PLUGIN_AUTH_ENABLED` | `false` | Check bearer tokens on the main API with the Access Manager. With `false`, the executor does not serve the credential key rotation. |
| `PLUGIN_AUTH_HOST` | **Required** | Address of the Access Manager. The executor gets its token for the Mensageria from this address, also when `PLUGIN_AUTH_ENABLED` is `false`. |

## License

[License Manager](/en/platform/licensing/license-manager) describes how the product checks the license.

| Variable | Default / Required | Description |
| - | - | - |
| `LICENSE_KEY` | **Required** | The license key that Lerian issued for Lerian SISBAJUD. The boot refuses an empty value in every environment. |
| `ORGANIZATION_IDS` | **Required** | License scope. Set it to `global`. Any other value refuses the boot. |

## Key management

| Variable | Default / Required | Description |
| - | - | - |
| `KMS_PROVIDER` | **Required when `ENVIRONMENT_NAME` is `production`** | Key manager: `vault` (HashiCorp Vault Transit) or `aws` (AWS KMS). Any other value refuses the boot. With any other environment, an unset value means `vault`. |
| `AWS_REGION` | **Required with `aws`** | Region of AWS KMS. |
| `VAULT_ADDR` | **Required with `vault`** | Address of your Vault. |
| `VAULT_AUTH_METHOD` | `token` | `token` or `approle`. Any other value refuses the boot. |
| `VAULT_TOKEN` | **Required for `token` when `ENVIRONMENT_NAME` is `production`** | Vault token. Sensitive. |
| `VAULT_APPROLE_ROLE_ID` | **Required for `approle`** | AppRole role ID. Sensitive. |
| `VAULT_APPROLE_SECRET_ID` | **Required for `approle`** | AppRole secret ID. Sensitive. |
| `VAULT_TRANSIT_MOUNT_PATH` | `transit` | Mount path of the Transit engine. |
| `VAULT_TIMEOUT_SEC` | `15` | Timeout of each Vault request, in seconds. |
| `VAULT_TOKEN_RENEW_ENABLED` | `true` | Renew the Vault token in the background. |
| `VAULT_TOKEN_RENEW_MIN_INTERVAL_SEC` | `60` | Minimum time between two renewals, in seconds. |

## Mensageria connection

The executor calls the execution API of the Mensageria. [Integrating with Lerian SISBAJUD](/en/rails/sisbajud/sisbajud-integration#execution-api) describes it.

| Variable | Default / Required | Description |
| - | - | - |
| `MENSAGERIA_BASE_URL` | **Required** | Base URL of the execution API of the Mensageria (`SISBAJUD_EXECUTION_ADDRESS` on the Mensageria). It must be an `https` URL with a host. |
| `MENSAGERIA_MTLS_ENABLED` | `false` | `true` presents a client certificate. `false` uses one-way TLS. Any other value refuses the boot. |
| `MENSAGERIA_TLS_CA_FILE` | **Required if `MENSAGERIA_MTLS_ENABLED=true`** | CA bundle that verifies the Mensageria. With one-way TLS, it is optional, and an empty value uses the system trust store. |
| `MENSAGERIA_TLS_CLIENT_CERT_FILE` | **Required if `MENSAGERIA_MTLS_ENABLED=true`** | Client certificate of the executor. |
| `MENSAGERIA_TLS_CLIENT_KEY_FILE` | **Required if `MENSAGERIA_MTLS_ENABLED=true`** | Private key of that certificate. Sensitive. |
| `EXECUTOR_M2M_SUBJECT` | **Required** | The `sub` of the M2M token of the executor. The executor records it as the owner of each institution that it creates. |
| `MENSAGERIA_CLIENT_ID` | **Required** | Client ID of the M2M client of the executor. |
| `MENSAGERIA_CLIENT_SECRET` | **Required** | Client secret of that client. Sensitive. The boot refuses a pair with only one of the two values. |
| `STREAMING_HUB_TENANT_ID` | **Required** | Tenant of the canary probes. The executor answers a probe only when the tenant of the delivery is this value. |

## Execution timing

| Variable | Default / Required | Description |
| - | - | - |
| `EXECUTOR_TICK_EVERY` | `30s` | Interval of the execution cycle. Go duration greater than 0. |
| `EXECUTOR_HEARTBEAT_EVERY` | **Required** | Interval of the heartbeats for a write whose outcome is not known. Go duration greater than 0. |
| `EXECUTOR_HUMAN_DECISION_AFTER_BEATS` | `3` | Number of heartbeats without a change before the order goes to a human decision. |
| `RESPONSE_DEADLINE_MARGIN` | **Required** | Go duration greater than 0, for example `2h`. Before the order deadline, the executor keeps this margin and hands an unresolved write to a human decision. |
| `EXECUTOR_SETTLE_WINDOW` | `1s` | Go duration. Set it to at least the asynchronous latency of your ledger. |
| `EXECUTOR_ORPHAN_RECONCILE_WINDOW` | `48h` | How far back the executor looks for operations on block accounts that it did not write. |

## Webhook listener

| Variable | Default / Required | Description |
| - | - | - |
| `EXECUTOR_TRANSPORT` | `webhook` | How the execution notices reach the executor. This page describes `webhook`. |
| `EXECUTOR_HUB_WEBHOOK_ADDRESS` | `:9082` | Listen address of the webhook listener. |
| `EXECUTOR_HUB_WEBHOOK_PATH` | `/v1/webhooks/hub` | Route of the webhook listener. It must start with `/`. |
| `EXECUTOR_HUB_WEBHOOK_SECRET` | **Required** | Signing secret of the Streaming Hub subscription. Sensitive. |
| `EXECUTOR_HUB_WEBHOOK_SECRET_PREVIOUS` | — | The secret before the last rotation. The listener accepts both secrets. Sensitive. |
| `EXECUTOR_HUB_WEBHOOK_MAX_SKEW_SEC` | `300` | From `1` to `300`. The listener accepts a delivery outside this clock skew, with a warning in the log. |
| `EXECUTOR_HUB_WEBHOOK_TLS_CERT_FILE` | **Required outside `DEPLOYMENT_MODE=local`, unless TLS is terminated upstream** | Server certificate of the listener. Set it together with the key. |
| `EXECUTOR_HUB_WEBHOOK_TLS_KEY_FILE` | **Required with the certificate** | Private key of that certificate. Sensitive. |
| `EXECUTOR_HUB_WEBHOOK_UPSTREAM_TLS_VALIDATED` | `false` | Set it to `true` when TLS is terminated in front of the listener. |
| `EXECUTOR_HUB_WEBHOOK_MAX_HANDLE_ATTEMPTS` | `5` | Number of attempts for each accepted delivery. It must be at least 1 + `EXECUTOR_SETTLE_WINDOW` / `EXECUTOR_TICK_EVERY`, rounded up. |

## Midaz

| Variable | Default / Required | Description |
| - | - | - |
| `MIDAZ_CRM_MODE` | `legacy` | CRM surface of the institutions that set no `crmMode`: `legacy` (the standalone Midaz CRM at `crmBaseUrl`) or `embedded` (the CRM of the Midaz ledger at `baseUrl`). |

The executor reads the Midaz connection of each institution from its configuration, not from environment variables. [Operating the Lerian SISBAJUD executor](/en/rails/sisbajud/sisbajud-executor-operations#institution-setup) describes it.

## Event streaming

| Variable | Default / Required | Description |
| - | - | - |
| `STREAMING_ENABLED` | `true` | Publish events. With HashiCorp Vault, a credential key rotation publishes `kek.rotated`. The boot refuses `false` when `STREAMING_BROKERS` is set. |
| `STREAMING_BROKERS` | — | Comma-separated list of Kafka brokers. |
| `STREAMING_TLS_ENABLED` | **`true` in production** | Connect to the brokers over TLS. |
| `OUTBOX_ENABLED` | `true` | Durable delivery path of events. `STREAMING_ENABLED=true` requires it. |

## Values that must match the Mensageria

* **`RESPONSE_DEADLINE_MARGIN`.** The Mensageria reads the same variable. Set the same value on both components.
* **Mutual TLS.** Set `MENSAGERIA_MTLS_ENABLED` to the same value as `SISBAJUD_EXECUTION_MTLS_ENABLED` on the Mensageria. With mutual TLS on the Mensageria and off on the executor, the TLS handshake fails.
* **Executor identity.** On the Mensageria, the M2M client in `MENSAGERIA_CLIENT_ID` holds the role `br-sisbajud-executor-role`. `EXECUTOR_M2M_SUBJECT` is the `sub` of the token of that client.


# Operating the Lerian SISBAJUD executor
Source: https://docs.lerian.studio/en/rails/sisbajud/sisbajud-executor-operations

Set up and run the Lerian SISBAJUD executor: institutions and their Midaz connector, ledger routing, orders that need attention, credential key rotation, roles, listeners, and deploy constraints.

This page describes how to set up and run the **executor**. [Operating Lerian SISBAJUD](/en/rails/sisbajud/sisbajud-operations) describes the Mensageria. [How the Lerian SISBAJUD executor runs orders](/en/rails/sisbajud/sisbajud-executor) describes what the executor does with each order.

## Institution setup

***

Register each institution on the Mensageria and on the executor, with the same `institutionId`. [Operating Lerian SISBAJUD](/en/rails/sisbajud/sisbajud-operations#institutions) describes the Mensageria request.

`POST /v1/institutions` registers an institution on the executor. The body has these fields:

| Field | Meaning |
| - | - |
| `institutionId` | The UUID of the institution. Use the same value as on the Mensageria. |
| `connectorType` | The ledger connector. Set it to `midaz`. |
| `institutionCode` | The CNPJ root of the institution, 8 digits. |
| `enabled` | Whether the institution is active. Send `true`. |
| `connectorMetadata` | The Midaz configuration of the institution. The tables below describe it. |
| `retryPolicyConfig` | Optional. The retry policy, as JSON. |
| `branchFormat` | Optional. A Go RE2 regular expression, at most 64 characters, for the branch number that a court can name in a block restriction. |
| `accountFormat` | Optional. A Go RE2 regular expression, at most 64 characters, for the account number that a court can name in a block restriction. |

The request also creates the tokenization keyset and the audit keyset of the institution. A second request with the same `institutionId` returns `409`.

The executor records itself as the owner of the institution, from its own M2M identity (`EXECUTOR_M2M_SUBJECT`). No request field sets the owner, and a `PATCH` does not change it.

### Connector metadata

| Key | Required | Meaning |
| - | - | - |
| `organizations` | Yes | A list of `{organizationId, ledgers}` entries: the Midaz organizations that the executor searches for the accounts of a subject. Without `ledgers`, the executor searches every ledger of the organization. |
| `baseUrl` | Yes | The base URL of the Midaz ledger of the institution. |
| `authAddress` | When credentials are stored | The Access Manager address that issues the Midaz token of the institution. |
| `blockableBalances` | Yes | The Midaz balance keys that a block can use, for example `default`. These are balance keys, not the `available` or `onHold` amounts. |
| `blockableAccountTypes` | Yes | The account types that a block can use. |
| `salaryAccountTypes` | Yes | The account types that are salary accounts. Send `["NONE"]` when the institution has no salary account type. |
| `crmMode` | No | `legacy` or `embedded`. Without a value, the institution uses `MIDAZ_CRM_MODE`. |
| `crmBaseUrl` | No | The base URL of the standalone Midaz CRM, for `legacy`. With `embedded`, leave it empty: the executor reads the CRM through `baseUrl`. |
| `executorLedger` | To run orders | The ledger where the executor writes. The next table describes it. |

### Executor ledger

| Key | Meaning |
| - | - |
| `organizationId` | The Midaz organization of the writes. |
| `ledgerId` | The Midaz ledger of the writes. |
| `asset` | Set it to `BRL`, exactly. |
| `judicialDepositAccountAlias` | The alias of the judicial deposit account. It must follow the Midaz alias rule. |

The executor refuses an institution request whose `executorLedger` is present and not valid, with `400`. At startup, the executor leaves out of its ledger routing an institution that has no valid `executorLedger`.

### Connector credentials

`PUT /v1/institutions/{institutionId}/connector-credentials` writes the Midaz credentials of the institution:

* `ledger_client_id` and `ledger_client_secret` are always required.
* `crm_client_id` and `crm_client_secret` are required with `crmMode` `legacy`. With `embedded`, do not send them.

The executor encrypts the credentials before it stores them. `PATCH /v1/institutions/{institutionId}` refuses a body with credentials. A new credential does not revoke the previous one at the Access Manager, so revoke it there.

The executor gets the Midaz token of the institution from `{authAddress}/v1/login/oauth/access_token`. When the institution has no stored credentials, the executor sends no `Authorization` header to Midaz.

### Change the configuration

* `PATCH /v1/institutions/{institutionId}` changes the fields of the institution. A `connectorMetadata` in the body replaces the whole bag, except the stored credentials.
* `PUT /v1/institutions/{institutionId}/connector-config` replaces `connectorType` and `connectorMetadata`. It keeps the stored credentials, and it refuses a body with credentials.
* `GET /v1/institutions/{institutionId}` returns the configuration without the credentials.

The executor reads the configuration of its institutions at startup. After you create an institution or change its configuration, restart the executor.

## Ledger routing

***

With `SYSTEMPLANE_ENABLED` on, the executor serves the tenant documents of its accounting routes under `/tenant-system`. The executor reads two of them: `routing.organizations` turns on accounting routes for each organization, and `routing.ledger_bindings` holds the routes. With `SYSTEMPLANE_ENABLED` off, the executor writes without routes.

`GET /v1/admin/ledger-routing/preflight` checks the routing configuration against the ledger of the institution. It writes nothing. A single-tenant executor needs the `institutionId` query parameter. The report covers these checks:

* The transaction routes and the operation routes exist, and they match the writes of the executor.
* A ledger that validates account types has `sisbajud_block` registered.
* The judicial deposit account in `executorLedger` exists in the ledger and is not blocked.

The `ready` field reports whether the configuration is ready. The report shows the stored `executorLedger`. The running executor uses the configuration that it read at startup.

## Orders that need attention

***

| Operation | What it returns |
| - | - |
| `GET /v1/institutions/{institutionId}/executor/failed-orders` | The order revisions that the executor failed or abandoned. Each item has the order ID, the revision, a reason token, and the ID of its journal entry. It does not list the revisions whose outcome is not known yet. |
| `GET /v1/institutions/{institutionId}/executor/human-decisions` | The order revisions that the executor stopped on a human decision. |

Each human decision has a `humanDisposition`:

* `GAVE_UP`: the executor attempted no ledger write and answered `EXECUTOR_GAVE_UP`.
* `HELD_MONEY_MOVED`: the executor attempted a write. Money can have moved, and the executor posted no answer.

The Mensageria also lists the orders that the executor gave up on. [Operating Lerian SISBAJUD](/en/rails/sisbajud/sisbajud-operations#orders-that-need-attention) describes that list.

## Credential key rotation

***

`POST /v1/institutions/{institutionId}/security/credential-kek:rotate` rotates the key that wraps the stored Midaz credentials of the institution. This key is not the institution-data key that the Mensageria rotates.

* The rotation moves the stored credentials to the new key version. The credential values do not change. To replace a credential, use `PUT /v1/institutions/{institutionId}/connector-credentials`.
* The response shows the previous and the new key version.
* An institution with no stored credentials returns `404`.
* While another rotation of the same institution runs, a rotation returns `409`.
* With HashiCorp Vault as the key provider and `STREAMING_ENABLED` on, the rotation publishes a `kek.rotated` event with `keyPurpose` `CREDENTIALS`.

With `PLUGIN_AUTH_ENABLED` off, the executor does not serve this operation.

## Audit verification

***

`GET /v1/admin/audit/verify` checks a range of the audit log of the institution, from `fromIndex` to `toIndex`. It does not decrypt any payload. It reports tampering and deleted entries.

## Roles

***

Each operation needs one permission:

| Operation | Permission |
| - | - |
| Create or update an institution, its connector configuration, or its credentials | `institution_config:write` |
| Read an institution, the failed orders, the human decisions, or the audit verification | `admin:read` |
| Credential key rotation | `credential_kek:rotate` |
| Ledger-routing preflight, and reads under `/tenant-system` | `tenant_policy:read` |
| Writes under `/tenant-system` | `tenant_policy:write` |

The `admin` role holds every permission in this table. The `operator`, `investigator`, and `compliance-officer` roles hold `admin:read`. The `systemplane` permissions of `/system` go to the M2M role `editor`, and to no business role.

### The executor on the Mensageria

The executor calls the execution API of the Mensageria with its own M2M client. Set the client in `MENSAGERIA_CLIENT_ID` and `MENSAGERIA_CLIENT_SECRET`. The executor gets its token from the Access Manager at `PLUGIN_AUTH_HOST`. On the Mensageria, the client holds the role `br-sisbajud-executor-role`. [Integrating with Lerian SISBAJUD](/en/rails/sisbajud/sisbajud-integration#execution-api) describes its permissions.

## Listeners

***

The executor has two listeners:

* **Main API**, at `SERVER_ADDRESS`. Set it to `:4029`, the port that the image exposes. It serves the operations of the API reference. It also serves `/health`, `/readyz`, and `/version`. With `SYSTEMPLANE_ENABLED` on, it serves `/system` and `/tenant-system`. With `SWAGGER_ENABLED` on, it serves `/swagger`.
* **Webhook listener**, at `EXECUTOR_HUB_WEBHOOK_ADDRESS`. The default is `:9082`. It has one route, `POST` at `EXECUTOR_HUB_WEBHOOK_PATH`, whose default is `/v1/webhooks/hub`. Expose this port to the Streaming Hub, and use your ingress address plus this path as the subscription URL.

The webhook listener has no application authentication. It accepts a delivery only when the HMAC signature verifies with the subscription secret or with the previous secret. Outside `DEPLOYMENT_MODE=local`, the listener needs its own TLS certificate. As an alternative, terminate TLS in front of it and set `EXECUTOR_HUB_WEBHOOK_UPSTREAM_TLS_VALIDATED=true`.

`/readyz` includes two executor checks:

* `hub_webhook`: the webhook listener.
* `executor_institutions`: the number of institutions that the executor owns, and how many of them have ledger routing. This check does not fail readiness.

## Deploy constraints

***

* **One tenant for each process.** The executor does not start when its tenant list holds more than one tenant.
* **Its own database.** The executor runs on its own empty PostgreSQL database. Its migrations refuse a database that already holds another migration history.
* **Restart after configuration changes.** The executor reads its institutions at startup.
* **Termination grace period.** Set the `terminationGracePeriodSeconds` of the pod to at least 90.


# Integrating with Lerian SISBAJUD
Source: https://docs.lerian.studio/en/rails/sisbajud/sisbajud-integration

How the Lerian SISBAJUD Mensageria connects to Lerian STA, the Streaming Hub, and the executor: file events, execution notices, the execution API, and the events it publishes.

The **Mensageria** connects to three systems. **Lerian STA** carries the files to and from BACEN. The **Streaming Hub** delivers the execution notices to the **executor**. The executor calls the Mensageria's **execution API** to get each order and report its result. The Mensageria calls no ledger.

## Lerian STA

***

The Mensageria consumes the topic `lerian.streaming.br-sta`, which Lerian STA produces. It registers six event types:

* `br_sta_transfers.accepted`
* `br_sta_transfers.rejected`
* `br_sta_transfers.inconsistent`
* `br_sta_transfers.canceled`
* `br_sta_transfers.download_finished`
* `br_sta_transfers.download_not_authorized`

The Mensageria keeps the events whose `source_product` matches its `STA_SOURCE_PRODUCT` setting. It ignores the events of other products. The `direction` field of each event selects the pipeline. One direction is a file that Lerian STA downloaded for the Mensageria. The other is the outcome of a response file that the Mensageria submitted.

The database also refuses a second remittance file with the same SHA-256 digest for the same institution.

With `STA_TRANSFERS_ENABLED` on, the Mensageria submits each response file to Lerian STA. [How Lerian SISBAJUD works](/en/rails/sisbajud/how-sisbajud-works) describes the submission.

### Dead-lettered events

A Lerian STA event that the Mensageria refuses goes to the topic `lerian.streaming.br-sisbajud.dlq`. The record carries a reason token, for example `institution_unresolved` or `sha256_mismatch`.

`POST /v1/institutions/{institutionId}/sta-dlq/{eventId}/acknowledge` records what an operator did with one dead-lettered event: `replayed`, `recorded`, or `escalated`. It writes an audit record. It does not remove the event, and the topic keeps the event for its retention period. To replay an event, move the consumer group back to the source offset that the record headers name.

## Streaming Hub and the executor

***

The Mensageria publishes the execution notices and the probes on `lerian.streaming.br-sisbajud`. The [Streaming Hub](/en/platform/streaming-hub/managing-subscriptions) delivers them to the executor by webhook.

An operator creates one Streaming Hub subscription for the executor. The subscription lists exactly two event types: `judicial_order.execution_requested` and `sisbajud_probe.requested`. The Streaming Hub signs each delivery with the secret of the subscription. The executor verifies that signature. It runs each delivery under its own tenant and does not use the tenant header of the delivery.

Do not rely on the arrival order of execution notices. The Mensageria keeps the order of releases for a subject in its database.

## Execution API

***

The executor reads orders and reports results through the execution API. These operations are not in the Mensageria API reference.

| Operation | Path | Permission |
| - | - | - |
| `getOrder` | `GET /v1/sisbajud/execution/orders/{orderId}` | `br-sisbajud-orders:read` |
| `listOrders` | `GET /v1/sisbajud/execution/orders` | `br-sisbajud-orders:read` |
| `postExecutionResult` | `POST /v1/sisbajud/execution/orders/{orderId}/execution-results` | `br-sisbajud-execution-results:create` |
| `getProbe` | `GET /v1/sisbajud/execution/probes/{probeId}` | `br-sisbajud-probes:respond` |
| `postProbe` | `POST /v1/sisbajud/execution/probes/{probeId}` | `br-sisbajud-probes:respond` |

The execution API has its own listener at `SISBAJUD_EXECUTION_ADDRESS`. The default is `:4032`. The main API at `SERVER_ADDRESS` does not serve these paths. The execution listener accepts TLS 1.2 or later and has no plain HTTP mode. `SISBAJUD_EXECUTION_TLS_CERT_FILE` and `SISBAJUD_EXECUTION_TLS_KEY_FILE` hold the server certificate and key.

`SISBAJUD_EXECUTION_MTLS_ENABLED` turns on mutual TLS. Then the listener requires a client certificate that `SISBAJUD_EXECUTION_CLIENT_CA_FILE` verifies. The executor has its own switch, `MENSAGERIA_MTLS_ENABLED`. Set both switches to the same value. With mutual TLS on the Mensageria and off on the executor, the TLS handshake fails.

The executor authenticates with an M2M bearer token. Its client holds the role `br-sisbajud-executor-role`, which grants the three permissions in the table. The Mensageria takes the identity and the role from the token only. The client certificate does not change authorization.

### Canary probe

Every `EXECUTION_CANARY_INTERVAL_SEC` seconds, the Mensageria publishes one `sisbajud_probe.requested` event for each enabled institution. The default is `300`. The executor answers with `POST /v1/sisbajud/execution/probes/{probeId}`. Enable an institution on the Mensageria when an executor serves that institution.

## Events

***

The Mensageria publishes three event types on the topic `lerian.streaming.br-sisbajud`.

| Event | Schema version | Payload | Delivery |
| - | - | - | - |
| `judicial_order.execution_requested` | `1.0.0` | `orderId`, `orderRevision`, `institutionId`, `operation`, `parentOrderId` | Written to the outbox in the release transaction. |
| `sisbajud_probe.requested` | `1.0.0` | `probeId` | Written to the outbox with the probe record. |
| `kek.rotated` | `1.1.0` | `eventId`, `keyType`, `keyScope`, `keyPurpose`, `institutionId`, `previousVersion`, `newVersion`, `rotatedAt` | Published directly, through the outbox when the circuit breaker is open. |

* The `operation` of an execution notice is `REQUISICAO_INFORMACAO`, `BLOQUEIO`, or `DESBLOQUEIO`.
* The Mensageria publishes `kek.rotated` when an operator rotates an institution's KEK with HashiCorp Vault as the key provider.
* The `ce-type` header is `studio.lerian.br-sisbajud.<resource>.<event>`, for example `studio.lerian.br-sisbajud.kek.rotated`.
* The `ce-schemaversion` header carries the schema version.
* The dead-letter topic of `kek.rotated` is `lerian.streaming.br-sisbajud.dlq`.

### Topics

With `STREAMING_TOPIC_AUTO_PROVISION` at its default, `true`, the Mensageria creates `lerian.streaming.br-sisbajud` and `lerian.streaming.br-sisbajud.dlq` at startup. Its broker identity needs permission to create these topics. If you create the topics before you deploy, set `STREAMING_TOPIC_AUTO_PROVISION` to `false`.


# Operating Lerian SISBAJUD
Source: https://docs.lerian.studio/en/rails/sisbajud/sisbajud-operations

Operating the Lerian SISBAJUD Mensageria: institutions, orders that need attention, response windows, key rotation, data protection, roles, and the HTTP surface.

This page describes how to run the **Mensageria**. [Operating the Lerian SISBAJUD executor](/en/rails/sisbajud/sisbajud-executor-operations) describes the executor.

## Institutions

***

`POST /v1/institutions` registers an institution on the Mensageria. The body has these fields:

| Field | Meaning |
| - | - |
| `institutionId` | The UUID of the institution. |
| `institutionCode` | The CNPJ root of the institution, 8 digits. The Mensageria matches it with the CNPJ root in each file header and writes it in the response files. |
| `retryPolicyConfig` | Optional. The retry policy, as JSON. |
| `enabled` | Whether the institution is active. |

The request creates the institution's tokenization keyset and audit keyset. A second request with the same `institutionId` returns `409`. `PATCH /v1/institutions/{institutionId}` changes `institutionCode`, `retryPolicyConfig`, or `enabled`.

### Register the institution on both components

Register each institution on the Mensageria and on the executor:

1. Send `POST /v1/institutions` to the Mensageria with the institution's `institutionId` and `"enabled": true`.
2. Send `POST /v1/institutions` to the executor with the same `institutionId` and `"enabled": true`. The executor's body also carries its Midaz connector configuration, and it takes the optional fields `branchFormat` and `accountFormat`. [Operating the Lerian SISBAJUD executor](/en/rails/sisbajud/sisbajud-executor-operations) describes this request.

The executor records itself as the owner of the institution, from its own M2M identity (`EXECUTOR_M2M_SUBJECT`). No request field sets the owner, and a `PATCH` does not change it. The executor writes on the ledger only for the institutions it owns.

### Tenant

A single-tenant Mensageria uses `DEFAULT_TENANT_ID`. The default is `11111111-1111-1111-1111-111111111111`. One tenant can hold many institutions.

## Orders that need attention

***

| Operation | What it returns |
| - | - |
| `GET /v1/institutions/{institutionId}/awaiting-decision-orders` | The orders that response-file generation holds for a human decision, and that no response file has answered. |
| `GET /v1/institutions/{institutionId}/failed-orders` | The orders in `FAILED`, and the orders that the executor gave up on. Each order shows its SLA deadline. |
| `GET /v1/institutions/{institutionId}/sla-status` | The active orders by SLA-risk band, with the detail of each order. |
| `GET /v1/institutions/{institutionId}/stats` | The number of orders, by status and by order type. An optional period limits the count. |

`GET /v1/institutions/{institutionId}/orders` and `GET /v1/institutions/{institutionId}/files` list the orders and the files. The detail operations return one order or one file.

## Response windows

***

SISBAJUD sets the block-response deadline by the send time of each remittance. A remittance sent up to 13:00 BRT is due by 19:00 BRT the same day. A remittance sent after 13:00 BRT is due by 12:00 BRT the next business day.

The Mensageria generates response files at intervals, not at fixed times. Set `RETURN_FILE_GENERATION_SCAN_INTERVAL` and `INFORMATION_RETURN_FILE_GENERATION_SCAN_INTERVAL` so that each cycle ends inside the BACEN window. Both values are in seconds, and both default to one hour.

### Response-file remedies

* `POST /v1/institutions/{institutionId}/return-file/generate` runs one response-file generation now.
* `POST /v1/institutions/{institutionId}/return-file/{id}/reconsolidate` releases the orders of a `FAILED` response file, so that a later generation can answer them. The file stays `FAILED`.
* `POST /v1/institutions/{institutionId}/return-file/{id}/resolve-transmission` applies one remedy to a submission that no automatic path can finish: `probe_now`, `attach_transfer`, `force_fail`, or `cancel_now`. The `reason` goes into the audit trail as written, so do not put personal data or amounts in it.

## Key rotation

***

Key rotation runs per institution:

* **Key-encryption key (KEK).** `POST /v1/institutions/{institutionId}/security/kek:rotate` rotates the institution's KEK. The response shows the previous and the new KEK version. With HashiCorp Vault as the key provider, the rotation publishes a `kek.rotated` event. With `KEK_REWRAP_BACKFILL_ENABLED` on, a background job re-wraps the data keys under the new KEK version. It is off by default.
* **Tokenization keyset.** `POST /v1/institutions/{institutionId}/security/keyset:rotate` adds a new primary key to the institution's tokenization keyset. An institution with no active keyset returns `422`.

A rotation returns `SBJ-0007` / **409** when another rotation of the same key for the same institution is in progress. Send it again after that rotation ends.

A rotation that returns `SBJ-0002` / **500** can have committed: the key can already be at the new version. Do not send the rotation again, because a second request rotates the key again. Contact Lerian support.

## Data protection

***

* **Envelope encryption.** The Mensageria encrypts sensitive fields with AES-256-GCM under a data key (DEK). The institution's KEK wraps the data key, in HashiCorp Vault Transit or AWS KMS. The additional authenticated data binds each ciphertext to its institution, table, record, and field.
* **Searchable tokenization.** A blind index keeps a token of the CPF/CNPJ and of the process number. The token comes from an HMAC-SHA256 key of the institution. It supports exact-match search.
* **Masked reads.** The order detail and the file detail mask sensitive fields unless the caller holds `admin:read_pii`. The Mensageria records a cleartext order read in the audit trail.
* **Audit trail.** `GET /v1/institutions/{institutionId}/audit/verify` checks a range of the audit log by leaf index without decrypting any payload. It reports tampering and deleted entries.
* **LGPD.** `POST /v1/institutions/{institutionId}/lgpd/requests` opens an access or portability request. `.../resolve` records the decision. `GET /v1/institutions/{institutionId}/lgpd/subject-data` exports the records of a data subject.

## Roles

***

The Mensageria declares four business roles: `operator`, `investigator`, `compliance-officer`, and `admin`. Each permission goes to these roles:

| Permission | Roles |
| - | - |
| `admin:read` | `operator`, `investigator`, `compliance-officer`, `admin` |
| `admin:read_pii` | `investigator`, `compliance-officer`, `admin` |
| `lgpd:request_read`, `lgpd:request_write` | `compliance-officer`, `admin` |
| `non_compliance:justify` | `compliance-officer`, `admin` |
| `institution_config:write` | `admin` |
| `kek:rotate`, `keyset:rotate` | `admin` |
| `return_file:generate`, `return_file:reconsolidate`, `return_file:resolve_transmission` | `admin` |
| `sta_dlq:acknowledge` | `admin` |

A role applies to every institution of the tenant. The Mensageria has no per-institution grant. The executor uses a separate M2M role, which [Integrating with Lerian SISBAJUD](/en/rails/sisbajud/sisbajud-integration#execution-api) describes.

## HTTP surface

***

Orders arrive only as files, so no operation accepts an order. The main API listens at `SERVER_ADDRESS`. The default is `:4031`. It serves these operation groups:

* Institutions: create, read, and update.
* Orders and files: lists, details, orders that need attention, SLA status, and statistics.
* Audit verification.
* LGPD requests.
* Non-compliance justifications.
* Response-file remedies.
* Key rotation.
* Lerian STA dead-letter acknowledgement.

It also serves `/health`, `/readyz`, `/version`, and the Systemplane admin routes under `/system`. The execution API has its own listener.

`PLUGIN_AUTH_ENABLED` must be `true` or `false`. The Mensageria accepts `false` only when `ENV_NAME` is `development`, `develop`, `dev`, `local`, or `test`, and `DEPLOYMENT_MODE` is not `saas`. With `false`, protected operations still require a bearer token. The Mensageria skips only the Access Manager check.


# What is Lerian SISBAJUD?
Source: https://docs.lerian.studio/en/rails/sisbajud/what-is-lerian-sisbajud

Lerian SISBAJUD connects your institution to the CNJ/BACEN judicial asset-blocking system. Two components receive court orders by file and run them on the Midaz ledger.

**Lerian SISBAJUD** connects a financial institution to **SISBAJUD** (Sistema de Busca de Ativos do Poder Judiciário), the Brazilian judicial asset-search and blocking system. The **CNJ** runs it with the **Banco Central (BACEN)**. Courts use it to order an institution to block, release, transfer, and report a defendant's funds.

Lerian SISBAJUD has two components:

* **Lerian SISBAJUD Mensageria** (the Mensageria) receives the judicial orders as files through [Lerian STA](/en/rails/sta/what-is-lerian-sta). It keeps the order record. It writes the response files and submits them to BACEN through Lerian STA. The Mensageria calls no ledger and holds no ledger credential.
* **Lerian SISBAJUD executor** (the executor) runs the orders on the client's **Midaz** ledger: blocks, unblocks, and information requests.

[How Lerian SISBAJUD works](/en/rails/sisbajud/how-sisbajud-works) shows the path of an order through both components.

## What Lerian SISBAJUD does and does not do

***

* It **receives orders as files.** A remittance file reaches the Mensageria as a Lerian STA event. The Mensageria has no HTTP operation that accepts an order, and it does not poll for files.
* It **separates the regulatory side from the ledger side.** The Mensageria keeps the files and the order record. The executor makes the ledger writes.
* It **does not start work when a deadline time arrives.** Response files are generated at configured intervals. Set those intervals so that each cycle ends inside the BACEN response window.
* It **runs one tenant per executor process.** The executor does not start when its tenant list holds more than one tenant.

## Who it serves

***

Lerian SISBAJUD serves banks and financial institutions that must honour judicial asset orders under the CNJ/BACEN SISBAJUD regime.

One Mensageria serves many institutions. It reads the CNPJ root from the header of each file and matches it to an institution registered on the Mensageria. Each institution has its own orders, files, and encryption keys.

## Glossary

***

| Term | Meaning |
| - | - |
| **Lerian SISBAJUD** | Lerian's participant-institution integration for judicial asset blocking under the CNJ/BACEN SISBAJUD system. |
| **Mensageria** | The Lerian SISBAJUD component that receives the order files, keeps the order record, and sends the response files. |
| **Executor** | The Lerian SISBAJUD component that runs the orders on the Midaz ledger. |
| **Execution notice** | The event `judicial_order.execution_requested`. The Mensageria publishes it when it releases an order to the executor. |
| **Human decision** | An order that the executor hands to an operator instead of finishing it alone. |
| **Judicial block (bloqueio)** | A court-ordered hold on a defendant's funds. |
| **Unblock (desbloqueio)** | A court-ordered release of held funds. |
| **Permanent block (bloqueio permanente)** | A block order that the court marks as permanent. In the 2026 layout, the indicator `P` or `D` marks it. Colloquially, the *teimosinha*. |
| **Remittance file** | The fixed-width file that the Judiciary and BACEN send with the judicial orders. |
| **Response / return file** | The fixed-width file that the institution sends back with the order outcomes. |
| **Block account** | The Midaz account that holds the funds of one block order. Its alias is `@block_sisbajud_` followed by the 32 hexadecimal digits of the order ID. |
| **Envelope encryption (KEK/DEK)** | A data key (DEK) for each operation, wrapped by the institution's key-encryption key (KEK). |
| **Searchable tokenization (blind index)** | A per-institution token that supports equality lookup. |
| **Audit trail** | An audit log in which each record carries a message authentication code (MAC) under an institution key. The audit verification operation checks these codes. |

For how Lerian SISBAJUD sits alongside the other native rails and the partner interfaces, see [Native messaging and partner interfaces](/en/rails/native-messaging).


# How Lerian SLC works
Source: https://docs.lerian.studio/en/rails/slc/how-slc-works

How Lerian SLC works: operation intake, online submissions and ASLC files, custody signing, Núclea returns, clearing and funding, and the NUliquid-keyed settlement lifecycle.

Lerian SLC runs one settlement pipeline for every card operation. It takes in the operation, submits it to Núclea, and correlates Núclea's verdict and returns. A custody backend signs every submission. The NUliquid tracks the operation after Núclea accepts it.

## Intake

***

Operations enter Lerian SLC through the operations API:

* **Single intake.** One operation as JSON. The caller's deduplication key is `externalId`. A second submission under an `externalId` already in use returns **409 Conflict**. A retried submission therefore never settles twice.
* **Batch intake.** NDJSON, one operation per line, up to 50,000 lines by default. Lerian SLC counts the lines and the bytes before it saves anything, so an over-limit batch answers **413** and saves nothing. A bad line is refused alone and does not stop the batch.

The file intake also accepts an artifact that the client already signed. Lerian SLC records its checksum and metadata for audit. It does not parse or transmit the artifact.

You submit three operation types: **CREDIT**, **DEBIT**, and **ANTICIPATION**. A **CANCELLATION** follows its own rules, because it carries a regulatory reason category and the identifier of the operation it cancels. Lerian SLC refuses **SWEEP** at intake: it builds the sweep (varredura) summary files itself. You can also cancel an operation locally while it is **CREATED** or **QUEUED**, before Núclea receives it.

## Submit, sign, transmit, correlate

***

Lerian SLC sends two kinds of traffic to Núclea:

* **Online submissions.** Credit, debit, and anticipation go to Núclea as JSON submissions: **SLC0914** for a credit, **SLC0913** for a debit, and **SLC0912** for an anticipation. Lerian SLC polls **SLC0915** for Núclea's verdict on each submission.
* **ASLC files.** Cancellations, forwards to the IF Domicílio, status relays to the credenciadora, and the sweep summaries travel as ASLC files. Lerian SLC builds each file as UTF-16BE with no BOM and validates those final bytes against the message's XSD before building the security envelope. It compresses the file with **GZIP** and wraps it in the **SPB security envelope**, which a custody backend signs (see [Signing orchestration](#signing-orchestration)).

Lerian SLC correlates each return with the operation that produced it, by the key the counterparty echoes. A **RET** line uses the 20-position control number derived from the operation's `externalId`, left-padded with zeros when shorter. An **ASLC023** or D+1 line uses its **NUliquid**. A **PRO** at file level uses the control number of the transmitted file. A line whose key matches nothing is skipped as uncorrelated.

### When one return contradicts itself

A single return file can state two different outcomes for the same reference. Lerian SLC resolves it by policy, whatever the order of the lines in the file:

* one outcome: applied as stated.
* the same outcome repeated: applied exactly once.
* an acceptance and a refusal for the same reference: the refusal wins, and Lerian SLC logs and counts the displaced acceptance.

The result is the same whichever order the two lines arrive in. The file is never aborted: every other reference in it keeps processing, and the return is still acknowledged.

## Message families

***

| Flow | Messages |
| - | - |
| Submission (credit / debit / anticipation) | SLC0914 / SLC0913 / SLC0912, verdict SLC0915 |
| Forward to the IF Domicílio | ASLC022 / ASLC024 / ASLC032 |
| IF Domicílio answer | ASLC023 / ASLC025 / ASLC033 |
| Status relay to the credenciadora | ASLC028 / ASLC030 / ASLC034 |
| D+1 result | ASLC041 / ASLC042 / ASLC043 |
| Cancellation | ASLC060–ASLC067 |
| Sweep (varredura) | ASLC050 / ASLC051 |

## Settlement flows

***

* **Credit, debit, and anticipation.** Lerian SLC submits the operation and reads Núclea's verdict. After Núclea accepts it, Lerian SLC forwards the settlement notice to the IF Domicílio through Núclea. It reads the IF Domicílio's answer and relays it to the credenciadora. The IF Domicílio's D+1 result closes the lifecycle.
* **Cancellation.** The credenciadora informs a cancellation (credit **ASLC060**, debit **ASLC064**). Lerian SLC forwards it to the IF Domicílio (**ASLC061**, **ASLC065**) and reads the answer (**ASLC062**, **ASLC066**). When the IF Domicílio confirms the cancellation, Lerian SLC emits `cancellation.confirmed_by_domicile`.

## Clearing and funding for the IF Liquidante

***

For the settling institution, Lerian SLC consumes Núclea's clearing messages over the RSFN: the preview and final clearing position (**SLC0001**) and the bilateral-movement divergence (**SLC0002**). The **GEN0015** message reports a file available for pickup, and **PAG0101** carries a participant's operational status. From [Lerian SILOC](/en/rails/siloc/what-is-lerian-siloc), it receives the cycle opening (**PAG0102**) and close (**PAG0103**) and the deposit value (**LDL0021**).

Lerian SLC keeps the clearing position per settlement cycle. When a cycle closes, it compares each participant's settlement instruction with the final position and marks the cycle reconciled when they agree. It raises a `clearing.*` event for each step.

1. Lerian SLC relays the deposit value to the client as `clearing.deposit_required`.
2. The client makes the deposit on its own STR connection. Lerian SLC does not send the deposit message.
3. The client records the result with the deposit acknowledgement, `SENT` or `FAILED`. `SENT` acknowledges the settlement instruction. `FAILED` is recorded, leaves the instruction open, and raises `funding.deposit_failed`.
4. A credit or debit operation moves from **CONFIRMED** to **SETTLED** when both confirmations exist: the client's deposit acknowledgement and the close of Núclea's cycle.

An anticipation settles outside the multilateral cycle. It moves from **CONFIRMED** to **SETTLED** on the IF Domicílio's confirmation, with no deposit acknowledgement and no cycle close.

## Gross settlement (LBTR)

***

From Lerian SILOC, Lerian SLC receives the gross settlement announcements: a settlement result (**LTR0001**), an operation between two of the institution's own non-liquidantes (**LTR0007**), and the cancellation of a result (**LTR0012**). The institution answers through Lerian SILOC:

* **LTR0002** confirms or diverges from a result.
* **LTR0008** confirms or rejects a non-liquidante operation.
* **LTR0009** asks for the institution's LBTR position.

A command moves from **REQUESTED** to **ACCEPTED**, then to **ANSWERED**, **REFUSED**, or **FAILED**. **ACCEPTED** means that Lerian SILOC queued the command. It does not mean that anything settled. Lerian SLC does not compute the LBTR position. The clearing house answers the position query.

Lerian SLC delivers these commands to Lerian SILOC through the Lerian SLC streaming producer. While `STREAMING_ENABLED` is `false`, Lerian SLC does not deliver them.

## Operation lifecycle

***

Each operation follows an eleven-state lifecycle. Núclea assigns its NUliquid when the operation is accepted.

| State | Meaning |
| - | - |
| **CREATED** | Lerian SLC has accepted the operation. It stays CREATED until an operator requeues it. |
| **QUEUED** | The operation waits in the dispatch queue for its window. |
| **SENT** | Lerian SLC has submitted the operation to Núclea. |
| **ACKNOWLEDGED** | Núclea has acknowledged receipt. |
| **ACCEPTED** | Núclea has accepted the operation. |
| **REJECTED** | Núclea refused the operation, or the IF Domicílio refused it before settlement or on D+1 after settlement. |
| **FORWARDED** | Lerian SLC has forwarded the settlement notice to the IF Domicílio. |
| **CONFIRMED** | The IF Domicílio has confirmed. |
| **SETTLED** | Lerian SLC recorded the settlement signal: the funding steps above for a credit or debit, or the IF Domicílio's confirmation for an anticipation. |
| **D1\_CONFIRMED** | The IF Domicílio confirmed the settled operation on D+1. |
| **CANCELLED** | The operation was cancelled locally, from **CREATED** or **QUEUED**. |

## Signing orchestration

***

Lerian SLC builds the unsigned payload and delegates signing to a custody backend. Each registered certificate names its backend.

| Custody backend | Where the key lives |
| - | - |
| **Software key** | A key file in the client's environment. |
| **PKCS#11 HSM** | A hardware security module. |
| **AWS KMS** | A key in AWS Key Management Service. |

SaaS deployments lock custody to AWS KMS. Lerian SLC never receives the signing private key in cleartext: the client wraps its key material locally against an import token, and the service imports the wrapped material into a KMS key for that tenant and participant. The service stores the public certificate and a key reference.

## Transport

***

Lerian SLC sends its online submissions and ASLC files to Núclea over **REST**, secured by **mTLS** and a **per-request JWS** signature. It polls and acknowledges Núclea's returns over the same channel.

> [!NOTE]
>
> You set the outbound transport at runtime, and REST is the default. A tenant set to **Connect:Direct** fails closed with a typed transport error. It does not fall back to REST.


# Environment variables
Source: https://docs.lerian.studio/en/rails/slc/slc-environment-variables

Deploy-time environment variables distinctive to Lerian SLC: Núclea/RSFN transport, the SFN inbound bus, the signing sidecar, and the settlement schedule.

Lerian SLC is the Lerian-owned rail for card-settlement messaging with Núclea's SLC. You set these variables at deploy time. A service restart applies them. Every Lerian Go service shares a universal backbone: server, datastores, telemetry, and plugin authentication. [BYOC configuration essentials](/en/reference/byoc-configuration) documents that backbone once. This page covers the variables distinctive to Lerian SLC.

In the tables below, the **Default / Required** column shows the default value. A bold qualifier (e.g. **Required**, **Required in production**) marks a variable you must set. `—` means no default. A variable marked **Sensitive** carries credential or key material. Inject it from your secret manager at deploy time. Never commit a value.

## Service and runtime

| Variable | Default / Required | Description |
| - | - | - |
| `SERVER_ADDRESS` | `:4111` | Main HTTP listen address. The liveness, readiness, metrics, and version probes bind this same port. |
| `SYSTEMPLANE_ENABLED` | `false` | Enable the [Systemplane](/en/reference/platform/systemplane/overview) runtime-configuration admin API under the `/system` prefix on the main port. Off by default (environment-variable-only mode). |
| `TENANT_RUNTIME_CONFIG_ENABLED` | `false` | Enable the per-tenant runtime-config store and admin surface, resolving each tenant's connectivity transport from a per-tenant record rather than the shared configuration. Selection and policy only. |

> [!NOTE]
>
> Lerian SLC exposes `/health` (liveness) and `/readyz` (readiness) on the main port, plus `/version` and `/metrics`. See [Health and readiness](/en/reference/health-and-readiness) for the probe contract. One installation serves one client.

## License

| Variable | Default / Required | Description |
| - | - | - |
| `LICENSE_KEY` | **Required** | License credential issued by Lerian. Sensitive. |
| `ORGANIZATION_IDS` | **Required** | Organization scope the license covers. |

## Operation intake

| Variable | Default / Required | Description |
| - | - | - |
| `INTAKE_BATCH_MAX_LINES` | `50000` | Line cap of the batch intake. A batch above it answers `413` and saves nothing. |
| `INTAKE_BATCH_SPOOL_MAX_BYTES` | `268435456` | Byte cap of the batch intake. A batch above it answers `413` and saves nothing. |
| `INTAKE_BATCH_SPOOL_DIR` | system temporary directory | Directory where the batch intake spools the body while it counts the lines. Point it at a writable volume when the root filesystem is read-only. |

## Núclea REST transport

This channel submits to Núclea online over mutual TLS. Leave `NUCLEA_REST_BASE_URL` empty to keep the transport unwired.

| Variable | Default / Required | Description |
| - | - | - |
| `NUCLEA_REST_BASE_URL` | — | Base URL of the Núclea node. Empty disables the whole REST transport: online submission, return polling, queries, and file submission. Under `ENV_NAME=production` or `DEPLOYMENT_MODE=saas`, the URL must use `https`. Locally it points at a simulator. |
| `NUCLEA_REST_TIMEOUT_SEC` | `30` | Per-request timeout in seconds. |
| `NUCLEA_REST_CB_CONSECUTIVE_FAILURES` | `5` | Consecutive failures that trip the circuit breaker open. |
| `NUCLEA_REST_CB_OPEN_TIMEOUT_SEC` | `30` | How long the breaker stays open before half-open. |
| `NUCLEA_REST_ALLOW_INSECURE_TLS` | `false` | Relax Núclea TLS verification for local development only. Boot is rejected when this is `true` under `ENV_NAME=production` or `DEPLOYMENT_MODE=saas`. |
| `NUCLEA_REST_RESPONSE_CERT_PATH` | **Required unless the base URL is a development target** | Path to Núclea's public certificate, which verifies the signature on each response. Boot fails when it is empty and the base URL points anywhere else. |
| `NUCLEA_REST_CLIENT_CERT_PATH` | **Required in production/SaaS when the base URL is set** | Path to the PEM client certificate presented to Núclea for mutual TLS. |
| `NUCLEA_REST_CLIENT_KEY_PATH` | **Required in production/SaaS when the base URL is set** | Path to the PEM client private key for mutual TLS. Sensitive. The file holds private key material. |

## RSFN inbound consumer

This channel receives inbound RSFN messages. It also observes XSD conformance.

| Variable | Default / Required | Description |
| - | - | - |
| `RSFN_CONSUMER_TRANSPORT` | `stub` | Inbound transport behind the RSFN consumer port: `stub` (a development REST channel) or `mq` (the RSFN network transport through the MQ bridge). Another value refuses boot. The consumer drains only when `SCHEDULE_RSFN_INGEST_ENABLED=true`. |
| `MQ_BRIDGE_URL` | **Required when the MQ transport is in use** | Base URL of the MQ bridge. You must declare it explicitly with `RSFN_CONSUMER_TRANSPORT=mq`, or with per-tenant transport selection on; it cannot inherit `http://localhost:9121`, because the correct address depends on your deployment topology. |
| `MQ_BRIDGE_QUEUE_MANAGER`, `MQ_BRIDGE_CHANNEL`, `MQ_BRIDGE_CONN_NAME`, `MQ_BRIDGE_QUEUE` | **Required when the MQ transport is in use** | IBM MQ connection details that the MQ transport hands to the bridge. With a blank queue, every drain fails closed. |
| `RSFN_CONSUMER_BASE_URL` | — | Base URL for the `stub` transport. Empty leaves the consumer unwired. |
| `RSFN_CONSUMER_TIMEOUT_SEC` | `30` | Per-request timeout in seconds. |
| `CIRCUIT_BREAKER_ENABLED` | `false` | Enable the shared circuit-breaker manager. The manager guards more than this consumer: startup fails closed without it when the `stub` channel has a base URL, when the MQ transport is in use, or when `NUCLEA_REST_BASE_URL` is set. |
| `RSFN_CONSUMER_CB_CONSECUTIVE_FAILURES` | `5` | Consecutive failures that trip the RSFN consumer breaker when `CIRCUIT_BREAKER_ENABLED=true`. |
| `RSFN_CONSUMER_CB_OPEN_TIMEOUT_SEC` | `30` | How long the breaker stays open before half-open. |
| `RSFN_CONSUMER_ALLOW_INSECURE_TLS` | `false` | Relax the stub-channel TLS verification for local development only. Under production or SaaS the stub channel always verifies TLS. |
| `RSFN_INBOUND_XSD_VALIDATION_ENABLED` | `true` | Observe-only XSD validation of inbound RSFN/SILOC messages against the official schemas. Logs and meters non-conformance without altering dispatch. |
| `ASLC_INBOUND_XSD_VALIDATION_ENABLED` | `true` | Observe-only XSD validation of inbound ASLC return messages. Logs and meters non-conformance without altering the return pipeline. |
| `RSFN_INBOUND_XSD_FAIL_CLOSED_CODMSGS` | — | Comma-separated RSFN and Lerian SILOC message types that leave observe-only mode: an XSD failure sends the message to the dead-letter queue. A message type the service does not route refuses boot. |
| `ASLC_INBOUND_XSD_FAIL_CLOSED_CODMSGS` | — | Comma-separated ASLC return types that leave observe-only mode: an XSD failure leaves the return unacknowledged for the next poll. A return type the service does not route refuses boot. |
| `XSD_VALIDATOR_URL` | `http://localhost:9091` | Base URL of the XSD-validation sidecar. The inbound observers call it, and so does the outbound file build, which fails closed when the sidecar does not answer. |
| `XSD_VALIDATOR_TIMEOUT_SEC` | `10` | Per-request timeout in seconds for XSD-validation calls. |

## SFN inbound bus

Lerian SILOC relays its messages to Lerian SLC on the SFN bus. `SFN_INGEST_ENABLED` turns on the ingest of the relayed messages. `SFN_FACTS_INGEST_ENABLED` turns on the ingest of the outcomes of the settlement commands that Lerian SLC sends. Both consumers use the same brokers and batch size.

| Variable | Default / Required | Description |
| - | - | - |
| `SFN_INGEST_ENABLED` | `false` | Master switch for the SFN ingest path (bus consumer and driver). |
| `SFN_BUS_PROVIDER` | `kafka` | Consumer adapter: `kafka` or `stub` (development/CI). |
| `SFN_KAFKA_BROKERS` | **Required if ingest is on with provider `kafka`, or if facts ingest is on** | Comma-separated Kafka/RedPanda bootstrap broker list. |
| `SFN_KAFKA_TOPIC` | `siloc.inbound` | Topic the SILOC relay publishes to. |
| `SFN_KAFKA_GROUP_ID` | service-scoped default | Kafka consumer group id; override per deployment when needed. |
| `SFN_KAFKA_BATCH_SIZE` | `100` | Records read per batch. |
| `SFN_STUB_TIMEOUT_SEC` | `30` | Per-request timeout in seconds for the `stub` adapter. |
| `SFN_FACTS_INGEST_ENABLED` | `false` | Master switch for the consumer of the settlement-command outcomes. |
| `SFN_FACTS_KAFKA_TOPIC` | `siloc.outbound.facts` | Topic on which Lerian SILOC publishes the command outcomes. |
| `SFN_FACTS_KAFKA_GROUP_ID` | service-scoped default | Kafka consumer group id of the facts consumer, distinct from `SFN_KAFKA_GROUP_ID`. |

## Streaming

Lerian SLC and the Lerian streaming library read the `STREAMING_` family. [Lerian Streaming Hub](/en/platform/streaming-hub/what-is-streaming-hub) delivers the published events.

| Variable | Default / Required | Description |
| - | - | - |
| `STREAMING_ENABLED` | `false` | Master switch for the streaming producer. The producer publishes business events and delivers the LBTR commands to Lerian SILOC. It also needs `OUTBOX_ENABLED=true`. |
| `STREAMING_BROKERS` | **Required** when streaming is on | Comma-separated broker bootstrap list. An enabled configuration with an empty list refuses to boot. |
| `STREAMING_CLOUDEVENTS_SOURCE` | **Required** when streaming is on | This service's CloudEvents source. Set it to the `publisher.source` value of the event manifest that `GET /v1/streaming/manifest` returns. The service serves the manifest while streaming is off. An empty or malformed value refuses the boot when streaming is on. |
| `STREAMING_CLIENT_ID` | `primary` | Broker client identifier used for broker-side diagnostics. |
| `STREAMING_CLOSE_TIMEOUT_S` | `30` | Maximum drain and flush window in seconds when the producer closes. |
| `STREAMING_TOPIC_AUTO_PROVISION` | `true` | When streaming is on, creates the event topic `lerian.streaming.<source>` and the dead-letter topic `lerian.streaming.<source>.dlq` if they are missing at boot. `<source>` is the value of `STREAMING_CLOUDEVENTS_SOURCE`. A refused or failed creation logs a warning, and the boot continues. Set it to `false` when you provision the topics yourself. |
| `STREAMING_TOPIC_PARTITIONS` | Broker default | Partition count of the topics that the service creates. An unset, zero, or invalid value uses the broker default. |
| `STREAMING_TOPIC_REPLICATION_FACTOR` | Broker default | Replication factor of the topics that the service creates. An unset, zero, or invalid value uses the broker default. |
| `STREAMING_HEALTH_CHECK_TIMEOUT` | `2s` | Time limit of the streaming check in the readiness probe. |

## Signing sidecar

Lerian SLC signs the SPB security envelope through a stateless signing sidecar. The signing private key never enters the service process. Each participant's active custody record selects the custody adapter and the key that sign its messages. The sidecar turns on each custody adapter only when that adapter's own settings are present.

| Variable | Default / Required | Description |
| - | - | - |
| `SIGNING_CUSTODY_ADAPTER` | `softkey` | Custody adapter that the startup check expects on the signing sidecar: `softkey`, `pkcs11`, or `awskms`. It does not select the custody of each participant. Under `DEPLOYMENT_MODE=saas` it is always `awskms`, and Lerian SLC refuses a custody record that maps to another adapter. |
| `SIGNER_URL` | `http://localhost:9101` | Base URL of the signing sidecar. |
| `SIGNER_TIMEOUT_SEC` | `10` | Per-request timeout in seconds for signing calls. |
| `SIGNER_SOFTKEY_PFX_PATH` | — | Path to the PKCS#12 file of the software-key adapter. Setting it turns the adapter on. |
| `SIGNER_SOFTKEY_PFX_PASSPHRASE` | — | Passphrase for the software-key custody adapter. Sensitive. |
| `SIGNER_SOFTKEY_ALLOW_IN_PRODUCTION` | `false` | Under `ENV_NAME=production`, the signing sidecar starts only when this is `true`, whatever custody adapter you use. |
| `SIGNER_AWSKMS_REGION` | — | AWS region of the KMS keys. Setting it turns on the cloud-KMS adapter and the signing-key import. |
| `SIGNER_PKCS11_MODULE` | image default | Path to the PKCS#11 module of the HSM. |
| `SIGNER_PKCS11_TOKEN_LABEL` or `SIGNER_PKCS11_SLOT` | — | HSM token, by label or by slot. Setting one turns on the HSM adapter, which then requires the module, the PIN, and the key label. |
| `SIGNER_PKCS11_PIN` | **Required with an HSM token** | PIN of the HSM token. Sensitive. |
| `SIGNER_PKCS11_KEY_LABEL` | **Required with an HSM token** | Label of the signing key inside the token. |

## Settlement schedule

Lerian SLC gates dispatch to Núclea's settlement windows and runs a schedule worker.

| Variable | Default / Required | Description |
| - | - | - |
| `SCHEDULE_CREDIT_WINDOW_OPEN` | **Required in every environment** | Credit-acceptance window open, as `HH:MM` São Paulo local time (half-open interval, opening boundary inclusive). Declare it explicitly for the grade in force. |
| `SCHEDULE_CREDIT_WINDOW_CLOSE` | **Required in every environment** | Credit-acceptance window close, as `HH:MM` São Paulo local time (exclusive). Declare it explicitly for the grade in force. `HH:MM+1` crosses midnight, and only the `especial1` grade accepts it. |
| `SCHEDULE_SPECIAL_GRADE` | `none` | Núclea grade that the credit window must obey: `none`, `especial1`, or `especial2`. Another value refuses boot. Under `ENV_NAME=production` or `DEPLOYMENT_MODE=saas`, the credit window must fit the grade. |
| `SCHEDULE_WORKER_ENABLED` | `true` | Enable the recurring schedule worker (cutoff alerting and, when enabled, the dispatch and return drivers). |
| `SCHEDULE_WORKER_INTERVAL_SEC` | `30` | Schedule worker tick period in seconds. |
| `SCHEDULE_GRID_GATE_ENABLED` | `false` | Gate dispatch to the calendar-backed STR grid instead of the single credit window. |
| `SCHEDULE_CUTOFF_ALERT_LEAD_MIN` | `30` | Minutes before an STR cutoff at which the window enters pre-cutoff and one alert is emitted. |
| `SCHEDULE_DISPATCH_MAX_TRANSMIT_ATTEMPTS` | `20` | Consecutive counterpart refusals an outbound submission may take before Lerian SLC parks the operation for operator review. A transport fault does not count, and a success resets the count. At the default 30-second tick, 20 refusals is about ten minutes before the first alert. |
| `SCHEDULE_HOLIDAYS` | — | Comma-separated `YYYY-MM-DD` banking holidays in São Paulo local time; no window opens on a holiday. A malformed date refuses boot. |

> [!NOTE]
>
> You must declare both credit-window variables, even when you use the standing schedule. The service refuses to start if either value is omitted or blank. It never assumes a credit grade from a default.

> [!NOTE]
>
> Each flow runs in the schedule worker only when its toggle is `true`. Every toggle defaults to `false`: `SCHEDULE_DISPATCH_ENABLED`, `SCHEDULE_FORWARD_ENABLED`, `SCHEDULE_DEBIT_DISPATCH_ENABLED`, `SCHEDULE_DEBIT_FORWARD_ENABLED`, `SCHEDULE_ANTICIPATION_DISPATCH_ENABLED`, `SCHEDULE_ANTICIPATION_FORWARD_ENABLED`, `SCHEDULE_ANTICIPATION_SETTLE_ENABLED`, `SCHEDULE_CANCELLATION_DISPATCH_ENABLED`, `SCHEDULE_CANCELLATION_FORWARD_ENABLED`, `SCHEDULE_RETURN_POLL_ENABLED`, `SCHEDULE_RELAY_STATUS_ENABLED`, `SCHEDULE_VARREDURA_ENABLED`, `SCHEDULE_RSFN_INGEST_ENABLED`, `SCHEDULE_D1_CONFIRMATION_ENABLED`, `SCHEDULE_CONFIRMATION_OVERDUE_ENABLED`, `SCHEDULE_OPERATION_STUCK_ENABLED`, `SCHEDULE_CERT_EXPIRY_ENABLED`, `SCHEDULE_SILOC_WINDOWS_ENABLED`, `SCHEDULE_STR_SETTLED_ENABLED`, and `OP107_VERDICT_POLL_ENABLED`.

## Webhooks

Lerian SLC can deliver settlement events to a subscriber endpoint. In BYOC the client supplies the credential material through their own Kubernetes secret.

| Variable | Default / Required | Description |
| - | - | - |
| `WEBHOOK_WORKER_ENABLED` | `false` | Enable the webhook delivery worker. |
| `WEBHOOK_DELIVERY_PROVIDER` | `direct` | Delivery adapter. `direct` delivers each webhook over HTTP with an HMAC signature. |
| `WEBHOOK_API_KEY` | **Required if delivering** | Client-defined API key sent in the webhook API-key header. Sensitive. |
| `WEBHOOK_API_KEY_FILE` | — | Path to a file holding the API key (a mounted secret volume). When set, the inline value is ignored. |
| `WEBHOOK_HMAC_SECRET` | **Required if delivering** | Client-defined shared secret used to sign each webhook. Sensitive. Never comes from the runtime-config plane or the database. |
| `WEBHOOK_HMAC_SECRET_FILE` | — | Path to a file holding the HMAC secret (a mounted secret volume). When set, the inline value is ignored. |
| `WEBHOOK_MAX_ATTEMPTS` | `6` | Per-subscription retry budget before a delivery is parked on the dead-letter queue. |
| `WEBHOOK_ALLOW_PRIVATE_NETWORK` | `false` | Development-only relaxation of the delivery SSRF block. Must stay `false` in production/SaaS. Otherwise, boot fails closed. |


# Integrating with Lerian SLC
Source: https://docs.lerian.studio/en/rails/slc/slc-integration

Integrating with Lerian SLC: the Núclea and Lerian SILOC messages it consumes, its card settlement and clearing events, HMAC-signed webhooks, and API conventions.

Lerian SLC is event-first at its edges. It consumes Núclea's inbound messages. It writes its business facts to a **transactional outbox**, which delivers them to webhook subscriptions. When streaming is on, the outbox also publishes events to the platform's streaming backbone. On the streaming backbone each event is a **CloudEvents** record. A webhook delivers the event payload as JSON.

## What it consumes

***

From Núclea, over the **RSFN**:

* **GEN0015** (a file is available for pickup, which starts the pull of the returns)
* **SLC0001** (clearing preview and final)
* **SLC0002**
* **PAG0101** (operational status)

On the SFN inbound bus:

* From Lerian SILOC, the SILOC cycle and funding messages: **PAG0102**, **PAG0103**, and **LDL0021**.
* From Lerian SILOC, the gross and bilateral settlement announcements: **LTR0001**, **LTR0007**, and **LTR0012**.
* The outcome of each settlement command that Lerian SLC sends.

From Núclea over REST, Lerian SLC polls the **SLC0915** verdicts, the **PRO / ERR / RET** returns, and the ASLC return messages. It correlates each return seam by the key the counterparty echoes: a **RET** line or an **SLC0915** verdict by its 20-position control number, an **ASLC023** or D+1 line by its **NUliquid**, and a **PRO** at file level by the control number of the transmitted file.

## What it emits

***

Lifecycle events and status relays are written in the same transaction as the state change they report.

* **Operation lifecycle events**: one for each state the operation enters, from `operation.created` to `operation.cancelled`. `operation.manually_advanced` reports an audited override. `operation.d1_rejected` reports a credit that the IF Domicílio refused after it settled.
* **`operation.status_relayed`**: the rail relayed the IF Domicílio's answer to the credenciadora.
* **`operation.forward_rejected`**: an outbound submission was parked and needs operator action. The payload, not the event name, says which leg and why. `stage` identifies the affected leg: `forward` to the IF Domicílio or `dispatch` to Núclea. In both cases, `parkReason` is `attempt_budget_exhausted`. `operationIdsScope` says whether `operationIds` is complete for the file or only a sample. `GET /v1/operations?transmitHold=parked` lists every parked operation.
* **`operation.verdict_unresolved`**: Núclea's verdict on a submission did not resolve into an acceptance or a refusal, so the operation did not move.
* **Schedule alerts**: `operation.stuck_detected`, `d1.missing_confirmation`, `confirmation.overdue`, and `schedule.cutoff_approaching`.
* **`cancellation.confirmed_by_domicile`**: the IF Domicílio confirmed a cancellation and the event carries the NUliquid.
* **`d1.value_mismatch`**: a D0-versus-D+1 value divergence.
* **`certificate.expiring`**: a certificate approaching expiry.
* The **`clearing.*`** family: `cycle_opened`, `cycle_closed`, `cycle_recalculated`, `preview_available`, `final_available`, `deposit_required`, `deposit_deadline_approaching`, and `divergence_reported`.
* **`funding.deposit_failed`**: the client reported that it could not make a deposit.
* **`report.request_acknowledged`** and **`report.result_available`**: Núclea acknowledged a report request, or its result is available.

## Midaz touchpoint

***

Lerian SLC is standalone. It does not post to a ledger itself. Midaz is an optional consumer. Midaz can subscribe to Lerian SLC's events or call its API to mirror settlement into the ledger. Lerian SLC does not depend on Midaz.

## Money-path boundary

***

Lerian SLC owns the card-settlement messaging with Núclea. It does not perform the monetary settlement itself. The netted position settles at the SLC and Núclea. The reserve leg settles at BACEN. The card-domain deferred-net settlement family reaches Lerian SLC relayed from [Lerian SILOC](/en/rails/siloc/what-is-lerian-siloc), the participant-side SILOC connectivity.

## API conventions

***

* **Idempotent intake.** Operation intake refuses an `externalId` that another operation already uses, with `409` and `SLC-0104`. In a batch, a line with a duplicate `externalId` is refused alone, and its error names the existing operation.
* **Idempotent writes.** Operation intake, batch intake, and the deposit acknowledgement accept an optional `X-Idempotency` header. The signing-key and settlement-command operations require it and answer `400` without it.
* **Signed webhooks.** Lerian SLC signs each webhook with HMAC-SHA256 and sends the signature in `X-Webhook-Signature`.
* **Online auth.** mTLS and a per-request JWS signature secure each individual online operation over REST.
* **Certificates are references, not secrets.** A registered certificate carries its public certificate and a custody reference, not the private key.


# Operating Lerian SLC
Source: https://docs.lerian.studio/en/rails/slc/slc-operations

Operating Lerian SLC: the participant catalog and connectivity test, Núclea's grade horária windows, ICP-Brasil certificates and custody, contingency and recovery endpoints, and reconciliation.

Lerian SLC runs against two constraints of Núclea's SLC: rigid daily settlement windows, and regulated ICP-Brasil credentials. The rail enforces the windows, signs through a custody backend, and gives operators endpoints to recover and reconcile operations.

## Participant catalog

***

Lerian SLC keeps a catalog of the participants that the tenant works with. The connectivity test and the operational-status read return `404` for a participant outside the catalog. Lerian SLC skips a clearing position for a participant outside the catalog.

* **Participants.** `POST /v1/participants` registers a participant. Its type is `ACQUIRER`, `SUBCREDITOR`, `DOMICILE_IF`, `SETTLEMENT_IF`, or `BRAND`.
* **Arrangements.** `POST /v1/participants/{id}/arrangements` registers a card-scheme code that the participant operates under. It also records the participant's role in that scheme: `ACQUIRER`, `ISSUER`, `BRAND`, `DOMICILE_IF`, or `SETTLEMENT_IF`. A second arrangement with the same code and role returns `409`.
* **Connectivity test.** `POST /v1/participants/{participantIspb}/test-connectivity` sends a connectivity probe to Núclea over the REST channel. The path takes the participant's ISPB, not its ID. The probe is **AGEN001** for a `DOMICILE_IF` participant and **AGEN999** for the other types. The response reports whether Núclea echoed the probe intact, and the round-trip latency.

## Settlement windows and grade horária

***

Núclea's SLC settles on rigid daily windows set by its grade horária. Lerian SLC evaluates each window as **OPEN**, **PRE\_CUTOFF**, or **CLOSED**, and gates dispatch on the result. The rail holds a **QUEUED** operation outside its window and dispatches it when the window opens. This avoids Núclea's out-of-window rejection (**ESLC0029**). Lerian SLC emits `schedule.cutoff_approaching` as a window approaches its cutoff, 30 minutes ahead by default. Use `GET /v1/schedule` to read the windows and the credit dispatch window that the rail enforces.

* **Queue and retransmit.** An operation stays **CREATED** until an operator requeues it into the dispatch queue. A retransmit resubmits one **QUEUED** operation.

The rail also holds the dispatch and forward of an operation while the latest **PAG0101** status of its creditor is **SUSPENDED** or **SPECIAL\_REGIME**. Use `GET /v1/participants/{id}/operational-status` to read that status and whether the hold applies.

## Certificates and custody

***

Lerian SLC delegates signing to a custody backend: a software key, a **PKCS#11 HSM**, or **AWS KMS**. The signing credential is an **ICP-Brasil** certificate with an RSA key of at least 2048 bits.

* **SaaS deployments** lock custody to AWS KMS. The rail imports the client's wrapped key material and never receives the signing private key in cleartext.
* **Validity.** Lerian SLC refuses to sign with a certificate outside its validity window.
* **Rotation.** Lerian SLC reads the active signing certificate on each signature, so a rotation takes effect on the next one. The mTLS client certificate loads at startup, so its rotation needs a restart.
* **Expiry alerts** escalate at 30, 15, 7, and 1 day before expiry, as `certificate.expiring` events, when `SCHEDULE_CERT_EXPIRY_ENABLED` is `true`.

## Contingency and recovery

***

* **Dead-letter queues.** The rail parks an inbound RSFN or Lerian SILOC message that it cannot process. A parked message stays on the queue for 30 days. `GET /admin/dlq/{queue}` lists the parked messages, and a replay reprocesses one. A replay of a message already processed changes nothing.
* **Recovery drains.** The dispatch, forward, repoll, status-relay, and reprocess endpoints re-run the rail's own outbound and return work without waiting for the next tick.
* **Retry.** A retry resubmits a **REJECTED** operation as a new operation linked to the original. An operation that the IF Domicílio refused on D+1, after it settled, is not retryable.
* **Parked operations.** When consecutive counterpart refusals exhaust an outbound operation's transmit-attempt budget, the rail parks the operation and alerts instead of retrying forever. The un-park endpoint returns it to the eligible backlog, so the next tick re-drives it. It resets the attempt counter, so a recovered operation receives a full budget. Without a fix for the cause, it parks again after that budget is exhausted.
* **Cancellation repasses.** When the rail cannot determine whether a cancellation relay to the credenciadora reached Núclea, it keeps the relay blocked. After you establish the outcome, the resolve endpoint records it: `CONFIRMED` keeps the relay blocked, and `ABANDONED` makes it relayable again.
* **Failed deposits.** `GET /v1/funding/acks?result=FAILED` lists the deposits that the client reported as failed.

## Reconciliation

***

* **Per operation.** The rail tracks each operation by its NUliquid. A lookup by NUliquid reads the local record. If that record does not exist, the lookup asks Núclea. This needs the participant's ISPB and a NUliquid at most 30 days old.
* **Against Núclea.** The reconcile endpoint asks Núclea for an operation's settlement status (**SLC0908**) and records the answer. It moves an operation only from **FORWARDED** to **CONFIRMED**, and it requires a reason.
* **Per clearing cycle.** The rail tracks the clearing position per cycle and reports a bilateral divergence. It flags a D+1 confirmation that also reports a divergence in the settled value.


# What is Lerian SLC?
Source: https://docs.lerian.studio/en/rails/slc/what-is-lerian-slc

Lerian SLC is your client-owned software for operating Núclea's Serviço de Liquidação Centralizada (SLC): what it does, the card roles it serves, and its glossary.

**Lerian SLC** is the client-owned software layer that operates the **Serviço de Liquidação Centralizada (SLC)** for a participant. The SLC is Núclea's centralized card-settlement messaging service. Lerian SLC runs inside the institution's own regulated environment. It signs with the institution's own **ICP-Brasil** certificate. It exchanges the SLC messages and the official **ASLC** files with Núclea (ISPB **29011780**). It submits over REST and receives Núclea's inbound messages over the **RSFN**, Brazil's National Financial System Network.

Lerian SLC submits the settlement operations, builds and signs the ASLC files, and correlates Núclea's returns. Each installation serves one client institution. Lerian SLC is API- and event-first.

## What Lerian SLC does and does not do

***

* Lerian SLC does not post to a ledger and does not require Midaz. It integrates with Lerian SILOC for settlement announcements and command outcomes.
* **Signing goes through a custody backend.** Lerian SLC builds the unsigned payload and delegates signing to a software key, a PKCS#11 HSM, or AWS KMS. In SaaS, Lerian SLC never receives the signing private key in cleartext.

## Who it serves

***

Lerian SLC works with the roles of the Brazilian card arrangement. It submits to Núclea as a credenciadora or a subcredenciadora, and it serves the clearing and funding of the IF Liquidante. The IF Domicílio and the bandeira are counterparties in its participant catalog.

| Role | What it is |
| - | - |
| **Credenciadora** (acquirer) | Captures card transactions from merchants and submits their settlement operations. |
| **Subcredenciadora** (sub-acquirer) | A participant that enables receiving merchants to accept payment instruments but does not act as creditor toward the issuer in settlement. |
| **IF Domicílio** | The domicile financial institution that receives settlement notices and credits the merchant. |
| **IF Liquidante** | The settling financial institution that funds the clearing position for a settlement cycle. |
| **Bandeira** | The card scheme of the arrangement. |

## Glossary

***

| Term | Meaning |
| - | - |
| **Lerian SLC** | Lerian's client-owned software for operating Núclea's centralized card-settlement (SLC) messaging. |
| **SLC** (Serviço de Liquidação Centralizada) | Núclea's centralized settlement service for the Brazilian card arrangement. |
| **ASLC** | The official Núclea XML message layout family used by the SLC (UTF-16BE, XSD-validated). |
| **NUliquid** | Núclea's 21-position settlement identifier (an `AAAAMMDD` date prefix plus a sequence) that tracks the operation after Núclea accepts it. |
| **ISPB** | The BACEN participant identifier; Núclea's SLC destination is 29011780. |
| **RSFN** | Brazil's National Financial System Network, which carries SLC traffic. |
| **ICP-Brasil** | The Brazilian public-key infrastructure whose certificate signs SLC files. |
| **SPB security envelope** | The BACEN payment-system envelope (GZIP plus an RSA/SHA-256 signature and AES-256, with a 588-byte security header) that wraps each file. |
| **Clearing cycle** | The settlement period over which Lerian SLC tracks and reconciles the IF Liquidante's positions. |

For how Lerian SLC sits alongside the other native rails and the partner interfaces, see [Native messaging and partner interfaces](/en/rails/native-messaging). The card-domain deferred-net settlement family reaches Lerian SLC relayed from [Lerian SILOC](/en/rails/siloc/what-is-lerian-siloc), the participant-side SILOC connectivity.


# How Lerian SPB works
Source: https://docs.lerian.studio/en/rails/spb/how-spb-works

The onboarding sequence, the transfer, liquidity and settlement flows, and the asynchronous queries that make up the STR message surface.

Lerian SPB exposes the STR message surface as a set of typed operations. Each flow persists its work before dispatch, returns an accepted-but-not-settled state, and reconciles against BACEN's asynchronous reply.

## Onboarding

***

You rotate the ICP-Brasil certificate, activate it at BACEN with GEN0006, and test connectivity with a GEN0001 echo. Readiness does not wait for the GEN0006 acknowledgement or the GEN0001 echo.

Bank-transfer, return, cancellation, IBS repasse, Conta PI, automatic-transfer, electronic-money, rediscount and compulsory-movement commands check rail readiness before they record anything. `READY` and `DEGRADED` admit commands. `PENDING_CONFIGURATION` and `UNAVAILABLE` block them. Readiness evaluates the channel configuration and the certificate state. The channel configuration needs an explicit participant ISPB and a delivery mode: `WEBHOOK`, `EVENT`, or `BOTH`.

## Bank transfers

***

You declare the typed sender and recipient parties. The platform derives the STR transfer code: STR0004, STR0005, STR0006, STR0007, or STR0008. It persists the operation and the outbound work, and only then dispatches. The rail returns the status `SUBMITTED`. It accepted the request, but BACEN did not settle it yet.

## Returns and cancellations

***

A return and a cancellation are both sub-resources of a parent operation. The parent's id in the request path ties each one to that parent.

* A **return** (STR0010) requires a parent in the state `CONFIRMED`. It gives back the full amount of the original transfer.
* A **cancellation** (STR0011) requires a parent that has not settled: `SUBMITTED`, `SENT`, or `DELIVERED`. When BACEN accepts it, the transfer and the cancellation end `CANCELLED`. If the rail did not dispatch the transfer yet, it cancels the transfer locally and sends no STR0011. The rail refuses a cancellation while a dispatch is unresolved. A transfer that waits for approval stops when an operator denies it.

The rail refuses a request against the wrong parent state.

## IBS repasse

***

An **IBS repasse** (STR0053) transfers IBS settlement values from the reserve account to the managing committee. The rail translates the request to the STR0053 message, persists it, and dispatches it. BACEN confirms it asynchronously.

## Conta PI liquidity

***

Two operations move liquidity between an institution's reserve/settlement account and its Conta PI:

* **Aporte** (LPI0001) funds the Conta PI from the reserve account.
* **Resgate** (LPI0003) recalls funds back to the reserve account.

With the account type `CCME`, the same two directions use LPI0002 and LPI0004 and move only the institution's own funds.

Both return `PENDING`. The inbound settlement reply (LPI0001R1 to LPI0004R1) moves the operation to `SETTLED` or `REJECTED`. Lerian SPB projects the reply value verbatim. GEN0021 operating-window grades are persisted and queryable. They do not impose a generic rejection of every submit outside an operating window. The explicit schedule-related admission rule is RLPI0007: during the additional-aporte window, an aporte to a foreign Conta PI is rejected. Aportes to the institution's own Conta PI and resgates remain allowed.

## Automatic-transfer policy

***

With LPI0005, you declare the STR automatic-transfer rule for both account classes, RB/CL and CCME, in each message: a percentage or a value. A zero turns off automatic transfer for that class, and a new rule replaces the previous one. BACEN acknowledges it (LPI0005R1) and later reports each automatic transfer it performs (LPI0006). Lerian SPB forwards the reported values verbatim and performs no arithmetic on them.

## Approval queue for high-value emissions

***

The rail classifies each declared amount against half-open configured bands and can apply an override for a specific message type. The selected rule determines the state: `requiredSignatures` of `0` sends the emission to `SUBMITTED`. A nonzero value sends it to `PENDING_APPROVAL`. At a band ceiling, the next band applies. Above all ceilings, the top-tier requirement applies.

An operator can sign or deny a queued emission. Each signature comes from a different operator, never the maker. An operator replaces the bands and the per-type overrides through the governance API, and the change applies without a restart.

## Curated message compose

***

A catalog-gated compose surface builds an allowlisted STR message type (STR0004, STR0005, STR0006, STR0007, STR0008, or STR0053). The chosen type must resolve in the capability catalog and be publicly submittable. Otherwise the rail refuses the request.

## Asynchronous single-party queries

***

Reserve-position and schedule reads return a correlation id with `PENDING`. BACEN's reply arrives asynchronously. You read it back by that correlation id. Lerian SPB projects what BACEN sends and computes no position of its own.

| Query | STR code | Returns |
| - | - | - |
| Reserve-account balance | STR0013 | Correlation id + `PENDING`, then the balance BACEN reports |
| Reserve statement (extrato) | STR0014 | Correlation id + `PENDING`, then the statement in message mode |
| STR operating schedule | STR0001 | Correlation id + `PENDING`, then the operating-window grades |

## Electronic money

***

Electronic-money movements (SME) move funds into and out of the conta correspondente a moeda eletrônica (CCME) that an electronic-money issuer holds at BACEN. You declare the kind, and the platform derives the code:

* **Deposit** (SME0001) funds the CCME from the reserve or settlement account.
* **Withdrawal** (SME0002) recalls funds out of the CCME.
* **Return** (SME0004) gives back an entry received in error. It quotes the STR control number of the original entry.

A movement returns `PENDING`. The STR settlement reply moves it to `SETTLED` or `REJECTED`. An SME0003 query returns the CCME statement asynchronously.

## Rediscount

***

A rediscount (RDC) is BACEN lending against federal securities registered at Selic. You declare the kind, and the platform derives the RDC code.

| Kind | RDC codes |
| - | - |
| Contract | RDC0002 intraday, RDC0003 one business day, RDC0004 tied to a Selic purchase, RDC0009 tied to a collateral release, RDC0013 consolidation |
| Payment | RDC0007 in cash, RDC0008 from the sale of the pledged securities |
| Conversion | RDC0005 |
| Cancellation | RDC0014, for a request that Selic still holds |

The operation starts as `PENDING`, before BACEN has answered. `ACCEPTED` means BACEN registered the request, but it is not settled and no settlement fact is emitted. `SETTLED` means a reserve-account entry exists, with a settlement reference.

Two queries return the unit price of an eligible security (RDC0001) and the open rediscounts of the day (RDC0006).

## Compulsory deposits

***

* A **movement** transfers funds between the institution's compulsory deposits at BACEN and its reserve account: a withdrawal (RCO0010) or a deposit (RCO0011). It returns `PENDING`, and BACEN's answer sets its final state.
* A **filing** (RCO0002) declares the compulsory statement for a calculation period. The rail refuses a day outside the declared period. The requirement that BACEN computes arrives on the answer.
* **Queries** return the period calendar (RCO0001), a filing read-back (RCO0003), the movement statement (RCO0005), the compliance position (RCO0006), and the cost ledger (RCO0007).

## BACEN entries

***

The rail records each SLB notice from BACEN and lists the charges still owed.

* An **SLB0002** payment authorizes the payment of a charge. The amount must equal the full charge. The rail refuses a charge that is settled or withdrawn.
* An **SLB0007** payment pays BACEN an amount that no charge demanded, including the return of an SLB0005 credit.
* An **SLB0006** query asks for the entries of a date, for one entry, or for every entry due from today.

When the approval rule for the amount requires signatures, an SLB payment waits in `PENDING_APPROVAL`.

## Clearing-house settlement

***

Lerian SPB settles clearing-house obligations at the STR. The platform derives the participant and clearing-house ISPBs and the movement date.

* **LDL** multilateral settlement: LDL0004 settles the participant's debit net position for a cycle. LDL0006 returns funds transferred in error. LDL0008 funds the settlement of asset events and issues. LDL0011 moves the clearing house's current account into its settlement account. LDL0014 funds a deposit at the clearing house.
* **LDL0022** makes an operational deposit into SILOC in answer to a deposit-required advisory from SILOC. The rail receives advisories only when `LDL_ADVISORY_CONSUMER_ENABLED` is on. One advisory admits one deposit.
* **LTR** gross or bilateral settlement: LTR0003 moves reserves to another institution and has the STR notify the clearing house. LTR0004 settles the participant's negotiation result into the clearing house's account. LTR0006 returns funds transferred in error.

The rail refuses a detail field that the chosen code does not carry, and a control number already used for the same code. The outcome arrives on the R1 reply of each code.

## Inbound notices and roster

***

* The rail records **notices** (GEN0001, GEN0004, GEN0005, GEN0016R2, GEN0017R2) to a queryable notice log.
* **Schedule broadcasts** (GEN0021) update the operating-window grades. A re-announced grade for the same reference date replaces the earlier one.
* A **responsável roster** submission (GEN0019) fully replaces the participant's roster.

For every inbound message family, see [Inbound messaging from BACEN](/en/rails/spb/spb-inbound-messaging).

## Reconciliation and recovery

***

The rail opens a reconciliation case when an operation uses all its dispatch attempts or ends with an uncertain outcome. It also opens one when it quarantines an inbound frame. Operators record `ACKNOWLEDGE`, `RESOLVE`, `DISMISS`, or `INVESTIGATE` actions against a case. A terminal case accepts no more actions. A cross-rail stuck-operations view lists the items that need attention. It exposes only the actions the rail can perform.

* An operator can replay one quarantined inbound frame through the inbound path. The replay sends no notice of its own to BACEN.
* An operator can ask to close as failed an STR0008 that passed its settlement deadline with no BACEN answer. A different operator approves the close. BACEN is not notified.


# Environment variables
Source: https://docs.lerian.studio/en/rails/spb/spb-environment-variables

Deploy-time environment variables for Lerian SPB: runtime, STR/RSFN connectivity, message signing and certificates, persistence, events, and security.

Lerian SPB is Lerian's native messaging integration for the STR (Sistema de Transferência de Reservas), BACEN's real-time gross settlement system, reached over the RSFN. Set these variables at deploy time. A change takes effect only after you restart the service. Most variables are specific to this rail. For the knobs that behave the same way across every Lerian Go service (deployment posture, datastores, and telemetry), see [BYOC configuration essentials](/en/reference/byoc-configuration).

In the tables below, **Required** marks a variable you must set, globally or under the condition named. A qualifier such as *In production* or *If enabled* narrows when the requirement applies. `—` means no default.

> [!NOTE]
>
> `ENV_NAME` arms the stricter security gates. Set it to `production` or `staging` and the service enforces TLS on Redis and the STR connection, and `verify-full` on PostgreSQL. It also requires hardware-backed custody for the key that decrypts inbound messages, and rejects development-only surfaces. `ENV_NAME` has no default. Set it explicitly. The service refuses to start when `ENV_NAME` is unset or holds an unrecognized value.

## Runtime and server

| Variable | Description | Default | Required |
| - | - | - | - |
| `ENV_NAME` | Runtime environment. Must be one of `production`, `staging`, or `develop`. Production and staging arm the security gates described above. | — | Yes |
| `DEPLOYMENT_MODE` | Deployment flavor: `local`, `byoc`, or `saas`. Production and staging refuse to start without it. `saas` also requires `ENV_NAME` `production` or `staging`, TLS on the datastores, upstreams, and broker, and SASL on the broker. | `local` | In production/staging |
| `SERVICE_NAME` | Service identifier used in logs and telemetry. | Service default | No |
| `LOG_LEVEL` | Log verbosity (`debug`, `info`, `warn`, `error`). | `info` | No |
| `SERVER_PORT` | HTTP listen port. The liveness, readiness, and systemplane surfaces bind this same port. | `3000` | No |
| `CORS_ALLOWED_ORIGINS` | Comma-separated allowed CORS origins. In production/staging, only `https://` origins are accepted and localhost origins are rejected. | `http://localhost:3000` | No |
| `TRUSTED_PROXIES` | Comma-separated proxy IPs/CIDRs trusted to set the real client IP. | — | No |

## Authentication

Lerian SPB delegates authorization, including the systemplane admin API, to Access Manager. See [BYOC configuration essentials](/en/reference/byoc-configuration#plugin-authentication).

| Variable | Description | Default | Required |
| - | - | - | - |
| `PLUGIN_AUTH_ENABLED` | Require Access Manager authentication on protected routes. Set it to `true` or `false`; the service refuses to start when it is unset. `false` is accepted only with `ENV_NAME=develop` and a `DEPLOYMENT_MODE` other than `saas`. | — | Yes |
| `PLUGIN_AUTH_ADDRESS` | Access Manager service address. Must be an `https://` URL in production/staging. | `http://localhost:4000` | In production/staging |

## PostgreSQL

| Variable | Description | Default | Required |
| - | - | - | - |
| `POSTGRES_HOST` | Primary PostgreSQL host. Must not be `localhost` in production/staging. | `localhost` | In production/staging |
| `POSTGRES_PORT` | Primary PostgreSQL port. | `5432` | No |
| `POSTGRES_USER` | Database user. | `postgres` | No |
| `POSTGRES_PASSWORD` | Database password. Sensitive. Inject it at deploy time and never commit it. Must not be `postgres` in production/staging. | `postgres` | In production/staging |
| `POSTGRES_DB` | Database name. | Service default | No |
| `POSTGRES_SSLMODE` | libpq TLS mode. Must be `verify-full` in production/staging. | `require` | No |
| `POSTGRES_MAX_OPEN_CONNS` | Maximum open connections. | `25` | No |
| `POSTGRES_MAX_IDLE_CONNS` | Maximum idle connections. | `10` | No |
| `POSTGRES_CONN_MAX_LIFETIME` | Connection max lifetime (Go duration, e.g. `5m`). | `5m` | No |
| `POSTGRES_CONN_MAX_IDLE_TIME` | Connection max idle time (Go duration). | `2m` | No |

### PostgreSQL replica

Optional read replica. All fields fall back to the primary when unset.

| Variable | Description | Default | Required |
| - | - | - | - |
| `POSTGRES_REPLICA_HOST` | Replica host. Unset = no replica. | — | No |
| `POSTGRES_REPLICA_PORT` | Replica port. | — | No |
| `POSTGRES_REPLICA_USER` | Replica user. | — | No |
| `POSTGRES_REPLICA_PASSWORD` | Replica password. Sensitive. | — | No |
| `POSTGRES_REPLICA_DB` | Replica database name. | — | No |
| `POSTGRES_REPLICA_SSLMODE` | Replica TLS mode. Must be `verify-full` in production/staging when a replica is set. | — | No |

## Redis

| Variable | Description | Default | Required |
| - | - | - | - |
| `REDIS_HOST` | Redis host. Must be explicit and non-local in production/staging. | `localhost` | In production/staging |
| `REDIS_PORT` | Redis port. | `6379` | No |
| `REDIS_PASSWORD` | Redis password. Sensitive. | — | In production/staging |
| `REDIS_DB` | Redis database number. | `0` | No |
| `REDIS_TLS_ENABLED` | Enable TLS to Redis. Must be `true` in production/staging. | `false` | In production/staging |
| `REDIS_TLS_CA_CERT_BASE64` | Base64-encoded CA certificate for Redis TLS. | — | In production/staging |
| `REDIS_POOL_SIZE` | Connection pool size. | `20` | No |
| `REDIS_MIN_IDLE_CONNS` | Minimum idle connections. | `5` | No |

## STR connectivity (RSFN)

Lerian SPB exchanges STR messages with BACEN over the RSFN using an IBM MQ transport. These variables define the participant identity, the queue-manager connection, and the queues. The three queue names derive from `STR_ISPB`. Production and staging refuse a queue name that differs from the derived name.

| Variable | Description | Default | Required |
| - | - | - | - |
| `STR_ISPB` | The participant's 8-digit ISPB. In production/staging it must be an explicit real ISPB, not `00000000`. | `00000000` | In production/staging |
| `SILOC_ISPB` | The SILOC câmara's 8-digit ISPB, resolved server-side into SILOC-related settlement messages (never client-supplied). In production/staging it must be an 8-digit câmara ISPB other than `00000000`. | `02992335` | No |
| `STR_MQ_HOST` | Queue-manager host. | — | Yes (live STR) |
| `STR_MQ_PORT` | Queue-manager listener port. | `1414` | No |
| `STR_MQ_CHANNEL` | MQ server-connection channel. | `DEV.APP.SVRCONN` | No |
| `STR_MQ_QUEUE_MGR` | Queue-manager name. | `QM1` | No |
| `STR_MQ_USER` | MQ connection user. | `app` | No |
| `STR_MQ_PASSWORD` | MQ connection password. Sensitive. | — | In production/staging |
| `STR_MQ_TLS_ENABLED` | Enable mutual TLS on the MQ channel. Required for a real STR connection. | `false` | In production/staging |
| `MQSSLKEYR` | Path stem of the GSKit key repository backing MQ TLS. The private key lives here, never in an environment variable. | — | In production/staging |
| `STR_MQ_SEND_QUEUE` | Outbound request queue. Derived from `STR_ISPB` when unset. | Derived | No |
| `STR_MQ_RESPONSE_QUEUE` | Response queue. Derived from `STR_ISPB` when unset. | Derived | No |
| `STR_MQ_RECEIVE_QUEUE` | Inbound receive queue. Derived from `STR_ISPB` when unset. | Derived | No |
| `MQ_HEARTBEAT_INTERVAL` | MQ heartbeat interval that the service sets on the channel (Go duration). | `300s` | No |
| `MQ_DISCONNECT_INTERVAL` | Disconnect interval expected on the queue manager (Go duration). The service logs it at connect and does not set it. | `6000s` | No |
| `MQ_SEQ_WRAP` | Message-sequence wrap ceiling expected on the queue-manager channel. The service logs it and does not set it. | `99999999` | No |
| `MQ_ADOPTNEWMCA` | `AdoptNewMCA` setting expected on the queue manager. The service logs it and does not set it. | `ALL` | No |

### Circuit breaker

Guards the STR transport against a failing queue manager.

| Variable | Description | Default | Required |
| - | - | - | - |
| `CB_MAX_REQUESTS` | Requests allowed through while the breaker is half-open. | `3` | No |
| `CB_INTERVAL` | Rolling window over which failures are counted (Go duration). | `30s` | No |
| `CB_TIMEOUT` | Open-state recovery timeout (Go duration). | `10s` | No |
| `CB_CONSECUTIVE_FAILURES` | Consecutive failures before the breaker trips. | `5` | No |
| `CB_FAILURE_RATIO` | Failure ratio that trips the breaker (0–1). | `0.5` | No |
| `CB_MIN_REQUESTS` | Minimum requests in a window before the failure ratio can trip the breaker. | `10` | No |

## Message signing and certificates

Lerian SPB signs every outbound STR message with the certificate at `CERT_PATH` and its key at `KEY_PATH`. The signing identity's metadata file under `CERT_BASE_PATH` can move that key to a PKCS#11 or KMIP HSM. `SPB_SIGNER_KIND` chooses the custody backend of a different key: the key that decrypts inbound messages. Production and staging reject the `file` backend for that key and require `pkcs11` or `kmip`.

| Variable | Description | Default | Required |
| - | - | - | - |
| `SPB_SIGNER_KIND` | Custody backend of the inbound-decryption key: `file`, `pkcs11`, or `kmip`. `file` is permitted only when `ENV_NAME=develop`; production and staging reject it. The service refuses `hsm` and `kms`. | `file` | No |
| `CERT_BASE_PATH` | Base directory for the signing identity's certificate material and metadata file. | `/certs` | No |
| `CERT_PATH` | Path to the signing certificate. | — | In production/staging |
| `KEY_PATH` | Path to the signing private key. | — | In production/staging |
| `PROCESS_CERT_PATH` | Path to the certificate of the inbound-decryption key. | — | In production/staging |
| `PROCESS_PRIVATE_KEY_PATH` | Path to the inbound-decryption private key when `SPB_SIGNER_KIND=file`. Sensitive. | — | No |
| `BACEN_PUBLIC_CERT_PATH` | Path to BACEN's public certificate, used to verify inbound signatures and for SFN encryption. | — | In production/staging |
| `CERT_READINESS_MIN_DAYS` | Minimum days-to-expiry. `/readyz` fails a certificate that expires sooner. | `30` | No |

### PKCS#11 custody

Required when `SPB_SIGNER_KIND=pkcs11`.

| Variable | Description | Default | Required |
| - | - | - | - |
| `SPB_PKCS11_MODULE_PATH` | Path to the PKCS#11 module library. | — | If `pkcs11` |
| `SPB_PKCS11_TOKEN_LABEL` | PKCS#11 token label. | — | If `pkcs11` |
| `SPB_PKCS11_PIN_FILE` | Path to a file holding the token PIN. Sensitive. | — | If `pkcs11` |
| `SPB_PKCS11_KEY_LABEL` | Label of the signing key on the token. | — | If `pkcs11` |

### KMIP custody

Required when `SPB_SIGNER_KIND=kmip` (KMIP-over-HTTP to a network HSM).

| Variable | Description | Default | Required |
| - | - | - | - |
| `SPB_KMIP_BASE_URL` | KMIP service base URL. | — | If `kmip` |
| `SPB_KMIP_VHSM` | Virtual HSM identifier. | — | If `kmip` |
| `SPB_KMIP_CRYPTO_USER` | KMIP crypto user. | — | If `kmip` |
| `SPB_KMIP_CRYPTO_USER_TOKEN` | KMIP crypto-user token. Sensitive. | — | If `kmip` |
| `SPB_KMIP_SIGN_PRIVATE_KEY_UID` | UID of the signing private key. | — | If `kmip` |
| `SPB_KMIP_SIGN_PUBLIC_KEY_UID` | UID of the signing public key. | — | If `kmip` |
| `SPB_KMIP_DECRYPT_KEY_UID` | UID of the decryption key used on the inbound decrypt path. Unset, the service uses `SPB_KMIP_SIGN_PRIVATE_KEY_UID`. | — | No |
| `SPB_KMIP_DIGEST_INFO_PREFIX` | Prepend the ASN.1 DigestInfo prefix before the KMIP sign call. | `false` | No |

### Signing identity metadata file

Lerian SPB reads an optional `metadata.json` file directly under `CERT_BASE_PATH`. Without this file, the service reads the signing key from `KEY_PATH`. The `signerKind` field sets where the signing key is kept:

* `file` or no value: the key file at `KEY_PATH`.
* `pkcs11`: a key on a PKCS#11 token, set in the `pkcs11` block.
* `kmip`: a key in a KMIP network HSM, set in the `kmip` block.

With `pkcs11` or `kmip`, the signing key stays in the HSM, and the signer reads only the certificate from `CERT_PATH`. The public key of the certificate must match the HSM key. Production and staging still require `KEY_PATH` to be set. The service rejects other `signerKind` values. It also rejects `pkcs11` or `kmip` without the matching block.

```json theme={null}
{
  "signerKind": "pkcs11",
  "pkcs11": {
    "modulePath": "/usr/lib/pkcs11/module.so",
    "tokenLabel": "spb",
    "pinFile": "/certs/token.pin",
    "keyLabel": "spb-signing"
  }
}
```

| Block | Field | Description | Required |
| - | - | - | - |
| `pkcs11` | `modulePath` | Path to the PKCS#11 module library. | Yes |
| `pkcs11` | `tokenLabel` | PKCS#11 token label. | Yes |
| `pkcs11` | `pinFile` | Path to a file holding the token PIN. Sensitive. | Yes |
| `pkcs11` | `keyLabel` | Label of the signing key on the token. | Yes |
| `kmip` | `baseUrl` | KMIP service base URL. | Yes |
| `kmip` | `vhsm` | Virtual HSM identifier. | Yes |
| `kmip` | `cryptoUser` | KMIP crypto user. | Yes |
| `kmip` | `cryptoUserToken` | KMIP crypto-user token. Sensitive. | Yes |
| `kmip` | `signPrivateKeyUid` | UID of the signing private key. | Yes |
| `kmip` | `signPublicKeyUid` | UID of the signing public key. | Yes |
| `kmip` | `digestInfoPrefix` | Boolean. Prepend the ASN.1 DigestInfo prefix before the KMIP sign call. Default `false`. | No |

## Events and outbox

Lerian SPB records every message before dispatch and publishes lifecycle events through a transactional outbox to the streaming broker. Streaming has no disabled mode. Configure the shared `STREAMING_*` settings as described in [Streaming and outbox](/en/reference/byoc-configuration#streaming-and-outbox).

| Variable | Description | Default | Required |
| - | - | - | - |
| `STREAMING_BROKERS` | Broker addresses for event publication. The service refuses to start when the value is absent or invalid. | — | Yes |
| `STREAMING_CLOUDEVENTS_SOURCE` | CloudEvents source identity. Must be exactly `br-spb`. A different value prevents startup; the service derives its broker topics from it. | — | Yes |
| `EMISSION_REQUIRED` | When `true`, bootstrap fails closed unless event emission is fully wired. | `false` | No |
| `OUTBOX_DISPATCH_INTERVAL` | Interval between outbox dispatch cycles (Go duration). | `2s` | No |
| `OUTBOX_BATCH_SIZE` | Rows drained per dispatch cycle. | `50` | No |
| `OUTBOX_MAX_PUBLISH_ATTEMPTS` | Total dispatch attempts for an outbox row, across dispatch cycles, before the service stops retrying it. Webhook delivery exhaustion is governed separately by `EVENT_DELIVERY_MAX_ATTEMPTS`. | `3` | No |
| `OUTBOX_POSTGRES_MAX_OPEN_CONNS` | Max open connections for the outbox pool. | `10` | No |
| `OUTBOX_POSTGRES_MAX_IDLE_CONNS` | Max idle connections for the outbox pool. | `5` | No |
| `EVENT_DELIVERY_BATCH_SIZE` | Events delivered per cycle. | `25` | No |
| `EVENT_DELIVERY_MAX_ATTEMPTS` | Webhook delivery attempts before the delivery is marked `EXHAUSTED`. | `3` | No |
| `EVENT_DELIVERY_RETRY_BACKOFF` | Delay between webhook delivery retries (Go duration). | `30s` | No |
| `DISPATCH_MAX_AUTO_ATTEMPTS` | Automatic dispatch attempts before manual intervention. | `8` | No |
| `DISPATCH_RETRY_BACKOFF_CEILING` | Maximum backoff between dispatch retries (Go duration). | `30m` | No |
| `LDL_ADVISORY_CONSUMER_ENABLED` | Enable the supervised consumer of SILOC OT-settlement advisory facts. It requires `STREAMING_BROKERS` and durable persistence when enabled, and refuses to start without them. The consumer topic and group are fixed in the service; neither is configurable through the environment. The broker connection comes from the shared `STREAMING_*` settings (see [Streaming and outbox](/en/reference/byoc-configuration#streaming-and-outbox)). Disabled, its readiness check reports `skipped`. | `false` | No |

## Approval (maker-checker)

Optional value-band approval that gates STR emission. Off by default. An empty band table lets every emission proceed single-step.

| Variable | Description | Default | Required |
| - | - | - | - |
| `APPROVAL_ALCADA_BANDS` | Initial band table: semicolon-separated `maxExclusive:requiredSignatures` bands (e.g. `10000.00:1;100000.00:2`). Empty keeps approval off until an operator sets bands through the governance API. | — | No |
| `APPROVAL_DEADLINE_WINDOW` | How long a parked emission may wait (Go duration, capped at 7 days). | `24h` | No |
| `APPROVAL_EXPIRY_ENABLED` | Run the background sweep that expires overdue parked emissions. | `true` | No |
| `APPROVAL_EXPIRY_SWEEP_INTERVAL` | Sweep interval (Go duration). | `1m` | No |

## Rate limiting and idempotency

| Variable | Description | Default | Required |
| - | - | - | - |
| `RATE_LIMIT_IP_MAX` | Max requests per IP per window. | `300` | No |
| `RATE_LIMIT_IP_WINDOW` | Per-IP rate-limit window (Go duration). | `1m` | No |
| `RATE_LIMIT_KEY_MAX` | Max requests per API key per window. | `100` | No |
| `RATE_LIMIT_KEY_WINDOW` | Per-key rate-limit window (Go duration). | `1m` | No |
| `IDEMPOTENCY_ENABLED` | Enable idempotency-key deduplication. Production and staging refuse `false`. | `true` | No |
| `IDEMPOTENCY_DEFAULT_TTL_SEC` | How long (seconds) an idempotency key is retained. | `86400` | No |

## Systemplane and runtime configuration

Lerian SPB mounts the systemplane runtime-configuration admin API at `/v1/system` on the main port. PostgreSQL backs this plane, so operators can read and change hot-reloadable settings without a restart. See [Systemplane](/en/reference/platform/systemplane/overview) for the API, namespaces, and permissions.

The CORS origins, the four rate-limit values, the three outbox dispatch values, and the approval bands are hot-reloadable. For these settings, the variable sets the initial value, and a value stored in Systemplane takes precedence.

## Encryption and secrets

| Variable | Description | Default | Required |
| - | - | - | - |
| `STR_PAYLOAD_ENCRYPTION_KEY` | Base64-encoded AES-256 key for at-rest encryption of stored STR payloads. Sensitive. Required in production/staging. | — | In production/staging |
| `WEBHOOK_SECRET_KEY` | Key used to encrypt stored webhook secrets, as 64 hexadecimal characters. Sensitive. Required in production/staging. | — | In production/staging |
| `INBOUND_ALLOW_CLEARTEXT_FALLBACK` | Allow the inbound path to accept unencrypted payloads. Production and staging refuse `true`. | `false` | No |

> [!WARNING]
>
> Never commit or log the values of any variable marked *Sensitive* (passwords, tokens, PINs, and AES keys). Inject them at deploy time through your secret manager.

## Observability

| Variable | Description | Default | Required |
| - | - | - | - |
| `ENABLE_TELEMETRY` | Enable OpenTelemetry tracing and metrics. | `false` | In production/staging |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector endpoint. Must use `https://` in production/staging. | `http://localhost:4318` | If telemetry enabled |
| `METRICS_PROMETHEUS_ENABLED` | Expose a dedicated Prometheus scrape endpoint. | `false` | No |
| `METRICS_PROMETHEUS_ADDRESS` | Listen address for the Prometheus endpoint. Binds loopback by default. | `127.0.0.1:9090` | No |

## Development-only

> [!WARNING]
>
> Keep these variables unset outside local development. They expand the attack surface, and production or staging rejects or forces them off.

| Variable | Description | Default | Required |
| - | - | - | - |
| `ENABLE_DEV_DEBUG_ROUTES` | Expose debug routes. Forbidden in production/staging. | `false` | No |
| `DEV_DEBUG_TOKEN` | Token guarding the debug routes. Sensitive. Required when debug routes are enabled. | — | If debug enabled |
| `SWAGGER_ENABLED` | Serve the OpenAPI spec and API docs UI. Forced off in production and staging. | `false` | No |
| `STR_MQ_MOCK` | Route the STR transport to a mock instead of a live queue manager. | `false` | No |
| `STR_MQ_MOCK_HOST` | Mock STR host. Required when `STR_MQ_MOCK=true`. | `http://localhost:8080` | If mock enabled |
| `STR_MQ_MOCK_ALLOWED_HOSTS` | Allow-list of hosts the mock transport may reach. | — | No |
| `ALLOW_MOCK_TRANSPORT` | Let the service start in `develop` without BACEN's public certificate and the inbound-decryption key. Refused outside `develop` and with a real `STR_MQ_HOST`. | `false` | No |

## Health and readiness

Lerian SPB exposes `GET /health` (liveness) and `GET /readyz` (readiness) on the main HTTP port. See [Health and readiness](/en/reference/health-and-readiness) for the probe contract.


# Inbound messaging from BACEN
Source: https://docs.lerian.studio/en/rails/spb/spb-inbound-messaging

How Lerian SPB consumes the inbound STR settlement replies (R-legs), the credits it did not start, and the notices that arrive from BACEN over the RSFN.

Lerian SPB consumes the inbound STR settlement replies (R-legs) and the notices that arrive from BACEN over the RSFN. A settled status on the R-leg moves the transfer's STR message to `CONFIRMED`, and a rejected status moves it to `REJECTED`. A pending status keeps the transfer open, because the STR still holds the entry. When BACEN accepts your STR0011, the transfer moves to `CANCELLED`. A cancelled status that answers no STR0011 of yours, or a status outside BACEN's domain, opens a reconciliation case.

Conta PI, electronic-money, rediscount and compulsory-deposit movements report a settled reply as `SETTLED`. Lerian SPB projects BACEN's settlement fields verbatim.

An STR transfer credit (an R2 or R3 reply) that matches no transfer the rail sent is a credit that another institution started. The rail records it as an inbound operation and publishes `str.operation.received` for your ledger to record.

For each inbound notice other than an electronic-money advice, the rail publishes `str.message.received`. Some notices also change rail state and publish a dedicated event.

| Inbound message | What the rail does | Dedicated event |
| - | - | - |
| GEN0001 | Answers the echo and records the notice | — |
| GEN0004 | Records the transmission error | `str.transmission.errorReceived` |
| GEN0005 | Records the administrative notice | `str.admin.noticeReceived` |
| GEN0007, GEN0018, GEN0022 | Updates the counterparty certificate state | `str.certificate.counterpartyChanged` |
| GEN0021 | Updates the operating-window grades | `str.schedule.changed` |
| STR0015, STR0017 | Reports the STR closing and opening | `str.readiness.changed` |
| STR0016 | Reports the closing balance and the additional-aporte window | `str.balance.closingReported` |
| STR0018, STR0019 | Reports a participant that BACEN excluded, included, or changed | `str.participant.directoryChanged` |
| LPI0006 | Reports an automatic transfer | `str.autoTransfer.reported` |
| RCO0014 | Reports a recalculated compulsory requirement | `str.compulsory.requirementRecalculated` |
| RCO0019 | Reports a compulsory deposit that a third party made | `str.compulsory.depositAdvised` |
| SLB0001, SLB0003, SLB0005, SLB0008 | Records the charge, the withdrawn charge, the credit, or the direct debit | `str.slb.entryNotified` |
| RDC0015, RDC0016 | Converts or cancels the open rediscounts at STR close | — |
| SME0001R2, SME0002R2, SME0004R2 | Records the electronic-money advice | `str.emoney.transferAdvised` |

The rail quarantines an inbound frame that it cannot turn into a message, and opens a reconciliation case for it.

The `str.emoney.transferAdvised` event's `data` object always includes `messageCode`, `numCtrlSTR`, `dtHrBC`, `vlrLanc`, and `dtMovto`. Depending on the advice leg, it can also include `debitedIspb`, `creditedIspb`, `numCtrlSTROr`, `hist`, `ispbIFCredtd`, `agCredtd`, and `ctCredtd`. The event does not expose `CNPJCliCredtd`. Deduplicate this event by `(eventType, data.numCtrlSTR)`, not by `ce-id`: a retry can produce a fresh `ce-id`, while the same control number identifies the same movement.


# What is Lerian SPB?
Source: https://docs.lerian.studio/en/rails/spb/what-is-lerian-spb

Lerian SPB is your direct, non-intermediated BACEN STR connector for TED-family interbank transfers and reserve-account operations over the RSFN network.

**Lerian SPB** is Lerian's own messaging connector to the **STR** (Sistema de Transferência de Reservas). The STR is the real-time gross-settlement core of the Brazilian payment system. Lerian SPB reaches the STR over the **RSFN**. The RSFN is the private national network that carries payment-system messages between participants and the Central Bank of Brazil (BACEN).

Lerian SPB gives a participant institution a direct path to BACEN. The institution sends and settles interbank and large-value wire transfers, the TED family. It also runs reserve-account operations against BACEN's settlement system. No connectivity partner sits between the institution and BACEN.

## Who it serves

***

Lerian SPB serves financial institutions that hold their own reserve and settlement account at BACEN. These institutions send TED-family transfers through the STR. They move liquidity between their reserve account and their liquidity account (Conta PI). They also query their reserve position directly through the STR. The same connector carries rediscount, compulsory-deposit, BACEN-entry, clearing-house settlement, and electronic-money messages.

## An operation-centric API

***

You declare the typed roles of the parties to an operation. You name who debits, who credits, and whether each side is an institution or a client. The platform then derives the correct STR message code for you.

| Declared parties | STR code | Movement |
| - | - | - |
| Institution to institution | STR0004 | Interbank transfer between two account-holding participants |
| Non-account-holders | STR0005 | Transfer between two parties that hold no account at either institution |
| Client to institution | STR0006 | A client sends to an institution |
| Institution to client | STR0007 | An institution sends to a client |
| Client to client | STR0008 | Transfer between two clients across institutions |

## Settlement is asynchronous

***

The STR is a real-time gross-settlement system. Every operation settles individually against reserve balances.

BACEN confirms asynchronously through a settlement reply, called the R-leg. It carries BACEN's settlement fields, for example `numCtrlSTR` and `sitLancSTR`, projected verbatim.

## Money-neutrality

***

Lerian SPB is money-neutral. It forwards the amounts you declare exactly as declared and computes no balance or position of its own. The rail carries the message and settlement state. Your ledger consumer records the money movement.

## Glossary

***

| Term | Meaning |
| - | - |
| **STR** (Sistema de Transferência de Reservas) | BACEN's real-time gross-settlement (RTGS) system, where each operation settles individually. |
| **SPB** (Sistema de Pagamentos Brasileiro) | The Brazilian payment system that the STR is the settlement core of. |
| **RSFN** | The private national financial-system network that carries SPB messages between participants and BACEN. |
| **TED** | An electronic wire transfer settled through the STR. |
| **NUOp** | 23-character BACEN operation identifier (ISPB + date + sequence) that correlates a submitted message with its reply. |
| **ISPB** | 8-character alphanumeric BACEN code identifying a payment-system participant institution. |
| **Conta PI / reserve-settlement account** | The accounts an institution holds at BACEN for settlement and liquidity. |
| **ICP-Brasil certificate** | The digital certificate used to sign outbound SPB messages. |
| **Settlement confirmation (R-leg)** | The asynchronous BACEN reply that updates an STR message from BACEN's settlement status. |
| **STR / LPI / GEN codes** | Official BACEN protocol identifiers for each STR and SPB message type (for example STR0004, LPI0001, GEN0006). |

For how Lerian SPB sits alongside the other native rails and the partner interfaces, see [Native messaging and partner interfaces](/en/rails/native-messaging).


# How Lerian SPI works
Source: https://docs.lerian.studio/en/rails/spi/how-spi-works

How Lerian SPI works: Pix onboarding, send and receive flows (pacs.008 and pacs.002), returns, DICT keys and claims, BR Code charges, Pix Automático, and MED.

Lerian SPI exposes the Pix message surface as a set of typed operations.

## Onboarding and readiness

***

You register an indirect participant by its ISPB. It enters `PENDING`, and the rail sends its registration request. Only BACEN's confirmation makes it `ACTIVE`. A BACEN refusal makes it `REGISTRATION_REJECTED`. The activation action only reactivates a `SUSPENDED` participant. The recommended preparation order before you submit payments is:

1. **Upload** a Pix certificate, the public `.cer` only. The rail rejects an uploaded private key.
2. Confirm the rail reports **ready**.
3. Pass a **connectivity test**.
4. Submit payments.

The same Core surface also suspends and offboards a participant over its lifecycle.

## Send a Pix

***

You create a payment order. The platform builds the ISO 20022 credit-transfer message (`pacs.008`), persists the operation, and dispatches it. BACEN returns an asynchronous status reply (`pacs.002`). The rail validates and applies it, then moves the payment to `COMPLETED` or `REJECTED`. You read a payment back by its end-to-end ID, with its history and a per-operation timeline.

## Receive a Pix

***

The ICOM consumer receives signed BACEN messages and passes them to the rail's authenticated internal ingress. For an inbound `pacs.008`, the rail validates the message and records the Pix as `PENDING`. Your client then decides that Pix in one of three ways. It sends funding evidence (available balance, available limit, risk score) for the rail to assess, it states that it already authorized the credit, or it sends a refusal reason.

The rail answers an accepted Pix to the SPI, and the Pix reaches `COMPLETED` only when the SPI confirms the credit, or `REJECTED` if the SPI refuses it. The rail refuses a Pix that no decision concludes within its regulatory window, and a later decision gets `409`. An outbound payment cannot receive funding as incoming money. You list the Pix you receive, and the Pix still waiting for a decision.

## Return (devolução)

***

You initiate a return (`pacs.004`) only for a settled Pix that the rail received from BACEN, then read the return's status. The return debits the original recipient and credits the original payer. You cannot initiate a return for a Pix your client sent. The counterparty issues a return of that Pix, and it reaches the rail as an inbound message. A return is the MED money-movement path, the way funds flow back to a payer for a completed dispute or error.

Two return surfaces exist, and the rail records which one created a return rather than inferring it later. A **full** return reverses the whole Pix and moves the parent payment out of `COMPLETED`. A **partial** return uses the `devolucaoId` you choose as its key and never moves the parent payment. Several partial returns can coexist for one Pix.

Three gates apply to every return, on both surfaces:

* **The parent must be an inbound Pix that settled.** Only a received payment that reached `COMPLETED` (or that already carries a return) can be returned.
* **BACEN's return window.** A return must be requested within 90 days of the original Pix settlement. The rail measures the window from the settlement instant, never from creation or from the last update. A Pix with no recorded settlement instant is not blocked: the rail logs the gap and forwards the request.
* **The sum ceiling.** The values of all returns of one Pix may not exceed that Pix's own value. The rail reads only that payment's amount and its own returns. It computes no position across payments.

A transport acceptance is not a conclusion.

A partial return takes the nature `ORIGINAL` (the default when you send none) or `RETIRADA`, the Pix Saque and troco leg. A full return takes a reason: `MD06`, `SL02`, `BE08`, or `FR01`. The two MED natures (operational failure and founded fraud suspicion) follow from `BE08` and `FR01`. You never request them as a nature.

## DICT key lifecycle

***

You manage Pix keys directly against the DICT directory: register, list, search, look up, update, and delete a key. You also batch-check whether a set of keys exists. The rail reads DICT key statistics and BACEN antifraud statistics, both per key and per person.

## DICT claims (reivindicação)

***

A claim moves a Pix key between participants for portability or ownership. You initiate a claim against a participant, then move it through its lifecycle. The lifecycle covers acknowledge, confirm or reject, and complete or cancel, across the donor and claimer sides. The claim-deadline job runs by default and advances claims against their BACEN windows. A claim can still require attention.

## BR Code and charges

***

A dynamic QR resolves to a persisted charge, so you create the charge first, then generate the payload that resolves to it. A static QR is generated from static payment input. It neither requires nor points to a charge.

* Create a charge: **Cob** (immediate), **CobV** (due-date, with interest and fine), or a **batch** of due-date charges.
* Generate the **dynamic EMV QR** payload, which links to the charge by its txid or locator and resolves as a signed JWS.

You also generate a static QR, decode a payload, validate it, and register a receiver profile (recebedor).

## Pix Automático (recurring)

***

Pix Automático authorizes recurring and scheduled payments through the ISO 20022 recurring family:

* **Create** a recurring authorization (recorrência) or a request for one.
* **Request confirmation** of the mandate (`pain.009`), **cancel** it (`pain.011`), or **accept / reject** it (`pain.012`).
* **Schedule** an instruction (`pain.013`) and **accept / reject** it (`pain.014`).
* **Request cancellation** of a scheduled instruction (`camt.055`) and **resolve** a received cancellation (`camt.029`).
* **Request a settlement retry** (retentativa) when a scheduled charge misses.

## MED disputes

***

You handle MED (Mecanismo Especial de Devolução) fraud and error cases in DICT, and report internal settlements on SPI:

* File DICT **refund requests**, **fraud markers**, and **funds-recovery** requests. A funds recovery is tracked through its lifecycle graph.
* Read, acknowledge, cancel, close, and refresh DICT **infraction reports**.
* Report internally-settled Pix through the MED 2.0 settlement report.

## Conta PI reporting

***

You request an account report (`camt.060`) for the balance (`camt.053`), the statement (`camt.052`), or the entry detail (`camt.054`). You read the balance and the statement back through the API. Synchronous reports round out the reporting surface: a count-only volumetria, a rejected-payments count with a paginated list, and balance and extract listings. Each report window spans at most 92 days.


# Environment variables
Source: https://docs.lerian.studio/en/rails/spi/spi-environment-variables

Deploy-time environment variables for Lerian SPI: BACEN SPI/DICT connectivity, ISO 20022 signing certificates, PII encryption, persistence, and streaming.

Lerian SPI is Lerian's native messaging integration for Pix. It reaches BACEN's instant-payment system (SPI) and the DICT key directory over the RSFN. It ships four runtime binaries (`spi`, `dict`, `brcode`, and `core`), so its variable set is broad.

The service reads every variable at startup. When systemplane is on (the default), it can override a subset at runtime without a restart. The rest of the variables need a restart to change. For the knobs that behave the same across every Lerian Go service (deployment posture, datastores, telemetry, streaming), see [BYOC configuration essentials](/en/reference/byoc-configuration).

In the tables below, **Required** marks a variable you must set, always (**Yes**) or under the condition named. `—` means no default. The conditions use three terms:

* **Live**: the BACEN endpoint uses `https`. A local environment also accepts an `http` endpoint.
* **Local environment**: `ENV_NAME` is `development`, `local`, or `test`.
* **Protected environment**: `ENV_NAME` is `production`, `prod`, `staging`, `stage`, `pre-prod`, `preprod`, `pre-production`, or `preproduction`.

> [!NOTE]
>
> Most BACEN-facing variables carry a surface prefix: `BACEN_SPI_*` for the SPI settlement transport, `BACEN_DICT_*` for the DICT client, `BACEN_BRCODE_JOSE_*` for BR Code JOSE signing, and `BACEN_ICOM_*` for the inbound long-poll channel.

## Runtime and server

| Variable | Description | Default | Required |
| - | - | - | - |
| `ENV_NAME` | Runtime environment label. When unset, it resolves to `development`. An explicit `none` is invalid. | `development` | No |
| `LOG_LEVEL` | Log verbosity (`debug`, `info`, `warn`, `error`). | `info` | No |
| `SERVER_ADDRESS` | Main HTTP listen address (`host:port` or `:port`). Liveness, readiness, and systemplane bind this port. | `:8080` | No |
| `HTTP_BODY_LIMIT_BYTES` | Maximum request body size in bytes. | `1048576` | No |
| `PUBLIC_BASE_URL` | Externally reachable base URL of the service. It builds the BR Code payload links and the URL of the JWS key set. | — | In a protected environment or if BR Code JOSE is enabled |
| `ACCESS_CONTROL_ALLOW_ORIGIN` | Allowed CORS origins. A protected environment refuses a wildcard. | `http://localhost:3000` | No |
| `ACCESS_CONTROL_ALLOW_METHODS` | Allowed CORS methods. | `GET,POST,PUT,PATCH,DELETE,OPTIONS` | No |
| `ACCESS_CONTROL_ALLOW_HEADERS` | Allowed CORS request headers. | (standard set) | No |
| `TRUSTED_PROXIES` | Comma-separated proxy IPs or CIDRs trusted to set the real client IP. Wildcards are refused. | — | In a protected environment with `TLS_TERMINATED_UPSTREAM=true` |
| `SERVER_TLS_CERT_FILE` | Path to the server TLS certificate. Set together with the key file. | — | No |
| `SERVER_TLS_KEY_FILE` | Path to the server TLS private key. Sensitive. | — | No |
| `SERVER_TLS_CLIENT_CA_FILE` | CA file for verifying client certificates (mutual TLS). Requires the certificate and key files. | — | No |
| `TLS_TERMINATED_UPSTREAM` | Set `true` when TLS is terminated by a load balancer or reverse proxy. | `false` | No |

A protected environment requires the server certificate and key files, or `TLS_TERMINATED_UPSTREAM=true`.

## Authentication

Lerian SPI authorizes protected routes, including the systemplane admin API, through Access Manager.

| Variable | Description | Default | Required |
| - | - | - | - |
| `AUTH_ENABLED` | Require Access Manager authentication on protected routes. Set `true` or `false`. A blank value stops startup. `false` starts only when `ENV_NAME` is `development`, `develop`, `dev`, `local`, or `test`, and never with `DEPLOYMENT_MODE=saas`. | — | Yes |
| `PLUGIN_AUTH_ADDRESS` | Access Manager service address. A protected environment requires `https://`. | — | If `AUTH_ENABLED=true` or in a protected environment |

## BACEN callback (inbound from SPI)

| Variable | Description | Default | Required |
| - | - | - | - |
| `BACEN_CALLBACK_TRUSTED_PROXY_CIDRS` | CIDRs trusted as the source of BACEN callbacks. Set together with the header secret. | — | With the header secret |
| `BACEN_CALLBACK_MTLS_HEADER_SECRET` | Shared secret proving the upstream terminated the callback mutual TLS. At least 32 characters. Sensitive. | — | If an ICOM consumer is enabled |

Outside a local environment, the rail needs exactly one callback mutual-TLS mode. In direct mode, set `SERVER_TLS_CERT_FILE`, `SERVER_TLS_KEY_FILE`, and `SERVER_TLS_CLIENT_CA_FILE`. In proxy mode, set `TLS_TERMINATED_UPSTREAM=true`, the trusted CIDRs, and the header secret.

## SPI settlement transport (`BACEN_SPI_*`)

Connection to BACEN's SPI settlement endpoint over the RSFN, with the secondary messaging channel and the file-transfer (ARQ) endpoint.

| Variable | Description | Default | Required |
| - | - | - | - |
| `BACEN_SPI_ENDPOINT` | Primary SPI endpoint URL. | `http://localhost:9900` | Outside a local environment |
| `BACEN_SPI_SECONDARY_ENDPOINT` | Secondary messaging channel URL. The rail sends `pain.013`, `pain.014`, `camt.025`, and `trck.002` on this channel. When it is unset, those sends fail. | — | If the secondary ICOM consumer is enabled |
| `BACEN_ARQ_ENDPOINT` | BACEN file-transfer endpoint URL. The rail fetches large statement files from it. | — | No |
| `BACEN_SPI_PARTICIPANT_ISPB` | The participant's 8-digit ISPB for the SPI surface. | — | When live or if an ICOM consumer is enabled |
| `BACEN_SPI_ALLOWED_ENDPOINT_HOSTS` | Allow-list of hosts the SPI client may reach (SSRF guard). It must include the endpoint host. | — | Outside a local environment |
| `BACEN_SPI_SECONDARY_ALLOWED_ENDPOINT_HOSTS` | Allow-list for the secondary endpoint. | — | No |
| `BACEN_ARQ_ALLOWED_ENDPOINT_HOSTS` | Allow-list for the ARQ endpoint. | — | No |
| `BACEN_SPI_TIMEOUT_SEC` | Request timeout (seconds). | `30` | No |
| `BACEN_SPI_INITIATION_TIMEOUT_MS` | Payment-initiation timeout (milliseconds). | `150` | No |
| `BACEN_SPI_RETRY_ATTEMPTS` | Retry attempts on transport failure. | `3` | No |
| `BACEN_SPI_RETRY_INITIAL_BACKOFF_MS` | Initial retry backoff (milliseconds). | `500` | No |
| `BACEN_SPI_RETRY_MAX_BACKOFF_MS` | Maximum retry backoff (milliseconds). | `5000` | No |
| `BACEN_SPI_OUTBOUND_QUOTA_ENABLED` | Enable client-side outbound rate quota. Must be `true` outside a local environment. | `false` | Outside a local environment |
| `BACEN_SPI_OUTBOUND_QUOTA_LIMIT` | Sustained outbound quota (requests per second). Must be positive. | — | If quota enabled |
| `BACEN_SPI_OUTBOUND_QUOTA_BURST` | Burst allowance above the quota. Must be positive. | — | If quota enabled |
| `BACEN_SPI_CATALOGUE_VERSION` | BACEN SPI message-catalogue version. | `5.12.1` | No |
| `BACEN_SPI_XSD_DIR` | Directory of the bundled BACEN XSD schemas for the catalogue. | Bundled path | No |
| `BACEN_SPI_CATALOGUE_ROOT` | Override root for the message catalogue. | — | No |
| `BACEN_SPI_INTERNAL_CALLBACK_SECRET` | Shared secret for the internal callback path. At least 32 characters when set. Sensitive. | — | In a protected environment or if an ICOM consumer is enabled |

### mutual TLS to BACEN

The `BACEN_TLS_*` files back the mutual-TLS channel to BACEN. The SPI and DICT clients share them.

| Variable | Description | Default | Required |
| - | - | - | - |
| `BACEN_TLS_CERT_FILE` | Client certificate presented to BACEN. | — | When live |
| `BACEN_TLS_KEY_FILE` | Client private key. Sensitive. | — | When live |
| `BACEN_TLS_CA_FILE` | CA bundle used to verify BACEN's server certificate. | — | When live |

## Message signing and certificates

Lerian SPI digitally signs its outbound messages. Pick a custody backend with `BACEN_SPI_SIGNER_KIND`.

| Variable | Description | Default | Required |
| - | - | - | - |
| `BACEN_SPI_SIGNER_KIND` | Signing custody backend: `file`, `pkcs11`, or `kmip`. A protected environment refuses `file`. | `file` | In a protected environment |
| `BACEN_SPI_SIGNER_COMMON_NAME` | Expected common name of the signing certificate. | — | Outside a local environment |
| `BACEN_SPI_SIGNING_CERT_FILE` | Path to the certificate bound to the signing key. | — | If `pkcs11` or `kmip` |
| `BACEN_SPI_VERIFY_CERT_FILE` | Certificate bundle used to verify BACEN's signature on inbound messages. | — | When live |
| `BACEN_SPI_INBOUND_SIGNER_COMMON_NAME` | Expected common name of the signer on inbound messages. | — | Outside a local environment |
| `CERT_READINESS_MIN_DAYS` | Minimum days-to-expiry before the certificate readiness check reports degraded. | `14` | No |
| `BACEN_SPI_PKCS11_MODULE_PATH` | PKCS#11 module library path. | — | If `pkcs11` |
| `BACEN_SPI_PKCS11_TOKEN_LABEL` | PKCS#11 token label. | — | If `pkcs11` |
| `BACEN_SPI_PKCS11_PIN_FILE` | Path to a file holding the token PIN. Sensitive. | — | If `pkcs11` |
| `BACEN_SPI_PKCS11_KEY_LABEL` | Signing-key label on the token. | — | If `pkcs11` |
| `BACEN_SPI_KMIP_BASE_URL` | KMIP service base URL. | — | If `kmip` |
| `BACEN_SPI_KMIP_VHSM` | Virtual HSM identifier. | — | If `kmip` |
| `BACEN_SPI_KMIP_CRYPTO_USER` | KMIP crypto user. | — | If `kmip` |
| `BACEN_SPI_KMIP_CRYPTO_USER_TOKEN` | KMIP crypto-user token. Sensitive. | — | If `kmip` |
| `BACEN_SPI_KMIP_SIGN_PRIVATE_KEY_UID` | UID of the signing private key. | — | If `kmip` |
| `BACEN_SPI_KMIP_SIGN_PUBLIC_KEY_UID` | UID of the signing public key. | — | If `kmip` |
| `BACEN_SPI_KMIP_DIGEST_INFO_PREFIX` | Prepend the ASN.1 DigestInfo prefix before the KMIP sign call. | `false` | No |

### Certificate validation (OCSP/CRL)

| Variable | Description | Default | Required |
| - | - | - | - |
| `BACEN_SPI_OCSP_MODE` | Certificate revocation-check mode: `soft_fail`, `hard_fail`, or `disabled`. A protected environment refuses `disabled`. | `soft_fail` | No |
| `BACEN_SPI_OCSP_TIMEOUT_MS` | OCSP request timeout (milliseconds). | `3000` | No |
| `BACEN_SPI_OCSP_CACHE_TTL_CAP_SEC` | Cap on cached OCSP response TTL (seconds). | `3600` | No |
| `BACEN_SPI_OCSP_CRL_CACHE_TTL_SEC` | CRL cache TTL (seconds). | `3600` | No |

### Payload resolver

These variables control how the service stores and references large SPI payloads.

| Variable | Description | Default | Required |
| - | - | - | - |
| `BACEN_SPI_PAYLOAD_RESOLVER_KIND` | Payload storage backend: `in_memory` or `postgres`. A protected environment refuses `in_memory`. | `in_memory` | In a protected environment |
| `BACEN_SPI_PAYLOAD_RESOLVER_IN_MEMORY_MAX_BYTES` | Max bytes held by the in-memory resolver. | `134217728` | No |
| `BACEN_SPI_PAYLOAD_RESOLVER_TTL_SEC` | Retention TTL for resolved payloads (seconds). | `86400` | No |
| `BACEN_SPI_PAYLOAD_RESOLVER_ENCRYPTION_KEY` | AES-256 key for encrypting stored payloads. Sensitive. | — | If kind is `postgres` |

## Inbound channel (`BACEN_ICOM_*`)

Long-poll channel for messages BACEN pushes back to the participant.

| Variable | Description | Default | Required |
| - | - | - | - |
| `BACEN_ICOM_BASE_URL` | Inbound channel base URL. | — | If the primary ICOM consumer is enabled |
| `BACEN_ICOM_ISPB` | Participant ISPB for the inbound channel. It must equal `BACEN_SPI_PARTICIPANT_ISPB`. | — | If an ICOM consumer is enabled |
| `BACEN_ICOM_CONSUMER_ENABLED` | Enable the primary inbound consumer. | `false` | No |
| `BACEN_ICOM_SECONDARY_CONSUMER_ENABLED` | Enable the secondary inbound consumer. | `false` | No |
| `BACEN_ICOM_LONGPOLL_TIMEOUT_MS` | Long-poll wait timeout (milliseconds). | `90000` | No |

Either consumer requires a configured persistence backend, `BACEN_ICOM_ISPB`, `BACEN_SPI_INTERNAL_CALLBACK_SECRET`, and `BACEN_CALLBACK_MTLS_HEADER_SECRET`. The primary consumer also requires `BACEN_ICOM_BASE_URL`. The secondary consumer also requires `BACEN_SPI_SECONDARY_ENDPOINT`.

## DICT client (`BACEN_DICT_*`)

Client for BACEN's Pix key directory (DICT), including the NP endpoint for batch key-existence checks.

| Variable | Description | Default | Required |
| - | - | - | - |
| `BACEN_DICT_ENDPOINT` | DICT endpoint URL. | `http://localhost:9900` | Outside a local environment |
| `BACEN_DICT_PARTICIPANT_ISPB` | Participant ISPB for the DICT surface. | — | Outside a local environment |
| `BACEN_DICT_ALLOWED_ENDPOINT_HOSTS` | Allow-list of hosts the DICT client may reach. It must include the endpoint host. | — | Outside a local environment |
| `BACEN_DICT_TIMEOUT_SEC` | DICT request timeout (seconds). | `10` | No |
| `BACEN_DICT_NP_ENDPOINT` | NP endpoint URL for batch key-existence checks. When it is unset, the batch check answers `501`. | — | No |
| `BACEN_DICT_NP_ALLOWED_ENDPOINT_HOSTS` | Allow-list for the NP endpoint. | — | No |
| `BACEN_DICT_SIGNER_KIND` | DICT signing custody backend: `file`, `pkcs11`, or `kmip`. | `file` | No |
| `BACEN_DICT_SIGNING_CERT_FILE` | Path to the DICT signing certificate. | — | For the selected DICT custody path |
| `BACEN_DICT_SIGNING_KEY_FILE` | Path to the DICT signing private key (file backend). Sensitive. | — | If `file` |
| `BACEN_DICT_VERIFY_CERT_FILE` | Certificate used to verify DICT responses. | — | When live |
| `BACEN_DICT_PKCS11_MODULE_PATH` | PKCS#11 module path. | — | If `pkcs11` |
| `BACEN_DICT_PKCS11_TOKEN_LABEL` | PKCS#11 token label. | — | If `pkcs11` |
| `BACEN_DICT_PKCS11_PIN_FILE` | Path to the token PIN file. Sensitive. | — | If `pkcs11` |
| `BACEN_DICT_PKCS11_KEY_LABEL` | Signing-key label on the token. | — | If `pkcs11` |
| `BACEN_DICT_KMIP_BASE_URL` | KMIP service base URL. | — | If `kmip` |
| `BACEN_DICT_KMIP_VHSM` | Virtual HSM identifier. | — | If `kmip` |
| `BACEN_DICT_KMIP_CRYPTO_USER` | KMIP crypto user. | — | If `kmip` |
| `BACEN_DICT_KMIP_CRYPTO_USER_TOKEN` | KMIP crypto-user token. Sensitive. | — | If `kmip` |
| `BACEN_DICT_KMIP_SIGN_PRIVATE_KEY_UID` | UID of the signing private key. | — | If `kmip` |
| `BACEN_DICT_KMIP_SIGN_PUBLIC_KEY_UID` | UID of the signing public key. | — | If `kmip` |
| `BACEN_DICT_KMIP_DIGEST_INFO_PREFIX` | Prepend the ASN.1 DigestInfo prefix before the KMIP sign call. | `false` | No |
| `BACEN_DICT_INTENT_ENCRYPTION_KEY` | AES-256 key that encrypts pending DICT requests (key deletions and claim operations) before storage. Sensitive. | — | In a protected environment |
| `BACEN_DICT_OUTBOUND_QUOTA_ENABLED` | Enable the client-side DICT request quota. `false` starts only in a local environment. | `true` | No |
| `BACEN_DICT_ENTRIES_READ_CATEGORY` | The participant's DICT entry-read category, a letter from `A` to `H`. | — | For the `dict` binary while the quota is enabled |
| `BACEN_DICT_SPONSORED_ENTRIES_READ_CATEGORIES` | Entry-read categories of sponsored participants, as `ispb:letter` pairs. A participant without a pair uses `H`. | — | No |
| `BACEN_DICT_QUERY_MONITOR_ENABLED` | Enable the DICT query monitor. `false` starts only in a local environment. Its thresholds have defaults. | `true` | No |

## BR Code JOSE signing (`BACEN_BRCODE_JOSE_*`)

Signs dynamic BR Code payloads (JWS). When `BACEN_BRCODE_JOSE_SIGNER_KIND` is unset, JOSE is disabled and the public payload endpoints refuse to serve.

| Variable | Description | Default | Required |
| - | - | - | - |
| `BACEN_BRCODE_JOSE_SIGNER_KIND` | JOSE signing custody backend: `file`, `pkcs11`, or `kmip`. | — | No |
| `BACEN_BRCODE_JOSE_SIGNING_CERT_FILE` | Path to the JOSE signing certificate. | — | If BR Code JOSE is enabled |
| `BACEN_BRCODE_JOSE_SIGNING_KEY_FILE` | Path to the JOSE signing private key (file backend). Sensitive. | — | If BR Code JOSE is enabled with `file` |
| `BACEN_BRCODE_JOSE_KID` | JWS key identifier (`kid`) header value. | — | If BR Code JOSE is enabled |
| `BACEN_BRCODE_JOSE_PKCS11_MODULE_PATH` | PKCS#11 module path. | — | If BR Code JOSE is enabled with `pkcs11` |
| `BACEN_BRCODE_JOSE_PKCS11_TOKEN_LABEL` | PKCS#11 token label. | — | If BR Code JOSE is enabled with `pkcs11` |
| `BACEN_BRCODE_JOSE_PKCS11_PIN_FILE` | Path to the token PIN file. Sensitive. | — | If BR Code JOSE is enabled with `pkcs11` |
| `BACEN_BRCODE_JOSE_PKCS11_KEY_LABEL` | Signing-key label on the token. | — | If BR Code JOSE is enabled with `pkcs11` |
| `BACEN_BRCODE_JOSE_KMIP_BASE_URL` | KMIP service base URL. | — | If BR Code JOSE is enabled with `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_VHSM` | Virtual HSM identifier. | — | If BR Code JOSE is enabled with `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER` | KMIP crypto user. | — | If BR Code JOSE is enabled with `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_CRYPTO_USER_TOKEN` | KMIP crypto-user token. Sensitive. | — | If BR Code JOSE is enabled with `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_SIGN_PRIVATE_KEY_UID` | UID of the signing private key. | — | If BR Code JOSE is enabled with `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_SIGN_PUBLIC_KEY_UID` | UID of the signing public key. | — | If BR Code JOSE is enabled with `kmip` |
| `BACEN_BRCODE_JOSE_KMIP_DIGEST_INFO_PREFIX` | Prepend the ASN.1 DigestInfo prefix before the KMIP sign call. | `false` | No |

## PII encryption and hashing

> [!WARNING]
>
> Every variable below holds sensitive key or pepper material. It protects personal data at rest through encryption and blind indexing. Never commit or log a value. Inject it at deploy time through your secret manager. A pepper or key rotation requires a planned re-index or re-encryption.

Each key is 32 bytes, raw or base64. Each pepper has at least 32 characters.

| Variable | Description | Default | Required |
| - | - | - | - |
| `DICT_KEY_PII_ENCRYPTION_KEY` | AES key for DICT key-holder PII. Sensitive. | — | `dict` binary in a protected environment |
| `DICT_KEY_BLIND_INDEX_PEPPER` | Pepper for blind-indexing DICT key PII. Sensitive. | — | `dict` binary in a protected environment |
| `DICT_AUDIT_HASH_PEPPER` | Pepper for DICT audit-record hashing. Sensitive. | — | In a protected environment, or for the `dict` binary outside a local environment |
| `AUDIT_HASH_PEPPER` | Fallback audit-hash pepper, read only when `DICT_AUDIT_HASH_PEPPER` is unset. Sensitive. | — | No |
| `SPI_RESPONSIBLES_ENCRYPTION_KEY` | AES key for responsible-party PII. Sensitive. | — | `spi` binary in a protected environment |
| `SPI_OPERATIONS_PII_ENCRYPTION_KEY` | AES-256 key for operation PII. Sensitive. | — | Yes, for the `spi` binary |
| `SPI_OPERATIONS_BLIND_INDEX_PEPPER` | Pepper for blind-indexing operation PII. Sensitive. | — | Yes, for the `spi` binary |
| `BRCODE_PII_ENCRYPTION_KEY` | AES key for BR Code PII. Sensitive. | — | `brcode` binary in a protected environment |
| `BRCODE_PII_BLIND_INDEX_PEPPER` | Pepper for blind-indexing BR Code PII. Sensitive. | — | `brcode` binary in a protected environment |

## PostgreSQL

| Variable | Description | Default | Required |
| - | - | - | - |
| `POSTGRES_HOST` | Primary PostgreSQL host. | `localhost` | Yes |
| `POSTGRES_PORT` | Primary PostgreSQL port. | `5432` | No |
| `POSTGRES_USER` | Database user. | `brspi` | No |
| `POSTGRES_PASSWORD` | Database password. Sensitive. Use an explicit secret in a protected environment. | In-code development password | No |
| `POSTGRES_DB` | Database name. | `brspi` | No |
| `POSTGRES_SSLMODE` | libpq TLS mode. A protected environment refuses `disable`. Use `verify-full` with a trusted CA for remote connections. `require` encrypts the channel but does not verify the server identity. | `disable` | In a protected environment |
| `POSTGRES_MAX_OPEN_CONNS` | Maximum open connections. | `25` | No |
| `POSTGRES_MAX_IDLE_CONNS` | Maximum idle connections. | `5` | No |
| `POSTGRES_CONN_MAX_LIFETIME_MINS` | Connection max lifetime (minutes). | `30` | No |
| `POSTGRES_CONN_MAX_IDLE_TIME_MINS` | Connection max idle time (minutes). | `5` | No |
| `POSTGRES_CONNECT_TIMEOUT_SEC` | Connection timeout (seconds). | `10` | No |
| `POSTGRES_REPLICA_HOST` | Optional read-replica host. The service uses the replica only when its host and port are both set. | — | No |
| `POSTGRES_REPLICA_PORT` | Replica port. | — | No |
| `POSTGRES_REPLICA_USER` | Replica user. | — | No |
| `POSTGRES_REPLICA_PASSWORD` | Replica password. Sensitive. | — | No |
| `POSTGRES_REPLICA_DB` | Replica database name. | — | No |
| `POSTGRES_REPLICA_SSLMODE` | Replica TLS mode. When unset, the replica uses the primary's mode. | — | No |

## Redis

| Variable | Description | Default | Required |
| - | - | - | - |
| `REDIS_HOST` | Redis host and port. | `localhost:6379` | No |
| `REDIS_MASTER_NAME` | Sentinel master name (if using Sentinel). | — | No |
| `REDIS_PASSWORD` | Redis password. Sensitive. | — | No |
| `REDIS_DB` | Redis database number. | `0` | No |
| `REDIS_PROTOCOL` | Redis protocol version (2 or 3). | `3` | No |
| `REDIS_TLS` | Enable TLS to Redis. | `false` | No |
| `REDIS_CA_CERT` | CA certificate for Redis TLS. | — | If `REDIS_TLS=true` |
| `REDIS_POOL_SIZE` | Connection pool size. | `10` | No |
| `REDIS_MIN_IDLE_CONNS` | Minimum idle connections. | `2` | No |
| `REDIS_READ_TIMEOUT_MS` | Read timeout (milliseconds). | `3000` | No |
| `REDIS_WRITE_TIMEOUT_MS` | Write timeout (milliseconds). | `3000` | No |
| `REDIS_DIAL_TIMEOUT_MS` | Dial timeout (milliseconds). | `5000` | No |

## Outbox and streaming

Lerian SPI publishes events through a transactional outbox and a streaming producer, and consumes settlement events for BR Code. The BR Code settlement consumer runs unconditionally. Streaming has no enable switch: `STREAMING_BROKERS` is required at startup, including when `OUTBOX_ENABLED=false`. Each binary requires its own fixed `STREAMING_CLOUDEVENTS_SOURCE` value, and any other value stops startup: `br-spi` for `spi`, `br-spi-dict` for `dict`, `br-spi-brcode` for `brcode`, and `br-spi-core` for `core`. Configure `STREAMING_COMPRESSION`, `STREAMING_REQUIRED_ACKS`, and `STREAMING_EVENT_POLICIES` as described in [Streaming and outbox](/en/reference/byoc-configuration#streaming-and-outbox).

| Variable | Description | Default | Required |
| - | - | - | - |
| `OUTBOX_ENABLED` | Enable the transactional outbox dispatcher. Must be `true` for the `spi`, `dict`, and `brcode` binaries in a protected environment. | `true` | No |
| `OUTBOX_DISPATCH_INTERVAL_MS` | Interval between dispatch cycles (milliseconds). | `2000` | No |
| `OUTBOX_BATCH_SIZE` | Rows drained per dispatch cycle. | `50` | No |
| `OUTBOX_MAX_DISPATCH_ATTEMPTS` | Dispatch attempts before an event is parked. | `10` | No |
| `OUTBOX_PROCESSING_TIMEOUT_MS` | Per-batch processing timeout (milliseconds). | `600000` | No |
| `OUTBOX_RETRY_WINDOW_MS` | Retry window before a stuck row is reclaimed (milliseconds). | `300000` | No |
| `SPI_PARTICIPANT_CONSUMER_ENABLED` | Enable the Core-to-SPI participant-request consumer. It subscribes to the Core producer's application stream; the topic is derived and not configurable. It requires `STREAMING_BROKERS`, BACEN transport, and persistence when enabled. | `false` | No |
| `CORE_PARTICIPANT_CONSUMER_ENABLED` | Enable the Core consumer that applies participant confirmations from the SPI binary. | `false` | No |
| `CORE_SETTLEMENT_COMPLETION_CONSUMER_ENABLED` | Enable the Core consumer that moves a settlement from `PENDING` to `SETTLED`. | `false` | No |
| `CORE_SETTLEMENT_TERMINATION_CONSUMER_ENABLED` | Enable the Core consumer that applies returns and failures to settlements. | `false` | No |

## Schedulers

Background jobs, each with its own switch. The four DICT jobs that default to `true` carry regulatory duties, so the `dict` binary starts its scheduler for them unless `SCHEDULER_ENABLED=false`. The jobs that default to `false` also need `SCHEDULER_ENABLED=true`. DICT discovery and inventory workers have their own controls in the next section.

| Variable | Description | Default | Required |
| - | - | - | - |
| `SCHEDULER_ENABLED` | Master switch for the scheduler subsystem. An explicit `false` stops every job below. | `false` | No |
| `SCHEDULER_CLAIM_DEADLINE_ENABLED` | Run the DICT claim-deadline job. | `true` | No |
| `SCHEDULER_INBOUND_DISCOVERY_ENABLED` | Run the DICT claim discovery walks, for the donor and the claimer sides. | `true` | No |
| `SCHEDULER_INBOUND_DISCOVERY_MAX_STALENESS_MINUTES` | Readiness staleness threshold for the claim discovery walks. Must be greater than zero. | `15` | No |
| `SCHEDULER_DICT_RECONCILIATION_INCREMENTAL_ENABLED` | Run the daily DICT reconciliation, at 02:00 Brasília time. | `true` | No |
| `SCHEDULER_DICT_RECONCILIATION_FULL_ENABLED` | Run the weekly full DICT reconciliation, on Sunday at 03:00 Brasília time. | `true` | No |
| `SCHEDULER_QUOTA_RESET_ENABLED` | Run the daily participant-quota reset in Core, at midnight Brasília time. | `false` | No |
| `SCHEDULER_DICT_AUDIT_RETENTION_ENABLED` | Run the DICT audit-log retention purge. | `false` | No |
| `SCHEDULER_APPROVAL_EXPIRY_ENABLED` | Every 5 minutes, move expired approval requests to `EXPIRED`. | `false` | No |
| `SCHEDULER_PORTABILITY_DEADLINE_ENABLED` | Every 5 minutes, mark portability operations whose 24-hour deadline has passed. It never confirms them. | `false` | No |

## DICT discovery and inventory

The workers below run independently of `SCHEDULER_ENABLED`, each with its own switch.

| Variable | Description | Default | Required |
| - | - | - | - |
| `DICT_FUNDS_RECOVERY_EVENTS_ENABLED` | Enable the DICT funds-recovery event feed. | `true` | No |
| `DICT_FUNDS_RECOVERY_EVENTS_MAX_STALENESS_MINUTES` | Readiness staleness threshold for the funds-recovery event feed. | `15` | No |
| `DICT_FUNDS_RECOVERY_EVENTS_GAP_BLOCK_HOURS` | Gap threshold after which the funds-recovery event feed records a blocked marker. Must be greater than zero. | `168` | No |
| `DICT_INFRACTION_DISCOVERY_ENABLED` | Enable the DICT infraction discovery walk. | `true` | No |
| `DICT_INFRACTION_DISCOVERY_MAX_STALENESS_MINUTES` | Readiness staleness threshold for infraction discovery. Must be greater than zero. | `15` | No |
| `DICT_REFUND_DISCOVERY_ENABLED` | Enable the DICT refund discovery walks. | `true` | No |
| `DICT_REFUND_DISCOVERY_MAX_STALENESS_MINUTES` | Readiness staleness threshold for refund discovery. Must be greater than zero. | `15` | No |
| `DICT_PERSON_WATCHLIST_ENABLED` | Enable polling for documents in the DICT person watchlist. | `true` | No |
| `DICT_PERSON_WATCHLIST_CADENCE_MINUTES` | Minimum age before a watched document is observed again. Must be greater than zero. | `60` | No |
| `DICT_PERSON_WATCHLIST_BATCH_LIMIT` | Maximum watched documents observed in one polling tick. Must be greater than zero. | `100` | No |
| `DICT_PERSON_WATCHLIST_MAX_DOCUMENTS_PER_PARTICIPANT` | Maximum active watched documents per participant. Must be greater than zero. | `500` | No |
| `DICT_PERSON_WATCHLIST_MAX_OBSERVATION_AGE_MINUTES` | Readiness threshold for the oldest watched document observation. Must be greater than zero. | `360` | No |
| `DICT_PERSON_WATCHLIST_QUARANTINE_AFTER_FAILURES` | Consecutive failed observations before a watched document is quarantined. Must be greater than zero. | `6` | No |
| `DICT_FRAUD_MARKER_INVENTORY_ENABLED` | Enable the DICT fraud-marker inventory sweep. | `true` | No |
| `DICT_FRAUD_MARKER_INVENTORY_SWEEP_MINUTES` | Interval between fraud-marker inventory sweeps. Must be greater than zero. | `60` | No |
| `DICT_FRAUD_MARKER_INVENTORY_MAX_DOCUMENTS_PER_SWEEP` | Maximum documents reconciled in one inventory sweep. Must be greater than zero. | `200` | No |
| `DICT_FRAUD_MARKER_INVENTORY_MAX_STALENESS_MINUTES` | Readiness staleness threshold for the fraud-marker inventory. Must be greater than zero. | `180` | No |

## Rate limiting, idempotency, and connectivity

| Variable | Description | Default | Required |
| - | - | - | - |
| `RATE_LIMIT_ENABLED` | Enable request rate limiting. Forced on in a protected environment. | `true` | No |
| `RATE_LIMIT_MAX` | Maximum requests per window. | `100` | No |
| `RATE_LIMIT_EXPIRY_SEC` | Rate-limit window (seconds). | `60` | No |
| `IDEMPOTENCY_RETRY_WINDOW_SEC` | How long (seconds) an idempotency key is retained. | `86400` | No |
| `IDEMPOTENCY_RESPONSE_ENCRYPTION_KEY` | AES-256 key for encrypting stored idempotency responses. Sensitive. | — | Yes |
| `INFRA_CONNECT_TIMEOUT_SEC` | Connect timeout for infrastructure dependencies at startup (seconds). | `30` | No |

## Systemplane and runtime configuration

| Variable | Description | Default | Required |
| - | - | - | - |
| `SYSTEMPLANE_ENABLED` | Enable the systemplane runtime-configuration admin API, mounted at `/v1/system` on the main port. When `false`, the service runs in env-only mode with no admin plane. SPI defaults this on. | `true` | No |

See [Systemplane](/en/reference/platform/systemplane/overview) for the API, namespaces, and required permissions.

## Observability

| Variable | Description | Default | Required |
| - | - | - | - |
| `ENABLE_TELEMETRY` | Enable OpenTelemetry tracing and metrics. | `false` | No |
| `TELEMETRY_REQUIRED` | Fail startup if telemetry cannot initialize. | `false` | No |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector endpoint. | `localhost:4317` | If telemetry enabled |
| `OTEL_RESOURCE_SERVICE_NAME` | Service name attached to exported telemetry. | Service default | No |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | Deployment environment label. | `development` | No |
| `OTEL_LIBRARY_NAME` | Instrumentation library name. | Service default | No |
| `METRICS_PROMETHEUS_ENABLED` | Expose a dedicated Prometheus scrape endpoint. | `false` | No |
| `METRICS_PROMETHEUS_ADDRESS` | Listen address for the Prometheus endpoint. Binds loopback by default. | `127.0.0.1:9090` | No |

## Documentation

| Variable | Description | Default | Required |
| - | - | - | - |
| `SWAGGER_ENABLED` | Serve the OpenAPI spec and API docs UI. Forced off in a protected environment. | `false` | No |

## Health and readiness

Lerian SPI exposes `GET /health` (liveness), `GET /readyz` (readiness), and `GET /version` on the main HTTP port. `/metrics` runs on its own listener when enabled. See [Health and readiness](/en/reference/health-and-readiness) for the probe contract.


# Inbound messaging from BACEN
Source: https://docs.lerian.studio/en/rails/spi/spi-inbound-messaging

How Lerian SPI receives the signed ISO 20022 messages that arrive from BACEN over the RSFN and applies them to its operations.

The ICOM consumer receives signed ISO 20022 messages from BACEN over the RSFN and passes them to the rail's authenticated internal ingress. A credit-transfer message (`pacs.008`) carries an inbound Pix. A status reply (`pacs.002`) reports a payment you sent. A return message (`pacs.004`) carries a devolução.

The rail validates each inbound message before it applies it. An outbound payment stays open until its `pacs.002` arrives. That reply applies `COMPLETED` or `REJECTED`.

The rail records an inbound `pacs.008` as `PENDING` until your client accepts or refuses it. An accepted Pix reaches `COMPLETED` only when the SPI confirms the credit, or `REJECTED` if the SPI refuses it. The rail refuses a Pix that no decision concludes within its regulatory window.


# What is Lerian SPI?
Source: https://docs.lerian.studio/en/rails/spi/what-is-lerian-spi

Lerian's direct, non-intermediated BACEN connector for Pix: instant payments, the DICT key directory, BR Code QR, Pix Automático, and MED disputes.

**Lerian SPI** is Lerian's own messaging connector to the **SPI** (Sistema de Pagamentos Instantâneos). The SPI is the Central Bank of Brazil (BACEN) infrastructure that settles **Pix**, Brazil's instant-payment system, 24 hours a day. Lerian SPI reaches the SPI and its key directory (**DICT**) over the **RSFN**. The RSFN is the private national network for payment-system messages between participants and BACEN. Lerian SPI speaks **ISO 20022** and puts no connectivity partner between the institution and BACEN.

Lerian SPI gives a participant institution a direct path to BACEN. The institution sends and receives Pix, manages Pix keys, issues QR charges, runs recurring authorizations, and handles disputes and refunds. The rail emits settlement facts. Your ledger consumer records the corresponding positions.

## Who it serves

***

Lerian SPI serves financial institutions that participate in Pix under their own **ISPB**. Each participant connects straight to BACEN, with no connectivity partner in the money path. The rail carries the participant's payments, Pix keys, charges, and disputes across every surface below.

## Four API surfaces

***

Lerian SPI has four API surfaces. At runtime, it ships four binaries: `spi`, `dict`, `brcode`, and `core`. The surfaces speak the messaging contract of one part of the Pix ecosystem.

| Surface | What it covers |
| - | - |
| **Payments** | Sending and receiving Pix, payment status and history, returns (devoluções), Pix Automático recurring authorizations, Conta PI reporting, and the MED 2.0 settlement report |
| **DICT** | The Pix key lifecycle, lookups and batch existence checks, antifraud statistics, portability and ownership claims (reivindicações), and MED refund requests, fraud markers, funds recoveries, and infraction reports |
| **BR Code** | Immediate (Cob), due-date (CobV), and batch Pix charges, and the EMV QR payloads that resolve to them |
| **Core** | Participant registration and lifecycle, operation orchestration, and payment routing |

## Settlement is real-time and asynchronous

***

The SPI settles each Pix individually, in real time, around the clock. When you submit a payment, the platform dispatches an ISO 20022 credit-transfer message (`pacs.008`). The platform records the payment as sent to BACEN, not yet settled. BACEN confirms settlement asynchronously through a status reply (`pacs.002`). The rail validates the reply and moves the payment to `COMPLETED` or `REJECTED`. Each payment carries an **end-to-end ID (E2EID)**.

## Money-neutrality

***

Lerian SPI is money-neutral. It forwards the amounts you declare exactly as declared and computes no balance or position of its own. The rail carries the message and its settlement state. Your ledger consumer records the money movement.

## Glossary

***

| Term | Meaning |
| - | - |
| **Lerian SPI** | Lerian's native Pix rail, integrated directly with BACEN over the SPI. |
| **Pix** | Brazil's instant-payment system, operated by BACEN and settling 24/7. |
| **SPI** (Sistema de Pagamentos Instantâneos) | BACEN's instant-payment settlement infrastructure. |
| **DICT** (Diretório de Identificadores de Contas Transacionais) | BACEN's Pix key directory. |
| **Pix key** | An alias (phone, email, tax ID, or random EVP) that resolves to an account. |
| **ISPB** | 8-character alphanumeric BACEN code identifying a participant institution in the Brazilian payment system. |
| **End-to-end ID (E2EID)** | The 32-character identifier tracking a single Pix payment across the rail. |
| **BR Code** | Brazil's EMV QR standard (QRCPS-MPM) for Pix, static or dynamic. |
| **Cob / CobV** | An immediate Pix charge (Cob) or a due-date charge with interest and fine (CobV). |
| **Pix Automático** | Recurring and scheduled Pix authorizations (recorrência and agendamento). |
| **MED** (Mecanismo Especial de Devolução) | BACEN's dispute and refund mechanism for fraud or error. |
| **Devolução** | A Pix return sent back to the payer against a settled payment. |
| **Reivindicação (claim)** | A portability or ownership claim to move a Pix key between participants. |
| **Conta PI** | A participant's instant-payment settlement account at BACEN, reported via camt.05x. |
| **ISO 20022** | The messaging standard (pacs / pain / camt) BACEN uses for Pix over the RSFN. |
| **Participant** | A financial institution connected to Pix, identified by its ISPB. |

For how Lerian SPI sits alongside the other native rails and the partner interfaces, see [Native messaging and partner interfaces](/en/rails/native-messaging).


# How Lerian SRC works
Source: https://docs.lerian.studio/en/rails/src/how-src-works

How Lerian SRC accepts a consultation, sends it to BACEN, handles BACEN's answer or rejection, retries, and keeps institution records, the evidence trail, and operator cases.

A consultation has one of three statuses: `pending`, `completed`, or `failed`. Lerian SRC accepts the consultation at once and works with BACEN after it answers your request.

## Consultation request

***

Your system sends `POST /v1/src/consultations` with an `X-Idempotency` header. The body names one document and the questions to ask about it.

| Field | Meaning |
| - | - |
| `document` | The CPF or CNPJ to consult. |
| `documentType` | `CPF` or `CNPJ`. It must match the document. |
| `protectionTypes` | `account_opening`, `ownership_change`, or both. |
| `motivation` | The reason for the consultation. `motivation.reference` is required. |
| `subjectRole` | Optional: `individual`, `company`, `holder`, or `representative`. Without it, Lerian SRC takes the role from `documentType`. |
| `companyConsultationId` | The id of the company consultation. Required for `holder` and `representative`. |

A `holder` or a `representative` is a person that you consult for a company. Send the company consultation first. Then send the person's consultation, with `companyConsultationId` set to the id that the company consultation returned. A request that breaks these rules returns `422` with a code from `SRC-0004` to `SRC-0008`.

Lerian SRC checks the request before it accepts it. It checks the check digits, the document type, the protection types, and the motivation. A request that fails one of these checks returns `422` with code `SRC-0002`, and Lerian SRC sends nothing to BACEN.

An accepted request returns `202` with the consultation `id` and the status `pending`. Lerian SRC stores the consultation before it sends anything to BACEN, and it publishes the accepted event.

## SRC0001: the consultation to BACEN

***

Lerian SRC sends each accepted consultation to BACEN as an SRC0001 message. Every 15 seconds, it takes up to 25 consultations that wait to go.

Each message carries the operation number of the consultation. The API returns it as `regulatoryOperationNumber`.

Lerian SRC checks each message against BACEN's message schema before it sends the message. If the message is not valid for BACEN, Lerian SRC does not send it. The consultation ends `failed` with the rejection code `SRC-OUTBOUND-INVALID`, and Lerian SRC opens an `invalid_outbound` operator case.

## SRC0001R1: BACEN's answer

***

BACEN answers with an SRC0001R1 message. The answer carries BACEN's control code and one verdict for each protection type.

Lerian SRC matches the answer to its consultation and stores the verdicts. The consultation becomes `completed`, and Lerian SRC publishes the completed event. A verdict with `permitted` set to `false` means an active restriction.

An answer that matches no consultation of the deployment opens an `orphan_response` operator case.

## SRC0001E: BACEN's rejection

***

BACEN can reject a consultation with an SRC0001E message. Lerian SRC puts the rejection code in one of three classes:

* **`transient`**: the code names a temporary state of the rail. Lerian SRC sends the consultation again, within the attempt budget. The transient codes are `EGEN0021`, `EGEN0050`, `EGEN0152`, `EGEN0300`, `EGEN0301`, and `EGEN1105`.
* **`permanent`**: the consultation ends `failed`. Fix the cause and send a new request.
* **`unknown`**: Lerian SRC does not recognize the code. The consultation ends `failed`, as for a permanent code.

A failed consultation carries the code as BACEN sent it, in `rejection.code`, and its class in `rejection.classification`. Lerian SRC publishes the failed event.

## Retries and BACEN unavailability

***

When a send fails, or BACEN gives a transient rejection, Lerian SRC sends the consultation again. If BACEN does not answer in time, Lerian SRC also sends the consultation again. Each send counts as one attempt.

Three runtime configuration keys set the attempt budget:

| Key | Default | Meaning |
| - | - | - |
| `src.dispatch.max_attempts` | `8` | Attempts for each consultation, from 1 to 20. |
| `src.dispatch.backoff_initial` | `1m` | Wait before the first retry, from `1s` to `1h`. |
| `src.dispatch.backoff_ceiling` | `30m` | Longest wait between two attempts, from `1m` to `24h`. |

The wait doubles after each attempt, up to the ceiling. Lerian SRC waits for an answer for 30 minutes, or for the ceiling when the ceiling is longer.

When a consultation uses its whole budget, Lerian SRC stops sending it and opens a `budget_exhausted` operator case. The consultation stays `pending`.

When BACEN or the IBM MQ channel is unavailable, the API does not return an error. Lerian SRC keeps accepting consultations, and they stay `pending`.

## Institution record

***

After a consultation completes with an active restriction, your institution files one record with `POST /v1/src/consultations/{id}/institution-record`. The record has one of two kinds:

| Kind | When to file it | Fields it needs |
| - | - | - |
| `exceptional_proceed` | Your institution went ahead with the contract despite the active restriction. | `justification` and `circumstance` |
| `refusal_explanation` | Your institution refused, and the record holds the explanation it gave to the interested party. | `explanation` |

Both kinds also need `registeredBy`, which names who files the record. A successful filing returns `201`. The record does not change the verdicts.

A consultation holds one record. A second record returns `409` with code `SRC-0101`. A consultation that did not complete with an active restriction returns `409` with code `SRC-0102`.

## Evidence trail

***

Lerian SRC keeps an evidence trail for each consultation.

| Operation | What it returns |
| - | - |
| `GET /v1/src/evidence/consultations/{id}` | The trail of one consultation, record by record. |
| `POST /v1/src/evidence` | The consultations that have a trail, found by period, consultation id, BACEN control code, or document. |
| `POST /v1/src/evidence/records` | The individual records, found by document or by record kind. |

To correct a record, send `POST /v1/src/evidence/consultations/{id}/corrections`. Put the position of the record in `correctsSequence`, and the reason in `reason`. Lerian SRC adds the correction to the trail as a new record and returns `201`.

If a concurrent correction of the same trail takes the position first, the request returns `409` with code `SRC-0104`. Lerian SRC writes nothing. Retry the correction.

## Operator cases

***

An operator case is an item that your back office must see. Each case names its `leg`. For example:

| Leg | What happened | What closing the case does |
| - | - | - |
| `invalid_outbound` | Lerian SRC refused to send a message that is not valid for BACEN. BACEN did not receive it. | It records that a person saw the case. Lerian SRC repairs nothing and sends nothing. Fix the cause and send a new request. |
| `orphan_response` | A message from BACEN matched no consultation of the deployment. | It records that a person examined the message. |
| `budget_exhausted` | A consultation used its whole attempt budget. | You cannot close it. If BACEN's answer arrives later, Lerian SRC records the answer and the case leaves the queue. |

[Operating Lerian SRC](/en/rails/src/src-operations#operator-cases) explains how to list and close cases.

Lerian SRC also publishes an event at each change of status. [Integrating with Lerian SRC](/en/rails/src/src-integration#polling-and-events) lists the events.


# Environment variables
Source: https://docs.lerian.studio/en/rails/src/src-environment-variables

Deploy-time environment variables for Lerian SRC: runtime posture, license, institution identity, PostgreSQL, events, Access Manager, IBM MQ, key custody, data at rest, and telemetry.

Lerian SRC reads its configuration from the process environment at startup. You set these variables at deploy time. A service restart makes them take effect. [BYOC configuration essentials](/en/reference/byoc-configuration) covers the BYOC configuration model.

In the tables below, the **Default / Required** column shows the value that Lerian SRC applies when you leave the variable unset. A bold qualifier marks a variable that you must set, in every environment or under a stated condition. The condition "outside local development" means every environment except an `ENV_NAME` of `develop` or `development` with `DEPLOYMENT_MODE` empty or `local`. The value `—` means that Lerian SRC applies no default. A description that ends with "Sensitive." marks a variable that holds a secret.

A production deployment is one where `ENV_NAME` names production or `DEPLOYMENT_MODE` is `saas` or `byoc`. Lerian SRC applies stricter checks there.

> [!NOTE]
>
> Where a value in the shipped example file differs from the value the code applies, this page publishes the code value.

## Service and runtime

| Variable | Default / Required | Description |
| - | - | - |
| `SERVICE_NAME` | `br-src` | Service name in logs and telemetry. |
| `ENV_NAME` | `development` | Deployment environment: `local`, `develop`, `development`, `uat`, `staging`, `prod`, or `production`. Another value stops the boot. |
| `DEPLOYMENT_MODE` | `local`. **Required in production** | Deployment model: `local`, `byoc`, or `saas`. Another value stops the boot. |
| `LOG_LEVEL` | `info` | Log level at startup: `debug`, `info`, `warn`, or `error`. The `src.log.level` runtime key changes it while the service runs. |
| `SERVER_PORT` | `3006` | HTTP listen port. |
| `TRUSTED_PROXIES` | `—` | Comma-separated list of proxy addresses or CIDR ranges that Lerian SRC trusts for the client IP address. Empty trusts no proxy. |
| `PROXY_HEADER` | `X-Forwarded-For` when `TRUSTED_PROXIES` is set | Header that carries the client IP address from a trusted proxy. |

## License

| Variable | Default / Required | Description |
| - | - | - |
| `LICENSE_KEY` | **Required** | License key that Lerian issues. Sensitive. |
| `ORGANIZATION_IDS` | **Required** | Comma-separated list of the organization IDs that the license covers. Set at least one. |

## Institution identity

| Variable | Default / Required | Description |
| - | - | - |
| `SRC_CNPJ_BASE8` | **Required** | The CNPJ base of your institution: 8 characters from `0-9` and `A-Z`, not all zeros. Lerian SRC derives the IBM MQ queue names and the operation numbers from it. |
| `SRC_SENDER_ISPB` | **Required in production, or when `SRC_MQ_HOST` is set** | The ISPB of your institution: 8 digits, not all zeros. |

## PostgreSQL

| Variable | Default / Required | Description |
| - | - | - |
| `POSTGRES_HOST` | **Required in production** | Database host. |
| `POSTGRES_PORT` | `5432` | Database port. |
| `POSTGRES_USER` | **Required in production** | Database user. |
| `POSTGRES_PASSWORD` | `—` | Database password. Sensitive. |
| `POSTGRES_DB` | **Required in production** | Database name. |
| `POSTGRES_SSLMODE` | `disable` | PostgreSQL `sslmode`. |
| `POSTGRES_MAX_OPEN_CONNS` | `25` | Maximum open connections in the pool. |
| `POSTGRES_MAX_IDLE_CONNS` | `10` | Maximum idle connections in the pool. |
| `POSTGRES_CONN_LIFETIME` | `30m` | Maximum lifetime of a connection, as a Go duration. |
| `POSTGRES_CONN_IDLE_TIME` | `5m` | Maximum idle time of a connection, as a Go duration. |

## Events

| Variable | Default / Required | Description |
| - | - | - |
| `SRC_STREAMING_BROKERS` | `—`. **Required in production**, unless `SRC_STREAMING_EMISSION_DISABLED` is `true` | Comma-separated list of broker addresses. |
| `SRC_STREAMING_CLIENT_ID` | `br-src` | Producer client ID. |
| `SRC_STREAMING_SOURCE` | `br-src` | CloudEvents source. Leave it unset, or set it to exactly `br-src`. Another value stops the boot. |
| `SRC_STREAMING_TLS` | `false` | Turns on TLS for the broker connection. |
| `SRC_STREAMING_EMISSION_DISABLED` | `false` | Set it to `true` to run without a broker. The events then stay pending in the outbox. |

## Access Manager

| Variable | Default / Required | Description |
| - | - | - |
| `PLUGIN_AUTH_ENABLED` | **Required** | Turns on Access Manager authentication. Set it to `true`. A production deployment refuses `false`. |
| `PLUGIN_AUTH_ADDRESS` | **Required in production** | Access Manager address. |
| `IDP_DECLARATION_ENABLED` | `false` | Set it to `true` to publish the Lerian SRC permission manifest to Access Manager at startup. |
| `IDP_HOST` | **Required when `IDP_DECLARATION_ENABLED` is `true`** | Address of the Access Manager identity service that receives the manifest. |
| `IDP_M2M_CLIENT_ID` | **Required when `IDP_DECLARATION_ENABLED` is `true`** | Client ID that Lerian SRC uses to publish the manifest. |
| `IDP_M2M_CLIENT_SECRET` | **Required when `IDP_DECLARATION_ENABLED` is `true`** | Client secret that Lerian SRC uses to publish the manifest. Sensitive. |

## IBM MQ

| Variable | Default / Required | Description |
| - | - | - |
| `SRC_MQ_HOST` | **Required in production** | Host of your institution's IBM MQ queue manager. |
| `SRC_MQ_PORT` | **Required when `SRC_MQ_HOST` is set** | Listener port of your queue manager. |
| `SRC_MQ_CHANNEL` | **Required when `SRC_MQ_HOST` is set** | Server-connection channel on your queue manager. At most 20 characters from `A-Z`, `a-z`, `0-9`, `.`, `/`, `_`, and `%`. |
| `SRC_MQ_QUEUE_MANAGER` | **Required in production** | Name of your queue manager. |
| `SRC_MQ_USER` | `—` | IBM MQ user ID. |
| `SRC_MQ_PASSWORD` | `—` | IBM MQ password. Sensitive. |
| `SRC_MQ_TLS_ENABLED` | `false` | Turns on TLS for the IBM MQ connection. A production deployment requires `true`. |
| `SRC_MQ_SSL_KEY_REPOSITORY` | `—` | Path stem of the IBM MQ key repository. |
| `SRC_MQ_CERT_LABEL` | `—` | Label of the certificate in the key repository that the IBM MQ connection presents. |
| `SRC_MQ_CIPHER_SPEC` | `TLS_RSA_WITH_AES_256_CBC_SHA256` | IBM MQ cipher spec. |
| `SRC_MQ_SEND_QUEUE` | Derived from `SRC_CNPJ_BASE8` | Name of the send queue. |
| `SRC_MQ_RECEIVE_QUEUE` | Derived from `SRC_CNPJ_BASE8` | Name of the receive queue. |
| `SRC_MQ_BACKOUT_QUEUE` | The receive queue name followed by `.BACKOUT` | Queue that takes a message after it fails delivery `SRC_MQ_BACKOUT_THRESHOLD` times. |
| `SRC_MQ_BACKOUT_THRESHOLD` | `5` | Failed deliveries before a message moves to the backout queue. `0` turns the move off. |
| `SRC_MQ_BACKOUT_DELAY` | `2s` | Pause after a failed delivery, as a Go duration. |
| `SRC_MQ_STALE_AFTER` | `30s` | Time with no completed IBM MQ call before the `src_mq` check reports `degraded`. `0` turns this off. |
| `SRC_MQ_HEARTBEAT_INTERVAL` | `30s` | IBM MQ heartbeat interval, as a Go duration in whole seconds. `0` uses the value of the channel. |

## Certificates and key custody

| Variable | Default / Required | Description |
| - | - | - |
| `SRC_LOCAL_CERT_FILE` | **Required in production, or when `SRC_MQ_HOST` is set** | Path to your institution's certificate. It must match the private key in PKCS#11 or KMIP. |
| `SRC_BACEN_CERT_FILE` | **Required in production, or when `SRC_MQ_HOST` is set** | Path to BACEN's certificate. Restart Lerian SRC after you replace it. |
| `SRC_PKCS11_MODULE_PATH` | `—` | Path to the PKCS#11 client library. |
| `SRC_PKCS11_TOKEN_LABEL` | `—` | Label of the PKCS#11 token. |
| `SRC_PKCS11_PIN_FILE` | `—` | Path to the file that holds the PKCS#11 PIN. |
| `SRC_PKCS11_KEY_LABEL` | `—` | Label of the key pair in the PKCS#11 token. |
| `SRC_KMIP_BASE_URL` | `—` | Base URL of the KMIP server. |
| `SRC_KMIP_VHSM` | `—` | Identifier of the virtual HSM. |
| `SRC_KMIP_CRYPTO_USER` | `—` | KMIP crypto user. |
| `SRC_KMIP_CRYPTO_USER_TOKEN` | `—` | Token of the KMIP crypto user. Sensitive. |
| `SRC_KMIP_SIGN_PRIVATE_KEY_UID` | `—` | Identifier of the signing private key. |
| `SRC_KMIP_SIGN_PUBLIC_KEY_UID` | `—` | Identifier of the matching public key. |
| `SRC_KMIP_DECRYPT_KEY_UID` | `—` | Identifier of the decryption key. |

## Data at rest

| Variable | Default / Required | Description |
| - | - | - |
| `SRC_ATREST_ENCRYPTION_KEY` | **Required outside local development** | The 32-byte key that encrypts document data at rest. Sensitive. |
| `SRC_ATREST_BLIND_INDEX_KEY` | **Required outside local development** | The key Lerian SRC uses to search by document number. At least 32 characters, and different from `SRC_ATREST_ENCRYPTION_KEY`. Sensitive. |

## Telemetry

| Variable | Default / Required | Description |
| - | - | - |
| `ENABLE_TELEMETRY` | `false`. **A production deployment requires `true`** | Turns on the export of traces and metrics over OTLP. |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | **Required in production** | Address of the OTLP collector. |


# Integrating with Lerian SRC
Source: https://docs.lerian.studio/en/rails/src/src-integration

Integrating with Lerian SRC: the API surface, permissions, idempotency, polling and events, errors, and request limits.

Every Lerian SRC business operation sits under the `/v1/src` base path. The [API Reference](/en/reference/rails/src/create-a-consultation) documents each operation, with its request and response.

## Before you start

***

An operator deploys and configures Lerian SRC for your institution. [Environment variables](/en/rails/src/src-environment-variables) lists the settings, and [Operating Lerian SRC](/en/rails/src/src-operations) covers the IBM MQ connection to BACEN.

## Authentication and permissions

***

Every call to `/v1/src` needs a bearer token from Access Manager. Use an application token for your onboarding systems and a user token for your back office. A request without a valid token returns `401`. A token of another type returns `401` with code `SRC-0201`.

Each operation needs one permission on the `src` product. A token without that permission returns `403` with code `SRC-0202`.

| Operations | Resource | Action |
| - | - | - |
| Create a consultation | `consultation` | `write` |
| List, search, and retrieve consultations | `consultation` | `read` |
| Register an institution record | `decision` | `write` |
| Search the evidence trail, retrieve a consultation's evidence trail, and search evidence records | `evidence` | `read` |
| Correct an evidence record | `evidence` | `correct` |
| Retrieve the consultation dashboard | `dashboard` | `read` |
| Retrieve the credential status | `credential` | `read` |
| List and retrieve operator cases | `operator` | `read` |
| Close or acknowledge an operator case | `operator` | `close` |
| Runtime configuration (`/v1/system`) | `system` | `write` |
| Event manifest (`GET /v1/streaming/manifest`) | `streaming` | `read` |

Lerian SRC serves one institution, which `SRC_CNPJ_BASE8` sets in its configuration.

## API surface

***

| Area | Operation | Purpose |
| - | - | - |
| Consultations | `POST /v1/src/consultations` | Create a consultation. |
| Consultations | `GET /v1/src/consultations` | List consultations, with filters. |
| Consultations | `POST /v1/src/consultations/search` | Search consultations, also by document. |
| Consultations | `GET /v1/src/consultations/{id}` | Read one consultation and its outcome. |
| Institution records | `POST /v1/src/consultations/{id}/institution-record` | File the institution record of a consultation. |
| Evidence | `POST /v1/src/evidence` | Find the consultations that have an evidence trail. |
| Evidence | `GET /v1/src/evidence/consultations/{id}` | Read the evidence trail of one consultation. |
| Evidence | `POST /v1/src/evidence/consultations/{id}/corrections` | Correct an evidence record. |
| Evidence | `POST /v1/src/evidence/records` | Find individual evidence records. |
| Dashboard | `GET /v1/src/dashboard/consultations` | Read the consultation totals for a period. |
| Credentials | `GET /v1/src/credentials` | Read the credential status. |
| Operator cases | `GET /v1/src/operator/cases` | List operator cases. |
| Operator cases | `GET /v1/src/operator/cases/{leg}/{caseId}` | Read one operator case. |
| Operator cases | `POST /v1/src/operator/orphan-responses/{caseId}/closure` | Close an orphan-response case. |
| Operator cases | `POST /v1/src/operator/invalid-dispatches/{caseId}/closure` | Acknowledge an invalid-dispatch case. |

Operational endpoints sit outside `/v1/src`.

| Endpoint | Purpose |
| - | - |
| `GET /health` | Liveness. |
| `GET /readyz` | Readiness of the dependencies. |
| `GET /version` | Build version. |
| `/v1/system` | Runtime configuration. |
| `GET /v1/streaming/manifest` | The event manifest. |

## Idempotency

***

`POST /v1/src/consultations` needs an `X-Idempotency` header, of at most 255 characters. A request without it returns `400` with code `SRC-0001`.

* The same key with the same body returns `202` with the original consultation id. The response shows the current status of that consultation, so it can be `completed` or `failed`.
* The same key with a different body returns `409` with code `SRC-0003`.

These two rules hold while Lerian SRC keeps the key. The retention sweep can delete a key older than `src.retention.transient_purge_age`, 24 hours by default. A request that reuses a deleted key starts a new consultation.

`POST /v1/src/consultations/{id}/institution-record` takes no idempotency key. A consultation holds one record, so a retry returns `409` with code `SRC-0101`.

An evidence correction is not idempotent. A retried request adds a second correction. Before you retry after a failure that you cannot confirm, read the evidence trail.

## Polling and events

***

A consultation starts `pending`, and `pending` is a normal state. Read the outcome in one of two ways:

* Poll `GET /v1/src/consultations/{id}`. A `completed` consultation carries `verdicts` and `bcbControlCode`. A `failed` consultation carries `rejection`.
* Consume the events that Lerian SRC publishes.

| Event type | Published when | Payload fields |
| - | - | - |
| `studio.lerian.br-src.consulta.accepted` | Lerian SRC accepts a consultation. | `consultationId`, `status`, `documentMasked`, `documentType`, `protectionTypes`, `motivationReference`, `acceptedAt`, `occurredAt` |
| `studio.lerian.br-src.consulta.completed` | BACEN answers a consultation. | `consultationId`, `status`, `bcbControlCode`, `bcbProcessedAt`, `concludedAt`, `verdicts`, `occurredAt` |
| `studio.lerian.br-src.consulta.failed` | A consultation fails. | `consultationId`, `status`, `rejectionCode`, `rejectionClassification`, `rejectionReceivedAt`, `concludedAt`, `occurredAt` |

The events travel on the topic `lerian.streaming.br-src`, with the CloudEvents source `br-src`. No variable changes the topic. See [Streaming Hub](/en/platform/streaming-hub/what-is-streaming-hub).

Lerian SRC writes each event to an outbox in the same transaction as the change it reports. With no broker, the events stay pending in the outbox.

## Errors

***

Errors follow RFC 9457 problem details, with the media type `application/problem+json`. Branch on the `code` field, not on the `detail` text. The [SRC error list](/en/reference/rails/src/src-error-list) gives each code, its meaning, and its HTTP status.

## Integration conventions

***

* **Request size.** A request body larger than 1 MiB returns `413`.
* **Pagination.** A list or search returns a page with `nextCursor`. To read the next page, send that value as `cursor`. `nextCursor` is `null` on the last page.
* **Rate limit.** Lerian SRC counts the requests of each client IP address in each replica. The default is 6000 requests per minute, set by `src.rate_limit.ip_max` and `src.rate_limit.ip_window`. Past the limit, the answer is `429` with code `SRC-0401`.


# Operating Lerian SRC
Source: https://docs.lerian.studio/en/rails/src/src-operations

Readiness checks, the IBM MQ connection, credentials and keys, personal data, operator cases, runtime configuration, storage, metrics, and the deployment posture of Lerian SRC.

Lerian SRC carries your institution's consultations to BACEN. An instance that is not ready is an operational event.

## Health and readiness

***

`GET /health` reports liveness. `GET /readyz` runs the checks below. It answers `503` when a check reports `down` or `degraded`, and while the service shuts down.

| Check | What it probes |
| - | - |
| `postgres` | The PostgreSQL database. |
| `outbox_dispatcher` | The loop that publishes events from the outbox. It reports `skipped` while event publication is held, for example with no broker. |
| `src_mq` | The IBM MQ connection that carries consultations. |
| `custody` | The PKCS#11 or KMIP provider. |
| `trust_anchor` | BACEN's certificate. |
| `license` | The Lerian license server. |
| `runtime_config` | The runtime configuration store. |
| `declaration` | The permission declaration to Access Manager. It reports `skipped` while `IDP_DECLARATION_ENABLED` is `false`. |
| `startup_self_probe` | The startup self-check of the service. |

`GET /version` returns the build version of the service.

## IBM MQ

***

Lerian SRC connects to your institution's own IBM MQ queue manager. That queue manager reaches BACEN over the RSFN.

Set `SRC_MQ_HOST`, `SRC_MQ_PORT`, `SRC_MQ_CHANNEL`, and `SRC_MQ_QUEUE_MANAGER`. Lerian SRC applies no default for the port and the channel, so ask your IBM MQ team for them.

Lerian SRC derives the queue names from `SRC_CNPJ_BASE8`:

* Send queue: `QR.REQ.<CNPJ base>.00038166.03`.
* Receive queue: `QL.RSP.00038166.<CNPJ base>.03`.

Set `SRC_MQ_SEND_QUEUE` and `SRC_MQ_RECEIVE_QUEUE` only when your queue manager uses other names.

While `SRC_MQ_BACKOUT_THRESHOLD` is above `0`, a message that fails delivery that many times moves to the backout queue. The default threshold is 5. The backout queue is the receive queue name followed by `.BACKOUT`, unless you set `SRC_MQ_BACKOUT_QUEUE`. Lerian SRC opens the backout queue when it connects, so create it on the queue manager before you start the service.

When no IBM MQ call completes for `SRC_MQ_STALE_AFTER`, 30 seconds by default, the `src_mq` check reports `degraded`.

The Lerian SRC image runs on `linux/amd64`.

## Credentials and keys

***

Lerian SRC signs each message it sends to BACEN with your institution's private key. It uses BACEN's certificate to protect each message for BACEN.

Lerian SRC uses the private key through PKCS#11 or KMIP. When you configure both, it uses PKCS#11. Set `SRC_LOCAL_CERT_FILE` to your institution's certificate for that key, and `SRC_BACEN_CERT_FILE` to BACEN's certificate. After you replace BACEN's certificate, restart Lerian SRC.

`GET /v1/src/credentials` returns the status of the credential.

## Personal data

***

Lists, search results, and events show the person's document masked, in `documentMasked`. The evidence trail returns the full record, including the document. Lerian SRC records each read of the evidence trail in the same transaction as the read. If it cannot record the read, the read fails.

## Operator cases

***

`GET /v1/src/operator/cases` lists the open cases, newest first. Send `status=closed` for the closed cases, or `status=all` for both. [How Lerian SRC works](/en/rails/src/how-src-works#operator-cases) explains the legs.

Close a case with the operation of its leg:

| Leg | Operation |
| - | - |
| `orphan_response` | `POST /v1/src/operator/orphan-responses/{caseId}/closure` |
| `invalid_outbound` | `POST /v1/src/operator/invalid-dispatches/{caseId}/closure` |

A `budget_exhausted` case has `closable` set to `false`. A closure of a case that is not open returns `404` with code `SRC-0301`.

Watch two numbers on `GET /v1/src/dashboard/consultations`:

* `openOperatorCases`: the operator cases that are open now.
* `pendingBeyondExpected`: the consultations that stay `pending` longer than `src.pending.alert_threshold`, 15 minutes by default.

## Runtime configuration (Systemplane)

***

Lerian SRC serves its runtime configuration admin API at `/v1/system`. [Authentication and permissions](/en/rails/src/src-integration#authentication-and-permissions) names the permission it needs. The admin API accepts 30 requests per minute from each client IP address.

A change takes effect without a restart. The tables list the keys that tune consultations, retries, rate limits, and retention. See [System plane](/en/reference/platform/systemplane/overview).

**Namespace `tenant_policy`**

| Key | What it controls | Default | Range |
| - | - | - | - |
| `src.channel.active` | The channel that carries consultations to BACEN. | `messaging` | `messaging` |
| `src.consultation.protection_types` | The protection types that a consultation can carry. A request with another type returns `422`. | `account_opening,ownership_change` | `account_opening`, `ownership_change` |
| `src.pending.alert_threshold` | How long a consultation can stay `pending` before `pendingBeyondExpected` counts it. | `15m` | `1m` to `168h` |

**Namespace `runtime_config`**

| Key | What it controls | Default | Range |
| - | - | - | - |
| `src.dispatch.max_attempts` | Attempts for each consultation. | `8` | 1 to 20 |
| `src.dispatch.backoff_initial` | Wait before the first retry. | `1m` | `1s` to `1h` |
| `src.dispatch.backoff_ceiling` | Longest wait between two attempts. | `30m` | `1m` to `24h` |
| `src.log.level` | Log level. | `INFO` | `DEBUG`, `INFO`, `WARN`, `ERROR` |
| `src.rate_limit.ip_max` | Requests that one client IP address can send in each window, in each replica. | `6000` | 1 to 1000000 |
| `src.rate_limit.ip_window` | Length of the rate-limit window. | `1m` | `1s` to `1h` |
| `src.retention.transient_purge_age` | Age after which the sweep can delete an idempotency key. | `24h` | `1h` to `720h` |
| `src.retention.transient_purge_batch` | Idempotency keys that one purge statement deletes. | `1000` | 100 to 10000 |
| `src.retention.resolved_orphan_payload_purge_age` | How long a closed orphan-response case keeps the message that Lerian SRC received. | `8760h` | `24h` to `8760h` |

## Storage, outbox and retention

***

Lerian SRC stores its state in PostgreSQL.

Events leave through an outbox table, in the same transaction as the change they report. With no broker, the events stay pending in the outbox.

The retention sweep deletes idempotency keys older than `src.retention.transient_purge_age`, 24 hours by default.

Lerian SRC does not apply its own database schema. The `br-src-migrations` image applies it. Run that image before you start the `br-src` image.

## Metrics and tracing

***

Set `ENABLE_TELEMETRY=true` to export traces and metrics over OTLP to `OTEL_EXPORTER_OTLP_ENDPOINT`. Lerian SRC has no `/metrics` endpoint. See [Observability](/en/platform/observability) for the platform view.

## Deployment posture

***

`DEPLOYMENT_MODE` takes `local`, `byoc`, or `saas`. One deployment serves one institution.

[Environment variables](/en/rails/src/src-environment-variables) defines a production deployment and marks each setting that it requires. A missing required setting stops the boot.


# What is Lerian SRC?
Source: https://docs.lerian.studio/en/rails/src/what-is-lerian-src

Lerian SRC sends your institution's restriction consultations to BACEN's BC Protege+ and records BACEN's verdict for each protection type.

**Lerian SRC** is the Lerian service for **BC Protege+**, a BACEN system. Your institution consults BC Protege+ before it opens an account, and before it changes the ownership of an existing relationship. BC Protege+ answers whether the person or the company has an active restriction.

Lerian SRC exchanges messages with BACEN over the RSFN, through IBM MQ. It sends each consultation as an SRC0001 message. BACEN answers with an SRC0001R1 message, or rejects the consultation with an SRC0001E message.

The API is asynchronous. Lerian SRC accepts a consultation with `202` and the status `pending`. `pending` is a normal state. You read the outcome later, from the API or from an event.

## What Lerian SRC does and does not do

***

**Lerian SRC does:**

* Checks each request before it sends anything to BACEN. It checks the CPF or CNPJ check digits, the document type, the protection types, and the motivation.
* Stores each accepted consultation before it sends the consultation to BACEN.
* Sends the consultation again, within a budget of attempts, when a send fails or BACEN gives a transient rejection.
* Matches each answer and each rejection from BACEN to its consultation, and stores BACEN's verdict for each protection type.
* Keeps BACEN's rejection code as BACEN sent it.
* Records the institution record that your institution files after a consultation with an active restriction.
* Keeps an evidence trail for each consultation.
* Opens an operator case for each situation that your back office must see, such as a message that Lerian SRC refused to send.
* Publishes an event when it accepts a consultation, and when the consultation completes or fails.

**Lerian SRC does not:**

* **Decide on the account.** Lerian SRC records BACEN's verdict and the record that your institution files. It does not approve, block, or score a contract.
* **File an institution record on its own.** Your institution files each record through the API.
* **Connect to Midaz.** Your systems call Lerian SRC and act on the outcome.
* **Serve several institutions from one deployment.** One deployment serves one institution. A client with several institutions runs one deployment for each.

## Who it serves

***

Lerian SRC serves supervised institutions that consult BC Protege+ before they open an account or change the ownership of an existing relationship.

Your onboarding and KYC systems create consultations and read their outcomes. Your back office reads consultations and the evidence trail, files institution records, and works the operator cases.

## Glossary

***

| Term | Meaning |
| - | - |
| **BC Protege+** | The BACEN system that answers restriction consultations. |
| **Consultation** | One request to BC Protege+ about one CPF or CNPJ. |
| **Protection type** | What the consultation asks about: `account_opening`, `ownership_change`, or both. |
| **Verdict** | BACEN's answer for one protection type. `permitted` is `true` when BACEN reports no active restriction for that protection type, and `false` when BACEN reports an active restriction. |
| **Subject role** | The role of the consulted person or company: `individual`, `company`, `holder`, or `representative`. A `holder` or a `representative` consultation links to the consultation of its company. |
| **Motivation** | The reason for a consultation. `motivation.reference` names the event in your system that caused it, such as an account-opening request. |
| **BACEN control code** | The code that BACEN assigns to a consultation that it answers. The API returns it as `bcbControlCode`. |
| **Operation number** | The number your institution assigns to a consultation for BACEN. It starts with your CNPJ base, followed by a date and a sequence number. The API returns it as `regulatoryOperationNumber`. |
| **Institution record** | The record that your institution files after a consultation with an active restriction: an exceptional proceed or a refusal explanation. |
| **Evidence trail** | The records that Lerian SRC keeps about each consultation. |
| **Operator case** | An item in the back-office queue, such as a message that Lerian SRC refused to send. |
| **SRC and SCR** | Lerian SRC is not [Lerian SCR](/en/rails/scr/what-is-lerian-scr), a separate service for a different BACEN system. |

See also [Native messaging and partner interfaces](/en/rails/native-messaging).


# How Lerian STA works
Source: https://docs.lerian.studio/en/rails/sta/how-sta-works

How Lerian STA works: outbound submission and inbound file discovery to BACEN, protocol state machine, SHA-256 integrity, attempt limits and TTL, and operator actions.

Lerian STA moves files in two directions. Each exchange is one **transfer**, a single file that moves between the institution and BACEN. A **protocol number** tracks the transfer through BACEN's protocol lifecycle. Each end verifies the **SHA-256**.

## Outbound submission

***

The institution, or an upstream Lerian product, stores the file in the Lerian STA bucket and creates a transfer whose file reference is `outbound/<file name>`. When `TRANSFER_SCHEDULER_ENABLED` is `true`, a worker computes the file's SHA-256 and size and obtains a protocol number from BACEN that declares them. It uploads the file's bytes. BACEN validates the bytes against the declared SHA-256.

Within the configured deduplication window, a completed request with the same tenant and key replays its cached result and returns `X-Idempotency-Replayed: true`, when that result is available in the idempotency store.

Without the header, Lerian STA derives the key from the source product, the selected credential, the document type, the file reference, and the file name. If your service creates transfers in reaction to an event, send a key derived from that event's identifier. Retries of one trigger then carry the same key.

The transfer advances through BACEN's lifecycle:

| State | Meaning |
| - | - |
| **Protocol generated** | Lerian STA has accepted the transfer. BACEN assigns the protocol number while the transfer is in this state. |
| **Transmission started / finished** | Lerian STA is uploading the bytes, then has uploaded them. |
| **Integrity check** | BACEN is validating the declared SHA-256. |
| **Received** | BACEN has received the file. |
| **Delivered** | BACEN has delivered the file to its destination. |
| **In processing** | BACEN is processing the file. |
| **Accepted** | BACEN has accepted the file. A terminal success. |
| **Inconsistent** | The bytes failed BACEN's integrity check. A terminal failure. |
| **Rejected** | BACEN has refused the file after processing. A terminal failure. |
| **Canceled** | The transfer ended before a BACEN verdict, for example by an operator, at the attempt ceiling, or at the TTL. A terminal state. |
| **Answered out of band** | Lerian STA found a separate inbound reply for the protocol. This local terminal state confirms reply arrival, not whether BACEN accepted or rejected the file; it records audit history but emits no transfer outcome event. |
| **Protocol create unconfirmed** | A local terminal state. Lerian STA cannot confirm that BACEN assigned a protocol. An operator must reconcile it. |
| **Evaluation unconfirmed** | A local terminal state. The TTL ran out while BACEN still owed a verdict. It emits no transfer outcome event. |

At the ceiling, Lerian STA cancels the transfer. Each transfer also carries a wall-clock **TTL** (44 hours by default), counted from when BACEN assigns its protocol. When the TTL runs out, Lerian STA cancels the transfer, or marks it **Evaluation unconfirmed** if BACEN still owed a verdict.

## Inbound discovery and download

***

When `TRANSFER_INBOUND_ENABLED` is `true`, Lerian STA polls BACEN for available files, per active tenant. Each inbound source configuration sets its polling interval, from 15 to 1,800 seconds.

For each file, Lerian STA matches the file's **BACEN system code** against the tenant's **inbound source configurations**. A file that matches none takes the source product `unrouted`. Lerian STA then downloads the bytes. It verifies the bytes against BACEN's reported SHA-256. It stores the file durably in object storage.

When the verified file is a single-entry ZIP archive, Lerian STA extracts the entry and delivers it instead of the archive. The claim-check then describes the extracted file: `object_key`, `file_name`, `size_bytes`, and `sha256` refer to the entry. Lerian STA computes that `sha256` over the extracted bytes. `TRANSFER_INBOUND_EXTRACT_MAX_EXPANSION_RATIO` and `TRANSFER_INBOUND_EXTRACT_MAX_EXTRACTED_BYTES` bound the extracted size. When Lerian STA does not extract an entry, it delivers the file as received. The claim-check then carries the hash and size that BACEN reported.

When the hash does not match, Lerian STA makes up to 3 attempts by default, then ends the transfer as inconsistent. When a download fails, it makes up to 5 attempts by default, then cancels the transfer. When BACEN refuses to authorize the download, the transfer ends as not authorized at once. In each case, Lerian STA does not deliver the file to its source product.

## Operator actions

***

An operator can act only where the transfer's state and configuration permit it:

* **Cancel** when the state machine permits a transition to `Canceled`, which excludes **Integrity check** and **Delivered**. The cancel is local. Lerian STA sends nothing to BACEN.
* **Retry** an outbound transfer when it is non-terminal, has fewer than 5 upload attempts, and its TTL has not expired. This threshold stays at 5 whatever the configured ceiling. Each retry counts as one attempt.
* **Mark urgent**, when `TRANSFER_INBOUND_ENABLED` is `true`, an inbound transfer in `AvailableForDownload` whose source product has urgency enabled on every enabled configuration. It fails closed otherwise.


# Environment variables
Source: https://docs.lerian.studio/en/rails/sta/sta-environment-variables

Deploy-time environment variables for Lerian STA: the BACEN environment target, S3-compatible object storage, and envelope-encryption master keys.

Lerian STA is the Lerian-owned rail that transmits and receives files with the BACEN STA hub. You set these variables at deploy time. A service restart makes them take effect. Every Lerian Go service shares a universal backbone: server, datastores, telemetry, and plugin authentication. [BYOC configuration essentials](/en/reference/byoc-configuration) documents that backbone once. This page covers the variables distinctive to Lerian STA.

To install or upgrade Lerian STA, see the [Lerian STA chart README](https://github.com/LerianStudio/helm/tree/main/charts/br-sta).

In the tables below, the **Default / Required** column shows the default value. A bold qualifier marks a variable you must set, such as **Required** or **Required in production**. `—` means no default. A variable flagged **Sensitive** carries credential or key material. Inject it from your secret manager at deploy time. Never commit a value.

## Service and runtime

| Variable | Default / Required | Description |
| - | - | - |
| `SERVER_ADDRESS` | `:4028` | Main HTTP listen address. The liveness, readiness, metrics, and version probes bind this same port. |
| `DEPLOYMENT_MODE` | `local` | Deployment model: `local`, `byoc`, or `saas`, in any letter case. Another value stops the boot. With `saas`, the boot fails when a configured connection to PostgreSQL, Redis, RabbitMQ, object storage, the streaming brokers, or Tenant Manager does not require TLS. |
| `PLUGIN_AUTH_ENABLED` | **Required** | `true` or `false`. A blank value or another value stops the boot. `true` turns on authorization through Lerian Access Manager. Lerian STA accepts `false` only when `ENV_NAME` is `development`, `develop`, `dev`, `local`, or `test`, and `DEPLOYMENT_MODE` is not `saas`. With `false`, each gated request still needs a bearer token that names a principal, and Lerian STA skips only the Access Manager call. |
| `PLUGIN_AUTH_HOST` | **Required** when `PLUGIN_AUTH_ENABLED` is `true` | Lerian Access Manager address. |
| `SYSTEMPLANE_ENABLED` | `false` | Enable the [Systemplane](/en/reference/platform/systemplane/overview) runtime-configuration admin API under the `/system` prefix on the main port. Off by default (environment-variable-only mode). |
| `DEFAULT_TENANT_ID` | `11111111-1111-1111-1111-111111111111` | UUID fallback used only for the streaming/outbox `ce-tenantid` when an event has no tenant ID. |
| `BACEN_ENVIRONMENT` | `homologation` | Selects the BACEN STA environment that every BACEN call targets: `homologation` (staging) or `production` (live). An unrecognized value falls back to `homologation` so a non-production stack cannot route traffic to the live BACEN service. |
| `SCHEDULER_ENABLED` | `false` | Run the worker's scheduled jobs, including the outbound status pollers, the credential sweep for stuck rotations, and the deletion of canceled and inconsistent transfers after 7 days. |

> [!NOTE]
>
> Lerian STA exposes `/health` (liveness) and `/readyz` (readiness) on the main port, plus `/version` and `/metrics`. See [Health and readiness](/en/reference/health-and-readiness) for the probe contract.

## License

| Variable | Default / Required | Description |
| - | - | - |
| `LICENSE_FILE_PATH` | **Required** without `LICENSE_KEY` | Path of the signed license file that Lerian issues. Lerian STA verifies the file locally and does not call the [license service](/en/platform/licensing/license-manager). If the file does not license Lerian STA, the boot fails. Lerian STA does not try `LICENSE_KEY` instead. Lerian STA reads the file again about once an hour, so a renewed file takes effect without a restart. The file contains the license key, so store it in a secret. In Kubernetes, mount that Secret as a directory, without `subPath`, because Kubernetes does not update a `subPath` mount. |
| `LICENSE_KEY` | **Required** without `LICENSE_FILE_PATH` | License key issued by Lerian. Lerian STA ignores it when `LICENSE_FILE_PATH` is set. Sensitive. |
| `ORGANIZATION_IDS` | **Required** | Organization scope the license covers. |

## Transfers

| Variable | Default / Required | Description |
| - | - | - |
| `TRANSFER_SCHEDULER_ENABLED` | `false` | Run the worker loop that uploads outbound transfers to BACEN. While it is `false`, Lerian STA accepts and stores new outbound transfers but sends none of them. |
| `TRANSFER_INBOUND_ENABLED` | `false` | Enable the inbound (BACEN-pulled) transfer pipeline. It does not change the production bucket requirement because outbound transfers also use the bucket. |
| `TRANSFER_MAX_ATTEMPTS` | `5` | Attempts an outbound transfer gets before Lerian STA cancels it, from 1 to 10. Runtime key: `sta.upload.max_attempts`. |
| `TRANSFER_TTL_HOURS` | `44` | Wall-clock lifetime of an outbound transfer after BACEN assigns its protocol, from 1 to 44 hours. Runtime key: `sta.upload.ttl_hours`. |
| `TRANSFER_MAX_FILE_SIZE_BYTES` | `5368709120` | Maximum size of the file a new outbound transfer references, in bytes (5 GiB). |

## Object storage

Lerian STA persists transfer bytes and inbound downloads to an S3-compatible object store.

| Variable | Default / Required | Description |
| - | - | - |
| `TRANSFER_OBJECT_STORAGE_BUCKET` | **Required in production** | Bucket holding both transfer directions. Production boot is refused if it is empty, regardless of whether inbound transfers are enabled. |
| `TRANSFER_S3_REGION` | `us-east-1` | Region of the transfer bucket. |
| `TRANSFER_S3_ENDPOINT` | — | Endpoint of an S3-compatible store, such as MinIO. Leave unset for AWS S3. |
| `TRANSFER_S3_PATH_STYLE` | `false` | Use path-style addressing, which most S3-compatible stores require. |
| `TRANSFER_INBOUND_MAX_FILE_SIZE_BYTES` | `5368709120` | Maximum BACEN-advertised inbound file size, in bytes (5 GiB). A value of `0` or less disables this admission bound. |
| `TRANSFER_INBOUND_EXTRACT_MAX_EXPANSION_RATIO` | `100` | Maximum ratio between the extracted entry size and its delivered ZIP envelope. A value of `0` or less disables the ratio check. |
| `TRANSFER_INBOUND_EXTRACT_MAX_EXTRACTED_BYTES` | `5368709120` | Absolute maximum size of the single extracted ZIP entry, in bytes (5 GiB). A value of `0` or less disables this bound. |
| `AWS_REGION` | — | Region for M2M AWS Secrets Manager (`us-east-1` when unset) and, when `MASTER_KEY_KMS_REGION` is empty, for AWS KMS. It does not configure object storage. |
| `AWS_ACCESS_KEY_ID` | — | Access key for the object store. Sensitive. Leave unset when an attached IAM role supplies credentials. |
| `AWS_SECRET_ACCESS_KEY` | — | Secret key for the object store. Sensitive. Leave unset when an attached IAM role supplies credentials. |

## Envelope encryption

Lerian STA protects operator credentials with AES-GCM envelope encryption. Every Lerian STA process needs the master-key material. A missing or malformed value aborts boot.

| Variable | Default / Required | Description |
| - | - | - |
| `MASTER_KEY_PROVIDER` | `envvar` | Source of the envelope-encryption key: `envvar` (key read from `MASTER_KEYS`) or `aws-kms` (key wrapped by a cloud KMS). |
| `MASTER_KEY_VERSION` | **Required** | Selects the currently active master-key version. Must match a version present in `MASTER_KEYS`. |
| `MASTER_KEYS` | **Required** | Comma-separated `version:key` pairs. Sensitive. With `envvar`, each value is a 64-hex-character AES-256 key: `version:<64-hex-key>`. With `aws-kms`, each value is base64 KMS ciphertext: `version:<base64-ciphertext>`, decrypted in process. Source from your secret manager. A missing or malformed value aborts boot. |
| `MASTER_KEY_KMS_KEY_ID` | **Required if `aws-kms`** | Identifier of the AWS KMS key used to decrypt the `MASTER_KEYS` ciphertext. With `aws-kms`, the ciphertext is decrypted in the STA process. |
| `MASTER_KEY_KMS_REGION` | — | Region of the AWS KMS key. When empty, Lerian STA uses `AWS_REGION`. |
| `CREDENTIALS_RECOVERY_ON_BOOT` | `false` | Set explicitly to `true` to run the worker-side credential-recovery sweep once at boot for credentials left mid-rotation by a previous process. |

> [!NOTE]
>
> Lerian STA runs its audit pipeline in a dedicated worker. The export generator also needs its S3 bucket.
>
> Configure the enabled flags and required knobs through the `AUDIT_PUBLISHER_*`, `AUDIT_CONSUMER_*`, `AUDIT_PARTITION_*`, `AUDIT_CLEANUP_*`, `AUDIT_VERIFIER_*`, `AUDIT_EXPORT_GENERATOR_*`, and `AUDIT_EXPORT_RATE_LIMIT_*` families. The runtime applies their declared defaults. The partition manager runs by default. Enable each other job before you expect it to run.

## Streaming

Lerian STA and the Lerian streaming library read the `STREAMING_` family. [Lerian Streaming Hub](/en/platform/streaming-hub/what-is-streaming-hub) delivers the published events.

| Variable | Default / Required | Description |
| - | - | - |
| `STREAMING_ENABLED` | `false` | Master switch for business-event emission to the streaming brokers. It also needs `BUSINESS_EVENTS_ENABLED` and `RABBITMQ_ENABLED`, both `true` by default. While it is off, the service sends no event to the brokers. |
| `STREAMING_BROKERS` | **Required** when streaming is on | Comma-separated broker bootstrap list. An enabled configuration with an empty list refuses to boot. |
| `STREAMING_CLOUDEVENTS_SOURCE` | `br-sta` (fixed) | This service's CloudEvents source. It sets the topic namespace and the event-type prefix. Leave it unset. Any non-empty value other than `br-sta` refuses the boot, even when streaming is off. |
| `STREAMING_CLIENT_ID` | `br-sta` | Broker client identifier used for broker-side diagnostics. |
| `STREAMING_CB_FAILURE_RATIO` | `0.5` | Failure ratio that opens the producer circuit breaker. With streaming on, a value of 0 or less, or above 1, refuses the boot. |
| `STREAMING_CB_MIN_REQUESTS` | `10` | Minimum requests before the producer circuit breaker evaluates the failure ratio. |
| `STREAMING_CB_TIMEOUT_S` | `30` | Open-state cooldown in seconds for the producer circuit breaker. |
| `STREAMING_CLOSE_TIMEOUT_S` | `30` | Maximum drain and flush window in seconds when the producer closes. |
| `STREAMING_TOPIC_AUTO_PROVISION` | `true` | With streaming on, the service creates its event topic `lerian.streaming.br-sta` and its dead-letter topic `lerian.streaming.br-sta.dlq` on the brokers at startup when they do not exist. A failed creation logs a warning and the boot continues. Set it to `false` when you create the topics in advance. |
| `STREAMING_TOPIC_PARTITIONS` | `-1` | Partition count for a topic the service creates. A value below 1 uses the broker default. |
| `STREAMING_TOPIC_REPLICATION_FACTOR` | `-1` | Replication factor for a topic the service creates. A value below 1 uses the broker default. |
| `STREAMING_TLS_ENABLED` | `false` (**Required** as `true` with `DEPLOYMENT_MODE=saas` when streaming is on) | Turns on TLS for the broker dial. The minimum version is TLS 1.2. |
| `STREAMING_TLS_CA_CERT` | — | PEM certificate authority for a private or on-premises broker, as plain or base64-encoded PEM. It applies when `STREAMING_TLS_ENABLED` is `true`. An empty value uses the host trust store. |
| `STREAMING_SASL_MECHANISM` | — | Broker authentication mechanism: `PLAIN`, `SCRAM-SHA-256`, or `SCRAM-SHA-512`. An empty value disables broker authentication. With streaming on, a mechanism without its credentials, or without `STREAMING_TLS_ENABLED=true`, refuses the boot. |
| `STREAMING_SASL_USERNAME` | — | Broker authentication username. |
| `STREAMING_SASL_PASSWORD` | — | Broker authentication password. Sensitive. |

## Reporter filings

These variables control the consumer that files Reporter's approved regulatory reports at BACEN. See [Regulatory filings from Reporter](/en/rails/sta/sta-integration#regulatory-filings-from-reporter).

| Variable | Default / Required | Description |
| - | - | - |
| `REPORTER_EVENTS_CONSUMER_ENABLED` | `false` | Consume the regulatory filing approvals from Reporter and file the approved reports at BACEN. |
| `REPORTER_EVENTS_CONSUMER_EXCHANGE` | **Required if the consumer is enabled** | Reporter events exchange that the consumer binds to. |
| `REPORTER_EVENTS_DOCTYPE_RESOLVER` | **Required if the consumer is enabled** | How Lerian STA gets the BACEN document type of a report. Set `payload` to read it from the event. |


# Integrating with Lerian STA
Source: https://docs.lerian.studio/en/rails/sta/sta-integration

Integrating with Lerian STA: transactional-outbox audit and business records, inbound claim-checks, and source-product routing.

Lerian STA is event-first at its edges. A transition to one of the six outcomes below writes the state change, an audit record, and a business record in one database transaction, through a **transactional outbox**. Consumers are the **source-product** services that own the files Lerian STA delivers.

## Event channels

***

Lerian STA publishes on these channels:

* An **audit channel** carrying the Lerian STA audit trail: credential changes, transfer state changes, operator actions, and inbound file outcomes. It feeds the Lerian STA audit log and runs when `AUDIT_PUBLISHER_ENABLED` is `true`.
* A **signed business channel**, routed as `sta.{direction}.{sanitized-source-product}` with an `unrouted` fallback, for external product consumers. It carries six terminal transfer outcomes. The payload field `status` names the state (`Accepted`, `Rejected`, `Inconsistent`, `Canceled`, `DownloadFinished`, or `NotAuthorized`), and `outcome` reads `SUCCESS`, `FAILURE`, or `CANCELED`. It also carries the Reporter filing outcomes, routed by outcome name.
* The **event stream**, when `STREAMING_ENABLED` is `true`. It carries the same outcomes as CloudEvents of type `studio.lerian.br-sta.br_sta_transfers.<event>`, where `<event>` is `accepted`, `rejected`, `inconsistent`, `canceled`, `download_finished`, or `download_not_authorized`.

Business events carry an `error_code` only for failed and canceled outcomes, and an operator cancel leaves it empty. Inbound-success events carry the **claim-check**.

## The claim-check

***

On a completed inbound download, Lerian STA emits its terminal **download-finished** event, routed by the file's source product. The event carries a **claim-check** (`object_key`, `sha256`, `size_bytes`, and `file_name`), but not the bytes themselves. For inbound terminal facts, `document_code` carries the observed BACEN code. When the persisted mnemonic and code corroborate each other, `document_type` carries the mnemonic. Otherwise it retains the code for compatibility. An operator cancel of an inbound transfer carries neither field.

The consuming domain product subscribes to its own key. It fetches the durable artefact by its object key and re-verifies the SHA-256. It then processes the file. Lerian STA is the transport and integrity boundary. The consuming product owns the ledger posting.

## Ledger boundary

***

Lerian STA does not write to the client's ledger itself. It delivers the file and the claim-check. The consuming product owns any ledger posting. For example, the Lerian SISBAJUD Mensageria reads the judicial order files, and the Lerian SISBAJUD executor runs the orders on Midaz. This keeps Lerian STA a pure transport-and-integrity layer, independent of any one file's business meaning.

## Regulatory filings from Reporter

***

When `REPORTER_EVENTS_CONSUMER_ENABLED` is `true`, Lerian STA consumes the [`regulatory.filing_approved`](/en/reference/events/reporter) event from Reporter. It files the approved report at BACEN as an outbound transfer. Before it sends the report, Lerian STA compares the stored file with the `artifact_sha256` of the event.

Lerian STA reports the result of a filing as a filing outcome. It publishes the outcome on the signed business channel, with the outcome name as the routing key. When `STREAMING_ENABLED` is `true`, it also publishes the outcome on the event stream.

| Outcome | Business routing key | Event stream type | Meaning |
| - | - | - | - |
| Delivered | `sta.filing.delivered` | `studio.lerian.br-sta.br_sta_filings.delivered` | BACEN accepted the file and issued a protocol. |
| Refused | `sta.filing.refused` | `studio.lerian.br-sta.br_sta_filings.refused` | The filing did not reach BACEN, or BACEN refused it. |

Both outcomes carry `report_id`, `document_id`, `document_version`, `event_id`, and `source_event_id`. `source_event_id` is the CloudEvent id of the approval, when the approval has one. A delivered outcome adds `channel`, `protocol`, and `delivered_at`, the time when Lerian STA observed the acceptance. A refused outcome adds `refused_at` and `reason`. The `reason` is `checksum_mismatch`, `digest_missing`, `credential_unavailable`, `malformed_approval`, `rejected_by_regulator`, `inconsistent_transfer`, `canceled`, or `transfer_failed`.

## Integration conventions

***

* **Commit-coupled events.** A record written with a state change becomes available only after that change commits.
* **Claim-check, not payload.** Consumers receive a reference to the durable artefact, fetch it, and re-verify its SHA-256 before acting on it.
* **At-least-once delivery.** Deduplicate on the payload `event_id`, which stays the same for one terminal fact.
* **Keyed subscription.** Clients choose their broker subscriptions. STA routes signed transfer outcomes by direction and sanitized source product, with an `unrouted` fallback. It does not enforce that only one subscriber can receive a file.


# Operating Lerian STA
Source: https://docs.lerian.studio/en/rails/sta/sta-operations

Operating Lerian STA: optional database-per-tenant isolation, BACEN operator credentials, three-phase password rotation, and protocol reconciliation.

Three realities of BACEN's file hub shape Lerian STA. Per-institution credentials expire, each outbound transfer has a bounded lifetime, and BACEN does not make the protocol-create step idempotent. Lerian STA manages each one under its selected tenancy mode. It reconciles at the grain of the BACEN protocol number.

## Pollers

***

When `SCHEDULER_ENABLED` is `true`, the scheduler runs a status poller on a roughly one-minute resync. Outbound status polling self-enqueues with a state-keyed backoff.

Lerian STA holds all credentials of one institution to one budget of 10 simultaneous file transfers and 10 commands per minute, which password rotation shares. It reserves 20 queries per minute for inbound discovery by default.

## Credentials

***

Each credential is a BACEN **operator password**. Lerian STA identifies it by institution code and operator ID. Lerian STA stores it encrypted with envelope encryption. Operators can create, update, test connectivity for, rotate, and revoke a credential. An update changes only the operator ID or the description.

### Which credential a transfer uses

A create-transfer request selects its BACEN credential in one of three ways. Lerian STA applies the first one that the request carries:

1. `credentialId`: Lerian STA uses that credential.
2. `institutionCode` without `credentialId`: Lerian STA uses the one non-revoked credential of that institution.
3. Neither field: Lerian STA uses the one non-revoked credential of the tenant.

The `201` response carries the `credentialId` that Lerian STA used. To leave a field unset, omit it or send `null`. An empty string returns `400` with `STA-0014`.

| Code | Status | When |
| - | - | - |
| `STA-0105` | 422 | The request has neither field, and the tenant has no non-revoked credential. |
| `STA-0106` | 422 | The request has no `credentialId`, and more than one non-revoked credential is a candidate. |
| `STA-0107` | 422 | No non-revoked credential matches `institutionCode`. |
| `STA-0005` | 404 | `credentialId` names no credential. |
| `STA-0007` | 409 | The selected credential is not active, for example during a password rotation. |

A `409` during a password rotation is not permanent. Retry the same request after a backoff.

## Password rotation

***

Rotation is a three-phase protocol that keeps the old and the new password until BACEN confirms one of them:

1. **Stage** the new password locally.
2. **Change** it at BACEN.
3. **Promote** it locally.

A **recovery sweep** resolves rotations left in flight. It runs once at worker boot when `CREDENTIALS_RECOVERY_ON_BOOT` is `true`, and on each credential sweep when `SCHEDULER_ENABLED` is `true`. If BACEN accepts neither the old nor the new password, Lerian STA locks the credential in an error state for a manual credential reset.

## Password-expiry monitoring

***

BACEN enforces periodic password changes. Lerian STA tracks each credential's BACEN-reported expiry through a read-through cache. It projects a **health band** with the days remaining. The bands are healthy above 15 days, warning from 6 to 15, critical from 1 to 5, and expired at 0 or below. An operator can then rotate the password before BACEN locks the operator out.

## Retention and protocol TTL

***

* **Outbound protocol TTL.** Each outbound transfer has a wall-clock lifetime, counted from when BACEN assigns its protocol. The default is 44 hours (`TRANSFER_TTL_HOURS`).
* **Canceled and inconsistent transfers.** When `SCHEDULER_ENABLED` is `true`, Lerian STA deletes them once their last state change is more than 7 days old (`SCHEDULER_QUARANTINE_RETENTION_DAYS`).
* **Inbound retention.** A lifecycle policy on the bucket controls how long inbound files stay.

## Reconciliation and contingency

***

Lerian STA reconciles at the grain of one transfer per BACEN protocol number. On discovery, the protocol number is the idempotency key: a protocol already on record creates no second transfer.

BACEN offers no idempotent protocol-create. A second create can duplicate the file at BACEN. When a transfer has a durable create-attempt marker but no protocol number, Lerian STA parks it in **Protocol create unconfirmed**. An operator must reconcile that attempt. Lerian STA does not repeat the marked create.


# What is Lerian STA?
Source: https://docs.lerian.studio/en/rails/sta/what-is-lerian-sta

Lerian STA is your client-owned integration to BACEN's STA file-exchange hub: two-way regulatory file transport with SHA-256 integrity and terminal events.

**Lerian STA** is the client-owned messaging integration between a financial institution and **BACEN's STA (Sistema de Transferência de Arquivos)**, the Banco Central file-exchange hub. It moves regulatory and operational files in both directions. The institution submits files to BACEN (outbound), and BACEN makes files available for the institution to download (inbound).

Lerian STA authenticates every exchange with a stored BACEN operator credential for the institution. It validates BACEN's public TLS chain through the system root pool and attaches no client certificate. It drives each transfer through BACEN's protocol state machine and verifies file integrity by SHA-256. It stores inbound artefacts durably and can publish terminal-state facts through separate audit and business channels for consumers. It is API- and event-first. For discovered inbound files, STA resolves `source_product` from the configured source filter. Files without a match are marked `unrouted`.

## What Lerian STA does and does not do

***

* It is the **transport and integrity boundary** between the institution and BACEN's file hub. It moves the bytes, authenticates the exchange, verifies the SHA-256, and records the outcome. It does not interpret the file's business content.
* It **does not post to a ledger**. On a completed inbound download, Lerian STA publishes a terminal-state event that carries a claim-check. The consuming domain product (for example, [Lerian SISBAJUD](/en/rails/sisbajud/what-is-lerian-sisbajud)) fetches the artefact and processes its content. The consumer owns any ledger posting.

## Who it serves

***

Lerian STA serves financial institutions that operate on BACEN rails and need a governed, auditable path for file exchange with the Banco Central.

Downstream, it serves the Lerian products that consume the files it delivers.

## Glossary

***

| Term | Meaning |
| - | - |
| **Lerian STA** | Lerian's client-owned integration to BACEN's file-exchange hub (Sistema de Transferência de Arquivos). |
| **Transfer** | One inbound or outbound exchange of a single file between the institution and BACEN, tracked through its lifecycle. |
| **Outbound transfer** | A file the institution submits to BACEN. |
| **Inbound transfer** | A file BACEN makes available for the institution to download. |
| **Protocol number** | The BACEN-assigned identifier for a transfer; the reconciliation and idempotency key. |
| **Inbound source configuration** | A per-tenant policy binding a BACEN system code to a source product, with its polling cadence and credential. |
| **Credential** | An encrypted BACEN operator password, identified by institution code and operator ID. |
| **Password rotation** | The three-phase change of a BACEN password: stage, change at BACEN, promote locally. |
| **Claim-check** | The `object_key`, `sha256`, `size_bytes`, and `file_name` carried on an inbound-success event so a consumer can fetch and re-verify the artefact. `document_code` carries the observed BACEN code; `document_type` carries the corroborated mnemonic or retains the code for compatibility. |
| **Source product** | The downstream product a discovered inbound file is routed to (for example, Lerian SISBAJUD). |
| **Lerian SISBAJUD** | The judicial asset-order product. Its Mensageria component consumes Lerian STA inbound-file events. |

For how Lerian STA sits alongside the other native rails and the partner interfaces, see [Native messaging and partner interfaces](/en/rails/native-messaging).


# What are Brazil Rails?
Source: https://docs.lerian.studio/en/rails/what-are-brazil-rails

The Brazil Rails tab documents Brazil's national payment and regulatory systems, and the Lerian native messaging that reaches each one.

**Brazil Rails** is the home of the rails. A rail is a national system that moves money or regulatory data under a defined messaging contract. The Central Bank of Brazil (BACEN) operates these systems, or market infrastructures operate them under its supervision. You keep ownership of your ledger, your data, and your business logic.

## How this section is organized

***

This tab holds one anchor per rail, with that rail's own pages. Its last anchor, [Interfaces](/en/interfaces/introduction), documents the Lerian and partner interfaces that reach each rail.

## Two ways to connect

***

**Native messaging** is a Lerian-owned connection straight to BACEN and to the market infrastructures under its supervision. A **partner interface** reaches the same rail through a connectivity provider's systems. Pix Lerian v1.0.0 is an application-plugin integration/testing lane with the mock provider adapter. Its native SPI connector is not available for use in this release.

See [Interfaces](/en/interfaces/introduction) for every interface Lerian offers.

## The rails

***

| Rail | System | Lerian native messaging |
| - | - | - |
| [SPB (TED)](/en/rails/spb/what-is-lerian-spb) | Sistema de Pagamentos Brasileiro | Lerian SPB |
| [SPI (Pix)](/en/rails/spi/what-is-lerian-spi) | Sistema de Pagamentos Instantâneos | Lerian SPI (not available for Pix Lerian v1.0.0) |
| [SLC](/en/rails/slc/what-is-lerian-slc) | Serviço de Liquidação Centralizada (Núclea) | Lerian SLC |
| [SILOC](/en/rails/siloc/what-is-lerian-siloc) | Sistema de Liquidação Diferida (Núclea) | Lerian SILOC |
| [STA](/en/rails/sta/what-is-lerian-sta) | Sistema de Transferência de Arquivos | Lerian STA |
| [SISBAJUD](/en/rails/sisbajud/what-is-lerian-sisbajud) | Sistema de Busca de Ativos do Poder Judiciário | Lerian SISBAJUD |
| [CCS](/en/rails/ccs/what-is-lerian-ccs) | Cadastro de Clientes do Sistema Financeiro Nacional | Lerian CCS |
| [SCR](/en/rails/scr/what-is-lerian-scr) | Sistema de Informações de Crédito | Lerian SCR |
| [BC Correios](/en/rails/bc-correios/what-is-lerian-bc-correios) | BC Correio (Sisbacen) | Lerian BC Correios |
| [SRC](/en/rails/src/what-is-lerian-src) | BC Protege+ | Lerian SRC |
| [Consignado CLT (Dataprev)](/en/rails/consignado/what-is-lerian-consignado) | Dataprev | Lerian Consignado |

> **[Native messaging and partner interfaces](/en/rails/native-messaging)**
>
> How the two connection models compare, and the Lerian native rails.

> **[Interfaces](/en/interfaces/introduction)**
>
> Every interface Lerian offers, with its API, its ledger integration, and its operator workflows.


# Integration diagrams
Source: https://docs.lerian.studio/en/diagrams/introduction

Sequence diagrams that show how messages, Lerian products and market infrastructures combine into a business journey.

An integration diagram shows one business journey from start to finish: who sends each message, who receives it, in which order, and what proves that the journey finished. A journey is organized by what your institution wants to achieve, not by rail, so one diagram can cross several rails and infrastructures.

## How the tab is organized

***

* **[Lerian Products](/en/diagrams/lerian-products/overview).** Journeys across Lerian products. Lerian's product documentation is the reference.
* **[Native rails](/en/diagrams/native-rails/overview).** Journeys on Lerian's native messaging with BACEN and Núclea. The regulator's manuals prevail.
* **[Partner interfaces](/en/diagrams/partner-interfaces/overview).** Payment journeys through a partner interface. The partner's documentation prevails.
* **[Market infrastructures](/en/diagrams/market-infrastructures/overview).** Treasury and securities journeys in Selic and B3, which are not Lerian products. Their manuals prevail.

## How to read a diagram

***

* **Columns.** Each column is a participant. Your institution is on the left, Lerian modules are yellow, market infrastructures are black, BACEN systems are blue, and other parties have a dashed border.
* **Rows.** Each row is one message or one action, top to bottom in time order. The number on the row matches the step table below the diagram.
* **Arrows.** A solid arrow starts something. A dashed blue arrow answers an earlier row.
* **Notes.** A yellow box on a column is an action inside that participant, with no message.
* **Messages.** Each message appears by its code from the official catalog. The [message index](/en/diagrams/message-index) lists every code and the journeys that use it.
* **Endpoints.** In the native rail journeys, a row between your institution and the Lerian column shows, under the message, the endpoint or the event your institution uses, unless the step is pending. The table under the diagram links each endpoint to the API reference.
* **Pending.** A gray dashed arrow marked pending is a step that the Lerian API does not cover yet.

## In construction

***

Some journeys are listed before their diagram is ready, so you can see the full map. Those pages say so at the top.


# Create accounts and transact in Midaz
Source: https://docs.lerian.studio/en/diagrams/lerian-products/midaz-create-and-transact

From organization and ledger to a posted transaction in Midaz.

Set up the ledger structure and post the first transaction.

> [!NOTE]
>
> This journey is in construction. The page shows where it sits in the tab; the diagram and steps come in a later update.


# Lerian product journeys
Source: https://docs.lerian.studio/en/diagrams/lerian-products/overview

Journeys that combine Lerian products, such as Midaz and Tracer, into one business flow.

These diagrams show how Lerian products work together in a business journey. They describe the behavior of our own products and APIs, so the product documentation and the API reference are the source for every step. Lerian supports these flows as part of the products.

## Journeys

***

**Midaz**

* [Create accounts and transact in Midaz](/en/diagrams/lerian-products/midaz-create-and-transact): From organization and ledger to a posted transaction in Midaz.

**Tracer**

* [Validate a transaction before the ledger](/en/diagrams/lerian-products/tracer-validate-before-ledger): How Tracer evaluates a transaction and returns ALLOW, DENY or REVIEW before Midaz posts it.


# Validate a transaction before the ledger
Source: https://docs.lerian.studio/en/diagrams/lerian-products/tracer-validate-before-ledger

How Tracer evaluates a transaction and returns ALLOW, DENY or REVIEW before Midaz posts it.

Decide on each transaction before it reaches the ledger.

> [!NOTE]
>
> This journey is in construction. The page shows where it sits in the tab; the diagram and steps come in a later update.


# Message index
Source: https://docs.lerian.studio/en/diagrams/message-index

Every message code used in the integration diagrams and the journeys where it appears.

Find a message by its code to see every journey that uses it. Codes follow the official catalogs of BACEN, Núclea and B3.

| Message | Journeys |
| - | - |
| `ASLC022` | [Receive card receivables at the domicile](/en/diagrams/native-rails/receive-receivables-at-domicile) |
| `ASLC023` | [Receive card receivables at the domicile](/en/diagrams/native-rails/receive-receivables-at-domicile) |
| `ASLC024` | [Receive card receivables at the domicile](/en/diagrams/native-rails/receive-receivables-at-domicile) |
| `ASLC025` | [Receive card receivables at the domicile](/en/diagrams/native-rails/receive-receivables-at-domicile) |
| `ASLC027` | [Register receivables as collateral](/en/diagrams/native-rails/register-receivables-collateral) |
| `ASLC029` | [Register receivables as collateral](/en/diagrams/native-rails/register-receivables-collateral) |
| `ASLC031` | [Register receivables as collateral](/en/diagrams/native-rails/register-receivables-collateral), [Settle anticipated receivables in real time](/en/diagrams/native-rails/settle-anticipated-receivables) |
| `ASLC032` | [Settle anticipated receivables in real time](/en/diagrams/native-rails/settle-anticipated-receivables) |
| `ASLC033` | [Settle anticipated receivables in real time](/en/diagrams/native-rails/settle-anticipated-receivables) |
| `ASLC041` | [Receive card receivables at the domicile](/en/diagrams/native-rails/receive-receivables-at-domicile) |
| `ASLC042` | [Receive card receivables at the domicile](/en/diagrams/native-rails/receive-receivables-at-domicile) |
| `DDA0101` | [Collect trade bills and boletos](/en/diagrams/native-rails/collect-trade-bills-and-boletos) |
| `GEN0015` | [Receive card receivables at the domicile](/en/diagrams/native-rails/receive-receivables-at-domicile) |
| `LDL0006` | [Recalculate after a default](/en/diagrams/native-rails/recalculate-after-a-default) |
| `LDL0006R2` | [Recalculate after a default](/en/diagrams/native-rails/recalculate-after-a-default) |
| `LDL0020` | [Receive card receivables at the domicile](/en/diagrams/native-rails/receive-receivables-at-domicile), [Collect trade bills and boletos](/en/diagrams/native-rails/collect-trade-bills-and-boletos), [Recalculate after a default](/en/diagrams/native-rails/recalculate-after-a-default) |
| `LDL0020R2` | [Receive card receivables at the domicile](/en/diagrams/native-rails/receive-receivables-at-domicile), [Collect trade bills and boletos](/en/diagrams/native-rails/collect-trade-bills-and-boletos), [Recalculate after a default](/en/diagrams/native-rails/recalculate-after-a-default) |
| `LDL0021` | [Receive card receivables at the domicile](/en/diagrams/native-rails/receive-receivables-at-domicile), [Collect trade bills and boletos](/en/diagrams/native-rails/collect-trade-bills-and-boletos), [Pay the net debit position](/en/diagrams/native-rails/pay-the-net-debit-position), [Recalculate after a default](/en/diagrams/native-rails/recalculate-after-a-default) |
| `LDL0022` | [Collect trade bills and boletos](/en/diagrams/native-rails/collect-trade-bills-and-boletos), [Pay the net debit position](/en/diagrams/native-rails/pay-the-net-debit-position), [Recalculate after a default](/en/diagrams/native-rails/recalculate-after-a-default) |
| `LDL0022R1` | [Pay the net debit position](/en/diagrams/native-rails/pay-the-net-debit-position), [Recalculate after a default](/en/diagrams/native-rails/recalculate-after-a-default) |
| `LTR0001` | [Settle anticipated receivables in real time](/en/diagrams/native-rails/settle-anticipated-receivables), [Recalculate after a default](/en/diagrams/native-rails/recalculate-after-a-default) |
| `LTR0002` | [Settle anticipated receivables in real time](/en/diagrams/native-rails/settle-anticipated-receivables), [Recalculate after a default](/en/diagrams/native-rails/recalculate-after-a-default) |
| `LTR0004` | [Settle anticipated receivables in real time](/en/diagrams/native-rails/settle-anticipated-receivables), [Recalculate after a default](/en/diagrams/native-rails/recalculate-after-a-default) |
| `LTR0004R1` | [Recalculate after a default](/en/diagrams/native-rails/recalculate-after-a-default) |
| `LTR0005` | [Settle anticipated receivables in real time](/en/diagrams/native-rails/settle-anticipated-receivables), [Recalculate after a default](/en/diagrams/native-rails/recalculate-after-a-default) |
| `LTR0005R2` | [Settle anticipated receivables in real time](/en/diagrams/native-rails/settle-anticipated-receivables), [Recalculate after a default](/en/diagrams/native-rails/recalculate-after-a-default) |
| `LTR0006` | [Settle anticipated receivables in real time](/en/diagrams/native-rails/settle-anticipated-receivables) |
| `LTR0007` | [Settle within the same bank](/en/diagrams/native-rails/settle-within-the-same-bank) |
| `LTR0008` | [Settle within the same bank](/en/diagrams/native-rails/settle-within-the-same-bank) |
| `LTR0008R1` | [Settle within the same bank](/en/diagrams/native-rails/settle-within-the-same-bank) |
| `PAG0102` | [Receive card receivables at the domicile](/en/diagrams/native-rails/receive-receivables-at-domicile) |
| `PAG0103` | [Pay the net debit position](/en/diagrams/native-rails/pay-the-net-debit-position) |
| `ROC` | [Collect trade bills and boletos](/en/diagrams/native-rails/collect-trade-bills-and-boletos) |
| `SLC0001` | [Receive card receivables at the domicile](/en/diagrams/native-rails/receive-receivables-at-domicile), [Pay the net debit position](/en/diagrams/native-rails/pay-the-net-debit-position) |
| `SLC0002` | [Pay the net debit position](/en/diagrams/native-rails/pay-the-net-debit-position) |
| `SLC0005` | [Settle anticipated receivables in real time](/en/diagrams/native-rails/settle-anticipated-receivables) |


# Deployment and configuration
Source: https://docs.lerian.studio/en/interfaces/jd-courier/jd-courier-deployment

Run JD Courier in your infrastructure: the four roles, the two ports, the environment variables, and the license behavior.

In BYOC, you run the Courier in your own environment. One image runs in four roles. On Lerian Cloud, Lerian operates the Courier: see [On Lerian Cloud](#on-lerian-cloud).

## Before you start

***

Make sure that you have these items:

* A PostgreSQL database for the Courier.
* The address of your Access Manager.
* Your Lerian license key and organization ID.
* The SPB channel settings that JD gave your institution.

## The four roles

***

One binary carries the four roles. The variable `COURIER_ROLES` selects the roles of a process. It has no default: a process without it does not start.

| Role | Replicas | Service port | What it serves |
| - | - | - | - |
| `spb-consumer` | Exactly `1` | None | Reads the SPB messages from JD and routes them. |
| `spb-sender` | `2` | `8081` | The SOAP interface for the engines. |
| `pix-ingress` | `2` | `8080` | The address where JD sends the Pix calls. |
| `admin` | `1` | `8080` | The operator API, the engine API, and reconciliation. |

Run `spb-consumer` as exactly one replica. A read from the JD queue removes the message, so the consumer is a single writer. A process that combines `spb-consumer` with another role stops at boot with the code `JDC-0314`.

## Ports

***

| Port | Variable | Default | Serves |
| - | - | - | - |
| HTTP | `SERVER_ADDRESS` | `:8080` | The probes, the operator API, the engine API, and the Pix address. |
| SOAP | `SOAP_SERVER_ADDRESS` | `:8081` | The SOAP interface, on the `spb-sender` role only. |

Every role answers the probes on the HTTP port: `/health` for liveness, `/readyz` for readiness, and `/version` for the build.

## Install

***

To install or upgrade the Courier, see the [JD Courier chart README](https://github.com/LerianStudio/helm/tree/main/charts/br-jd-courier).

Keep `LICENSE_KEY`, `POSTGRES_PASSWORD`, `DATABASE_URL` and `JD_PASSWORD` in your secret vault.

The Courier does not apply database migrations at boot. Apply them before each install and upgrade.

## Environment variables

***

This section lists the variables of the Courier. For the datastore, telemetry, and authentication variables that every Lerian service shares, see [BYOC configuration essentials](/en/reference/byoc-configuration).

> [!NOTE]
>
> In the tables below, the **Default / Required** column shows the default value. **Required** marks the variables that you must set. `—` means no default. `🔒` marks a secret.

### Service

| Variable | Default / Required | Description |
| - | - | - |
| `COURIER_ROLES` | **Required** | The roles of the process, separated by commas: `spb-consumer`, `spb-sender`, `pix-ingress`, `admin`. |
| `ENVIRONMENT_NAME` | `development` | The environment. Set `production` in production: the Courier then applies its production checks at boot. |
| `DEPLOYMENT_MODE` | `local` | `byoc`, `saas`, or `local`. Another value stops the boot. |
| `HTTP_BODY_LIMIT_BYTES` | `1048576` | The largest request body on the HTTP port. |
| `POSTGRES_SSLMODE` | `disable` | With `disable`, the Courier does not start unless `ALLOW_INSECURE_TLS=true`. Use `verify-full` in production. |

### JD SPB channel

The two SPB roles read these variables.

| Variable | Default / Required | Description |
| - | - | - |
| `JD_BASE_URL` | **Required** in production | The address of the JD SPB service. |
| `JD_SOAP_PATH` | `/soap` | The path of the JD SOAP service. |
| `JD_LEGACY_CODE` | **Required** in production | See the note below. |
| `JD_USER_CODE` | **Required** in production | See the note below. |
| `JD_PASSWORD` | 🔒 **Required** in production | See the note below. |
| `SPB_VENDOR_TIMEOUT` | `7s` | How long the Courier waits for JD. It must be more than zero and less than `8s`. |

`JD_LEGACY_CODE`, `JD_USER_CODE` and `JD_PASSWORD` are the JD credentials you already hold. In production, use https for `JD_BASE_URL`.

### SOAP interface

The `spb-sender` role reads these variables.

| Variable | Default / Required | Description |
| - | - | - |
| `SOAP_MAX_BODY_BYTES` | `10485760` | The largest SOAP request body. |
| `SPB_CHANNEL_CREDENTIAL_ROTATION_OVERLAP` | `24h` | See the note below. |
| `SOAP_TLS_CERT_FILE` | — | See the note below. |
| `SOAP_TLS_KEY_FILE` | — | See the note below. |
| `SOAP_TLS_TERMINATED_UPSTREAM` | `false` | See the note below. |

In production, give `spb-sender` a TLS certificate and key (`SOAP_TLS_CERT_FILE`, `SOAP_TLS_KEY_FILE`), or set `SOAP_TLS_TERMINATED_UPSTREAM` when TLS ends before the Courier. The minimum TLS version is 1.2.

### Pix

| Variable | Default / Required | Description |
| - | - | - |
| `PIX_VENDOR_SUBJECTS` | **Required** for `pix-ingress` | See the note below. |
| `AWS_REGION` | `us-east-1` | The AWS region of AWS Secrets Manager. |

`PIX_VENDOR_SUBJECTS` lists the JD identities that can call `pix-ingress`. The Courier refuses every other caller, engines included.

The Courier reads each engine's client ID and secret from AWS Secrets Manager, in `AWS_REGION`. Store them there before you register the engine.

Store each engine's secret under `tenants/{ENVIRONMENT_NAME}/{tenantId}/jd-courier/external/pix-engine-{engineId}/credentials/versions/{versionId}`. `pixDelivery.credentialRef` must point to that secret. The Courier does not deliver to the engine when the reference points to any other path. The secret is a JSON object with the fields `clientId` and `clientSecret`. `{versionId}` is a lowercase UUID. `{tenantId}` is the identifier in the answer to the [activation of the Pix rail](#activate-the-rails).

### License

| Variable | Default / Required | Description |
| - | - | - |
| `LICENSE_KEY` | 🔒 **Required** | Your Lerian license key. |
| `ORGANIZATION_IDS` | — | Your organization ID. |
| `APPLICATION_NAME` | `jd-courier` | The application name that the license check uses. |

## License behavior

***

The Courier checks the license at boot. Do not restart a pod while the license is not valid: the pod does not start until you fix the license.

While the process runs, the Courier checks the license again every 6 hours. When the license becomes revoked, the process stays up:

* The operator API and the engine API answer `503 JDC-0902`.
* The Pix address and the SOAP interface answer `503`.
* The `spb-consumer` role stops reading from JD.

The `/readyz` probe reports the license state. While the license is revoked, the Courier checks it again after 1 minute, and the interval doubles up to 15 minutes. At the first valid answer, the Courier serves again with no restart.

## Activate the rails

***

The Courier delivers no message of a rail to the engines until an operator activates the rail. To activate a rail, use the operation [Activate a rail](/en/reference/interfaces/jd-courier/activate-a-rail-for-the-caller-s-tenant) of the operator API. It requires the `activation:write` permission on the `channels` resource.

* **SPB.** Activate SPB at cutover, when no engine reads from JD directly. After the activation, the Courier reads the messages from the JD queue, and a read removes the message from JD.
* **Pix.** Activate Pix before you ask JD to send the Pix calls to the Courier.

The answer gives the identifier that the Pix secret path uses. One installation holds each rail. When the rail is already active for another holder, the activation answers `409 JDC-0117`.

## On Lerian Cloud

***

On Lerian Cloud, Lerian operates the Courier. You do not set any of the variables on this page.

* **Lerian** configures and runs the deployment.
* **Your operator** uses the operator API: the engines, the ownership map, the delivery modes, bypass, the retained messages, and reconciliation.
* **Your engines** use the engine API, the SOAP interface, and the Pix address.


# Connecting an engine
Source: https://docs.lerian.studio/en/interfaces/jd-courier/jd-courier-engine-integration

What the team of each core banking engine changes and implements to work behind JD Courier, on the SPB rail and the Pix rail.

This page is for the team of each engine that works behind the Courier: your existing core and the Lerian stack. An operator first registers the engine in the Courier, through the [engine API](/en/reference/interfaces/jd-courier/register-an-engine). The registration holds the participant ISPBs of the engine and, for Pix, the address where the engine receives Pix calls.

## SPB: point the engine at the Courier

***

On the SPB rail, the Courier serves the same SOAP interface as JD. An engine that already talks to JD changes the address and the channel credential. It keeps its messages and its calls.

The `spb-sender` role serves the interface at the path `/soap`, on its own port (default `8081`). It accepts the four JD operations:

| Operation | What the Courier does |
| - | - |
| `RecebeMensagem` | Gives the engine the oldest SPB message that waits for it. When none waits, it answers with the empty-queue code `ALS01`. The Courier does not call JD. |
| `EnviaMensagem` | Writes the send in the send journal, sends the message to JD once, and relays the answer of JD. |
| `ConsultaNumCtrlIF` | Forwards the query to JD, for the control numbers of the sends that this engine made through the Courier. |
| `ConsultaMensagem` | Forwards the query to JD, for the sequence numbers of the messages of this engine. |

Each engine signs in to the Courier's SOAP address with its own channel credential, not with your JD credential. An operator issues the credential through the Courier API. The response shows the password once. Store it then.

When you issue a new credential for the same engine, the previous one keeps working for an overlap window (24 hours by default), then stops. An operator can revoke a credential at any time. The Courier forwards each send to JD with your JD credential. A refused sign-in gets 401 with no body.

### Before the engine changes its address

1. Clear the reconciliation backlog of the engine against JD. The Courier answers a query only for the sends and messages that passed through it. A query about an earlier send receives `503`.
2. Ask the operator to issue the channel credential of the engine.
3. Change the JD address and credential of the engine to the values of the Courier.

### What the engine receives

A redelivered message keeps its original sequence number (`NumCabSeq`). The engine must accept a repeated sequence number as a repeat, not as a new message.

The Courier gives these answers to `EnviaMensagem`:

| Answer | Meaning |
| - | - |
| The answer of JD, as it came | JD answered. |
| The answer of JD with the header `X-Send-Outcome: indeterminate` | JD failed or answered without a verdict. The message possibly reached JD. |
| `503` with `X-Send-Outcome: indeterminate` and `X-Control-Id` | The message left and no answer came back. It possibly reached JD. |
| `503` with `X-Send-Outcome: duplicate` | The control number already has a send. The Courier did not send the message. |
| `503` without `X-Send-Outcome` | The message did not reach JD. |

After an indeterminate send, query the control number with `ConsultaNumCtrlIF`. A final answer of JD settles the send in the journal. Do not send the message again with the same control number: the Courier refuses it. When every earlier send of the control number has the outcome `NOT_SENT`, the Courier answers the query with the JD code `ALN01`, and it does not forward the query.

## Pix: receive the calls of JD

***

On the Pix rail, the Courier delivers each inbound call to the Pix address of the owner engine. The engine serves the same paths that JD calls, for the account validation, the cash-in, the refund, and the Pix Automático calls.

### How the Courier calls the engine

* The Courier appends the path of the JD call to the Pix address of the engine. It uses the same method.
* The body is the body that JD sent, byte for byte.
* The Courier forwards these headers when JD sends them: `Chave-Idempotencia`, `X-DataHoraEvento`, `X-NomeEvento`, and `Content-Type`.
* The Courier waits up to 60 seconds for the answer. It reads up to 1 MiB of the answer.
* The Courier does not follow redirects.

To deliver Pix messages, the Courier calls the Pix address you register for each engine. Register a credential for every engine: the Courier then sends an Access Manager token with each call. Without a credential, the Courier calls the engine without authentication. In production, use an https address. Registering a Pix address requires the `pix-delivery:write` permission.

The engine's client ID and secret live in AWS Secrets Manager. See [Deployment](/en/interfaces/jd-courier/jd-courier-deployment#pix).

### How the Courier reads the answer

The Courier relays the answer of the engine to JD. For a message, the status decides what happens next:

| Status of the engine | Result |
| - | - |
| `5xx`, `408`, `429` | The Courier relays the answer to JD and retains the message. The next resend of JD reaches the engine again. |
| `3xx`, `401`, `403`, or no answer | JD receives `503`, and the Courier retains the message. |
| Any other status, for example `200`, `400`, or `422` | The message is delivered. The Courier stores the answer and gives it to JD at each resend. |

A status from the last row is final. To have JD send the message again, answer with a status from the first row.

The engine can receive the same message more than once. For example, the Courier calls the engine again after a timeout. Use the identifiers that JD sends, such as `Chave-Idempotencia`, to recognize a repeat.

## Calls the engine makes to the Courier

***

The `admin` role serves three operations for the engines.

Each engine calls the ownership API with its own Access Manager application. The application needs the `ownership:read` permission, and `ownership:write` to claim its own Pix Automático recurrences and declare their payment legs. The Courier answers 401 to any other caller.

When the engine is [Pix via JD](/en/interfaces/pix-jd/direct-pix-via-jd), it makes these claims and declarations itself. Its worker claims the recurrences on the Courier. Before the Courier starts to receive Pix, an operator calls its [Courier ownership route](/en/reference/interfaces/pix-jd/tell-the-jd-courier-which-pix-automatico-traffic-is-this-engine-s) (`POST /v1/pix-automatico/courier-ownership`). The route claims the recurrences that already exist and declares the legs of the payments in progress. See [Claims on the Courier](/en/interfaces/pix-jd/pix-jd-environment-variables#claims-on-the-courier).

### Ownership lookup

Before the engine settles a payment inside your institution, it must know which engine owns the destination. Call the [ownership lookup](/en/reference/interfaces/jd-courier/resolve-which-engine-owns-a-key) with the key as you hold it. The answer tells if the key has an owner, and if that owner is the engine that made the call.

The answer is authoritative:

* `200` with `resolved: true` names the owner.
* `200` with `resolved: false` means that no engine of your institution owns the key.
* `422` means that the key is not valid.
* Treat any other status as a refusal: fail the payment and do not settle it inside your institution.

### Pix Automático recurrence claim

When the engine authorizes a Pix Automático recurrence, it [claims the recurrence](/en/reference/interfaces/jd-courier/claim-a-pix-automatico-recurrence-for-the-calling-engine). The Courier then routes the schedule calls of that recurrence to the engine. The claim is idempotent. A recurrence that another engine holds receives `409 JDC-0102`. Only an operator can move it.

Before the Courier starts to receive Pix, each engine claims the recurrences that already exist. A schedule message for a recurrence without an owner stays retained until the claim arrives. A schedule validation for that recurrence receives `503`.

### Pix Automático leg declaration

Some Pix Automático calls follow an earlier leg of the same payment. A debit and a debit reversal go to the engine that received the debit block. A schedule cancellation status goes to the engine that holds the schedule.

Before the Courier starts to receive Pix, each engine [declares the legs it holds](/en/reference/interfaces/jd-courier/declare-an-earlier-leg-of-a-pix-automatico-payment-the-calling-engine-holds) for the payments in progress:

* `block`: each debit block that the engine accepted, when the debit or its reversal has not arrived yet.
* `schedule`: each schedule whose cancellation status has not arrived yet.

A call that arrives before its leg is declared stays retained. The Courier releases it after the declaration. A declaration that conflicts with the record of the Courier receives `409 JDC-0116`. Stop and report it to an operator.


# Daily operations
Source: https://docs.lerian.studio/en/interfaces/jd-courier/jd-courier-operations

The daily work of the JD Courier operator: engines, the ownership map, account moves, retained messages, the SPB channel halt, the SPB rail suspension, indeterminate sends, and reconciliation.

This page is for the operator of your institution who runs the Courier. Each task uses the operator API that the `admin` role serves.

## Engines

***

Register each engine once, through the [engine API](/en/reference/interfaces/jd-courier/register-an-engine). An engine has an ID, a display name, its participant ISPBs, and, for Pix, the address where it receives Pix calls.

There is no delete. To stop an engine, [disable it](/en/reference/interfaces/jd-courier/enable-disable-or-rename-an-engine) with a reason. A disabled engine receives no new deliveries and no new keys. It keeps the keys that it owns, so the new messages for those keys stay retained until you enable the engine again or move the keys.

## The ownership map

***

[Assign](/en/reference/interfaces/jd-courier/assign-a-key-to-an-engine) each account to its engine before the Courier receives messages for it. A message for an account without an owner stays retained. On Pix Automático, also assign the CNPJ of each charger that your institution serves. Each engine claims its own recurrences.

To find the owner of a key, [list the assignments](/en/reference/interfaces/jd-courier/list-ownership-assignments) with the key kind and value. To read the changes to a key, use its [audit history](/en/reference/interfaces/jd-courier/ownership-history-for-one-key).

When you [remove a key](/en/reference/interfaces/jd-courier/unassign-a-key), the messages for that key stay retained. The Courier does not credit them and does not return them to BACEN.

## Moving accounts between engines

***

A migration wave moves accounts from one engine to another. [Move each key](/en/reference/interfaces/jd-courier/move-a-key-to-another-engine) with a reason. The Courier records the previous owner and the reason in the audit history. After the move, the next lookup answers the new owner.

Some messages do not follow the move:

* On SPB, the reply to a send goes to the engine that made the send.
* On Pix, a message that an earlier attempt sent to the previous owner stays retained. The Courier does not send it to the new owner.
* On Pix Automático, a debit, its reversal, and a schedule cancellation status stay with the engine that holds the block or the schedule.

## Retained messages

***

Check the [retained messages](/en/reference/interfaces/jd-courier/list-retained-messages) every day. For these reasons, fix the cause:

| Reason | What to do |
| - | - |
| `ACCOUNT_UNASSIGNED` | Assign the key to its engine. On Pix Automático, ask the engine to claim the recurrence or declare the earlier leg. |
| `DELIVERY_FAILED` | Check the engine, its Pix address and its credential. |
| `UNRECOGNIZED_TYPE` | For a non-money code, declare a [delivery mode](/en/interfaces/jd-courier/jd-courier-routing#delivery-modes) for the code. |
| `OWNERSHIP_DECISION_UNAVAILABLE` | Make sure that the Courier database is available and that the engines declare their participant ISPBs. |

When the cause clears, the message leaves by itself at the next re-check. To have it checked first, [request a re-evaluation](/en/reference/interfaces/jd-courier/run-a-retained-message-s-routing-decision-again) with a reason. You do not choose the engine: the routing rules choose it.

## SPB channel halt

***

The `spb-consumer` role halts the SPB channel when a read from JD can have removed a message that the Courier did not receive. For example, JD answers with a `5xx` status other than `503`, or the read times out after the request left. The halt stops the inbound SPB messages for every engine.

While the channel is halted, the Courier does not read from JD, does not route, and does not re-check retained SPB messages. A restart does not lift the halt.

1. Read the halt reason in the [channel list](/en/reference/interfaces/jd-courier/list-the-registered-rails-their-declared-properties-and-their-state).
2. Check with JD if the read removed a message that the Courier did not receive.
3. [Lift the halt](/en/reference/interfaces/jd-courier/lift-a-durable-channel-halt) with a note of 10 to 500 characters about what you checked.

The Courier cannot get a removed message again. Ask JD for the message and give it to the team of the engine that owns its account.

## Suspend the SPB rail

***

To stop the Courier from reading the SPB messages, [suspend the SPB rail](/en/reference/interfaces/jd-courier/suspend-a-rail-for-the-caller-s-tenant) with a reason. JD keeps the messages until you [activate the rail](/en/interfaces/jd-courier/jd-courier-deployment#activate-the-rails) again. The history and the retained messages stay.

You cannot suspend the Pix rail. The request answers `422 JDC-0304`. To stop Pix, ask JD to stop sending the Pix calls to the Courier.

## Indeterminate sends

***

An indeterminate send is an SPB send that left the Courier without a verdict from JD. A query of the engine with `ConsultaNumCtrlIF` can settle it. To see the sends that stay open, [list the send journal](/en/reference/interfaces/jd-courier/list-spb-sends) with `open=true`.

When you find the result outside the Courier, for example from the engine or from JD support, [close the send by hand](/en/reference/interfaces/jd-courier/close-an-indeterminate-send-by-hand). Give a reference to the evidence and a note.

The close is a record only:

* The outcome stays `INDETERMINATE`.
* The control number stays blocked for a new send.
* A later query of the engine still goes to JD.
* The send no longer counts as an open send.

The Courier has no close as `NOT_SENT`. If an operator was wrong about a send that "never left", a second send of the same control number could reach BACEN.

## Reconciliation

***

The `admin` role runs a reconciliation cycle for each rail every minute. A cycle checks a past time window. The [reconciliation report](/en/reference/interfaces/jd-courier/reconciliation-report-for-a-rail) shows these counts:

* **Expected**: the outcomes that the messages of the window expect.
* **Completed**: the deliveries to the engines, for each engine.
* **Retained**: the messages that stay retained.
* **Refused**: the messages refused by a delivery mode.

The divergence is the expected count minus the other three. A divergence that is not zero is a possible lost message: investigate it. The report also lists the SPB sends that JD accepted and whose reply did not arrive within the return window. To run a cycle now, [trigger one](/en/reference/interfaces/jd-courier/trigger-a-reconciliation-cycle-for-a-rail). A rail that already runs a cycle answers `409 JDC-0601`.

The report gives the open findings of the rail, oldest first. A finding stays open until an operator closes it. After you investigate a finding, [close it](/en/reference/interfaces/jd-courier/close-a-reconciliation-finding):

* Give a note of 10 to 500 characters about what you checked.
* Give the `updatedAt` of the finding, as you read it. If a cycle found the finding again after you read it, the close answers `409 JDC-0008`. Read the finding again.

A closed finding stays in the history. When a later cycle finds a new divergence, it opens a new finding.


# How routing works
Source: https://docs.lerian.studio/en/interfaces/jd-courier/jd-courier-routing

How JD Courier decides which engine receives each SPB and Pix message, and what happens to a message that it cannot route or deliver.

For each message that JD sends to your institution, the Courier decides only which engine receives it. This page explains the ownership map, the routing rules of each rail, and the retention of the messages that the Courier cannot route or deliver.

## The ownership map

***

The ownership map is a list of keys. Each key has one owner engine. An operator creates and changes the map through the [ownership API](/en/reference/interfaces/jd-courier/assign-a-key-to-an-engine). The Courier refuses a second owner for a key with `409 JDC-0102`. To change the owner, the operator [moves the key](/en/reference/interfaces/jd-courier/move-a-key-to-another-engine).

The map accepts seven kinds of key:

| Key kind | What it identifies | Used by inbound routing |
| - | - | - |
| `ACCOUNT` | An account, as branch and account number. A payment account has no branch. | Yes, on SPB and Pix |
| `DOCUMENT` | A CPF or a CNPJ. | Yes, on Pix Automático, for the CNPJ of the charger |
| `PIX_RECURRENCE_ID` | A Pix Automático recurrence. | Yes, on Pix Automático |
| `PIX_KEY_EMAIL` | An email Pix key. | No |
| `PIX_KEY_PHONE` | A phone Pix key, in E.164 format. | No |
| `PIX_KEY_RANDOM` | A random Pix key. | No |
| `PAYMENT_ID` | A payment identifier. | No |

The kinds that inbound routing does not use are available to the engines through the [ownership lookup](/en/reference/interfaces/jd-courier/resolve-which-engine-owns-a-key). An engine uses the lookup to find out if another engine owns the destination of a payment.

The Courier normalizes each key value. For example, it removes the punctuation from a CPF and the leading zeros from a branch. Send the value as you hold it.

Every change to the map writes an entry in the audit history of the key, in the same transaction. The entry records who made the change, when, the previous owner, and the new owner. A move also records its reason. You can read the history of a key after its removal, through the [audit lookup by key](/en/reference/interfaces/jd-courier/ownership-history-for-one-key-addressed-by-the-key).

## Routing on the SPB rail

***

The `spb-consumer` role reads the SPB messages that JD holds for your institution. The Courier stores each message before it decides the route. Then it applies these rules, in order:

1. **Send journal.** When the control number (`NumCtrlIF`) of the message matches a send in the [send journal](#sends-to-jd-and-the-send-journal), the message goes to the engine that made the send. This rule routes the replies to messages that an engine sent.
2. **Ownership map.** The Courier reads the credited account of the message: branch and account, or the payment account. When the map has an owner for that account, the message goes to the owner.
3. **Delivery mode.** When the map has no owner, the Courier reads the [delivery mode](#delivery-modes) declared for the message code. This rule never applies to the money codes `STR0008`, `STR0008R1`, `STR0008R2`, `STR0010`, `STR0010R1`, and `STR0010R2`.
4. **Retention.** When no rule decides, the Courier [retains](#retained-messages) the message.

The engine must be enabled. When rule 1 or rule 2 names a disabled engine, the Courier retains the message with the reason `DELIVERY_FAILED`.

The Courier does not push SPB messages to the engines. Each engine asks the Courier for its messages through the same SOAP interface it uses with JD. The Courier answers with the oldest message that waits for that engine. For details, see [Connecting an engine](/en/interfaces/jd-courier/jd-courier-engine-integration).

### Delivery modes

A delivery mode applies to one SPB message code. An operator [declares it](/en/reference/interfaces/jd-courier/declare-the-delivery-mode-for-one-message-code) with a reason. There are two modes:

* `ALL_ENGINES`: the message goes to every enabled engine.
* `REFUSE`: the message goes to no engine. The Courier keeps it, with the state `REFUSED`.

A code without a declaration follows the default: one owner. The Courier refuses a declaration for a money code with `422 JDC-0110`. A revoked declaration stays readable as history. The Pix rail accepts no declaration.

### Redelivery

An operator can [serve an SPB message again](/en/reference/interfaces/jd-courier/reopen-the-delivery-of-a-message-to-an-engine) to one of the engines that the message was routed to. The Courier does not ask JD again. The next request of the engine receives the stored message, with its original sequence number. Your operator gives a reason, and the Courier records it.

### Bypass

A bypass is the state where one engine connects to JD directly again, outside the Courier. An operator declares a bypass on the SPB rail with the engine and a reason.

While a bypass is active, the Courier does not read from JD on that rail. It also does not route or re-check SPB messages. A reconciliation cycle that runs during a bypass lists the suspended guarantees. At most one engine can be in bypass on a rail. The Pix rail has no bypass.

## Routing on the Pix rail

***

JD sends the inbound Pix calls of your institution to the address that the `pix-ingress` role serves. The Courier decides the owner during the call, delivers the call to the engine, and relays the answer of the engine to JD.

JD makes two kinds of call:

* **Questions.** JD waits for an answer before it continues: account validation, the Pix Automático debit block, and the authorization and schedule validations. The Courier does not retain a question.
* **Messages.** JD reports a fact: cash-in, refund (devolução), and the Pix Automático registrations, settlements, and events. The Courier can retain a message.

### Which key routes each call

| JD call | The owner is the engine that owns |
| - | - |
| Account validation, cash-in, refund | The account of the payee |
| Pix Automático debit block | The account in the block |
| Pix Automático debit and debit reversal | No key: the call goes to the engine that received the debit block |
| Authorization payer registration, and its event | The account of the payer |
| Authorization recipient registration, and its event | The CNPJ of the charger |
| Authorization validation, cancellation, and status events | The account of the payer, when the payer ISPB is one of yours. The CNPJ of the charger, when the payer ISPB is not one of yours. |
| Schedule validation, registration, cancellation, and their registration events | The recurrence |
| Schedule status event | The account of the payee |
| Schedule cancellation status event | No key: the call goes to the engine that holds the schedule |

Your ISPBs are the participant ISPBs that the operator registers on the engines.

The Pix Automático calls that follow an earlier leg need a record of that leg. The Courier records the earlier legs that it delivers. For the payments in progress before the Courier receives Pix, each engine declares its legs. See [Connecting an engine](/en/interfaces/jd-courier/jd-courier-engine-integration).

### What JD receives

| Situation | Message | Question |
| - | - | - |
| The owner engine takes the call | The answer of the engine, as it came. The Courier stores it and answers each resend of JD with it. | The answer of the engine, as it came. |
| The Courier stores the call but cannot route or deliver it | `503`. The Courier retains the message. | — |

When the engine answers a message with a `5xx`, `408`, or `429` status, the Courier relays that answer to JD and retains the message. The next resend of JD reaches the engine again. When the engine answers with a `3xx`, `401`, or `403` status, or does not answer, JD receives `503` and the Courier retains the message.

## Retained messages

***

A retained message stays in the Courier database with its reason. The Courier does not credit it, return it to BACEN, or delete it. Your operator lists the retained messages, oldest first, through [the retained API](/en/reference/interfaces/jd-courier/list-retained-messages). The list shows the reason and the times. It does not show the content of the message.

| Reason | Rail | Meaning | Re-checked |
| - | - | - | - |
| `ACCOUNT_UNASSIGNED` | SPB, Pix | The Courier read the key of the message, and no engine owns it. On Pix, also: the earlier leg of the message has no record. | Yes |
| `UNRECOGNIZED_TYPE` | SPB | The message has no key that the Courier reads, and its code has no delivery mode. | Yes |
| `OWNERSHIP_DECISION_UNAVAILABLE` | Pix | The Courier could not read the data for the decision. Also used when an earlier attempt sent the message to an engine that is no longer the owner. | Yes |
| `DELIVERY_FAILED` | SPB, Pix | The delivery to the engine failed. | Yes |
| `CLASSIFICATION_FAILED` | SPB, Pix | The Courier could not classify the message. | No |

### How a retained message leaves

When the cause clears, the message leaves by itself. For example, an operator assigns the account, or enables the owner engine again. On Pix, a resend of JD also runs the decision again.

An operator can also [request a re-evaluation](/en/reference/interfaces/jd-courier/run-a-retained-message-s-routing-decision-again) with a reason. The Courier records who asked, when, and why, and re-checks the message first. The re-evaluation runs the same routing rules as a new message. The operator never chooses the engine. The Courier refuses a re-evaluation for the reason `CLASSIFICATION_FAILED` with `422 JDC-0204`.

When the Courier releases a Pix message, JD is not in the call. The Courier stores the answer of the engine and gives it to JD at the next resend.

## Sends to JD and the send journal

***

Engines send their SPB messages to JD through the `spb-sender` role. The Courier writes each send in the send journal before the send leaves. Then it sends the message to JD once and relays the answer of JD to the engine. The Courier never sends a message again by itself.

The send journal records one of these outcomes for each send:

| Outcome | Meaning |
| - | - |
| `DETERMINED` | JD answered with a verdict. |
| `INDETERMINATE` | The message left, and no verdict came back. It possibly reached JD. |
| `RESOLVED` | A later answer of JD settled an indeterminate send. |
| `NOT_SENT` | The message did not leave the Courier. |

The Courier accepts each control number once for each tenant. A send with the outcome `NOT_SENT` does not count. A second send of the same control number does not reach JD.

An indeterminate send gets its answer when the engine queries JD about it through the Courier. To handle the indeterminate sends that remain, see [Daily operations](/en/interfaces/jd-courier/jd-courier-operations).


# What is JD Courier
Source: https://docs.lerian.studio/en/interfaces/jd-courier/what-is-jd-courier

JD Courier lets two or more core banking engines share one JD channel and one ISPB on the SPB (TED) rail and the Pix rail.

**JD Courier** lets two or more core banking engines share one JD Consultores channel and one ISPB. Each core banking system that processes the money movements of its own accounts is an engine. Your existing core is one engine. The Lerian stack is another.

JD gives each participant one channel. On SPB, a read from the channel removes the message. On Pix, JD calls one address. So two engines cannot share the channel directly. The Courier sits between JD and the engines. JD sees one participant, and each engine receives only the messages that belong to it.

## When you need it

***

You need the Courier when your institution runs more than one engine on the same ISPB and the same JD channel. The most common case is a migration. You move accounts from your existing core to the Lerian stack in waves, and both engines operate at the same time.

The Courier covers two rails:

* **SPB (TED).** The Courier reads the SPB messages that JD holds for your institution and delivers each one to its engine. Engines send their own SPB messages to JD through the Courier.
* **Pix.** JD sends the inbound Pix calls of your institution to the Courier. The Courier delivers each call to its engine and relays the answer of the engine to JD. The Courier does not send Pix requests to JD.

## What the Courier guarantees

***

* **One owner for each account.** An explicit ownership map tells the Courier which engine owns each account. The map accepts one owner for each key. The Courier delivers each financial message to one engine.
* **Unrouted messages stay retained.** When the Courier cannot route or deliver a message that it stored, it retains the message. The Courier does not credit a retained message and does not return it to BACEN. Your operator sees each retained message with its reason and its age.
* **A message retained for a routing or delivery cause leaves through the routing decision.** When a routing or delivery cause clears, the Courier routes the message again by itself. An operator can also request a new routing decision, with a reason. The operator never chooses the engine.
* **An account validation that the Courier cannot route is refused in the same call.** JD receives `AC03` or `AB09`. A validation comes before settlement, so no money moves.
* **Moving an account is a configuration change.** An operator moves an account from one engine to another through the API. The move requires a reason, and the Courier records it in an audit history.

## What the Courier does not do

***

* The Courier does not create payment messages.
* The Courier does not access a ledger and does not hold balances. Each engine keeps its own books.
* The Courier does not decide whether an engine accepts or refuses a payment. It relays the answer of the engine.

## How it runs

***

The Courier runs in your own cloud (BYOC) or on Lerian Cloud, where Lerian operates it. It uses its own PostgreSQL database. One binary runs in four roles, and the Helm chart runs each role as its own deployment:

| Role | What it does |
| - | - |
| `spb-consumer` | Reads the SPB messages from JD and routes them. It runs as exactly one replica. |
| `spb-sender` | Serves the SPB interface that engines call to receive and send messages. |
| `pix-ingress` | Receives the Pix calls from JD and delivers them to the engines. |
| `admin` | Serves the operator API, the API that engines call, and reconciliation. |

The setup is in [Deployment and configuration](/en/interfaces/jd-courier/jd-courier-deployment).

## Where to start

***

1. **[How routing works](/en/interfaces/jd-courier/jd-courier-routing)**: the ownership map, the routing rules for each rail, and what happens to a message that the Courier cannot route.
2. **[Connecting an engine](/en/interfaces/jd-courier/jd-courier-engine-integration)**: what the team of each engine changes and implements to work behind the Courier.
3. **[Deployment and configuration](/en/interfaces/jd-courier/jd-courier-deployment)**: the Helm chart, the four roles, and the environment variables.
4. **[Daily operations](/en/interfaces/jd-courier/jd-courier-operations)**: the work of your operator, from retained messages to account moves.
5. **The [API reference](/en/reference/interfaces/jd-courier/list-the-registered-engines)** and the [JD Courier error list](/en/reference/interfaces/jd-courier/jd-courier-error-list).


# Boletos & Bill Payment
Source: https://docs.lerian.studio/en/interfaces/payments-btg/boleto-and-bill-payment

Issue boletos and pay bills like DARF taxes and utility invoices through the Payments module in Lerian Console, with Midaz ledger tracking.

**Boletos & Bill Payment** covers Brazil's boleto rail: issuing boletos bancários and paying bills such as DARF tax documents and utility/concessionaire invoices. On the Lerian platform, you operate this capability through the **Payments module in Lerian Console**, a managed plugin for Midaz provisioned for your organization.

## What you can do

***

* **Issue boletos** with due dates, recorded against your Midaz ledger. Through the API, a boleto can also carry fines, interest, and discounts, and you can choose its nosso número.
* **Pay bills** (DARF tax payments and utility/concessionaire bills) directly from the Console.
* **Consult a bill** by its digitable line through the [API](/en/reference/interfaces/payments-btg/consult-a-bill-by-digitable-line) before you pay it. The answer shows the amount, the dates, and who receives the money.
* **Track operations** from a dashboard with KPI cards, recent activity, and quick actions.

## How a bill payment moves money

***

1. The ledger reserves the amount in the funding account. If the balance or the overdraft limit does not allow it, the payment fails here, and BTG does not receive it.
2. Payments sends the payment to BTG.
3. When BTG accepts the payment, the API answers `201` and the payment is `CREATED`. When the outcome at BTG is unknown, the API answers `202` and the payment is `UNCONFIRMED`. Its funds stay reserved.
4. For a bank slip or utility payment, the reconciliation reads the payment from BTG. If BTG has no record of it for the whole window that the deployment sets, the payment fails with `PBP-0211`, and Payments releases the funds.
5. For a DARF payment, the funds stay reserved until the outcome from BTG arrives.

> [!WARNING]
>
> Do not send an `UNCONFIRMED` payment again under a new `Idempotency-Key`. BTG can already have it, and a second request can pay the bill twice. A resend under the same key is safe.

## Find a payment after an error

***

A request to create a payment can end without a payment id, for example after a timeout or an answer with status `5xx`. First send the request again under the same `Idempotency-Key`. After a `409` with `PBP-0007` or a `503` with `PBP-0008`, wait, then send it again under the same key. After the same key returns another answer, call [`GET /v1/payments`](/en/reference/interfaces/payments-btg/list-payments) with `idempotencyKey` set to that key to find what the request created. Send the same `X-Organization-Id` as that request.

After you send a request again under a new `Idempotency-Key`, do not send it under the old key again. The old key can run the request again, and the two requests can both pay.

## Where to start

***

> **[Payments in Lerian Console](/en/interfaces/payments-btg/console/payments-introduction)**
>
> Activate the Payments plugin and take a first tour of the module.

> **[Payments Overview](/en/interfaces/payments-btg/console/payments-overview)**
>
> The dashboard: KPI cards, recent operations, and shortcuts.

> **[Boletos](/en/interfaces/payments-btg/console/payments-boletos)**
>
> Issue, consult, and manage boletos.

> **[Bill Payments](/en/interfaces/payments-btg/console/payments-bill-payments)**
>
> Pay DARF and utility bills from the Console.


# Environment variables
Source: https://docs.lerian.studio/en/interfaces/payments-btg/boleto-environment-variables

Configure the Boleto and bill payments rail via BTG: BTG OAuth, credential encryption with key rotation, Midaz ledger, reconciliation, and webhooks.

The Boleto and bill payments rail issues boletos and settles bill and tax (DARF) payments through BTG. DevOps sets its behavior through environment variables at deploy time. A change to one variable needs a service restart. This page covers the variables distinctive to this rail. For the shared datastore, telemetry, and authentication knobs, see [BYOC configuration essentials](/en/reference/byoc-configuration).

> [!NOTE]
>
> In the tables below, the **Default / Required** column shows the default value. A bold qualifier (for example **Required**) marks variables you must set. `—` means no default. `🔒` marks a **secret**. Inject it at deploy time from your secret store. Never commit it. This page lists variable names and behavior only. It prints no secret values.

> [!NOTE]
>
> This rail does **not** mount the systemplane admin API. It uses the shared `POSTGRES_*` datastore shape. See [Datastores](/en/reference/byoc-configuration#datastores).

## Server and port

The service listens on the address in `SERVER_ADDRESS` (default `:8080`). The liveness, readiness, and version probes bind this same port. `PLUGIN_AUTH_ENABLED` defaults to `true`, and production forces it on. See [Default network ports](/en/reference/default-network-ports).

## License

A license is mandatory in every environment. The boot fails when either variable is blank. [License Manager](/en/platform/licensing/license-manager) describes how the product checks the license.

| Variable | Default / Required | Description |
| - | - | - |
| `LICENSE_KEY` | 🔒 **Required** | The license key that Lerian issued for this rail. |
| `ORGANIZATION_IDS` | **Required** | License scope: `global`, or a comma-separated list of lowercase organization UUIDs. |

## BTG integration

These variables set the endpoints and credentials for the BTG connection. They also set the background refresh intervals for the BTG access token and the synced credentials.

| Variable | Default / Required | Description |
| - | - | - |
| `BTG_API_BASE_URL` | **Required** | Base URL of the BTG API. |
| `BTG_AUTH_URL` | **Required** | BTG OAuth token endpoint. |
| `BTG_COMMON_BASE_URL` | — | Base URL of the BTG Common Methods API. Without it, provider connect does not verify the account and answers `account_verified: false`. |
| `PROVIDER_CLIENT_ID` | **Required** | OAuth client ID for the BTG API. |
| `PROVIDER_CLIENT_SECRET` | 🔒 **Required** | OAuth client secret for the BTG API. |
| `BTG_WEBHOOK_HMAC_SECRET` | 🔒 **Required** in production | Secret that authenticates inbound BTG webhooks. At least 32 characters. |
| `BTG_HTTP_TIMEOUT` | `30s` | Timeout for calls to the BTG API. |
| `BTG_TOKEN_REFRESH_INTERVAL` | `2m` | How often the BTG access token is refreshed. Values above `4m` are capped at `4m`. |
| `BTG_CREDENTIAL_SYNC_INTERVAL` | `20h` | How often stored BTG credentials are re-synced. |

## Credential encryption and internal API keys

The rail encrypts stored credentials at rest. It authenticates internal calls between the worker and API pods with an API key. Both keys support a `_PREVIOUS` slot so you can rotate the active value without downtime.

| Variable | Default / Required | Description |
| - | - | - |
| `CREDENTIAL_ENCRYPTION_KEY` | 🔒 **Required** | Key used to encrypt stored credentials at rest. |
| `CREDENTIAL_ENCRYPTION_KEY_PREVIOUS` | 🔒 — | Prior encryption key, kept readable during rotation. |
| `INTERNAL_API_KEY` | 🔒 **Required** | Key the API presents on its calls to the worker. At least 32 characters. Worker pods always need it; API pods need it in production. |
| `INTERNAL_API_KEY_PREVIOUS` | 🔒 — | Prior internal API key, accepted during rotation. |
| `INTERNAL_WORKER_URL` | **Required** | URL the API uses to reach the internal worker. |

## Midaz ledger binding

| Variable | Default / Required | Description |
| - | - | - |
| `MIDAZ_LEDGER_URL` | **Required** | Midaz ledger service URL. For bill and DARF payer lookup, this service must serve the CRM instruments and holders endpoints at `/v2`. |
| `MIDAZ_AUTH_ENABLED` | `false` | Authenticate calls to Midaz through Access Manager. Production requires `true`. |
| `MIDAZ_ALLOW_INSECURE_HTTP` | `false` | Allow a cleartext `http://` Midaz or Access Manager URL. Leave `false` in production. |

## Internal Midaz outbox

The rail always initializes an internal PostgreSQL outbox for asynchronous Midaz ledger operations. This is an internal work queue, not an external CloudEvents or Streaming Hub catalog. Startup validates the retry and processing-time budgets together and rejects unsafe combinations.

| Variable | Default / Required | Description |
| - | - | - |
| `OUTBOX_DISPATCH_INTERVAL_SEC` | `2` | Interval in seconds between dispatcher polls. |
| `OUTBOX_BATCH_SIZE` | `50` | Maximum rows claimed per poll. |
| `OUTBOX_PUBLISH_MAX_ATTEMPTS` | `1` | Handler attempts within one claimed-row dispatch. Keep this low because Midaz calls already retry internally. |
| `OUTBOX_PUBLISH_BACKOFF_MS` | `200` | Backoff in milliseconds between handler attempts. |
| `OUTBOX_RETRY_WINDOW_SEC` | `180` | Delay before a failed row becomes eligible for another dispatch. |
| `OUTBOX_MAX_DISPATCH_ATTEMPTS` | `10` | Maximum outer dispatch attempts before the row becomes invalid. |
| `OUTBOX_PROCESSING_TIMEOUT_SEC` | `120` | Processing timeout in seconds for a claimed row. |
| `OUTBOX_MAX_FAILED_PER_BATCH` | `25` | Maximum failed rows handled in one batch. |
| `OUTBOX_INCLUDE_TENANT_METRICS` | `false` | Include tenant identifiers in outbox metrics. |
| `OUTBOX_PRIORITY_EVENT_TYPES` | — | Keep empty. Any non-empty value makes startup fail. |
| `OUTBOX_ALLOW_EMPTY_TENANT` | `true` | Allow internal outbox rows without a tenant identifier. |

## Reconciliation

| Variable | Default / Required | Description |
| - | - | - |
| `RECONCILIATION_INTERVAL` | `90s` | How often the reconciliation cycle runs. |
| `RECONCILIATION_MAX_MONEY_ITEMS_PER_CYCLE` | `100` | Maximum payment and settlement items reconciled per cycle. |
| `RECONCILIATION_MAX_BOLETOS_PER_CYCLE` | `40` | Maximum boletos reconciled per cycle. |
| `RECONCILIATION_DELAY_MS` | `500` | Delay in milliseconds between reconciliation steps. |
| `RECONCILIATION_PAYMENT_GRACE_PERIOD` | `5m` | Age a payment must reach before the reconciliation asks BTG about it. Values below `2m` read `2m`. |
| `PAYMENT_UNCONFIRMED_DISPATCH_GRACE` | `5m` | Minimum age before the reconciliation fails an `UNCONFIRMED` payment that was never sent to BTG. Nothing was paid, and any reservation is cancelled. Startup fails below `5m`. |
| `PAYMENT_UNCONFIRMED_ABSENCE_WINDOW` | `30m` | How long BTG must have no record of a sent bill or utility payment before the reconciliation fails it with `PBP-0211` and releases its funds. Startup fails below `10m`. |
| `PAYMENT_UNCONFIRMED_BATCH_SIZE` | `50` | Maximum `UNCONFIRMED` payments read per cycle. Values above `100` read `100`. |
| `RECONCILIATION_BOLETO_GRACE_PERIOD` | `5m` | Age a boleto must reach before the reconciliation asks BTG about it. Values below `2m` read `2m`. |
| `RECONCILIATION_BOLETO_PROCESSING_CEILING` | `24h` | Age, by the creation time at BTG, after which a boleto that BTG still answers as `PROCESSING` or `ERROR` stops counting as a registration in progress. It must be greater than `RECONCILIATION_BOLETO_GRACE_PERIOD`, or the reconciliation does not start. Values below `15m` read `15m`. |
| `RECONCILIATION_BOLETO_RESERVATION_GRACE_PERIOD` | `30m` | Minimum age before the reconciliation asks BTG about a boleto issuance that holds a nosso número and has no BTG identifier. |
| `RECONCILIATION_WEBHOOK_SILENCE_WINDOW` | `30m` | How long the rail can receive no BTG webhook before the reconciliation reports the silence as an error. It reports it only when a boleto that BTG accepted before the window started still waits for its registration webhook. Values below `10m` read `10m`. |
| `RECONCILIATION_WEBHOOK_CLAIM_LEASE` | `2h` | How long one replica keeps its exclusive claim on a batch of BTG webhooks that it processes. Raise it when you raise `RECONCILIATION_MAX_MONEY_ITEMS_PER_CYCLE`. Values below `1h` read `1h`. |

## Webhook dispatch and idempotency

| Variable | Default / Required | Description |
| - | - | - |
| `WEBHOOK_DISPATCHER_BATCH_SIZE` | `50` | Number of webhook events dispatched per batch. |
| `WEBHOOK_DISPATCHER_INTERVAL` | `10s` | Interval between webhook dispatch cycles. |
| `WEBHOOK_DISPATCHER_CLAIM_LEASE` | `15m` | How long one replica keeps its exclusive claim on a batch of webhook deliveries that it sends. Raise it when you raise `WEBHOOK_DISPATCHER_BATCH_SIZE`. Values below `5m` read `5m`. |
| `WEBHOOK_CONSUMER_INTERVAL` | `5s` | Interval between the cycles that process the webhooks BTG sends to the rail. Values below `1s` read `1s`. |
| `WEBHOOK_CONNECTION_GRACE_WINDOW_SEC` | `1800` | How long, in seconds, the previous webhook URL and signing key keep authenticating deliveries after a provider connect rotates them. Startup fails on a value below `1200` or on a value that is not a positive integer. Leave it unset to keep the default. |
| `WEBHOOK_SKIP_URL_VALIDATION` | `false` | Skip subscriber-URL validation. Keep `false` in production. |
| `IDEMPOTENCY_RECORD_TTL_HOURS` | `48` | How long idempotency records are retained, in hours. |
| `ACCOUNT_VALIDATION_DISABLED` | `false` | Disable account validation. Keep `false` in production. |

## Bill consult

These variables configure `POST /v1/payments/consult`. The rate limit counts consults per caller, and each replica counts on its own.

| Variable | Default / Required | Description |
| - | - | - |
| `CONSULT_RATE_LIMIT_MAX` | `100` | Maximum consults per caller in one window. `0` or a negative value reads `100`. |
| `CONSULT_RATE_LIMIT_WINDOW_SEC` | `60` | Length of the window, in seconds. `0` or a negative value reads `60`. |
| `CONSULT_AUDIT_HMAC_KEY` | 🔒 **Required** | The key the service uses to fingerprint the payment line in each consult audit record. Use at least 32 characters, with no spaces at the start or end. A pod that serves the payment API does not start without it. In production, the service refuses the example value from the configuration template. |

## Migrations

| Variable | Default / Required | Description |
| - | - | - |
| `MIGRATION_TIMEOUT_SEC` | `300` | Timeout in seconds for a database migration run. |
| `MIGRATION_LOCK_TIMEOUT_MS` | `10000` | Timeout in milliseconds to acquire the migration lock. |

## Health and readiness

The rail exposes `GET /health` (liveness) and `GET /readyz` (readiness) on the main port. See [Health and readiness](/en/reference/health-and-readiness) for the response shape.


# Bill Payments
Source: https://docs.lerian.studio/en/interfaces/payments-btg/console/payments-bill-payments

Pay DARF tax forms and bills (boletos, utility slips) from the Lerian Console Payments plugin: required fields, payment states, and error handling.

The **Bill Payments** page in [Lerian Console](/en/platform/console/about-lerian-console) lets you pay bills. It covers **DARF** tax forms and **bills** such as boletos and utility slips. It lists the fields each form needs, the states a payment moves through, and how to handle errors.

## Accessing the Bill Payments page

***

To open the **Bill Payments** page, click **Payments** → **Bill Payments** from the left-side menu.

The page displays bill payments in a data table. Use the **Filters** section to narrow the payments shown by status, type, or creation date range. Click a row to open the payment's details page.

The top-right of the page shows two buttons:

* **Pay bill**: pay a bill with a digitable line or barcode.
* **Pay DARF**: pay a DARF tax form. Enter the tax details manually.

## Paying a bill

***

**Step 1**

From the **Bill Payments** page, click **Pay bill**.

**Step 2**

The **New payment** panel opens with the **Pay bill** tab active.

**Step 3**

Fill in the fields:

* **Digitable line or barcode** *(required)*: the full digitable line or barcode from the bill. For a 47-digit line, the form shows the amount and the due date that it reads from the line. It warns you if that due date has passed.
* **Source account ID** *(required)*: the Midaz account to debit for this payment.
* **Description** *(optional)*: an internal note for this payment.

**Step 4**

Click **Pay bill**.

## Paying a DARF

***

**Step 1**

From the **Bill Payments** page, click **Pay DARF**.

**Step 2**

The **New payment** panel opens with the **Pay DARF** tab active.

**Step 3**

Fill in the fields:

* **Treasury revenue code** *(required)*: the revenue code, 4 to 20 digits (for example, `0190`).
* **DARF type** *(required)*: **Normal DARF** or **Simples DARF**.
* **Reference date** *(required)*: the competency or reference date for the tax. It cannot be in the future.
* **Due date** *(optional)*: the due date for the payment.
* **Principal amount** *(required)*: the main tax value (R\$).
* **Interest** *(required)*: the interest amount due (R\$). The field starts at zero.
* **Fine** *(required)*: the fine amount due (R\$). The field starts at zero.

The **Total amount** summary updates as you fill in the amount fields.

* **Source account ID** *(required)*: the Midaz account to debit. The DARF is filed in the name of this account's holder.
* **Reference number** *(optional)*: an internal reference for this DARF payment.
* **Description** *(optional)*: an internal note for this payment.
* **History** *(optional)*: the history text for this DARF payment.

**Step 4**

Click **Pay DARF**.

## Payment states

***

A bill payment can show these states:

* **Created**: the plugin sent the payment to the provider and waits for its confirmation.
* **Settled**: the provider confirmed the payment. The payment is complete.
* **Rejected**: the provider rejected the payment.
* **Failed**: the payment did not complete. See [Error handling](#error-handling).
* **Canceled**: the payment was canceled and does not complete.

## Error handling

***

The form checks each field before it sends the request. If the service refuses the payment, an error message appears. The details page of a **Rejected** payment says that the provider rejected it. The details page of a **Failed** payment shows the **Failure details** in the **Status history**.

> [!WARNING]
>
> Bill payments require the appropriate Payments permissions. If you cannot see the **Pay bill** or **Pay DARF** buttons, ask your administrator to check your role permissions.

## Related pages

***

> **[Payments introduction](/en/interfaces/payments-btg/console/payments-introduction)**

> **[Boletos](/en/interfaces/payments-btg/console/payments-boletos)**


# Boletos
Source: https://docs.lerian.studio/en/interfaces/payments-btg/console/payments-boletos

Issue single or batch boletos from Lerian Console, track lifecycle states, and cancel boletos.

The **Boletos** page in [Lerian Console](/en/platform/console/about-lerian-console) lets you issue boletos and follow their lifecycle. It lists the form fields, the boleto states, and how to handle errors.

## Accessing the Boletos page

***

To open the **Boletos** page, click **Payments** → **Boletos** from the left-side menu.

The page displays boletos in a data table, with the following columns:

* **ID**: the boleto identifier.
* **Type**: the boleto type.
* **Amount**: the boleto amount.
* **Due date**: the date the boleto is due.
* **Status**: the current lifecycle state (see [States](#boleto-states)).
* **Created at**: the date when you issued the boleto.
* **Actions**: the cancel action, when the state allows it.

You can filter boletos by status, type, or due date range. Use the filter fields above the table. Click a row to open the boleto's details page.

## Issuing a boleto

***

To issue a boleto, click the **Issue new boleto** button on the top-right of the **Boletos** page. A side panel opens. Choose the issuance type that fits your use case:

### Boleto types

| Type | Description |
| - | - |
| **Single** | Issue one boleto for a single payer with a fixed amount and due date. |
| **Batch** | Issue up to 10 boletos for different payers in one operation. Each entry is sent individually to the provider. |

### Single boleto

**Step 1**

From the **Boletos** page, click **Issue new boleto**.

**Step 2**

Select the **Single** tab.

**Step 3**

Fill in the fields:

* **Amount** *(required)*: the boleto value (R\$).
* **Due date** *(required)*: the date the payer must pay the boleto. It cannot be in the past.
* **Account ID** *(required)*: the Midaz account to associate with the boleto.
* **Type** *(required)*: **Traditional**, the only type the service accepts.
* **CPF / CNPJ** *(required)*: the payer's tax document.
* **Full name** *(required)*: the full name of the payer.
* **Street** *(required)*: payer's street address.
* **Number** *(required)*: address number.
* **Complement** *(optional)*: apartment, suite, or additional address info.
* **Neighborhood** *(required)*: payer's neighborhood.
* **City** *(required)*: payer's city.
* **UF** *(required)*: payer's state.
* **ZIP code** *(required)*: payer's ZIP code.
* **Instructions** *(optional)*: payment instructions for the boleto.

**Step 4**

Click **Issue boleto**.

**Step 5**

The boleto's details page opens. When the provider returns the **digitable line** and the **barcode**, the **Payment data** card shows them.

### Batch

The **Batch** tab lets you issue up to 10 boletos at once. Each entry is sent individually to the provider.

For each entry, fill in: **Amount**, **Due date**, **Account ID**, **CPF / CNPJ**, and **Full name**. Use **Add entry** to add more entries. The counter shows how many entries you queued (for example, `1 / 10 entries`).

Click **Issue batch** to submit all entries.

> [!TIP]
>
> After you issue a boleto, share its **digitable line** with the payer.

## Boleto states

***

A boleto moves through the following states:

* **Pending**: the provider has not confirmed the boleto yet.
* **Created**: the provider registered the boleto and the payer can pay it.
* **Settled**: the payer paid the boleto.
* **Canceled**: the boleto was canceled before payment.
* **Inactivated**: the provider inactivated the boleto. The payer can no longer pay it.
* **Failed**: the boleto issuance did not complete (see [Error handling](#error-handling)).

## Canceling a boleto

***

You can cancel a boleto in the **Created** state. Click the cancel icon in the **Actions** column, or **Cancel boleto** on the details page. Enter a **Reason** and click **Cancel boleto** to confirm.

## Error handling

***

The form checks each field before it sends the request. If the service refuses the request, an error message appears. A boleto whose issuance did not complete shows the **Failed** state. Its details page shows the **Failure details** in the **Status history**.

> [!WARNING]
>
> To issue boletos, you need the appropriate Payments permissions. If you cannot see the **Issue new boleto** button, ask your administrator to check your role permissions.

## Related pages

***

> **[Payments introduction](/en/interfaces/payments-btg/console/payments-introduction)**

> **[Bill Payments](/en/interfaces/payments-btg/console/payments-bill-payments)**


# Payments in Lerian Console
Source: https://docs.lerian.studio/en/interfaces/payments-btg/console/payments-introduction

Issue boletos, pay bills (DARF and utilities), and manage payment operations through the Payments plugin for Midaz in Lerian Console.

**Payments** is a managed plugin for **Midaz** in Lerian Console. It lets you issue boletos and pay bills. Bill types include DARF tax payments, bank slips, and utility bills. This section explains how to use the Console to issue boletos, pay bills, and manage payment operations.

> [!WARNING]
>
> Payments is available only if your organization acquired the Payments product. To get access, [contact our team](https://lerian.studio/contact).

## Activating the Payments plugin

***

Lerian delivers Payments as a managed plugin. After Lerian provisions it for your organization, you enable it from the [Plugins Settings](/en/platform/console/plugin-settings) page.

To enable Payments:

**Step 1**

Make sure the Payments plugin is available for your organization. If it is not, [contact our team](https://lerian.studio/contact).

**Step 2**

Open the **product launcher** in Lerian Console and select **Midaz**.

**Step 3**

In the **PLUGINS** section, select **Settings** > **Plugins**.

**Step 4**

Enable **Payments**.

## Accessing Payments

***

To access Payments, select it from the **PLUGINS** section in the Midaz module. It opens into **Overview**, **Boletos**, and **Bill Payments**. These pages need a selected ledger. Without one, the menu shows "No ledger selected. To access, create a ledger."

## Permissions and RBAC

***

Role-based access control (RBAC) controls access to the Payments plugin. You manage permissions the same way as other Midaz plugins, through [Access Manager](/en/platform/console/managing-applications).

The permissions the Payments pages check include:

* `dashboard` read: open the **Overview**.
* `boletos` read, create, and cancel: list and open boletos, issue them, and cancel them.
* `payments` read and create: list and open bill payments, and pay bills and DARF.

Assign these permissions to the relevant roles. A user without the read permission for a page sees "You are not authorized to access this page." instead of its content.

## Available pages

***

> **[Boletos](/en/interfaces/payments-btg/console/payments-boletos)**
>
> Issue boletos, track their lifecycle states, and handle issuance errors.

> **[Bill Payments](/en/interfaces/payments-btg/console/payments-bill-payments)**
>
> Pay DARF tax forms and bills, and track payment states.


# Payments Overview
Source: https://docs.lerian.studio/en/interfaces/payments-btg/console/payments-overview

The Payments dashboard in Lerian Console: KPI cards, recent activity, and quick actions for boletos and bill payments.

The **Overview** is the home page of the Payments plugin for Midaz in [Lerian Console](/en/platform/console/about-lerian-console). It shows a summary of **boletos** and **bill payments**. The page has summary metrics, recent operations, and shortcuts to the most common actions.

## Accessing the Overview

***

To open the Overview, select **Payments** → **Overview** from the **PLUGINS** section in the Midaz module.

> [!NOTE]
>
> The Overview requires the `dashboard` read permission. Without it, the page shows a message that you are not authorized. See [Permissions and RBAC](/en/interfaces/payments-btg/console/payments-introduction#permissions-and-rbac).

The dashboard shows all amounts in Brazilian Real (BRL). If a section fails to load, it shows an error with a **Retry** button. Select **Retry** to load it again.

## Needs attention

***

The **Needs attention** block shows at the top of the page. It lists only the counts that are above zero:

* **Boletos past due**: the number and the amount of overdue boletos. The link opens the boletos due up to today, so check the **Status** column.
* **Payments failed**: the number of failed payments. The link opens the list of failed payments.

If all counts are zero, the block does not show.

## Operations

***

Below **Needs attention**, the **Operations** section provides quick-action cards to start the most common tasks. Each card appears only if your role has the matching permission. If the page cannot load the summary for a card, the card is unavailable and says that the provider does not respond.

> **Issue boleto**
>
> Create a new boleto for collection. Opens the [Boletos](/en/interfaces/payments-btg/console/payments-boletos) page. Requires the `boletos` create permission.

> **Pay bill**
>
> Pay a DARF tax form, or a bill such as a boleto or a utility slip. Opens the [Bill Payments](/en/interfaces/payments-btg/console/payments-bill-payments) page. Requires the `payments` create permission.

## Boletos summary

***

The **Boletos** section summarizes the boleto lifecycle through a set of KPI cards.

| Card | What it shows |
| - | - |
| **Issued** | Total number of boletos issued. |
| **Pending** | Boletos that the provider has not confirmed yet. |
| **Settled** | Boletos that have been paid. |
| **Overdue** | Boletos that are still unpaid after their due day ends in Brazil time. A boleto due today is not overdue. |
| **Total amount** | Sum of all boleto amounts. |
| **Settled amount** | Sum of the amounts already settled. |
| **Overdue amount** | Sum of the amounts that are overdue. |
| **Settlement rate** | Share of issued boletos that have been settled, as a percentage. The value's color reflects performance: green at 80% or above, blue from 50% to under 80%, and amber below 50%. |

### Recent boletos

Below the KPI cards, the **Recent boletos** table lists the five most recently created boletos with the following columns:

* **ID**: the boleto identifier (shortened).
* **Type**: the boleto type.
* **Amount**: the boleto value.
* **Status**: the current lifecycle state.
* **Created at**: the boleto issue date.

Select any row to open the full boleto details, or select **View all** to go to the [Boletos](/en/interfaces/payments-btg/console/payments-boletos) page. If there are no boletos yet, the table shows "No boletos yet."

## Payments summary

***

The **Payments** section summarizes your bill payment activity with its own set of KPI cards.

| Card | What it shows |
| - | - |
| **Created** | Payments in the **Created** state. |
| **Scheduled** | Payments in the **Scheduled** state. |
| **Settled** | Payments that have been completed. |
| **Failed** | Payments that failed to process. |
| **Total amount** | Sum of all payment amounts. |
| **Settled amount** | Sum of the amounts already settled. |
| **Rejected** | Payments that were rejected. |
| **Canceled** | Payments that were canceled. |

### Recent payments

The **Recent payments** table lists the five most recent payments, with the same columns as the boletos table: **ID**, **Type**, **Amount**, **Status**, and **Created at**.

Select any row to open the full payment details, or select **View all** to go to the [Bill Payments](/en/interfaces/payments-btg/console/payments-bill-payments) page. If there are no payments yet, the table shows "No payments yet."


# Pix Automático in Lerian Console
Source: https://docs.lerian.studio/en/interfaces/pix-btg/console/pix-automatico

List the Pix Automático mandates that let a merchant debit an account on a schedule, read their charges, and cancel a mandate, through the Pix Indirect (BTG) plugin in Lerian Console.

The **Pix Automático** page of the **Pix** section lists the standing mandates that let a merchant debit an account on a schedule. Use it to read a mandate and its charges, and to cancel a mandate.

The **Pix** section appears in the Midaz Module when the **Pix Indirect (BTG)** plugin is on. See [Plugin settings](/en/platform/console/plugin-settings).

To see mandates, a user needs the `authorizations:get` permission. To see the charge history of a mandate, the user also needs `charges:get`. To cancel a mandate, the user also needs `authorizations:cancel`.

## Accessing the Pix Automático page

***

**1. Open Pix**

From the Midaz Module sidebar, expand **Pix**.

**2. Click Pix Automático**

Select **Pix Automático** in the submenu.

**3. Select the account**

The list shows the mandates of all accounts. To see the mandates of one account, search for the account by its alias in the account filter.

## Mandates list

***

| Column | Description |
| - | - |
| Created Date | When the mandate was created. |
| Mandate ID | ID of the mandate. |
| Merchant | Name and key of the merchant. |
| Status | **Authorized**, **Cancelled**, or **Expired**. |
| Next Charge | Date of the next charge. |
| Next Amount | Amount of the next charge. |
| Actions | **Details**. |

Use the status chips above the list to filter by status.

**Details** opens the mandate. It shows the mandate data, with the merchant, the periodicity, the authorized amount, and the retry budget. It also shows the next charge, the cancellation data of a cancelled mandate, and the charge history with the attempts of each charge.

## Cancel a mandate

***

**1. Open the mandate**

In the row menu of an **Authorized** mandate, select **Details**. Then click **Cancel mandate**.

**2. Select the reason**

Select **The payer asked to end this mandate** or **Suspected fraud**. The dialog shows what happens to the charges already scheduled for that reason.

**3. Enter the justification**

Enter the **Justification**. It is required for **Suspected fraud**.

**4. Cancel**

Click **Cancel this mandate**.


# Pix Decode QR in Lerian Console
Source: https://docs.lerian.studio/en/interfaces/pix-btg/console/pix-decode-qr

Paste the payload behind a Pix QR code to read who it pays, how much, and if it can still be paid, through the Pix Indirect (BTG) plugin in Lerian Console.

The **Decode QR** page of the **Pix** section reads the payload behind a Pix QR code. It shows who the QR pays, how much, and if the QR can still be paid.

The **Pix** section appears in the Midaz Module when the **Pix Indirect (BTG)** plugin is on. See [Plugin settings](/en/platform/console/plugin-settings).

To use the page, a user needs the `collections:post` permission.

## Accessing the Decode QR page

***

**1. Open Pix**

From the Midaz Module sidebar, expand **Pix**.

**2. Click Decode QR**

Select **Decode QR** in the submenu.

**3. Select the account**

Search for the account by its alias in the account filter. Each decode needs an account.

## Decode a QR payload

***

**1. Paste the payload**

In **QR payload**, paste the text behind the QR code.

**2. Add the payment context**

Optionally, open **Payment context (optional)** and set the **City code (IBGE)** and the **Payment date**. For a due-date charge, the payment date sets the discount or interest band. When you leave it empty, the provider uses today.

**3. Decode**

Click **Decode**.

## Decode result

***

The result starts with **Paid to**, **Amount**, and **Validity**. The other fields depend on the type of the QR:

| QR type | Other fields |
| - | - |
| Static | The description, the transaction ID (txId), and the merchant city, category, and postal code. |
| Immediate charge | The charge data, and the Pix Saque or Pix Troco values when the QR has them. |
| Due-date charge | The amount breakdown and the charge data. |
| Pix Automático recurrence | The recurrence mandate, for reading only. |

## Related pages

***

> **[QR Codes](/en/interfaces/pix-btg/indirect-pix-qrcodes)**
>
> The QR code types of the API and the decoder behind this page.


# Pix Infraction Management in Lerian Console
Source: https://docs.lerian.studio/en/interfaces/pix-btg/console/pix-infractions

List Pix infraction reports, read the reported transaction, and answer a report with your analysis, through the Pix Indirect (BTG) plugin in Lerian Console.

The **Infraction Management** page of the **Pix** section lists Pix infraction reports. Use it to read a report and the reported transaction, and to answer a report with your analysis.

The **Pix** section appears in the Midaz Module when the **Pix Indirect (BTG)** plugin is on. See [Plugin settings](/en/platform/console/plugin-settings).

To see infraction reports, a user needs the `infraction-reports:get` permission. To answer a report, the user also needs `infraction-reports:post`.

## Accessing the Infraction Management page

***

**1. Open Pix**

From the Midaz Module sidebar, expand **Pix**.

**2. Click Infraction Management**

Select **Infraction Management** in the submenu.

## Infraction list

***

| Column | Description |
| - | - |
| Created Date | When the report was created. |
| ID | ID of the infraction report. |
| End-to-End ID | The end-to-end ID of the reported transaction. |
| Status | Status of the report. |
| Actions | **Details**, and **Answer** for a report in **Acknowledged**. |

Search for a report by its transaction ID, and set a start date and an end date. Use the status chips above the list to filter by status. The view button switches between the table and a grid of cards.

**Details** opens the report in three tabs:

| Tab | Content |
| - | - |
| Infraction | The report IDs, the status, the situation type, the reason, the amount, the report details, the analysis, and the dates. |
| Transaction | The reported transfer, with its amount, status, type, debit party, and credit party. |
| Participants | The reporter participant and the counterparty participant. |

When the report has a BACEN funds recovery ID, **Open recovery case** opens that value recovery. This link needs the `funds-recoveries:get` permission.

## Answer an infraction report

***

**1. Open the form**

In the row menu of a report in **Acknowledged**, select **Answer**. The **Details** panel of that report also has **Respond to Infraction**.

**2. Select the analysis result**

In **Analysis Result**, select **Agreed** or **Disagreed**.

**3. Select the fraud type**

For **Agreed**, select the **Fraud Type**.

**4. Describe the analysis**

Optionally, add your notes in **Analysis Details**.

**5. Send the answer**

Click **Confirm Response**.

## Related pages

***

> **[DICT](/en/interfaces/pix-btg/indirect-pix-dict)**
>
> The API behind infraction reports and refund requests (MED 1.0).


# Pix Key Claims in Lerian Console
Source: https://docs.lerian.studio/en/interfaces/pix-btg/console/pix-key-claims

Follow the ownership and portability claims of Pix keys, and acknowledge, confirm, complete, or cancel a claim, through the Pix Indirect (BTG) plugin in Lerian Console.

The **Key Claims** page of the **Pix** section lists the ownership and portability claims of Pix keys. Use it to follow a claim and to act on it at each step.

The **Pix** section appears in the Midaz Module when the **Pix Indirect (BTG)** plugin is on. See [Plugin settings](/en/platform/console/plugin-settings).

To see claims, a user needs the `claims:get` permission. To act on a claim, the user also needs `claims:post`.

## Accessing the Key Claims page

***

**1. Open Pix**

From the Midaz Module sidebar, expand **Pix**.

**2. Click Key Claims**

Select **Key Claims** in the submenu.

## Claims list

***

| Column | Description |
| - | - |
| Date | When the claim was created. |
| Type | **Ownership** or **Portability**. |
| Key | The claimed key. |
| Status | Status of the claim. A claim in **Open** also shows **Awaiting acknowledgement**. |
| Claimer | Name of the claimer. |
| Actions | **Details**, and the claim actions for the status. |

Filter the list by claim type, or search for a key value. Use the status chips above the list to filter by status.

**Details** opens the claim in three tabs:

| Tab | Content |
| - | - |
| Claim | The claim IDs, the type, the status, the key, the donor participant, the reasons of earlier actions, and the dates. |
| Claimer | The claimer information and the claimer account. |
| Deadlines | The resolution deadline and the completion deadline. |

The claim actions are also at the bottom of the panel.

## Claim actions

***

| Claim status | Actions |
| - | - |
| Open | **Acknowledge**, **Cancel** |
| Waiting Resolution | **Confirm**, **Cancel** |
| Confirmed | **Complete**, **Cancel** |

Each action opens a dialog that tells you what the action does. To confirm or cancel a claim, you also select a reason.

## Related pages

***

> **[DICT](/en/interfaces/pix-btg/indirect-pix-dict)**
>
> The claim lifecycle and the claim operations of the API.


# Pix Key Lookup in Lerian Console
Source: https://docs.lerian.studio/en/interfaces/pix-btg/console/pix-key-lookup

Resolve a Pix key in the DICT before you pay it, screen a batch of keys, and read the risk history of a key or a taxpayer, through the Pix Indirect (BTG) plugin in Lerian Console.

The **Key Lookup** page of the **Pix** section resolves a Pix key before you pay it. It shows who owns the key today, the account that the key settles into, and what the DICT reports about the key and its owner.

The **Pix** section appears in the Midaz Module when the **Pix Indirect (BTG)** plugin is on. See [Plugin settings](/en/platform/console/plugin-settings).

The page has three panels. Each panel needs its own permission, and a user sees only the panels that their permissions allow:

| Panel | Permission | Use |
| - | - | - |
| Resolve a key | `keys:get` | Look up one key in the DICT. |
| Screen a batch of keys | `keys:post` | Check if each key in a list is registered. |
| Risk history | `statistics:get` | Read the DICT counters for a key or for a taxpayer. |

## Accessing the Key Lookup page

***

**1. Open Pix**

From the Midaz Module sidebar, expand **Pix**.

**2. Click Key Lookup**

Select **Key Lookup** in the submenu.

**3. Select the account**

To resolve a key, search for the account by its alias in the account filter. The DICT records the account that asks.

## Resolve a key

***

**1. Enter the key**

In **Pix key**, enter a CPF, a CNPJ, an email, a phone in international form, or a random key (EVP).

**2. Look up**

Click **Look up**.

The answer shows the **Owner**, the **Settlement account**, the **Key** dates, and the consultation ID of the query.

## Screen a batch of keys

***

This check uses no account. Paste the keys in **Pix keys, one per line**, up to 200 keys, and click **Check keys**. The panel shows how many keys are registered, and the status of each key: **Registered** or **Not found**.

**Copy not-found keys** copies the keys that the DICT did not find. With the `keys:get` permission, **Look this key up** sends a key of the list to **Resolve a key**.

## Risk history

***

The panel shows the DICT counters for the last 90 days, 12 months, and 60 months. The counters cover fraud markers, infraction reports, SPI settlements, and DICT entries. They are counters, not a score.

| Tab | Use |
| - | - |
| This key | Reads the counters for the key that you resolved in **Resolve a key**. |
| This taxpayer | Reads the counters for a CPF or a CNPJ. Enter it in **Taxpayer document** and click **Screen document**. |

## Related pages

***

> **[DICT](/en/interfaces/pix-btg/indirect-pix-dict)**
>
> The key and person statistics of the API.


# Pix Key Reconciliation in Lerian Console
Source: https://docs.lerian.studio/en/interfaces/pix-btg/console/pix-key-reconciliation

Follow the synchronization between the Pix service and the DICT, start a full reconciliation, and read the reconciliation job history, through the Pix Indirect (BTG) plugin in Lerian Console.

The **Key Reconciliation** page of the **Pix** section shows the synchronization status between the Pix service and the DICT. It also shows the history of the reconciliation jobs. Use it to follow each key type and to start a full reconciliation.

The **Pix** section appears in the Midaz Module when the **Pix Indirect (BTG)** plugin is on. See [Plugin settings](/en/platform/console/plugin-settings).

To see the page, a user needs the `vsync:get` permission. To start a full reconciliation, the user also needs `reconciliation:post`.

## Accessing the Key Reconciliation page

***

**1. Open Pix**

From the Midaz Module sidebar, expand **Pix**.

**2. Click Key Reconciliation**

Select **Key Reconciliation** in the submenu.

## Synchronization status

***

The **Synchronization Status** section shows one card for each key type. Each card shows the sync status, the **Local VSync**, the **Last Check**, and the **Last Reconciliation**.

**Trigger Full Reconciliation** starts a full reconciliation. A message then names the key types that the reconciliation started for, and the key types that it skipped.

## Reconciliation history

***

| Column | Description |
| - | - |
| Date | When the job was created. |
| Key Type | The key type of the job. |
| Job Type | The type of the job. |
| Status | Status of the job. |
| Progress | Items that the job processed, out of the total. |
| Added | Entries that the job added. |
| Removed | Entries that the job removed. |
| Duration | Time from the start to the end of the job. |

Filter the history by key type and job type, and set a start date and an end date.

## Related pages

***

> **[DICT](/en/interfaces/pix-btg/indirect-pix-dict)**
>
> How VSync and the reconciliation of the DICT work in the API.


# Pix Keys in Lerian Console
Source: https://docs.lerian.studio/en/interfaces/pix-btg/console/pix-keys

List the Pix keys of an account in the DICT, update the data of a key, and delete a key, through the Pix Indirect (BTG) plugin in Lerian Console.

The **Pix Keys** page of the **Pix** section lists the Pix keys of an account in the DICT directory. Use it to read a key, update the data of a key, or delete a key.

The **Pix** section appears in the Midaz Module when the **Pix Indirect (BTG)** plugin is on. See [Plugin settings](/en/platform/console/plugin-settings).

To see Pix keys, a user needs the `entries:get` permission. To update the data of a key, the user also needs `entries:patch`. To delete a key, the user also needs `entries:delete`.

## Accessing the Pix Keys page

***

**1. Open Pix**

From the Midaz Module sidebar, expand **Pix**.

**2. Click Pix Keys**

Select **Pix Keys** in the submenu.

**3. Select the account**

Search for the account by its alias in the account filter. The page lists keys per account only.

## Pix keys list

***

| Column | Description |
| - | - |
| Date | When the key was created. |
| Key Type | The type of the key, for example CPF, email, phone, or EVP. |
| Key | The value of the key. |
| Status | **Active** or **Inactive**. |
| Owner | Name of the key owner. |
| Document | Document of the key owner. |
| Actions | **Details**, and **Update Data** and **Delete Key** for an **Active** key. |

Filter the list by key type, or search for a key value. Use the status chips above the list to filter by status.

**Details** opens the key in two tabs:

| Tab | Content |
| - | - |
| Key | The entry ID, the request ID, the key type and value, the status, and the dates. |
| Account | The owner information and the account information. |

## Update the data of a key

***

**Update Data** updates the key in the DICT with the account data from the CRM.

**1. Open the dialog**

In the row menu of an **Active** key, select **Update Data**.

**2. Select the reason**

Select the **Reason**. **User Requested** is not a reason for an EVP key.

**3. Confirm**

Click **Confirm**.

## Delete a key

***

**1. Open the dialog**

In the row menu of an **Active** key, select **Delete Key**.

**2. Select the reason**

Select the **Reason**.

**3. Delete**

Click **Delete Key**.

## Related pages

***

> **[DICT](/en/interfaces/pix-btg/indirect-pix-dict)**
>
> The API behind Pix keys, claims, and key reconciliation.


# Pix Refund Requests in Lerian Console
Source: https://docs.lerian.studio/en/interfaces/pix-btg/console/pix-refund-requests

List MED refund requests for Pix transactions, answer a request with your analysis, and cancel a request, through the Pix Indirect (BTG) plugin in Lerian Console.

The **Refund Requests** page of the **Pix** section lists MED refund requests for Pix transactions. Use it to answer a refund request with your analysis, or to cancel a request.

The **Pix** section appears in the Midaz Module when the **Pix Indirect (BTG)** plugin is on. See [Plugin settings](/en/platform/console/plugin-settings).

To see refund requests, a user needs the `refund-requests:get` permission. To respond to a request or to cancel it, the user also needs `refund-requests:post`.

## Accessing the Refund Requests page

***

**1. Open Pix**

From the Midaz Module sidebar, expand **Pix**.

**2. Click Refund Requests**

Select **Refund Requests** in the submenu.

## Refund requests list

***

| Column | Description |
| - | - |
| Created Date | When the request was created. |
| Refund Request ID | ID of the refund request. |
| Transaction ID | The transaction that the request is about. |
| Reason | Reason of the refund request. |
| Amount | Amount that the request asks for. |
| Status | Status of the request. |
| Result | Result of the analysis. |
| Actions | **Details**, and **Respond** and **Cancel request** for a request in **Open**. |

Search for a request by its transaction ID, and set a start date and an end date. Use the status chips above the list to filter by status.

**Details** opens the request in three tabs:

| Tab | Content |
| - | - |
| Refund | The request IDs, the refund reason, the status, the requesting participant, the refund details, and the dates. |
| Outcome | The analysis, the refund destination, and the references, with the BACEN IDs and the contested participant. |
| Infractions & Refunds | The infractions and the refunds linked to the request. |

When the request has a BACEN funds recovery ID, **Open recovery case** opens that value recovery. This link needs the `funds-recoveries:get` permission.

## Respond to a refund request

***

**1. Open the form**

In the row menu of a request in **Open**, select **Respond**.

**2. Select the analysis result**

In **Analysis Result**, select **Totally Accepted**, **Partially Accepted**, or **Rejected**.

**3. Fill in the result fields**

The fields depend on the result. See the table below.

**4. Send the answer**

Click **Confirm Response**.

| Analysis result | Fields |
| - | - |
| Totally Accepted | **Refunded Amount** shows the requested amount, and you cannot change it. Enter the **Refund Transaction ID**. |
| Partially Accepted | Enter a **Refunded Amount** greater than zero and less than the requested amount. Enter the **Refund Transaction ID**. |
| Rejected | Select a **Rejection Reason**. |

The **Refund Transaction ID** is the end-to-end ID of the transaction that carried the refund. The **Analysis Details** field is optional, except for the rejection reason **Invalid Request**. This reason appears only for a request with the reason **Operational Flaw**.

## Cancel a refund request

***

**Cancel request** withdraws a refund request in **Open**. It is in the row menu and in the **Details** panel. In the dialog, click **Cancel request** to confirm, or **Keep request** to go back.

## Related pages

***

> **[DICT](/en/interfaces/pix-btg/indirect-pix-dict)**
>
> The API behind infraction reports and refund requests (MED 1.0).


# Pix Refunds in Lerian Console
Source: https://docs.lerian.studio/en/interfaces/pix-btg/console/pix-refunds

List the Pix refunds of an account and release a refund stuck in processing, through the Pix Indirect (BTG) plugin in Lerian Console.

The **Refunds** page of the **Pix** section lists the Pix refunds of an account. Use it to release a refund that stays in **Processing** while it waits for BTG.

The **Pix** section appears in the Midaz Module when the **Pix Indirect (BTG)** plugin is on. See [Plugin settings](/en/platform/console/plugin-settings).

To see refunds, a user needs the `refunds:get` permission. To release a stuck refund, the user also needs `refunds:post`.

## Accessing the Refunds page

***

**1. Open Pix**

From the Midaz Module sidebar, expand **Pix**.

**2. Click Refunds**

Select **Refunds** in the submenu.

**3. Select the account**

Search for the account by its alias in the account filter. The page shows the refunds of that account.

## Refunds list

***

| Column | Description |
| - | - |
| Date | When the refund was created. |
| End-to-end ID | The end-to-end ID of the original Pix. |
| Amount | Amount of the refund. |
| Type | **Cash In** or **Cash Out**. |
| Status | Status of the refund. |
| Actions | **Details**, and **Release stuck refund** for a refund in **Processing**. |

Use the status chips above the list to filter by status.

**Details** opens the refund. It shows the refund ID, the original and return end-to-end IDs, and the ledger transaction ID. It also shows the amount, the status, the type, and the last update.

## Release a stuck refund

***

A reversal call to BTG can end before BTG confirms it. The refund then stays in **Processing**. **Release stuck refund** asks BTG what became of the refund and settles the refund on that answer.

**1. Open the dialog**

In the row menu of a refund in **Processing**, select **Release stuck refund**. The same action is in the **Details** panel.

**2. Check the refund**

The dialog shows the refund ID and the amount.

**3. Ask BTG**

Click **Ask BTG and settle**. The dialog then shows what the Pix service reported, the status at BTG, and the refund status now.

What the release does depends on the answer of BTG and on the type of the refund:

| BTG answer | Cash Out refund | Cash In refund |
| - | - | - |
| Still processing | Nothing changes. | Nothing changes. |
| Confirmed | The refund completes. The amount stays debited. | The refund completes. The amount goes to the account. |
| Error | The refund is rejected. The amount returns to the account. | The refund is rejected. Nothing is credited. |
| No record of the refund | Nothing moves. The dialog offers to revert the hold. See below. | The dialog shows an error. Nothing moves. |

### Revert the hold without a BTG record

This option applies only to a **Cash Out** refund that BTG has no record of.

> [!WARNING]
>
> Reverting marks the refund as failed, with no confirmation from BTG. If BTG did send the refund, the account holder keeps money that already left the institution.

**1. Read the warning**

The dialog **Revert the hold without a BTG record** opens after BTG reports no record of the refund.

**2. Confirm the refund ID**

Type the last four characters of the refund ID.

**3. Revert**

Click **Revert the hold**.

## Related pages

***

> **[Unblocking stuck operations](/en/interfaces/pix-btg/indirect-pix-refund-operations)**
>
> The API operations behind this page, and the rules for an operation that BTG has no record of.


# Pix Static QR in Lerian Console
Source: https://docs.lerian.studio/en/interfaces/pix-btg/console/pix-static-qr

List the static Pix QR codes and issue a reusable QR code that any customer can pay, through the Pix Indirect (BTG) plugin in Lerian Console.

The **Static QR** page of the **Pix** section lists the static Pix QR codes and issues new ones. A static QR is a reusable code that any customer can pay, any number of times.

The **Pix** section appears in the Midaz Module when the **Pix Indirect (BTG)** plugin is on. See [Plugin settings](/en/platform/console/plugin-settings).

To see static QR codes, a user needs the `brcode:get` permission. To issue a static QR, the user also needs `brcode:post`.

## Accessing the Static QR page

***

**1. Open Pix**

From the Midaz Module sidebar, expand **Pix**.

**2. Click Static QR**

Select **Static QR** in the submenu.

## Static QR list

***

The list shows the static QR codes of all accounts.

| Column | Description |
| - | - |
| Created At | When the QR was issued. |
| Receiver key | The Pix key that receives the money. |
| Amount | Amount of the QR, or **Payer chooses** when the QR has no amount. |
| Description | The message that the payer reads before confirming. |
| Reference (txId) | The reference of the QR. |
| Actions | **Details**. |

**Details** shows the QR code with its **Pix Copia e Cola** payload, the QR ID, the payment data, and the merchant data.

## Issue a static QR

***

**1. Open the form**

At the top of the page, click **Issue static QR**.

**2. Select the account**

Search for the account by its alias in the account filter.

**3. Enter the receiver key**

In **Receiver key**, enter a Pix key that the selected account owns.

**4. Enter the amount**

Optionally, enter the **Amount**, with a dot for the cents, for example `100.00`. Leave it empty to let the payer type the value.

**5. Add the optional data**

Optionally, enter the **Description**. In **Reference and merchant data (optional)**, you can set the **Reference (txId)**, the **Merchant name**, the **City**, the **Postal code**, and the **Category code (MCC)**.

**6. Issue**

Click **Issue QR**.

Then the panel shows the QR code and its **Pix Copia e Cola** payload, with a copy button. To start a new QR, click **Issue another**.

## Related pages

***

> **[QR Codes](/en/interfaces/pix-btg/indirect-pix-qrcodes)**
>
> The static BR Code and the other QR code types of the API.


# Pix Transfers in Lerian Console
Source: https://docs.lerian.studio/en/interfaces/pix-btg/console/pix-transfers

List the Pix transfers of an account, find the ones that need attention, and release a stuck payment, through the Pix Indirect (BTG) plugin in Lerian Console.

The **Transfers** page of the **Pix** section lists the Pix cash-in and cash-out transfers of an account. Use it to find a transfer, read its details, and release a payment that waits for BTG.

The **Pix** section appears in the Midaz Module when the **Pix Indirect (BTG)** plugin is on. See [Plugin settings](/en/platform/console/plugin-settings).

To see transfers, a user needs the `transfers:get` permission. To release a stuck payment, the user also needs `transfers:post`.

## Accessing the Transfers page

***

**1. Open Pix**

From the Midaz Module sidebar, expand **Pix**.

**2. Click Transfers**

Select **Transfers** in the submenu.

**3. Select the account**

Search for the account by its alias in the account filter. The page shows the transfers of that account.

## Transfers list

***

| Column | Description |
| - | - |
| Date | When the transfer was created. |
| End-to-End ID | The end-to-end ID of the Pix. |
| Amount | Amount of the transfer. |
| Type | **Cash In** or **Cash Out**. |
| Status | Status of the transfer. |
| Debit Party | Name of the payer. |
| Credit Party | Name of the payee. |
| Actions | **Details**, and **Release stuck payment** for a transfer that you can release. |

Search for a transfer by its end-to-end ID in the filter bar. The expanded filters add the type, a start date, and an end date. Use the status chips above the list to filter by status.

### Transfers that need attention

**Needs attention** lists the transfers in **Pending** or **Processing** that did not change for longer than the minutes in **Untouched for**. The default is 15 minutes, and you can enter from 1 to 1440 minutes. The button needs a selected account.

### Transfer details

**Details** opens the transfer in five tabs:

| Tab | Content |
| - | - |
| Transaction | The transfer, end-to-end, and account IDs, the amount, the status, the type, the purpose, the urgency, the payment type, the initiation type, and the dates. |
| Money | The fees of the transfer, the Pix Saque or Pix Troco values when the transfer has them, and the metadata. |
| Ledger | The IDs of the ledger posting, and of the reversal posting when there is one. |
| Payer | The name, tax ID, person type, and account of the payer. |
| Payee | The name, tax ID, person type, and account of the payee. |

## Release a stuck payment

***

**Release stuck payment** asks BTG what became of a payment and settles the transfer on that answer. The action appears for a **Cash Out** in **Pending** or **Processing**, and for a **Cash In** in **Created** or **Processing**.

**1. Open the dialog**

In the row menu of the transfer, select **Release stuck payment**. The same action is in the **Details** panel.

**2. Check the transfer**

The dialog shows the transfer ID and the amount.

**3. Ask BTG**

Click **Ask BTG and settle**. The dialog then shows what the Pix service reported, the status at BTG, and the transfer status now.

### Return the money without an answer from BTG

This option applies only to a **Cash Out**. The dialog offers it when BTG gives no answer about the payment.

> [!WARNING]
>
> Returning the money marks the transfer as failed and releases the hold on the balance, with no answer from BTG. If BTG did send the payment, the account holder keeps money that already left the institution.

**1. Read the warning**

The dialog **Return the money without a provider answer** shows the transfer ID, the amount to return, and the counterparty.

**2. Confirm the transfer ID**

Type the last four characters of the transfer ID.

**3. Return the money**

Click **Return the money**.

## Related pages

***

> **[Transfers and cash-out](/en/interfaces/pix-btg/indirect-pix-transfers)**
>
> How the plugin sends a Pix transfer and how the transfer lands in Midaz.

> **[Unblocking stuck operations](/en/interfaces/pix-btg/indirect-pix-refund-operations)**
>
> The API operation behind **Release stuck payment**, and the rules for a payment that BTG has no record of.


# Pix Value Recovery in Lerian Console
Source: https://docs.lerian.studio/en/interfaces/pix-btg/console/pix-value-recovery

Create and follow MED 2.0 value recovery processes for Pix fraud cases, and request the refund of the blocked values, through the Pix Indirect (BTG) plugin in Lerian Console.

The **Value Recovery** page of the **Pix** section lists the value recovery processes for Pix fraud cases (MED 2.0). Use it to create a recovery, follow its tracking graph, and request the refund of the blocked values.

The **Pix** section appears in the Midaz Module when the **Pix Indirect (BTG)** plugin is on. See [Plugin settings](/en/platform/console/plugin-settings).

To see value recoveries, a user needs the `funds-recoveries:get` permission. To create, cancel, or request a refund, the user also needs `funds-recoveries:post`.

## Accessing the Value Recovery page

***

**1. Open Pix**

From the Midaz Module sidebar, expand **Pix**.

**2. Click Value Recovery**

Select **Value Recovery** in the submenu.

## Value recovery list

***

| Column | Description |
| - | - |
| Created Date | When the recovery was created. |
| ID | ID of the value recovery. |
| Root Transaction E2E | The end-to-end ID of the Pix transaction that started the case. |
| Situation Type | The type of fraud situation. |
| Status | Status of the recovery. |
| Actions | **Details**, and **Cancel** or **Request Refund** by the status of the recovery. |

Filter the list by situation type, and set a start date and an end date. Use the status chips above the list to filter by status.

**Details** opens the recovery in three tabs:

| Tab | Content |
| - | - |
| Recovery | The IDs, the root transaction, the situation type, the status, the reporter participant, the contact data, the report details, and the dates. |
| Tracking Graph | The persons, the accounts, and the transactions in the flow of the funds. |
| Infractions & Refunds | The infractions and the refunds linked to the recovery. |

## Create a value recovery

***

**1. Open the form**

At the top of the page, click **Create Recovery**.

**2. Identify the transaction**

In **Root Transaction E2E**, enter the end-to-end ID of the Pix transaction under suspicion of fraud.

**3. Describe the case**

Select the **Situation Type**. Enter the **Contact Email** and the **Contact Phone**, with the phone in E.164 format. Optionally, add **Report Details**.

**4. Set the tracking graph**

Optionally, set the **Tracking Graph Parameters**: **Min. Amount**, **Max. Transactions**, **Hop Window**, and **Max. Hops**.

**5. Create the recovery**

Click **Create Recovery**.

## Recovery actions

***

| Action | Recovery status | What it does |
| - | - | - |
| Cancel | **Created**, **Tracked**, or **Awaiting Analysis** | Cancels the value recovery. |
| Request Refund | **Analysed** | Requests the refund of the blocked values. |

Both actions are in the row menu. Each one asks you to confirm in a dialog.

## Related pages

***

> **[MED 2.0: Funds Recovery](/en/interfaces/pix-btg/indirect-pix-med-2-funds-recovery)**
>
> The API behind value recovery, the tracking graph, and the refund request.


# Pix Webhooks in Lerian Console
Source: https://docs.lerian.studio/en/interfaces/pix-btg/console/pix-webhooks

Track the Pix events received from BTG and the deliveries sent to client endpoints, read their payloads, and send them again, through the Pix Indirect (BTG) plugin in Lerian Console.

The **Webhooks** page of the **Pix** section tracks the Pix events received from BTG and the event deliveries sent to client endpoints. Use it to read what each event carried and to send again the ones that did not go through.

The **Pix** section appears in the Midaz Module when the **Pix Indirect (BTG)** plugin is on. See [Plugin settings](/en/platform/console/plugin-settings).

The page has two tabs. Each tab needs its own permissions:

| Tab | To see | To retry |
| - | - | - |
| Sent to clients | `webhooks-outbound:get` | `webhooks-outbound:post` |
| Received from BTG | `webhooks-inbound:get` | `webhooks-inbound:post` |

## Accessing the Webhooks page

***

**1. Open Pix**

From the Midaz Module sidebar, expand **Pix**.

**2. Click Webhooks**

Select **Webhooks** in the submenu.

## Sent to clients

***

This tab lists the deliveries sent to client endpoints. Select a **Flow type** first: the list shows one flow at a time.

| Column | Description |
| - | - |
| Created at | When the delivery was created. |
| Entity type | The type of the entity that the event is about. |
| Entity ID | The ID of the entity that the event is about. |
| Status | Status of the delivery. |
| Attempts | Attempts made, out of the maximum. |
| Last error | The last error of the delivery. |
| Target URL | The client endpoint. |
| Delivered at | When the delivery reached the endpoint. |
| Actions | **Details**, and **Retry** for a delivery in **Failed**, **Delivered**, or **Dead letter (not delivered)**. |

Search by entity ID or request ID, and set **Created from** and **Created until**. Use the status chips above the list to filter by status.

## Received from BTG

***

This tab lists the events that BTG sent to the plugin. Select an **Event type** first: the list shows one type at a time.

| Column | Description |
| - | - |
| Received at | When the event arrived. |
| Entity type | The type of the entity that the event is about. |
| Request ID | The `clientRequestId` of BTG for the event. |
| Source | Where the event came from. |
| Status | Status of the event. |
| Attempts | Attempts made, out of the maximum. |
| Last error | The last error when the plugin handled the event. |
| Processed at | When the plugin processed the event. |
| Actions | **Details**, and **Retry** for an event in **Failed**. |

Search by request ID, and set **Created from** and **Created until**. Use the status chips above the list to filter by status.

## Details and retry

***

**Details** shows the IDs of the webhook, the handling data, the last error, and the payload. For a delivery in dead letter, it also shows the dead-letter data.

**1. Select Retry**

In the row menu, select **Retry**.

**2. Confirm**

The dialog tells you what happens next. Click **Retry**.

## Related pages

***

> **[Webhooks](/en/interfaces/pix-btg/indirect-pix-webhooks)**
>
> The events of the plugin, the request format, and the retry behavior.


# Collections
Source: https://docs.lerian.studio/en/interfaces/pix-btg/indirect-pix-collections

Create Pix collections (cobranças) through the Pix Indirect Plugin via BTG: immediate COB, due-date COBV, lifecycle states, payment linking, and webhooks.

A **collection** (cobrança) is a dynamic, single-use Pix charge that requests a specific payment. The Pix Indirect Plugin (BTG) supports two types. Both types use a dynamic QR Code:

* **Immediate (COB)** (`cobrança imediata`): a short-lived charge for a fixed amount. Use it for checkout and one-time payments.
* **Due-date (COBV)** (`cobrança com vencimento`): a boleto-like charge with a due date and optional fine, interest, discount, and abatement. Use it for bills, installments, and B2B invoicing.

This guide covers the collection lifecycle and the payment flow. For QR Code generation details and field-by-field validation, see the [QR Codes guide](/en/interfaces/pix-btg/indirect-pix-qrcodes).

# Lifecycle

***

Each collection type reports its status with its own values:

| Status | Type | Meaning |
| - | - | - |
| `ACTIVE` | COB + COBV | Created and available for payment |
| `COMPLETED` | COB + COBV | Payment received. The collection is settled |
| `DELETED` | COB | Deleted by the merchant (`DELETE`) |

A collection moves from **`ACTIVE`** to **`COMPLETED`** when the payer pays it. An immediate collection moves to **`DELETED`** when the merchant deletes it. Each type has its own validity window:

* **Immediate (COB):** the charge is valid for `expirationSeconds` after creation.
* **Due-date (COBV):** the charge stays payable until `dueDate` plus `validAfterDue` days.

After a collection reaches `COMPLETED`, the plugin denies any further payment to it. The plugin also rejects any attempt to delete or update a `COMPLETED` collection (`PIX-0704`).

# Key fields

***

| Field | Required in | Notes |
| - | - | - |
| `txId` | COB + COBV | Unique per receiver; used to link the incoming payment |
| `amount` | COB + COBV | Decimal with 2 places, greater than 0 |
| `receiverKey` | COB + COBV | Pix key receiving the payment; must be owned by the account |
| `expirationSeconds` | COB only | Validity window for immediate charges |
| `dueDate` / `validAfterDue` | COBV only | Due date and post-due grace period |
| `debtor` | COBV (optional in COB) | Name + CPF/CNPJ of the expected payer |
| `amount.fine` / `interest` / `discount` / `abatement` | COBV only (optional) | COBV-only charge rules |

For COBV, the final value depends on payment timing. Early payment applies discounts. On-time payment uses the original amount. Late payment adds fine and interest, minus any abatement.

# Creating, retrieving, updating, deleting

***

| Action | Immediate (COB) | Due-date (COBV) |
| - | - | - |
| Create | `POST /v1/collections/immediate` | `POST /v1/collections/duedate` |
| List | `GET /v1/collections/immediate` | `GET /v1/collections/duedate` |
| Retrieve | `GET /v1/collections/immediate/{id}` | `GET /v1/collections/duedate/{id}` |
| Update | `PUT /v1/collections/immediate/{id}` | `PATCH /v1/collections/duedate/{id}` |
| Delete | `DELETE /v1/collections/immediate/{id}` | — |

All requests require the `X-Account-Id` header. A delete also requires `X-Reason` (`DELETED_BY_USER` or `DELETED_BY_PSP`). You can update or delete a collection only while it is `ACTIVE`.

# Payment flow

***

The payer settles a collection with an **incoming Pix (cash-in)** that carries the collection's `txId`:

1. The merchant creates a collection and presents its QR Code (or `txId`) to the payer.
2. The payer settles the charge. BTG notifies the plugin of the inbound cash-in.
3. The plugin links the cash-in to the collection by matching the payment's `txId` against the collection's `txId` and the receiver document. The collection must be `ACTIVE`. For an immediate charge, the amount must also match. Otherwise the plugin denies the payment.
4. The plugin posts the cash-in to Midaz as a ledger transaction, then moves the collection to `COMPLETED`.
5. The plugin emits the cash-in webhook to notify your system.

> [!NOTE]
>
> When you set a `debtor` on the collection, the charge records the expected payer's CPF/CNPJ. The plugin does not block a different payer at settlement.

# Webhook event when paid

***

After a payment settles a collection, the plugin queues an **outbound webhook**: the `TRANSFER` / `CASHIN` event of the payment. The outbound webhook worker delivers it asynchronously. Configure the destination through the cash-in webhook URLs (`WEBHOOK_TRANSFER_CASHIN_URL`, then `WEBHOOK_TRANSFER_URL`, with `WEBHOOK_DEFAULT_URL` as the fallback). For event types, payloads, retries, and URL resolution, see the [Webhooks guide](/en/interfaces/pix-btg/indirect-pix-webhooks).

# Error cases

***

| Case | Behavior |
| - | - |
| **Not payable** | The plugin denies a dynamic QR Code payment whose `txId` matches no `ACTIVE` collection of the receiver |
| **Amount mismatch** | For an immediate charge, the plugin denies a payment whose amount differs from the charge |
| **Duplicate `txId`** | Creation fails with `409`. A `txId` must be unique per receiver (`PIX-0701`) |
| **Update/delete after completion** | The plugin rejects the request (`PIX-0704`). A `COMPLETED` collection is immutable |

# Reference

***

**Immediate (COB):** [Create](/en/reference/interfaces/pix-btg/create-an-immediate-charge) · [List](/en/reference/interfaces/pix-btg/list-immediate-charges) · [Retrieve](/en/reference/interfaces/pix-btg/retrieve-immediate-charge-details) · [Update](/en/reference/interfaces/pix-btg/update-an-immediate-charge) · [Delete](/en/reference/interfaces/pix-btg/delete-an-immediate-charge)

**Due-date (COBV):** [Create](/en/reference/interfaces/pix-btg/create-a-dynamic-charge-with-due-date) · [List](/en/reference/interfaces/pix-btg/list-dynamic-charges-with-due-date) · [Retrieve](/en/reference/interfaces/pix-btg/retrieve-dynamic-charge-with-due-date-details) · [Update](/en/reference/interfaces/pix-btg/update-a-dynamic-charge-with-due-date)

# Next steps

***

* [QR Codes](/en/interfaces/pix-btg/indirect-pix-qrcodes): QR Code types and the decoder
* [Intra-PSP transfers](/en/interfaces/pix-btg/indirect-pix-intra-psp): Internal settlement when payer and payee share your ISPB
* [Webhooks](/en/interfaces/pix-btg/indirect-pix-webhooks): Payment and status notifications


# DICT
Source: https://docs.lerian.studio/en/interfaces/pix-btg/indirect-pix-dict

How the Pix Indirect Plugin (BTG) manages Pix keys in DICT: entries, key queries, portability and ownership claims, reconciliation (VSync), and fraud markers.

**DICT** (Diretório de Identificadores de Contas Transacionais) is BACEN's directory that maps **Pix keys** to transactional accounts. The Pix Indirect Plugin (BTG) connects you to DICT through BTG. You register and resolve keys, transfer keys between institutions with claims, reconcile your local data with BACEN, and manage MED fraud markers.

The DICT API spans several domains: entries and keys, claims, reconciliation, statistics, and the MED fraud tools. Account-scoped operations require the `X-Account-Id` header.

# Entries and keys

***

An **entry** links a Pix key to one of your accounts. The plugin resolves the account and holder data from CRM. You create entries by key type instead of account details.

**Supported key types:**

| Type | Value source |
| - | - |
| `CPF` | Provided in the request (must match the CRM holder's CPF) |
| `CNPJ` | Provided in the request (must match the CRM holder's CNPJ) |
| `EMAIL` | Provided in the request (valid email, ≤ 77 chars) |
| `PHONE` | Provided in the request (`^\+[1-9][0-9]\d{1,14}$`) |
| `EVP` | Random UUID generated by the system (do not send `key`) |

```json theme={null}
POST /v1/dict/entries
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
X-Reason: USER_REQUESTED
{ "keyType": "EMAIL", "key": "john.doe@example.com" }
```

Manage entries with create / list / retrieve / update / delete (`/v1/dict/entries`). Create, update, and delete require an `X-Reason` header. Create and delete validate against active claims and check the key against the holder document. For example, a `CPF` key must match the holder's CPF. A holder can have up to 5 keys (`NATURAL_PERSON`) or 20 keys (`LEGAL_PERSON`), and active claims count toward that limit.

> [!NOTE]
>
> The plugin does not validate keys with Receita Federal and does not run MFA ownership checks. It assumes you completed those checks before you call it. See the [integration guide](/en/interfaces/pix-btg/indirect-pix-integration) for prerequisites.

**Key queries** (`GET /v1/dict/keys/{key}`) resolve a key for payment. The response returns the current owner and account, so you can start a payment. The query requires the `X-End-To-End-Id` header for payment tracking. Use `POST /v1/dict/keys/check` to check existence in bulk. The plugin returns the data as it receives it from BTG. Mask sensitive fields before you display them on your side.

**Reference:** [Create entry](/en/reference/interfaces/pix-btg/create-entry) · [List](/en/reference/interfaces/pix-btg/list-entries) · [Retrieve](/en/reference/interfaces/pix-btg/retrieve-an-entry) · [Update](/en/reference/interfaces/pix-btg/update-an-entry) · [Delete](/en/reference/interfaces/pix-btg/delete-an-entry) · [Retrieve a key](/en/reference/interfaces/pix-btg/retrieve-a-key) · [Check keys](/en/reference/interfaces/pix-btg/check-keys-existence)

# Claims: portability and ownership

***

A **claim** transfers a Pix key between institutions. There are two kinds:

* **PORTABILITY**: moves a key to another bank for the same holder. Allowed for `CPF`, `CNPJ`, `PHONE`, and `EMAIL`.
* **OWNERSHIP**: claims a key from a different person. Allowed only for `PHONE`.

The two parties are the **donor** (the participant that currently holds the key) and the **claimer** (the participant that requests it). The plugin pulls the claimer's account data from CRM via `X-Account-Id`. BTG sets `claimerParticipant` and `donorParticipant` automatically.

## Claim lifecycle

| Status | Meaning |
| - | - |
| `OPEN` | Claim created; awaiting the donor's acknowledgment |
| `WAITING_RESOLUTION` | Donor acknowledged; resolution period running (D+7) |
| `CONFIRMED` | Donor confirmed; key is blocked pending completion |
| `COMPLETED` | Key transfer finalized |
| `CANCELLED` | Cancelled by donor or claimer |

While a claim is active (`OPEN`, `WAITING_RESOLUTION`, or `CONFIRMED`), the claim locks the key. The plugin blocks new entries and deletes. During `OPEN` and `WAITING_RESOLUTION`, the donor can still update account data, and key queries return the donor's data. After `CONFIRMED`, queries return "key not found" until the claim reaches `COMPLETED` or `CANCELLED`.

* **PORTABILITY** can complete immediately after confirmation.
* **OWNERSHIP** adds a completion window. BTG returns `resolutionPeriodEnd` (D+7) and `completionPeriodEnd` on the claim.

## Claim operations

| Operation | Role | Endpoint |
| - | - | - |
| Create | Claimer | `POST /v1/dict/claims` |
| Acknowledge | Donor | `POST /v1/dict/claims/{id}/acknowledge` |
| Confirm | Donor | `POST /v1/dict/claims/{id}/confirm` |
| Complete | Claimer | `POST /v1/dict/claims/{id}/complete` |
| Cancel | Donor or claimer | `POST /v1/dict/claims/{id}/cancel` |

CLAIM outbound webhooks deliver claim status changes to your system. See the [Webhooks guide](/en/interfaces/pix-btg/indirect-pix-webhooks).

**Reference:** [Create a claim](/en/reference/interfaces/pix-btg/create-a-claim) · [List](/en/reference/interfaces/pix-btg/list-claims) · [Retrieve](/en/reference/interfaces/pix-btg/retrieve-a-claim) · [Acknowledge](/en/reference/interfaces/pix-btg/acknowledge-a-claim) · [Confirm](/en/reference/interfaces/pix-btg/confirm-a-claim) · [Complete](/en/reference/interfaces/pix-btg/complete-a-claim) · [Cancel](/en/reference/interfaces/pix-btg/cancel-a-claim)

# Reconciliation (VSync)

***

**Reconciliation** keeps your local DICT data consistent with BACEN's authoritative records. It uses two concepts:

* **CID** (Content Identifier): a 256-bit HMAC-SHA256 hash of an entry's attributes (key type, key, owner, participant, branch, account, etc.).
* **VSync**: a single checksum that XORs every CID of a key type. Because XOR is commutative, you compare your VSync to BTG/BACEN's to reveal whether your entries are in sync without exchanging every record.

There are two paths:

* **Manual / administrative API**: operators trigger on-demand checks, download CID files, and investigate inconsistencies. Use [Start full reconciliation](/en/reference/interfaces/pix-btg/start-full-reconciliation) and [List reconciliation jobs](/en/reference/interfaces/pix-btg/list-all-reconciliation-jobs).
* **VSync worker**: an automated background process that periodically compares internal entries against DICT and reconciles drift without user intervention.

Configure the reconciliation worker's time window and the DICT write-block window in the [integration guide](/en/interfaces/pix-btg/indirect-pix-integration#7-dict-reconciliation-vsync).

> [!WARNING]
>
> During the write-block window the API rejects Pix key create, update, and delete requests to prevent inconsistencies with BACEN. The plugin reads the window in `America/Sao_Paulo` time. Schedule it during low-traffic periods.

# Statistics

***

The **Statistics** domain exposes BACEN's Pix risk and usage aggregates. You can assess a counterparty before you settle a payment. Both endpoints query the provider directly and do not store data locally. Treat every call as a fresh, real-time lookup.

| Endpoint | Scope | Use it to |
| - | - | - |
| `GET /v1/dict/statistics/persons/{tax_id}` | A person (CPF or CNPJ) | Assess a payer/payee across all their keys and accounts |
| `GET /v1/dict/statistics/keys/{key}` | A single Pix key | Assess a specific key, plus its current owner |

## Person statistics

Pass the tax ID (CPF or CNPJ) in the path. The response aggregates settlement data, fraud markers, infraction reports, and entry information. It covers three rolling windows: **d90** (last 90 days), **m12** (last 12 months), and **m60** (last 60 months).

```json theme={null}
GET /v1/dict/statistics/persons/12345678901
→ 200 OK
{
  "spi": { "settlements": { "d90": "42", "m12": "310", "m60": "1580" } },
  "fraudMarkers": { "muleAccounts": { "d90": "0", "m12": "1" } },
  "infractionReports": { "openReports": 0, "rejectedReports": { "m12": "2" } },
  "entries": { "registeredAccounts": 2 }
}
```

## Key statistics

Pass the Pix key in the path. The response returns two statistics in a single call: key-level and owner-level. Key-level statistics tie to the key as an entity, independent of its current owner. Owner-level statistics match the person statistics for the key's current owner.

```json theme={null}
GET /v1/dict/statistics/keys/john.doe@example.com
→ 200 OK
{
  "keyStatistics": {
    "spi": { "settlements": { "d90": "12" } },
    "infractionReports": { "openReports": 0 },
    "entries": { "distinctAccounts": { "m12": "1" } }
  },
  "ownerStatistics": {
    "fraudMarkers": { "muleAccounts": { "d90": "0" } },
    "infractionReports": { "openReports": 0 },
    "entries": { "registeredAccounts": 1 }
  }
}
```

> [!NOTE]
>
> Use key statistics when you pay a specific key. Use person statistics for a broader counterparty risk view. The plugin does not persist either result. Cache responsibly on your side if you reuse a result within a request flow.

**Reference:** [Retrieve person statistics](/en/reference/interfaces/pix-btg/retrieve-person-statistics) · [Retrieve key statistics](/en/reference/interfaces/pix-btg/retrieve-key-statistics)

# Fraud markers and MED 1.0

***

DICT also exposes BACEN's **MED** (Mecanismo Especial de Devolução) fraud-prevention tools. **Fraud markers** flag a key or account as associated with fraud. You can create and cancel them (fraud types: `APPLICATION_FRAUD`, `MULE_ACCOUNT`, `SCAMMER_ACCOUNT`, `OTHER`). Related **infraction reports** and **refund requests** drive the MED 1.0 dispute workflow.

**Reference:** [Create a fraud marker](/en/reference/interfaces/pix-btg/create-a-fraud-marker) · [Cancel a fraud marker](/en/reference/interfaces/pix-btg/cancel-a-fraud-marker) · [List fraud markers](/en/reference/interfaces/pix-btg/list-fraud-markers)

## Infraction reports

An **infraction report** tells the counterparty PSP that you dispute a transaction as fraud. You can open a report only within 90 days of the transaction date. The report follows a create → acknowledge → close/cancel lifecycle:

| Step | Role | Endpoint |
| - | - | - |
| Create | Reporter (payer's PSP) | `POST /v1/dict/infraction-reports` |
| Acknowledge | Counterparty PSP | `POST /v1/dict/infraction-reports/{id}/acknowledge` |
| Close | Payee's/payer's PSP | `POST /v1/dict/infraction-reports/{id}/close` |
| Cancel | Reporter | `POST /v1/dict/infraction-reports/{id}/cancel` |

* **Create**: open the report against the disputed end-to-end ID, e.g. `reason: REFUND_REQUEST`, `situationType: SCAM`.
* **Acknowledge**: the receiving PSP confirms receipt of the report.
* **Close**: the responding PSP submits its analysis result (`AGREED` or `DISAGREED`) within 7 days. The payee's PSP closes `REFUND_REQUEST` infractions. The payer's PSP closes `REFUND_CANCELLED` infractions. After close, the report becomes immutable.
* **Cancel**: the reporter withdraws a report it opened.

```json theme={null}
POST /v1/dict/infraction-reports
{
  "transactionId": "E12345678202411241430ABCDEFGHIJK",
  "reason": "REFUND_REQUEST",
  "situationType": "SCAM",
  "reportDetails": "Customer reported receiving a call from a fake bank employee"
}
```

## Refund requests

A **refund request** is the MED 1.0 mechanism to ask the counterparty PSP to return disputed funds. It follows a create → close/cancel lifecycle:

| Step | Endpoint |
| - | - |
| Create | `POST /v1/dict/refund-requests` |
| Retrieve / List | `GET /v1/dict/refund-requests/{id}` · `GET /v1/dict/refund-requests` |
| Close | `POST /v1/dict/refund-requests/{id}/close` |
| Cancel | `POST /v1/dict/refund-requests/{id}/cancel` |

**Close** records the analysis result and finalizes the request. **Cancel** withdraws a pending request. Outbound webhooks deliver status changes for both infraction reports and refund requests. See the [Webhooks guide](/en/interfaces/pix-btg/indirect-pix-webhooks).

**Reference:** [Create an infraction report](/en/reference/interfaces/pix-btg/create-an-infraction-report) · [Acknowledge](/en/reference/interfaces/pix-btg/acknowledge-an-infraction-report) · [Close](/en/reference/interfaces/pix-btg/close-an-infraction-report) · [Cancel](/en/reference/interfaces/pix-btg/cancel-an-infraction-report) · [Create a refund request](/en/reference/interfaces/pix-btg/create-a-refund-request)

For the fund-recovery flows, see [Refund operations](/en/interfaces/pix-btg/indirect-pix-refund-operations) and [MED 2.0: Funds Recovery](/en/interfaces/pix-btg/indirect-pix-med-2-funds-recovery).

# Next steps

***

* [QR Codes](/en/interfaces/pix-btg/indirect-pix-qrcodes): Generating QR Codes on registered keys
* [Webhooks](/en/interfaces/pix-btg/indirect-pix-webhooks): Claim, infraction, and refund notifications
* [Integration](/en/interfaces/pix-btg/indirect-pix-integration): DICT reconciliation and worker configuration


# Environment variables
Source: https://docs.lerian.studio/en/interfaces/pix-btg/indirect-pix-environment-variables

Configure the Pix Indirect via BTG rail: BTG mTLS, DB_* datastores, Midaz and CRM bindings, webhook endpoints, and worker components at deploy time.

Pix Indirect via BTG reaches the Pix arrangement through BTG as the direct participant. It ships as several components: an API, plus reconciliation, schedule, and inbound and outbound webhook workers. DevOps sets the environment variables for each component at deploy time. To change a variable, you restart that component. This page covers the variables distinctive to this rail. For the streaming, telemetry, and authentication knobs shared across every Lerian Go service, see [BYOC configuration essentials](/en/reference/byoc-configuration).

> [!NOTE]
>
> In the tables below, the **Default / Required** column shows the default value. A bold qualifier (for example **Required**) marks variables you must set. `—` means no default. `🔒` marks a secret. Inject each secret at deploy time from your secret store. Never commit a secret. This page lists variable names and behavior only. It prints no secret values.

> [!NOTE]
>
> This rail does not mount the systemplane admin API. Its datastore variables use a `DB_*` prefix rather than the shared `POSTGRES_*` shape. See [Datastores](#datastores) below.

## Components and ports

The API component listens on `SERVER_ADDRESS` (for example `:4014`). The reconciliation, schedule, and webhook workers each bind a `WORKER_PORT` for their health probes. See [Default network ports](/en/reference/default-network-ports).

## BTG integration and mTLS

These variables hold the BTG credentials and the mutual-TLS settings in both directions: the client certificate the plugin presents to BTG, and the check of the certificate BTG presents on inbound webhooks.

| Variable | Default / Required | Description |
| - | - | - |
| `BTG_BASE_URL` | **Required** | Base URL of the BTG API. |
| `BTG_CERTIFICATE_URL` | **Required** when `MTLS_ENABLED=true` | URL of BTG's public certificate. The API compares it with the certificate BTG presents on inbound webhooks. |
| `BTG_CLIENT_ID` | **Required** | OAuth client ID for the BTG API. |
| `BTG_CLIENT_SECRET` | 🔒 **Required** | OAuth client secret for the BTG API. |
| `BTG_WEBHOOK_SECRET` | 🔒 **Required** when validation is enabled | Secret used to validate inbound BTG webhook signatures. |
| `BTG_WEBHOOK_VALIDATION_ENABLED` | `false` | Verify BTG webhook signatures. Set `true` in production. |
| `MTLS_ENABLED` | `false` | Check the certificate BTG presents on inbound webhooks. Enable in production. |
| `MTLS_CERTIFICATE_HEADER` | `X-Client-Cert` | Header in which your ingress forwards the certificate BTG presented. Your ingress must set this header from the TLS handshake and overwrite any value the caller sends. |
| `MTLS_CERTIFICATE_TTL` | `24h` | How long the fetched BTG certificate is cached before refresh. |
| `MTLS_HTTP_TIMEOUT` | `10s` | Timeout for the certificate-fetch HTTP call. |
| `BTG_OUTBOUND_MTLS_ENABLED` | `false` | Present a client certificate on calls to BTG. |
| `CLIENT_TLS_CERT_FILE` · `CLIENT_TLS_KEY_FILE` | 🔒 **Required** when outbound mTLS is enabled | Paths to the PEM client certificate and private key. |
| `CLIENT_TLS_CA_FILE` | — | Optional PEM bundle that verifies the BTG server certificate. |

## Datastores

This rail uses a `DB_*` prefix for datastores, not the shared `POSTGRES_*` shape. It connects to a primary PostgreSQL, a separate read replica, MongoDB, and Redis.

| Variable | Default / Required | Description |
| - | - | - |
| `DB_HOST` · `DB_PORT` | **Required** | Primary PostgreSQL host and port. |
| `DB_USER` · `DB_PASSWORD` | 🔒 **Required** | Primary PostgreSQL credentials. |
| `DB_NAME` | **Required** | Primary database name. |
| `DB_SSL_MODE` | — | libpq TLS mode. Set it explicitly. Use `require` or stronger in production. |
| `DB_REPLICA_HOST` · `DB_REPLICA_PORT` · `DB_REPLICA_NAME` · `DB_REPLICA_USER` · `DB_REPLICA_PASSWORD` | 🔒 — | Optional read-replica connection (same shape as the primary). |
| `MONGO_URI` · `MONGO_HOST` · `MONGO_PORT` · `MONGO_USER` · `MONGO_PASSWORD` · `MONGO_NAME` | 🔒 **Required** | MongoDB connection. `MONGO_URI` sets the connection scheme (`mongodb` or `mongodb+srv`); `MONGO_HOST`, `MONGO_PORT`, `MONGO_USER`, `MONGO_PASSWORD`, and `MONGO_NAME` supply the host, credentials, and database. All combine into one connection string. They are not URI-versus-discrete alternatives. The password is a secret. |
| `MONGO_TLS` | `false` | Enable TLS to MongoDB. |
| `REDIS_HOST` · `REDIS_PASSWORD` | 🔒 — | Redis/Valkey `host:port` endpoint and auth password. |
| `REDIS_TLS` · `REDIS_CA_CERT` | `false` · — | Enable TLS to Redis and supply a base64-encoded PEM CA. |
| `DEPLOYMENT_MODE` | `local` | `local`, `byoc`, or `saas`. With `saas`, a component does not start if a datastore it uses has no TLS. PostgreSQL needs `DB_SSL_MODE` set to `require`, `verify-ca`, or `verify-full`. Redis needs `REDIS_TLS=true`. MongoDB needs `MONGO_TLS=true`. |

## Midaz, CRM, and Fees

| Variable | Default / Required | Description |
| - | - | - |
| `MIDAZ_ONBOARDING_URL` · `MIDAZ_TRANSACTION_URL` | **Required** | Midaz onboarding and transaction service URLs. |
| `MIDAZ_ORGANIZATION_ID` · `MIDAZ_LEDGER_ID` | **Required** | Midaz organization and ledger UUIDs for Pix bookings. |
| `MIDAZ_CLIENT_ID` · `MIDAZ_CLIENT_SECRET` | 🔒 **Required** | OAuth credentials for Midaz M2M. |
| `MIDAZ_COUNTERPARTY_ACCOUNT_ALIAS` | `@external/BRL` | Midaz account that Pix cash-out postings credit. |
| `MIDAZ_CASHOUT_TRANSACTION_ROUTE` · `MIDAZ_CASHOUT_SOURCE_OPERATION_ROUTE` · `MIDAZ_CASHOUT_DESTINATION_OPERATION_ROUTE` | — | Midaz transaction route, debit operation route, and credit operation route for Pix cash-out postings. If a value is empty, the plugin sends no route for it. |
| `MIDAZ_CASHOUT_REFUND_TRANSACTION_ROUTE` | — | Midaz transaction route for a refund that sends an `operations` array, or that returns the full amount of a cash-in with fees. If it is empty, the plugin uses `MIDAZ_CASHOUT_TRANSACTION_ROUTE`. |
| `PLUGIN_CRM_BASE_URL` · `PLUGIN_CRM_CLIENT_ID` · `PLUGIN_CRM_CLIENT_SECRET` | 🔒 **Required** | CRM service URL and OAuth credentials. |
| `FEE_SERVICE_URL` · `FEE_CLIENT_ID` · `FEE_CLIENT_SECRET` | 🔒 **Required** when `CASHIN_FEE_CALCULATION_TYPE=segment` | Fees Engine service URL and OAuth credentials. |
| `FEE_SERVICE_TIMEOUT` | `5000` | Fee request timeout, in milliseconds. |
| `CASHIN_FEE_CALCULATION_TYPE` | — | Set `segment` to calculate cash-in fees from the account segment. Leave it empty to skip cash-in fees. |

## Internal webhooks and scheduling

The API and workers exchange events over an internal webhook channel. They also run recurring and scheduled Pix flows.

| Variable | Default / Required | Description |
| - | - | - |
| `INTERNAL_WEBHOOK_SECRET` | 🔒 **Required** | HMAC secret shared between the API and workers for internal webhook signing. At least 32 characters. |
| `INTERNAL_WEBHOOK_VALIDATION_ENABLED` | `false` | Verify internal webhook signatures. Set `true` in production. |
| `INTERNAL_WEBHOOK_TIMESTAMP_TOLERANCE` | `300` | Allowed clock skew, in seconds, when validating internal webhook timestamps. |
| `WEBHOOK_RECEIVER_MAX_PAYLOAD_SIZE` · `WEBHOOK_RECEIVER_MAX_RETRIES` | `10485760` (10 MB) · `3` | Inbound webhook payload cap and retry ceiling. |
| `RECURRING_SCHEDULE_LEAD_DAYS` · `RECURRING_ANTISPAM_WINDOW` · `RECURRING_REPLY_BACKOFF` · `RECURRING_REPLY_MAX_ATTEMPTS` | `1` · `720h` · `150ms` · `3` | Recurring-Pix scheduling and reply-handling knobs. |
| `SCHEDULE_DEFAULT_EXECUTE_HOUR_BRT` · `SCHEDULE_MAX_ATTEMPTS` · `SCHEDULE_MAX_FUTURE_DAYS` · `SCHEDULE_MIN_FUTURE_SECONDS` | `6` · `2` · `180` · `60` | Scheduled-payment execution window and bounds. |
| `RECONCILIATION_INTERNAL_CIDR` | — | Network range of your internal reconciliation service. |

## Pix and ledger scope

| Variable | Default / Required | Description |
| - | - | - |
| `PIX_ISPB` | **Required** | The ISPB (participant code) this deployment operates under: 8 characters, digits or uppercase letters. |
| `ENTRY_WRITE_BLOCK_START` · `ENTRY_WRITE_BLOCK_END` | — | Daily window (`HH:MM`, São Paulo time) during which the API blocks Pix key create, update, and delete. |
| `ORGANIZATION_IDS` | **Required in production** | Comma-separated Midaz organization UUIDs in the licensing scope. |
| `GOOGLE_APPLICATION_CREDENTIALS` | 🔒 — | Google service-account credentials (a file path or the JSON content) for Redis GCP IAM authentication. |

## Health and readiness

Each component exposes `GET /health` (liveness) and `GET /readyz` (readiness) on its port. See [Health and readiness](/en/reference/health-and-readiness) for the response shape.


# Setting up the integration
Source: https://docs.lerian.studio/en/interfaces/pix-btg/indirect-pix-integration

Configure the Pix Indirect Plugin (BTG): licensing, authentication, Midaz, CRM, BTG connectivity, and worker setup.

The Pix Indirect Plugin (BTG) connects to multiple Lerian services and external providers to process Pix payments. To set it up, you configure the plugin's connection to each service and prepare the data those services need.

The plugin runs as two main layers. The **Application** exposes the Pix API and processes business logic. The **Workers** handle inbound webhooks from BTG, outbound event delivery to your system, DICT reconciliation with BACEN, and scheduled payments. Both layers share the same foundational configuration (license, Midaz, CRM, BTG) but have their own service-specific settings.

# Prerequisites

***

Before you begin, make sure you have:

* Your **ISPB** (Identificador do Sistema de Pagamentos Brasileiro): the 8-character identifier derived from your institution's CNPJ
* Access to your Midaz and CRM instances (deployed and running)
* Access to BTG provider services (BTG provides the credentials)

```bash theme={null}
# Your institution's ISPB (8 characters: digits or uppercase letters)
PIX_ISPB=12345678
```

> [!NOTE]
>
> The plugin uses `PIX_ISPB` to build and check end-to-end IDs. It detects intra-PSP (P2P) transfers from the payer's alias account instead: see [Intra-PSP transfers](/en/interfaces/pix-btg/indirect-pix-intra-psp).

# 1. License

***

The plugin is an enterprise solution and requires a valid license to operate. Lerian provides the license key during onboarding.

```bash theme={null}
# License key provided by Lerian
LICENSE_KEY=

# Authorized organization IDs (comma-separated)
ORGANIZATION_IDS=
```

**Related documentation:** [Lerian's License](/en/start-here/evaluate-and-deploy/lerians-license)

# 2. Access Manager (optional)

***

Access Manager handles authentication for the plugin. When enabled, it validates incoming requests before they reach the plugin's API.

```bash theme={null}
# Require authentication for plugin requests (true/false)
PLUGIN_AUTH_ENABLED=false

# Access Manager service URL (required: the plugin also gets its Midaz, CRM, and Fee tokens here)
PLUGIN_AUTH_ADDRESS=
```

When `PLUGIN_AUTH_ENABLED=true`, the plugin validates the `Authorization` header of each request to ensure:

* The token belongs to an authorized user or application
* The token grants access to the requested API endpoint and method

> [!NOTE]
>
> The Midaz and CRM client credentials (`CLIENT_ID` / `CLIENT_SECRET`) are required even when `PLUGIN_AUTH_ENABLED=false`. The Fee credentials are required when `CASHIN_FEE_CALCULATION_TYPE=segment`.

**Related documentation:** [Access Manager](/en/platform/access-manager)

# 3. Midaz

***

Midaz is the core ledger for all Pix transactions the plugin processes. The plugin posts every cash-in, cash-out, and refund operation to Midaz as a double-entry transaction.

## Connection

***

```bash theme={null}
# Your organization ID in Midaz
MIDAZ_ORGANIZATION_ID=

# Your ledger ID in Midaz
MIDAZ_LEDGER_ID=

# Midaz Transaction module URL
MIDAZ_TRANSACTION_URL=

# Midaz Onboarding module URL
MIDAZ_ONBOARDING_URL=

# Midaz API credentials (required)
MIDAZ_CLIENT_ID=
MIDAZ_CLIENT_SECRET=
```

## Asset requirements

***

Configure an asset in your organization and ledger with these properties:

| Property | Value |
| - | - |
| Type | `currency` |
| Code | `BRL` |

Link all accounts to your ledger using the `BRL` asset. The plugin rejects operations on accounts that don't match this configuration.

## Account setup

***

Before using the plugin, create an account in Midaz for each customer under your ISPB.

Use the **Create an Account** endpoint to set up accounts. Each account must:

* Belong to your configured organization and ledger
* Use the `BRL` asset

## X-Account-Id header

***

Many Pix operations require the `X-Account-Id` header to identify which account performs the action. This ID corresponds to the **Midaz ledger account ID**.

When you call a plugin endpoint, the `X-Account-Id` value tells the plugin:

* Which account to use for ledger operations
* Which customer data to fetch from CRM
* Which balance to validate and update

### How the plugin uses the account ID

The plugin uses the account ID differently depending on the operation type:

| Flow type | How the plugin uses the account ID |
| - | - |
| **Non-transactional** (e.g., creating keys or QR codes) | Fetches customer and bank account data from CRM |
| **Transactional** (e.g., payments, refunds) | Fetches customer data for payment initiation |
| | Validates account data for incoming payment authorization |
| | Executes the transaction in the ledger |

## Account compliance

***

The plugin does not enforce business-level account restrictions, such as blocked or suspended accounts. Your application must validate account status before it calls the plugin.

To prevent Pix settlements on a specific account, block it directly in Midaz. The plugin receives a rejection when it attempts to post the transaction.

**Related documentation:**

* [Update an Account](/en/reference/products/midaz/v2/update-account)
* [Update a Balance](/en/reference/products/midaz/v2/update-balance)

# 4. CRM

***

The CRM stores customer (holder) information and their associated bank accounts. Every Midaz account must have a corresponding **holder** and **alias account** in the CRM to perform Pix operations.

The plugin queries CRM data to:

* Register and validate Pix keys
* Build payment messages for BACEN
* Authorize incoming transactions
* Process refund and dispute workflows

## Connection

***

```bash theme={null}
# CRM base URL
PLUGIN_CRM_BASE_URL=

# CRM API credentials (required)
PLUGIN_CRM_CLIENT_ID=
PLUGIN_CRM_CLIENT_SECRET=
```

## Holders

***

Holder data represents the customer who owns the account. Create each holder in the CRM before executing any Pix operation for that customer.

### Required fields

| Field | Requirement | Example |
| - | - | - |
| `name` | Maximum 120 characters | `Maria Silva Santos` |
| `document` | For `NATURAL_PERSON`, a CPF with 11 digits; for `LEGAL_PERSON`, a CNPJ with 14 digits | `12345678900` |
| `type` | Person type (enum values from CRM) | `NATURAL_PERSON` |

### Optional fields

| Field | When to use |
| - | - |
| `legalPerson.tradeName` | When associating a trade name with the key data |
| `addresses.primary` | Required for Due Date collection creation |

**Related documentation:** [Create a Holder](/en/reference/products/midaz/v2/create-holder)

## Alias accounts

***

Alias accounts link a Midaz account to its banking details. Each alias account must include the banking information that the Pix ecosystem requires for transaction processing.

### Required fields

| Field | Requirement | Example |
| - | - | - |
| `accountId` | Midaz account ID (UUID) | `3c90c3cc-0d44-4b50-8888-8dd25736052a` |
| `bankingDetails.branch` | Exactly 4 digits | `0001` |
| `bankingDetails.account` | 1 to 20 digits | `123456789` |
| `bankingDetails.type` | Account type (see table below) | `CACC` |
| `bankingDetails.openingDate` | YYYY-MM-DD format | `2024-01-15` |
| `bankingDetails.bankId` | The ISPB of the institution that holds the account. Required to send a Pix | `12345678` |

> [!WARNING]
>
> The `bankingDetails.branch` field must contain exactly 4 digits. Pad with leading zeros if necessary. For example, if the branch number is `1`, register it as `0001`. The plugin can only validate the account in the CRM when the branch code follows this format.

### Supported account types

| Code | Description |
| - | - |
| `CACC` | Checking account |
| `SLRY` | Salary account |
| `SVGS` | Savings account |
| `TRAN` | Transaction account |

**Related documentation:** [Create an Alias Account](/en/reference/products/midaz/v2/create-instrument)

# 5. BTG provider

***

BTG is the direct participant that connects your institution to BACEN's Pix infrastructure. BTG provides the credentials directly when your institution signs up for indirect BACEN integration.

## Connection

***

```bash theme={null}
# BTG API base URL
BTG_BASE_URL=

# BTG API credentials
BTG_CLIENT_ID=
BTG_CLIENT_SECRET=
```

## mTLS (webhook security)

***

Mutual TLS (mTLS) validates BTG's certificate on webhook requests. It confirms that incoming webhooks originate from BTG. Your ingress forwards the certificate BTG presents in the `MTLS_CERTIFICATE_HEADER` header (default `X-Client-Cert`).

```bash theme={null}
# Enable mTLS validation (true/false)
# Use 'true' in production, 'false' for local development
MTLS_ENABLED=false

# How long to cache the certificate before refreshing
# Format: Go duration (e.g., 24h, 12h, 1h)
MTLS_CERTIFICATE_TTL=24h

# BTG endpoint that provides the public certificate (required when MTLS_ENABLED=true)
BTG_CERTIFICATE_URL=

# Timeout for certificate fetch requests
# Format: Go duration (e.g., 10s, 30s)
MTLS_HTTP_TIMEOUT=10s
```

> [!WARNING]
>
> Always enable mTLS in production environments. Only disable it during local development.

To present a client certificate on the plugin's own calls to BTG, set `BTG_OUTBOUND_MTLS_ENABLED=true` with `CLIENT_TLS_CERT_FILE` and `CLIENT_TLS_KEY_FILE`. See [Environment variables](/en/interfaces/pix-btg/indirect-pix-environment-variables).

# 6. Fee service (optional)

***

Enable fee calculation to automatically charge and distribute fees on incoming payments. This is optional. If you don't configure it, the plugin processes transactions without fee calculation.

## Connection

***

```bash theme={null}
# Fee calculation method (currently only 'segment' is supported)
CASHIN_FEE_CALCULATION_TYPE=

# Fee service URL
FEE_SERVICE_URL=

# Request timeout in milliseconds
FEE_SERVICE_TIMEOUT=5000

# Fee service API credentials (required when CASHIN_FEE_CALCULATION_TYPE=segment)
FEE_CLIENT_ID=
FEE_CLIENT_SECRET=
```

## How it works

***

When you set `CASHIN_FEE_CALCULATION_TYPE=segment`, the plugin:

1. **Retrieves the segment** associated with the receiving account
2. **Calculates applicable fees** before processing the transaction in Midaz
3. **Distributes the incoming payment** according to any package rules linked to that segment

## Setup steps

***

1. **Create segments in Midaz**: Define the account segments that determine fee rules
2. **Configure packages in Fees Engine**: Link each segment to its fee calculation rules
3. **Assign segments to accounts**: Create or update Midaz accounts with the appropriate segment ID

**Related documentation:**

* [Fees Engine - Guides](/en/products/midaz/fees/fees-engine-overview)
* [Fees Engine - APIs](/en/reference/products/midaz/v2/create-package)

# 7. DICT reconciliation (VSync)

***

VSync reconciles your local DICT data with BACEN by processing all key-related events from the day. It keeps your local state consistent with BACEN's authoritative records.

```bash theme={null}
# Write block window (24-hour format, America/Sao_Paulo time)
ENTRY_WRITE_BLOCK_START=23:30
ENTRY_WRITE_BLOCK_END=23:35

# Network allowed to write Pix keys during the window
RECONCILIATION_INTERNAL_CIDR=
```

> [!WARNING]
>
> During the window, the API rejects Pix key create, update, and delete requests to prevent data inconsistencies with BACEN. Plan the write block window during low-traffic periods.

## Redis cache configuration

***

VSync uses Redis to cache BTG/DICT entries and CRM holders during reconciliation. In Helm deployments the default `REDIS_HOST` points to the built-in Valkey, so no extra setup is required for a standard install.

```bash theme={null}
# Connection (always used)
REDIS_HOST=<valkey-host>:6379
REDIS_MASTER_NAME=
REDIS_DB=0
REDIS_PROTOCOL=3

# Connection pool and retries (always used)
REDIS_POOL_SIZE=10
REDIS_MIN_IDLE_CONNS=0
REDIS_READ_TIMEOUT=3
REDIS_WRITE_TIMEOUT=3
REDIS_DIAL_TIMEOUT=5
REDIS_POOL_TIMEOUT=2
REDIS_MAX_RETRIES=3
REDIS_MIN_RETRY_BACKOFF=8
REDIS_MAX_RETRY_BACKOFF=512

# Authentication (optional — only used if set)
REDIS_PASSWORD=

# TLS (optional — only used if REDIS_TLS=true)
REDIS_TLS=false
REDIS_CA_CERT=

# GCP IAM authentication (optional — only used if REDIS_USE_GCP_IAM=true)
REDIS_USE_GCP_IAM=false
REDIS_SERVICE_ACCOUNT=
GOOGLE_APPLICATION_CREDENTIALS=
REDIS_TOKEN_LIFETIME=60
REDIS_TOKEN_REFRESH_DURATION=45

# VSync cache TTLs (always used)
CACHE_BTG_ENTRY_TTL=30m
CACHE_CRM_HOLDER_TTL=30m
```

### Connection (always used)

| Var | Type | Default | Description |
| - | - | - | - |
| `REDIS_HOST` | string (host:port, CSV) | Built-in Valkey (Helm chart) | Redis address(es). Multiple addresses separated by comma define Sentinel/Cluster topology. |
| `REDIS_MASTER_NAME` | string | `""` | Sentinel master name. Empty = standalone (direct connection). |
| `REDIS_DB` | int | `0` | Redis logical database number. |
| `REDIS_PROTOCOL` | int | `3` | RESP protocol version (2 or 3). |

### Connection pool and retries (always used)

| Var | Type | Default | Description |
| - | - | - | - |
| `REDIS_POOL_SIZE` | int | `10` | Maximum connections in the pool. |
| `REDIS_MIN_IDLE_CONNS` | int | `0` | Minimum idle connections kept ready. |
| `REDIS_READ_TIMEOUT` | int (seconds) | `3` | Read operation timeout. |
| `REDIS_WRITE_TIMEOUT` | int (seconds) | `3` | Write operation timeout. |
| `REDIS_DIAL_TIMEOUT` | int (seconds) | `5` | Timeout to establish the initial connection. |
| `REDIS_POOL_TIMEOUT` | int (seconds) | `2` | Timeout waiting for a free connection from the pool. |
| `REDIS_MAX_RETRIES` | int | `3` | Maximum retries for a failed command. |
| `REDIS_MIN_RETRY_BACKOFF` | int (milliseconds) | `8` | Minimum delay between retries. |
| `REDIS_MAX_RETRY_BACKOFF` | int (seconds) | `512` | Maximum delay between retries. Note: stored in seconds in code (different unit from min). |

### Authentication (optional, only used if set)

| Var | Type | Default | Description |
| - | - | - | - |
| `REDIS_PASSWORD` | string (secret) | `""` | Redis password. Empty = no password authentication. |

### TLS (optional, only used if `REDIS_TLS=true`)

| Var | Type | Default | Description |
| - | - | - | - |
| `REDIS_TLS` | bool | `false` | Enables TLS. Required `true` in `DEPLOYMENT_MODE=saas` (validated at boot). |
| `REDIS_CA_CERT` | string (PEM base64) | `""` | CA certificate (base64) to validate the server when TLS is active. |

### GCP IAM authentication (optional, only used if `REDIS_USE_GCP_IAM=true`)

| Var | Type | Default | Description |
| - | - | - | - |
| `REDIS_USE_GCP_IAM` | bool | `false` | Enables GCP IAM authentication (Memorystore) instead of password. |
| `REDIS_SERVICE_ACCOUNT` | string | `""` | GCP service account that generates the access token. |
| `GOOGLE_APPLICATION_CREDENTIALS` | string | `""` | GCP credentials (a file path or the JSON content) to generate the token. |
| `REDIS_TOKEN_LIFETIME` | int (minutes) | `60` | Lifetime of the generated IAM token. |
| `REDIS_TOKEN_REFRESH_DURATION` | int (minutes) | `45` | Token refresh interval (must be less than lifetime). |

### VSync cache TTLs (always used)

| Var | Type | Default | Description |
| - | - | - | - |
| `CACHE_BTG_ENTRY_TTL` | Go duration | `30m` | Cache TTL for BTG/DICT entries in Redis. Negative value reverts to default. |
| `CACHE_CRM_HOLDER_TTL` | Go duration | `30m` | Cache TTL for CRM holders in Redis. Negative value reverts to default. |

# 8. Internal webhook security

***

The plugin uses an internal communication channel between the Worker and Application services. HMAC-SHA256 signatures secure this channel to prevent tampering and replay attacks.

```bash theme={null}
# Shared secret for signing internal requests (Worker -> Application)
# Must be at least 32 characters
# Generate one with: openssl rand -base64 32
INTERNAL_WEBHOOK_SECRET=

# Validate signatures on incoming internal webhooks (true/false)
# Always use 'true' in production
INTERNAL_WEBHOOK_VALIDATION_ENABLED=true

# Maximum age (in seconds) for request timestamps before rejection
# Default: 300 (5 minutes)
INTERNAL_WEBHOOK_TIMESTAMP_TOLERANCE=300
```

> [!WARNING]
>
> Use the exact same `INTERNAL_WEBHOOK_SECRET` value in both the Application and Worker services. A mismatch causes the plugin to reject all internal webhooks.

# 9. Worker layers

***

The plugin operates with four workers, each handling a different part of the Pix lifecycle. Each worker runs as a separate service alongside the main application.

## Inbound worker

***

The Application receives webhook notifications from BTG and stores them. The inbound worker then delivers each notification to the Application's internal endpoints for processing.

```bash theme={null}
# Application URL for internal webhooks
WEBHOOK_INBOUND_BASE_URL=

# Shared secret for signing requests (must match the application's INTERNAL_WEBHOOK_SECRET)
INTERNAL_WEBHOOK_SECRET=
```

## Outbound worker

***

The outbound worker sends event notifications from the plugin to your application via webhooks. This is how your system stays informed about Pix events (transfers, refunds, claims, disputes).

### URL resolution priority

The plugin resolves webhook URLs in this order, using the first match:

1. **Entity URL**: A URL specific to the event type (e.g., `WEBHOOK_DICT_CLAIM_URL`)
2. **Flow URL**: A URL for the broader category (e.g., `WEBHOOK_DICT_URL`)
3. **Default URL**: The fallback URL (`WEBHOOK_DEFAULT_URL`)

```bash theme={null}
# Default fallback URL
WEBHOOK_DEFAULT_URL=

# DICT-related events
WEBHOOK_DICT_URL=
WEBHOOK_DICT_CLAIM_URL=
WEBHOOK_DICT_INFRACTION_REPORT_URL=
WEBHOOK_DICT_REFUND_URL=

# MED 2.0 Funds Recovery events (DICT flow)
# These route under the DICT flow and fall back to WEBHOOK_DICT_URL,
# then WEBHOOK_DEFAULT_URL, if no entity-specific URL is set.
WEBHOOK_DICT_FUNDS_RECOVERY_URL=
WEBHOOK_DICT_FUNDS_RECOVERY_EVENTS_URL=

# Refund events
WEBHOOK_REFUND_CASHIN_URL=
WEBHOOK_REFUND_CASHOUT_URL=

# Transfer events
WEBHOOK_TRANSFER_CASHIN_URL=
WEBHOOK_TRANSFER_CASHOUT_URL=
```

Each entity needs its own `WEBHOOK_<FLOW>_<ENTITY>_*` variable. See [Webhooks](/en/interfaces/pix-btg/indirect-pix-webhooks).

For webhook event types, payloads, retry behavior, and best practices, see the [Webhooks guide](/en/interfaces/pix-btg/indirect-pix-webhooks).

## Reconciliation worker

***

The reconciliation worker needs the same credentials as the Application layer for these services:

* **CRM**: URL and credentials
* **BTG**: URL and credentials
* **Midaz**: Organization ID

It also calls the Application API with its own client credentials: `PLUGIN_PIX_BTG_BASE_URL`, `PLUGIN_PIX_BTG_CLIENT_ID`, and `PLUGIN_PIX_BTG_CLIENT_SECRET`, with the token endpoint in `PLUGIN_AUTH_URL`.

See the corresponding sections above for details on each configuration.

You can restrict when the worker operates by configuring a specific time window. This is useful for scheduling reconciliation tasks during off-peak hours. The plugin supports time windows that span midnight.

```bash theme={null}
# Start time in HH:MM format (24-hour, BRT). Example: "23:00" for 11 PM BRT
RECONCILIATION_START_TIME=

# End time in HH:MM format (24-hour, BRT). Example: "05:00" for 5 AM BRT
RECONCILIATION_END_TIME=
```

> [!NOTE]
>
> If you leave both fields empty, the worker runs without time restrictions (24/7).

> [!NOTE]
>
> The worker always interprets the reconciliation window in the **`America/Sao_Paulo`** (BRT) timezone, whatever the container clock or the `TZ` variable. The worker embeds the IANA timezone data. The window stays aligned with the BACEN DICT write-block, even on minimal or distroless images. You do not need to set `TZ`.

## Schedule worker

***

The schedule worker runs scheduled Pix payments when they are due. It is off by default. It calls the Application API with the same client-credential variables as the reconciliation worker.

```bash theme={null}
# Turn the worker on (default false)
SCHEDULE_WORKER_ENABLED=true

# Application API URL
SCHEDULE_APP_BASE_URL=

# Token endpoint and the worker's client credentials
PLUGIN_AUTH_URL=
PLUGIN_PIX_BTG_CLIENT_ID=
PLUGIN_PIX_BTG_CLIENT_SECRET=
```

> [!NOTE]
>
> Indirect Pix cashout and refund endpoints support idempotency through the `X-Idempotency` request header. The plugin keeps a replayable response for `IDEMPOTENCY_RESPONSE_TTL` seconds (default `86400`, 24 hours). For retry strategies and implementation details, see [Retries and idempotency](/en/reference/retries-idempotency).

# 10. Observability (OpenTelemetry)

***

The plugin ships with OpenTelemetry instrumentation (traces, metrics, and logs) across the Application and Worker layers. The plugin traces the Pix flows end to end: transfers (cash-in and cash-out), refunds, inbound and outbound webhooks, DICT reconciliation, and intra-PSP settlement. You can follow a single payment across the plugin, Midaz, CRM, and BTG calls.

Telemetry is disabled by default. Enable it and point the OTLP exporter at your collector:

```bash theme={null}
# Master switch — telemetry is off until this is true
ENABLE_TELEMETRY=true

# Resource attributes that identify this service in your backend
OTEL_RESOURCE_SERVICE_NAME=plugin-br-pix-indirect-btg
OTEL_LIBRARY_NAME=github.com/LerianStudio/plugin-br-pix-indirect-btg
OTEL_RESOURCE_SERVICE_VERSION=${VERSION}
OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT=${ENV_NAME}

# OTLP collector endpoint (gRPC, default port 4317)
OTEL_EXPORTER_OTLP_ENDPOINT_PORT=4317
OTEL_EXPORTER_OTLP_ENDPOINT=otel-collector:${OTEL_EXPORTER_OTLP_ENDPOINT_PORT}
```

> [!NOTE]
>
> When `ENABLE_TELEMETRY=true`, `OTEL_EXPORTER_OTLP_ENDPOINT` is required. Set the same OTel variables on the Application and on each Worker so traces correlate across services.

## Exporter: gRPC and TLS

***

The plugin exports traces, metrics, and logs over OTLP/gRPC. The endpoint scheme controls transport security:

| Endpoint value | Transport | Security |
| - | - | - |
| `https://collector:4317` | gRPC over TLS | Secure (recommended for production) |
| `http://collector:4317` | gRPC, plaintext | Insecure (inferred automatically) |
| `collector:4317` (bare `host:port`) | gRPC, plaintext | Insecure (inferred automatically) |

> [!WARNING]
>
> When `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` is `production` or `prod`, the plugin refuses to start with an insecure exporter. Use an `https://` endpoint, or set `ALLOW_INSECURE_OTEL` to a short justification only when you fully control the network path to the collector.

## Example: collector endpoint

***

Point the plugin at any OTLP-compatible collector (the OpenTelemetry Collector, Grafana LGTM/Alloy, etc.) listening on the gRPC port:

```bash theme={null}
# Local / development (plaintext gRPC)
ENABLE_TELEMETRY=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317

# Production (TLS gRPC)
ENABLE_TELEMETRY=true
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4317
```

The collector then fans telemetry out to your tracing, metrics, and logging backends.

# 11. Health and readiness

***

The Application and Workers expose a readiness probe at **`/readyz`** (alongside the standard liveness checks). Point your orchestrator's readiness probe at this endpoint so traffic is only routed once the service and its dependencies are ready.

# Transfer purpose (MED 2.0)

***

The cashout endpoint accepts an optional `X-Purpose` header that identifies the transaction purpose, used for MED 2.0 refund transfers. When omitted, it defaults to `TRANSFER`.

```bash theme={null}
# Example: a MED 2.0 refund transfer
POST /v1/transfers/cashout/process
X-Purpose: INSTANT_PAYMENT_REFUND
```

For the supported values, see [Transfers](/en/interfaces/pix-btg/indirect-pix-transfers).

# Next steps

***

With the plugin configured, you can start operating Pix.

* [Webhooks](/en/interfaces/pix-btg/indirect-pix-webhooks): Event types, payloads, retries, and best practices
* [MED 2.0: Funds Recovery](/en/interfaces/pix-btg/indirect-pix-med-2-funds-recovery): Cross-account fraud recovery and the X-Purpose header
* [Refund operations](/en/interfaces/pix-btg/indirect-pix-refund-operations): Distributed partial refunds and unblocking
* [Intra-PSP transfers](/en/interfaces/pix-btg/indirect-pix-intra-psp): Internal P2P settlement and TRCK002 reporting
* [Main domains: DICT](/en/interfaces/pix/main-domains-dict): Understanding Pix key management
* [Main domains: transactions](/en/interfaces/pix/main-domains-transactions): Transaction flows and lifecycle
* [Main domains: QR Codes](/en/interfaces/pix/main-domains-qrcodes): Static and dynamic QR code generation
* [API reference](/en/reference/interfaces/pix-btg/create-entry): Full API documentation for DICT, Claims, Transactions, QR Codes, and MED operations


# Intra-PSP transfers
Source: https://docs.lerian.studio/en/interfaces/pix-btg/indirect-pix-intra-psp

How the Pix Indirect Plugin via BTG settles intra-PSP (P2P) transfers and refunds internally without BTG settlement, while reporting to BACEN via TRCK002.

An intra-PSP transfer (also called P2P) is a Pix transfer between a payer and a payee at the same participant. The source and destination ISPB are identical. The money never leaves the institution, so the plugin settles the transfer internally and does not route it to BTG. The plugin still reports the transfer to BACEN for regulatory compliance.

> [!NOTE]
>
> The plugin supports intra-PSP transfers and refunds. It settles them internally and reports each one to BACEN through TRCK002.

# Detection

***

The plugin marks a transfer as intra-PSP when the destination ISPB matches the payer's ISPB, the `bankingDetails.bankId` of the payer's alias account in the CRM:

| Initiation type | Source of destination ISPB |
| - | - |
| `KEY` / `QR_CODE` | DICT lookup response (`account.participant`) |
| `MANUAL` | `destination.account.participant` in the request payload |

Detection is internal. The initiation response and the cashout status match an external transfer. The plugin routes an intra-PSP transfer through the internal settlement path instead of BTG. A Pix Saque or Pix Troco charge cannot settle internally: the plugin rejects it with `PIX-0497` (422).

# Processing model

***

An intra-PSP transfer uses the same Midaz routing as an external transfer, through the `@external` transit account. The ledger behavior is identical. The plugin settles the transfer synchronously and does not wait for BTG webhooks.

The plugin creates two Midaz transactions per transfer:

1. **Cashout**: `source → @external` (`pending: false`)
2. **Cashin**: `@external → destination` (`pending: false`)

The internal cash-in reuses the same approval and settlement steps as an external cash-in. These steps run CRM alias validation, balance checks, Pix key ownership, collection completion, and fee calculation.

## Flow

***

```
Process Cashout (intra-PSP detected)
  → Midaz debit: source → @external
  → Write inbound record to the webhook queue
  → Cashout status → PROCESSING (intermediary)
  → Return PROCESSING to client

Inbound worker
  → Picks up the record and delivers it (HTTP + HMAC)
    to POST /v1/payment/intra-psp/transfers/webhooks

Intra-PSP endpoint (orchestrates the full lifecycle)
  → Cash-in approval → ACCEPTED / DENIED
  → ACCEPTED  → Cash-in settlement → Midaz credit → Cashout COMPLETED
  → DENIED / settlement fails → revert Midaz debit → Cashout REJECTED
  → Report to BTG TRCK002 (async, non-blocking)
  → Outbound webhooks: TRANSFER/CASHOUT + TRANSFER/CASHIN
```

> [!NOTE]
>
> The cashout responds with `PROCESSING`, like an external cashout that waits for BTG. The plugin delivers the final status (`COMPLETED` or `REJECTED`) asynchronously through an outbound webhook. The intra-PSP endpoint is idempotent, so worker retries never duplicate transactions.

# TRCK002 regulatory reporting

***

The plugin reports every successful intra-PSP transaction to BACEN through BTG's **TRCK002** endpoint.

* TRCK002 reporting is non-blocking. A report failure never rolls back the Midaz transaction or the transfer completion. The plugin retries a failed report.
* The plugin creates a transaction report for each transaction. After BTG accepts the submission, the report status becomes `PROCESSING` and carries a `pactualId`.
* BTG sends report status updates through a **CAMT025** webhook, typed `PIX_INTERNAL_TRANSACTIONS_REPORT`. The webhook moves the report to `CONFIRMED` (terminal) or `ERROR` (recoverable).
* You can also query a report by end-to-end ID or return identification when a webhook does not arrive.

# Intra-PSP refunds

***

The plugin also processes a refund internally when the original cash-in was intra-PSP:

* The plugin detects intra-PSP from the original transfer, when its source and destination ISPB match.
* It debits the refund requester (`requester → @external`). It then delivers the refund cash-in to the original sender through the same queue and endpoint pattern.
* The plugin reports the refund to TRCK002 with a `returnIdentification`.
* The plugin sends a `REFUND` / `CASHOUT` webhook for the refund requester and a `REFUND` / `CASHIN` webhook for the original sender.

> [!WARNING]
>
> Do not call unblock for an intra-PSP transfer. The unblock flow queries BTG for the transfer status. BTG never processes an internal transaction, so the query does not apply. See [Refund operations](/en/interfaces/pix-btg/indirect-pix-refund-operations).

# Next steps

***

* [Webhooks](/en/interfaces/pix-btg/indirect-pix-webhooks): Event envelope, retries, and routing
* [Refund operations](/en/interfaces/pix-btg/indirect-pix-refund-operations): Distributed refunds and unblocking
* [Setting up the integration](/en/interfaces/pix-btg/indirect-pix-integration): ISPB and worker configuration
* [API reference](/en/reference/interfaces/pix-btg/create-entry): Full API documentation


# MED 2.0: Funds Recovery
Source: https://docs.lerian.studio/en/interfaces/pix-btg/indirect-pix-med-2-funds-recovery

Run BACEN's MED 2.0 Funds Recovery through the Pix Indirect Plugin via BTG: tracking graphs, infraction report analysis, refunds, and webhook events.

MED 2.0 (Mecanismo Especial de Devolução) is BACEN's enhanced mechanism to recover funds in cases of fraud, scams, and operational errors. MED 1.0 handles single-transaction disputes through infraction reports. MED 2.0 introduces a Funds Recovery flow that tracks how fraudulent funds moved across multiple accounts. The flow coordinates blocking, analysis, and refunds across the participating institutions.

The Pix Indirect Plugin (BTG) exposes the full Funds Recovery lifecycle as REST endpoints. It also sends webhook events, so your system stays in sync with each status change.

> [!NOTE]
>
> MED 2.0 is a BACEN requirement for Pix participants. The plugin implements the Funds Recovery flow, so you can meet this requirement through your BTG indirect connection.

# Concepts

***

| Term | Definition |
| - | - |
| **Funds Recovery** | The MED 2.0 process that recovers funds across multiple accounts after a reported fraud |
| **Tracking Graph** | A representation of how funds flowed across accounts, persons, and transactions |
| **Root transaction** | The original fraudulent Pix transaction that starts the recovery |
| **Infraction Report** | A report of a fraudulent/problematic transaction, linked to its parent Funds Recovery |
| **Refund Request** | A request to return blocked funds to the victim |

# Lifecycle and status

***

A Funds Recovery moves through the following states:

![Funds Recovery](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/indirect-pix-funds-recovery.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=67506539be970a4497522d01b46b7bd6)

| Status | Description |
| - | - |
| `CREATED` | Initial state after creation |
| `TRACKED` | Tracking graph generated |
| `AWAITING_ANALYSIS` | Blocking flow started, awaiting infraction report analysis |
| `ANALYSED` | All infraction reports analysed, ready for refund |
| `REFUNDING` | Refund requests initiated |
| `COMPLETED` | All refunds completed |
| `CANCELLED` | Recovery cancelled (only allowed before refund starts) |

# Endpoints

***

All Funds Recovery endpoints live under the DICT domain.

| Method | Endpoint | Description |
| - | - | - |
| `GET` | [`/v1/dict/funds-recoveries`](/en/reference/interfaces/pix-btg/list-funds-recoveries) | List funds recoveries |
| `POST` | [`/v1/dict/funds-recoveries`](/en/reference/interfaces/pix-btg/create-a-funds-recovery-request) | Create a funds recovery |
| `GET` | [`/v1/dict/funds-recoveries/{id}`](/en/reference/interfaces/pix-btg/retrieve-funds-recovery-details) | Consult a funds recovery |
| `PATCH` | [`/v1/dict/funds-recoveries/{id}`](/en/reference/interfaces/pix-btg/update-a-funds-recovery-request) | Update situation type and contact info |
| `POST` | [`/v1/dict/funds-recoveries/{id}/cancel`](/en/reference/interfaces/pix-btg/cancel-a-funds-recovery-request) | Cancel (before refund starts) |
| `GET` | [`/v1/dict/funds-recoveries/{id}/tracking-graph`](/en/reference/interfaces/pix-btg/retrieve-funds-recovery-tracking-graph) | View the tracking graph |
| `GET` | [`/v1/dict/funds-recoveries/{id}/infraction-reports`](/en/reference/interfaces/pix-btg/list-funds-recovery-infraction-reports) | List linked infraction reports |
| `POST` | [`/v1/dict/funds-recoveries/{id}/refund`](/en/reference/interfaces/pix-btg/request-funds-recovery-refund) | Request refunds (status must be `ANALYSED`) |
| `GET` | [`/v1/dict/funds-recoveries/{id}/refunds`](/en/reference/interfaces/pix-btg/list-funds-recovery-refunds) | List refund requests |

## Create a funds recovery

***

```json theme={null}
POST /v1/dict/funds-recoveries
{
  "rootTransactionId": "E9999901012341234123412345678900",
  "situationType": "SCAM",
  "contactInformation": {
    "email": "fraud-ops@example.com",
    "phone": "+5511999999999"
  },
  "reportDetails": "Customer reported unauthorized Pix transfer",
  "trackingGraphParameters": {
    "minTransactionAmount": "10.00",
    "maxTransactions": 5,
    "hopWindow": "PT24H",
    "maxHops": 2
  }
}
```

### Validation rules

| Field | Requirement |
| - | - |
| `rootTransactionId` | Required, 32 alphanumeric characters |
| `situationType` | Required, one of `SCAM`, `ACCOUNT_TAKEOVER`, `COERCION`, `FRAUDULENT_ACCESS`, `OTHER`, `UNKNOWN` |
| `contactInformation` | Required, object with `email` and `phone` (`+` country code and number) |
| `reportDetails` | Optional, up to 2000 characters |
| `trackingGraphParameters.minTransactionAmount` | Optional, 1 to 10 digits, a dot and 2 decimal places (e.g. `10.00`) |
| `trackingGraphParameters.maxTransactions` | Optional |
| `trackingGraphParameters.hopWindow` | Optional, ISO 8601 duration (e.g. `PT24H`) |
| `trackingGraphParameters.maxHops` | Optional |

A successful call returns **HTTP 201**. The response contains the new funds recovery and its tracking graph data. The plugin persists the record locally with status `CREATED`.

## Tracking graph

***

The plugin fetches the tracking graph fresh from BTG on every call. The graph has no local state. It lists the persons, accounts, and transactions in the fraud flow, with the refundable amount for each transaction.

```
GET /v1/dict/funds-recoveries/{id}/tracking-graph
```

Response includes:

* `parameters`: the graph generation parameters
* `persons[]`: natural and legal persons involved
* `accounts[]`: accounts in the flow with their participant ISPBs
* `transactions[]`: Pix transactions with amounts and refundable amounts

## Request refunds

***

Once the recovery reaches `ANALYSED`, request the return of blocked funds:

```
POST /v1/dict/funds-recoveries/{id}/refund
```

The plugin calls BTG, transitions the recovery to `REFUNDING`, and returns **HTTP 200**. Track individual refund statuses with [List Refunds](/en/reference/interfaces/pix-btg/list-funds-recovery-refunds).

# X-Purpose header (MED 2.0 transfers)

***

MED 2.0 refund transfers must carry a transaction purpose. The cashout endpoint accepts an optional `X-Purpose` header that the plugin sends to BTG as `transactionType`.

```
POST /v1/transfers/cashout/process
X-Purpose: INSTANT_PAYMENT_REFUND
```

| Value | Description | BTG `transactionType` |
| - | - | - |
| `TRANSFER` | Standard Pix transfer (default when header is omitted) | `TRANSFER` |
| `INSTANT_PAYMENT_REFUND` | MED 2.0 refund transfer | `INSTANT_PAYMENT_REFUND` |
| `WITHDRAWAL` | Pix Saque: pays a charge that carries a withdrawal | `WITHDRAWAL` |
| `CHANGE` | Pix Troco: pays a charge that carries a purchase and a withdrawal | `CHANGE` |

> [!WARNING]
>
> `WITHDRAWAL` and `CHANGE` must match the charge that the transfer pays. If they do not match, the plugin returns **HTTP 400** with error `PIX-0496`. The values `REFUND_AUTOMATIC_PIX` and `INSTALLMENT_PIX` return **HTTP 400** with error `PIX-0429` (Unsupported Purpose).

Transfer responses also include the `purpose` value ([Retrieve a Pix Transfer](/en/reference/interfaces/pix-btg/retrieve-a-pix-transfer) and the list endpoints). Existing records default to `TRANSFER`.

# Correlation fields

***

Two existing entities carry a `bacenFundsRecoveryId` field that links a dispute to its parent recovery:

* **Infraction reports**: [Retrieve an Infraction Report](/en/reference/interfaces/pix-btg/retrieve-an-infraction-report) and [the list endpoint](/en/reference/interfaces/pix-btg/list-infraction-reports)
* **Refund requests**: [Retrieve a Refund Request](/en/reference/interfaces/pix-btg/retrieve-a-refund-request) and [the list endpoint](/en/reference/interfaces/pix-btg/list-refund-requests)

Records created outside the MED 2.0 flow do not carry this field.

# Webhooks

***

Two inbound BTG webhooks drive the Funds Recovery flow. Each one produces a matching outbound event to your system:

| Outbound `entityType` | Trigger | Behavior |
| - | - | - |
| `FUNDS_RECOVERY` | BTG `FUNDS_RECOVERY` webhook | Plugin updates the local record, then notifies your system with its main fields |
| `FUNDS_RECOVERY_EVENTS` | BTG `FUNDS_RECOVERY_EVENTS` webhook | Pass-through lifecycle event, with no database update |

Both use `flowType: DICT`. See the [Webhooks guide](/en/interfaces/pix-btg/indirect-pix-webhooks) for envelope format, retries, and routing.

**Funds recovery entity event:**

```json theme={null}
{
  "entityType": "FUNDS_RECOVERY",
  "flowType": "DICT",
  "payload": {
    "id": "91d65e98-97c0-4b0f-b577-73625da1f9fc",
    "externalId": "ca1b9c01-ff9e-4a58-90ab-d31512e15ce0",
    "rootTransactionId": "E9999901012341234123412345678900",
    "situationType": "SCAM",
    "status": "CREATED",
    "reporterParticipant": "99999010",
    "reportDetails": "Details to help receiving participants",
    "createdAt": "2020-01-17T10:00:00.000Z",
    "updatedAt": "2020-01-17T10:00:00.000Z"
  }
}
```

**Lifecycle event (pass-through):**

```json theme={null}
{
  "entityType": "FUNDS_RECOVERY_EVENTS",
  "flowType": "DICT",
  "payload": {
    "pactualId": "74ab3e2c-f69c-4a59-a507-8302186ee743",
    "clientRequestId": "40a9bab9eda647f1b21c17bba36e2add",
    "entity": "FundsRecoveryEvents",
    "status": "FUNDS_RECOVERY_COMPLETED",
    "createTimestamp": "2025-01-11T10:00:00Z",
    "body": {
      "id": "10001",
      "event": "FUNDS_RECOVERY_COMPLETED",
      "entityType": "FUNDS_RECOVERY",
      "entityId": "527179ce-b991-4add-a70f-e0fdbb98e6da",
      "timestamp": "2025-01-11T10:00:00.000Z"
    }
  }
}
```

Lifecycle `body.event` values: `FUNDS_RECOVERY_ANALYSED`, `FUNDS_RECOVERY_COMPLETED`, `FUNDS_RECOVERY_INFORMATION_UPDATED`, `FUNDS_RECOVERY_CANCELLED`.

# Deprecation notice

***

> [!WARNING]
>
> Do not use [Create an Infraction Report](/en/reference/interfaces/pix-btg/create-an-infraction-report) or [Close an Infraction Report](/en/reference/interfaces/pix-btg/close-an-infraction-report) for new integrations. MED 2.0 deprecates both endpoints and manages infraction reports through the Funds Recovery flow. The endpoints still work for backward compatibility. New integrations must use the Funds Recovery APIs.

# Next steps

***

* [Refund operations](/en/interfaces/pix-btg/indirect-pix-refund-operations): Distributed partial refunds and unblocking stuck refunds
* [Webhooks](/en/interfaces/pix-btg/indirect-pix-webhooks): Event envelope, retries, and routing
* [Main domains: MED](/en/interfaces/pix/main-domains-med): MED dispute and refund concepts
* [API reference](/en/reference/interfaces/pix-btg/create-entry): Full API documentation


# What is Pix Indirect (BTG)?
Source: https://docs.lerian.studio/en/interfaces/pix-btg/indirect-pix-overview

BTG Pactual is the direct participant that connects your institution to BACEN's Pix infrastructure through its Banking as a Service offering.

BTG Pactual is a **direct participant** in Brazil's Pix ecosystem. Through its Banking as a Service (BaaS) infrastructure, BTG connects indirect participants to BACEN's SPI and DICT. SPI is the Instant Payment System. DICT is the directory of transactional account identifiers.

# BTG's role in the Pix ecosystem

***

As the direct participant, BTG handles the layers that require regulatory licensing and direct BACEN integration:

* **SPI connectivity**: Sends and receives Pix payment and refund messages through BACEN's real-time settlement infrastructure
* **DICT access**: Manages Pix key lookups, registrations, and claim resolutions at the BACEN directory level
* **Settlement and liquidity**: Processes financial settlement between institutions through BACEN's infrastructure
* **Regulatory compliance**: Maintains the certifications, audits, and operational requirements BACEN mandates for direct participants
* **Webhook notifications**: Delivers real-time event callbacks for transaction status changes, key events, and dispute updates
* **mTLS security**: Provides certificate-based authentication for secure webhook communication

> [!NOTE]
>
> Your institution retains full control of its ledger, customer data, business rules, and operational infrastructure. BTG provides connectivity, not account management.

Beyond standard transfers and DICT operations, the plugin supports the advanced Pix flows BACEN requires:

* **MED 2.0 Funds Recovery**: Track fraudulent fund movements across accounts and request coordinated refunds
* **Distributed partial refunds**: Return one refund debited from several internal accounts in a single operation
* **Intra-PSP (P2P) transfers**: Settle internal transfers without BTG and report them to BACEN through TRCK002
* **Unblock**: Recover refunds or transfers stuck in `PROCESSING`

# Why BTG

***

BTG brings specific advantages as a direct participant for Pix operations:

* **Production infrastructure**: BTG already operates at scale in the Pix ecosystem
* **Built-in BTG integration**: The plugin includes support for BTG's APIs, authentication, and event model. You do not build custom middleware
* **Faster launch**: BTG absorbs the regulatory and infrastructure complexity, so your institution launches Pix sooner
* **Simplified onboarding**: BTG provides credentials directly when your institution signs up for indirect BACEN integration. You do not need a separate certification process

# Next steps

***

* [Setting up the integration](/en/interfaces/pix-btg/indirect-pix-integration): Configure the plugin's connection to BTG, Midaz, CRM, and supporting services
* [Webhooks](/en/interfaces/pix-btg/indirect-pix-webhooks): Event types, payloads, retries, and handling of BTG notifications
* [MED 2.0: Funds Recovery](/en/interfaces/pix-btg/indirect-pix-med-2-funds-recovery): Cross-account fraud recovery and the X-Purpose header
* [Refund operations](/en/interfaces/pix-btg/indirect-pix-refund-operations): Distributed partial refunds and unblocking stuck operations
* [Intra-PSP transfers](/en/interfaces/pix-btg/indirect-pix-intra-psp): Internal P2P settlement and TRCK002 reporting
* [API reference](/en/reference/interfaces/pix-btg/create-entry): Full API for DICT, Claims, Transactions, QR Codes, and MED operations


# QR Codes
Source: https://docs.lerian.studio/en/interfaces/pix-btg/indirect-pix-qrcodes

Generate and decode Pix QR Codes via BTG: static BR Codes, immediate COB and due-date COBV charges, EMV payloads, and the universal QR Code decoder.

The Pix Indirect Plugin (BTG) generates and manages Pix QR Codes (BR Codes) so your customers can receive payments. The plugin supports four QR Code types: static BR Codes, immediate charges (COB), due-date charges (COBV), and a decoder for payment initiation.

All QR Codes follow the EMV QCO specification and embed the receiver's Pix key. Before you create a QR Code, the receiver key must already exist in DICT. The requesting account must own the key. You identify the account with the `X-Account-Id` header. See the [DICT guide](/en/interfaces/pix-btg/indirect-pix-dict) for key registration.

# Choosing a QR Code type

***

| Type | Characteristics | Best for |
| - | - | - |
| **Static** | Reusable (multiple payments) · optional amount (fixed or payer-entered) · no expiration | POS displays, printed material, donations, e-commerce with variable amounts |
| **Immediate (COB)** | Single payment · amount required · seconds-based expiration | Checkout, invoicing, one-time purchases |
| **Due-date (COBV)** | Single payment · amount + charges · due date + grace period | Bills, installments, subscriptions, B2B invoicing (boleto-like) |
| **Decode** | Reads any scanned QR Code | Initiating a payment from a scanned code |

# Static QR Codes

***

Static BR Codes (`/v1/brcode/static`) are reusable. Different payers can pay the same code many times. Each code links to a Pix key and, optionally, to merchant data.

**Fixed vs. variable amount:**

* **With amount**: the payer scans and confirms a predefined value. Useful for fixed-price items.
* **Without amount**: the payer scans and enters the value manually. Useful for donations or open checkout.

You can add merchant data to the code: `merchant.name`, `merchant.city`, `merchant.categoryCode` (MCC), and `merchant.postalCode`. You can also add an optional `txId` (alphanumeric, up to 25 characters) for reconciliation. The request requires a `clientRequestId`. If you omit merchant data, the plugin fills it from CRM holder data.

```json theme={null}
POST /v1/brcode/static
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{
  "clientRequestId": "8c4ffd09-a264-4779-8d7e-fd24c971d7ff",
  "receiverKey": "+5511999999999",
  "amount": "100.00",
  "description": "Payment for order #12345",
  "txId": "TX123ABC",
  "merchant": { "name": "Loja ABC", "city": "São Paulo", "categoryCode": "5411" }
}
→ 201 Created  { "id": "...", "emv": "00020126580014br.gov.bcb.pix..." }
```

Pass `include_base64=true` to also receive a Base64-encoded PNG of the QR Code. The plugin validates that the account owns the receiver key before it creates the code.

**Reference:** [Create a static QR code](/en/reference/interfaces/pix-btg/create-a-static-qr-code) · [List](/en/reference/interfaces/pix-btg/list-static-qr-codes) · [Retrieve](/en/reference/interfaces/pix-btg/retrieve-a-static-qr-code)

# Immediate charges (COB)

***

Immediate collections (`/v1/collections/immediate`), or cobrança imediata, are dynamic, single-use QR Codes. Each charge sets a specific amount and a short validity window. A required `txId` identifies each charge. A payer can settle a charge only once.

**Required fields:** `amount`, `expirationSeconds`, `receiverKey`, and `txId`. The optional `debtorName` and `debtorDocument` fields identify the intended payer.

**Pix Saque and Pix Troco:** to create a Pix Saque charge, add the optional `withdrawalAmount` field. To create a Pix Troco charge, send `withdrawalAmount` together with `transactionAmount`. The `transactionAmount` must equal `amount`. Both values must be greater than zero.

**Lifecycle:**

| Status | Meaning |
| - | - |
| `ACTIVE` | Created and available for payment |
| `COMPLETED` | Payment received successfully |
| `DELETED` | Cancelled by the merchant |

The charge is valid for `expirationSeconds` after creation. You can update (`PUT`) or delete (`DELETE`) a charge only while it is `ACTIVE`.

**Payment confirmation:** when an incoming Pix settles the charge, the plugin moves it to `COMPLETED`. The plugin then emits a webhook to notify your system in real time. See the [Webhooks guide](/en/interfaces/pix-btg/indirect-pix-webhooks) and the [Collections guide](/en/interfaces/pix-btg/indirect-pix-collections) for the full payment flow.

**Reference:** [Create an immediate charge](/en/reference/interfaces/pix-btg/create-an-immediate-charge) · [List](/en/reference/interfaces/pix-btg/list-immediate-charges) · [Retrieve](/en/reference/interfaces/pix-btg/retrieve-immediate-charge-details) · [Update](/en/reference/interfaces/pix-btg/update-an-immediate-charge) · [Delete](/en/reference/interfaces/pix-btg/delete-an-immediate-charge)

# Due-date charges (COBV)

***

Due-date collections (`/v1/collections/duedate`), or cobrança com vencimento, are dynamic QR Codes for billing with a due date, like a boleto. They support complex amount rules. They require full debtor and receiver data.

**Key fields:** `dueDate`, `validAfterDue`, a required `debtor`, and an `amount` object. The required `validAfterDue` field sets the days the charge stays payable after the due date. The `debtor` needs a name and a CPF or CNPJ. It also takes optional email, address, city, state, and zipCode. The `amount` object holds the `original` value and optional charge components:

| Component | Modality | Applies |
| - | - | - |
| `fine` | `FIXED_VALUE` or `PERCENT` | Penalty for late payment |
| `interest` | e.g. `PERCENTAGE_PER_MONTH_CALENDAR_DAYS` | Accrues after the due date |
| `discount` | a modality with a value, or a `discountDateFixed` array | Reward for early payment |
| `abatement` | `FIXED_VALUE` or `PERCENT` | Reduction on the amount |

Payment timing determines the final value. Before the due date, the payer gets any discount. On the due date, the `original` amount applies. After the due date, the fine and interest apply, minus any abatement. A dated discount (`discountDateFixed`) needs a `date` before the `dueDate`.

The plugin requires a valid debtor document (CPF or CNPJ). The charge stays payable until the due date plus `validAfterDue` days.

**Reference:** [Create a due-date charge](/en/reference/interfaces/pix-btg/create-a-dynamic-charge-with-due-date) · [List](/en/reference/interfaces/pix-btg/list-dynamic-charges-with-due-date) · [Retrieve](/en/reference/interfaces/pix-btg/retrieve-dynamic-charge-with-due-date-details) · [Update](/en/reference/interfaces/pix-btg/update-a-dynamic-charge-with-due-date)

# Decoding QR Codes

***

The decoder (`POST /v1/qrcodes/decode`) parses any scanned Pix QR Code. It returns the embedded payment data. Use it in payment-initiation flows. A customer scans a QR Code, and you read the receiver, amount, and charge details before you confirm the payment.

The plugin auto-detects the QR Code type and returns a typed response:

* **STATIC**: receiver key, optional amount/description, merchant info, `txId`.
* **IMMEDIATE (COB)**: receiver key, amount, expiration, `txId`, status, review number, and the optional debtor.
* **DUE\_DATE (COBV)**: receiver key, `txId`, due date, `validAfterDue`, debtor, receiver, status, review number, and the fine/interest/discount/abatement structure with the final amount.
* **RECURRENCE**: the recurrence data of a Pix Automático QR Code.

For dynamic codes, the plugin resolves the payload from BTG before it returns. The response reflects the charge's current state.

```json theme={null}
POST /v1/qrcodes/decode
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{ "emv": "00020126580014br.gov.bcb.pix..." }
→ 200 OK  { "type": "IMMEDIATE", "amount": "100.00", "receiverKey": "...", "status": "ACTIVE" }
```

**Reference:** [Decode a Pix QR code](/en/reference/interfaces/pix-btg/decode-a-pix-qr-code)

# Next steps

***

* [Collections](/en/interfaces/pix-btg/indirect-pix-collections): Collection lifecycle, payment linking, and webhook events
* [DICT](/en/interfaces/pix-btg/indirect-pix-dict): Registering the Pix keys your QR Codes receive on
* [Webhooks](/en/interfaces/pix-btg/indirect-pix-webhooks): Payment and status notifications


# Refund operations
Source: https://docs.lerian.studio/en/interfaces/pix-btg/indirect-pix-refund-operations

Handle Pix refund edge cases via BTG: distributed partial refunds (devoluções) across internal accounts and unblocking operations stuck in PROCESSING.

The Pix Indirect Plugin (BTG) processes Pix refunds (devoluções) through the [Refund a Received Pix Transfer](/en/reference/interfaces/pix-btg/refund-a-received-pix-transfer) endpoint. Two capabilities extend that flow for MED and fraud scenarios:

* **Distributed partial refunds**: return a refund from multiple internal accounts in a single operation
* **Unblock**: recover a refund or transfer that is stuck in `PROCESSING`

# Distributed partial refunds

***

A received Pix can split internally across several accounts. For example, the principal amount goes to the customer account and a fee goes to a fee account. A later MED or fraud refund can then debit part of the amount from each account.

The standard refund flow debits one account. To split the debit, send an optional `operations` array in the request body. The `operations` array is the only signal. There is no new endpoint, environment variable, or feature flag.

## Request

***

```json theme={null}
POST /v1/transfers/{transfer_id}/refunds
X-Account-Id: <account-id>
X-Reason: FR01
{
  "amount": "1000.82",
  "description": "MED refund",
  "operations": [
    { "accountAlias": "alias-conta-cliente", "amount": "0.82" },
    { "accountAlias": "alias-conta-fee", "amount": "1000.00" }
  ]
}
```

* Without `operations` → the current single-account flow runs unchanged.
* With `operations` → the plugin debits each `accountAlias` for its `amount` in Midaz, and BTG receives a single pacs.004 for the total refund value.

## Validation rules

***

| Rule | Error |
| - | - |
| `sum(operations[].amount)` must equal `amount` | `400 PIX-0447` Operations Sum Mismatch |
| `accountAlias` must not repeat within the request | `400 PIX-0448` Duplicate Account Alias |
| each `amount` must be greater than `0` | `400 PIX-0004` Invalid Field Values |
| each `amount` must have at most 2 decimal places | `400 PIX-0004` Invalid Field Values |
| the request must contain at most 50 operations | `400 PIX-0004` Invalid Field Values |
| the original cash-in must exist | `404 PIX-0425` Cashin Not Found |

> [!NOTE]
>
> The endpoint, BTG flow (pacs.004 with the total value), idempotency, and authentication match the standard refund. Only the internal Midaz debit composition changes.

## Example: fee split

***

The plugin split a R$ 50,000.00 cash-in: R$ 49,000.00 to the customer account and R$ 1,000.00 to a fee account. After fraud, the refund must be R$ 1,000.82. Only R$ 0.82 remains in the customer account. The `operations` array debits R$ 0.82 from the customer account and R$ 1,000.00 from the fee account. BTG receives a single R$ 1,000.82 refund with no manual ledger consolidation.

# Unblocking stuck operations

***

A reversal call to BTG can time out before BTG confirms it. The refund or transfer then stays stuck in `PROCESSING`, and Midaz still holds the funds. Two endpoints re-query BTG and drive the operation to its terminal state.

| Method | Endpoint | Unblocks |
| - | - | - |
| `POST` | [`/v1/refunds/{refund_id}/unblock`](/en/reference/interfaces/pix-btg/unblock-a-pix-refund) | A refund stuck in `PROCESSING` |
| `POST` | [`/v1/transfers/{transfer_id}/unblock`](/en/reference/interfaces/pix-btg/unblock-a-pix-transfer) | A transfer stuck in `PROCESSING`, a cash-out in `PENDING`, or a cash-in in `CREATED` |

Both require the `X-Account-Id` header of the account that owns the operation.

## How unblock works

***

The plugin re-queries the reversal or transfer status at BTG and:

* If BTG reports `CONFIRMED` or `ERROR` → dispatches the corresponding settlement and moves the operation to its terminal state.
* If BTG still reports `INITIATED`/`PROCESSING` → returns **HTTP 200** with no action. Retry later.

A consistency guard aborts the operation if BTG's `entity`, `returnIdentification`, or `originalEndToEndId` diverge from the local record. This prevents settlement against the wrong transaction.

```json theme={null}
POST /v1/refunds/{refund_id}/unblock
X-Account-Id: <account-id>
```

The response includes the updated `refund`, a `message`, and the `btgStatus`.

## Handling a 404 from BTG

***

BTG can return `404` when it no longer has the reversal or transfer. The result then depends on the operation type and the opt-in `allowNotFoundUnblock` flag in the request body.

| Operation | Default (strict) | With `allowNotFoundUnblock: true` |
| - | - | - |
| **Transfer** ([`/v1/transfers/{id}/unblock`](/en/reference/interfaces/pix-btg/unblock-a-pix-transfer)) | Returns an error | Reverts the Midaz hold (best-effort, idempotent), marks the cashout `FAILED` with `BTG_NOT_FOUND`, emits a `CASHOUT` outbound webhook, and returns `200` with `btgStatus: "NOT_FOUND"` |
| **Refund** ([`/v1/refunds/{id}/unblock`](/en/reference/interfaces/pix-btg/unblock-a-pix-refund)) | Returns `PIX-1012` | For a `CASHOUT` refund: marks the refund failed and emits a `CASHOUT` outbound webhook. A `CASHIN` refund still returns `PIX-1012` |

```json theme={null}
POST /v1/transfers/{transfer_id}/unblock
{
  "allowNotFoundUnblock": true
}
```

> [!WARNING]
>
> `allowNotFoundUnblock` defaults to `false`. An empty or absent body, or `false`, preserves the strict behavior. A BTG 404 then returns an error and never reverts the hold. Opt in only when you have confirmed that the operation must be released.

> [!NOTE]
>
> The opt-in 404 recovery applies only to `CASHOUT` operations in `PENDING`/`PROCESSING` with a non-empty `endToEndId`. Cash-ins and terminal statuses never enter this branch.

## Intra-PSP limitation

***

Do not call transfer unblock for an intra-PSP transfer: it has no BTG transaction to query. See [Intra-PSP transfers](/en/interfaces/pix-btg/indirect-pix-intra-psp).

# Next steps

***

* [Intra-PSP transfers](/en/interfaces/pix-btg/indirect-pix-intra-psp): Internal P2P transfers and refunds
* [MED 2.0: Funds Recovery](/en/interfaces/pix-btg/indirect-pix-med-2-funds-recovery): Cross-account fraud recovery
* [Webhooks](/en/interfaces/pix-btg/indirect-pix-webhooks): Refund and transfer event handling
* [API reference](/en/reference/interfaces/pix-btg/create-entry): Full API documentation


# Transfers and cash-out
Source: https://docs.lerian.studio/en/interfaces/pix-btg/indirect-pix-transfers

Send Pix cash-out through the Indirect Pix Plugin via BTG: the two-step initiate-and-process flow that confirms the destination before moving funds.

A Pix cash-out moves money from an account to an external destination. The Indirect Pix Plugin (BTG) runs it in two steps: **initiate**, then **process**. You confirm where the money goes before any funds leave the ledger.

## Why two steps

***

Splitting a cash-out into initiate and process gives you a checkpoint between "who is the payee?" and "send the money":

* **Verify the destination first.** Initiate validates and resolves the payee account without touching balances. A wrong Pix key or an invalid account fails here, before any money moves.
* **Show the payer who receives the money.** The initiate response returns the resolved account owner. Your app can display the real name and let the payer confirm first.
* **Move funds only on confirmation.** The plugin debits nothing until you process the transfer. If the payer abandons the flow, there is no movement to undo.

> [!NOTE]
>
> Both steps accept an `X-Idempotency` key. Retry with the same key to avoid duplicate transfers. See [Retries and idempotency](/en/reference/retries-idempotency).

## Step 1: Initiate (confirm the destination)

***

Initiating a transfer creates a short-lived record that validates and resolves the payee without moving funds. How the plugin finds the destination depends on what you start with:

| You start with | Initiation type | What the plugin does |
| - | - | - |
| A Pix key (CPF, CNPJ, email, phone, or EVP) | `KEY` | Looks the key up in [DICT](/en/interfaces/pix-btg/indirect-pix-dict) and resolves the destination account for you. |
| A QR code (BR Code) | `QR_CODE` | Decodes the code and resolves the destination via DICT. See [QR Codes](/en/interfaces/pix-btg/indirect-pix-qrcodes). |
| The payee's full account details | `MANUAL` | Uses the branch, account, participant, and owner document you provide, with no DICT lookup. |

For `KEY` and `QR_CODE`, you never supply the destination yourself. The plugin resolves it and returns it in the response, ready to show the payer for confirmation.

### Request: pick the tab for your initiation type

```json KEY theme={null}
POST /v1/transfers/cashout/initiate
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{
  "initiationType": "KEY",
  "key": "john.doe@example.com"
}
```

```json QR_CODE theme={null}
POST /v1/transfers/cashout/initiate
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{
  "initiationType": "QR_CODE",
  "emv": "00020126...5802BR5913Fulano..."
}
```

```json MANUAL theme={null}
POST /v1/transfers/cashout/initiate
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
{
  "initiationType": "MANUAL",
  "destination": {
    "account": {
      "branch": "0001",
      "number": "123456789",
      "participant": "12345678",
      "type": "CACC"
    },
    "owner": {
      "document": "12345678901",
      "name": "John Doe"
    }
  }
}
```

Account `type` values are `CACC` (checking), `SVGS` (savings), `TRAN` (transaction), and `OTHR` (other). `endToEndId` is optional for all types. The plugin generates one when you omit it.

### Response

The response returns the initiation `id` (used as `initiationId` in step 2) and the resolved `destination`:

```json theme={null}
→ 201 Created
{
  "id": "019c96a0-0c82-7c3d-8dcc-c180868b45c4",
  "initiationType": "KEY",
  "endToEndId": "E1234567820240101000001234567890",
  "destination": { "account": { ... }, "owner": { ... } },
  "expiresAt": "2024-01-15T11:00:00Z",
  "createdAt": "2024-01-15T10:30:00Z"
}
```

> [!NOTE]
>
> Initiations expire. The response includes an `expiresAt` timestamp. Process the transfer before it lapses, or initiate again. This keeps a confirmed destination from going stale between the lookup and the payment.

> [!TIP]
>
> **API reference:** [Initiate a Pix Transfer](/en/reference/interfaces/pix-btg/initiate-a-pix-transfer)

## Step 2: Process (move the money)

***

Processing executes the cash-out from the initiation you confirmed. It debits the source account, then routes the payment to BTG for settlement with BACEN.

Settlement with the Pix network is asynchronous. The transfer comes back as `PROCESSING` while BTG settles. The final result (for example `COMPLETED` or `REJECTED`) arrives later through a `TRANSFER` / `CASHOUT` webhook. Build your flow to react to that event, not to wait on the process response. See [Webhooks](/en/interfaces/pix-btg/indirect-pix-webhooks).

### Request

Pass the `id` from the initiate response as `initiationId`, along with the `amount` to transfer:

```json theme={null}
POST /v1/transfers/cashout/process
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
X-Purpose: TRANSFER
{
  "initiationId": "019c96a0-0c82-7c3d-8dcc-c180868b45c4",
  "amount": "100.50"
}
```

`amount` is required. You can also pass an optional `description` (max 140 characters) and `metadata` (custom key-value attributes).

#### The `X-Purpose` header

Use the optional `X-Purpose` header to declare the reason for the cash-out. It defaults to `TRANSFER` when omitted:

| Value | When to use |
| - | - |
| `TRANSFER` | A regular Pix cash-out, the default for ordinary payments. |
| `INSTANT_PAYMENT_REFUND` | When the cash-out is refunding a previously received instant payment, so the network can classify it as a refund rather than a new transfer. |
| `WITHDRAWAL` | When the `QR_CODE` initiation is a Pix Saque charge. |
| `CHANGE` | When the `QR_CODE` initiation is a Pix Troco charge. |

> [!NOTE]
>
> **Fixed-amount QR codes:** the initiation can be a `QR_CODE` whose EMV payload carries a fixed amount. In that case, the `amount` you send to process must equal that encoded amount. A mismatch is rejected before any funds move.

### Response

```json theme={null}
→ 201 Created
{
  "id": "019c96a0-0c21-71f9-a487-66a1258278a1",
  "endToEndId": "E1234567820240101000001234567890",
  "amount": "100.50",
  "status": "PROCESSING",
  "type": "CASHOUT",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
```

> [!NOTE]
>
> When the destination belongs to your own institution, the money never leaves for BTG. It settles internally as a P2P transfer. See [Intra-PSP transfers](/en/interfaces/pix-btg/indirect-pix-intra-psp).

> [!TIP]
>
> **API reference:** [Process a Pix Transfer](/en/reference/interfaces/pix-btg/process-a-pix-transfer)

## Tracking a transfer

***

A transfer starts in `CREATED` and moves through `PENDING`/`PROCESSING` while in flight. It then reaches a terminal `COMPLETED`, `FAILED`, `CANCELLED`, or `REJECTED`. To check where a transfer stands, retrieve a single one by its id. You can also list transfers filtered by status, type (cash-out or cash-in), or date range.

```json theme={null}
GET /v1/transfers?type=CASHOUT&status=COMPLETED&limit=10&page=1
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
```

List filters include `status`, `type` (`CASHOUT`/`CASHIN`), `end_to_end`, and `modified_after`/`modified_before`, plus `page`/`limit`/`sort_order` pagination.

> [!TIP]
>
> **API reference:** [List transfers](/en/reference/interfaces/pix-btg/list-pix-transfers) · [Retrieve a transfer](/en/reference/interfaces/pix-btg/retrieve-a-pix-transfer)

## Scheduled payments

***

A scheduled payment runs a Pix cash-out at a future date and time. First, initiate the transfer as in step 1. Then pass the initiation `id` as `initiationId` to `POST /v1/schedules`, with the `amount` and the `scheduledFor` date and time:

```json theme={null}
POST /v1/schedules
X-Account-Id: 01989f9e-6508-79f8-9540-835be49fbd0d
X-Idempotency: 7b2c4f8a-3d1e-4c5b-9a6f-8e2d1c7b4a3f
{
  "initiationId": "019c96a0-0c82-7c3d-8dcc-c180868b45c4",
  "scheduledFor": "2026-08-15T09:00:00Z",
  "amount": "100.50"
}
```

The schedule takes its destination from the initiation. `scheduledFor` must be at least `SCHEDULE_MIN_FUTURE_SECONDS` in the future and at most `SCHEDULE_MAX_FUTURE_DAYS` days ahead. You can also pass an optional `description` (max 140 characters) and `maxAttempts` (`1` or `2`). If you omit `maxAttempts`, the plugin uses `SCHEDULE_MAX_ATTEMPTS`.

A schedule starts in `SCHEDULED`. At the scheduled time, the schedule worker moves it to `PROCESSING` and runs the cash-out. The schedule then ends in `EXECUTED`, `FAILED`, or `CANCELLED`. To cancel a schedule, send `DELETE /v1/schedules/{schedule_id}` while the schedule is `SCHEDULED`. The plugin sends a `SCHEDULE` / `CASHOUT` webhook with the event type `schedule.executed`, `schedule.failed`, or `schedule.cancelled`.

> [!TIP]
>
> **API reference:** [Create a Pix schedule](/en/reference/interfaces/pix-btg/create-a-pix-schedule) · [List schedules](/en/reference/interfaces/pix-btg/list-pix-schedules) · [Retrieve a schedule](/en/reference/interfaces/pix-btg/get-a-pix-schedule) · [Cancel a schedule](/en/reference/interfaces/pix-btg/cancel-a-pix-schedule)

## Pix Automático (payer)

***

Pix Automático lets a receiver debit the payer's account on a schedule, after the payer authorizes it. The plugin handles the payer side. The calls take the payer account in the `X-Account-Id` header. On the authorizations list, the header is optional. Without it, the list covers all accounts.

| Task | Endpoint |
| - | - |
| Read the authorization requests | `GET /v1/recurrences/payer/authorization-requests` lists the requests. `GET /v1/recurrences/payer/authorization-requests/{id}` returns one request. |
| Accept or reject a request | `POST /v1/recurrences/payer/authorization-requests/{id}/decision`, with `decision` set to `ACCEPTED` or `REJECTED`. |
| Confirm a recurrence from a QR code | `POST /v1/recurrences/payer/qr/confirm`, with the `idRec` of the scanned recurrence, the `decision`, and the `journey` (`J2` or `J4`). |
| Pay and confirm in one call | `POST /v1/recurrences/payer/qr/pay-and-confirm`. It processes the cash-out of the QR code charge (`initiationId` and `amount`) and confirms the recurrence (`idRec`). |
| Read the authorizations | `GET /v1/recurrences/payer/authorizations` lists them, with `nextChargeAt` and `nextChargeAmount`. `GET /v1/recurrences/payer/authorizations/{id}` returns one authorization. |
| Read the charges | `GET /v1/recurrences/payer/authorizations/{authorizationId}/charges` lists the charges of an authorization. `GET /v1/recurrences/payer/charges/{id}` returns one charge. |
| Cancel an authorization | `POST /v1/recurrences/payer/authorizations/{id}/cancel`, with `reasonKind` set to `PAYER` or `FRAUD`. With `FRAUD`, also send `reasonText` and `cancelledBy`. |

When you accept a request, the request moves to `APPROVING`. The authorization starts when BTG approves it. When the plugin accepts a charge from the receiver, it creates a [scheduled payment](#scheduled-payments) for that charge. The plugin sends `RECURRING` webhooks for the `AUTHORIZATION_REQUEST`, `AUTHORIZATION`, and `CHARGE` entities. See [Webhooks](/en/interfaces/pix-btg/indirect-pix-webhooks).

> [!TIP]
>
> **API reference:** [List authorization requests](/en/reference/interfaces/pix-btg/list-pix-automatico-authorization-requests) · [Decide on a request](/en/reference/interfaces/pix-btg/decide-on-a-pix-automatico-authorization-request) · [Confirm a scanned recurrence](/en/reference/interfaces/pix-btg/confirm-a-scanned-pix-automatico-recurrence) · [Pay and confirm](/en/reference/interfaces/pix-btg/pay-and-confirm-a-scanned-pix-automatico-recurrence) · [List authorizations](/en/reference/interfaces/pix-btg/list-pix-automatico-authorizations) · [List charges](/en/reference/interfaces/pix-btg/list-pix-automatico-charges-by-authorization) · [Cancel an authorization](/en/reference/interfaces/pix-btg/cancel-a-pix-automatico-authorization)

## How transfers land in Midaz

***

The plugin posts every settled movement to Midaz as a ledger transaction, with the external leg against the `@external/BRL` account. Midaz records the accounting entry and correlation metadata, not the transfer's full banking details. Counterparty branch, account number, account type, and Pix key never reach Midaz. The one exception is the payer's identity on cash-in (`sourceBank`, `sourceDocument`, `sourceName`), stamped when known. The full counterparty detail lives in the plugin's transfer record.

The metadata stamped on the Midaz transaction depends on the flow:

| Flow | Metadata keys |
| - | - |
| Cash-out | `initiationId`, `endToEndId`, `accountId`, `transferType: CASHOUT`, `paymentType`, `initiationType` |
| Cash-in | `endToEndId`, `accountId`, `transferType: CASHIN`, `paymentType`, `initiationType`, plus `sourceBank`, `sourceDocument`, and `sourceName` when the payer is known |
| Refund (out) | `refundId`, `originalEndToEndId`, `returnIdentification`, `accountId`, `transferType: REFUND_CASHOUT`, `refundType`, `reason` |
| Refund (in) | The same refund keys with `transferType: REFUND_CASHIN` |

The Midaz transaction `code` also carries the `endToEndId` (or the `returnIdentification` for refunds), so the E2E identifier is visible directly on the ledger entry.

Correlation works in both directions:

* The plugin stores the Midaz transaction and operation identifiers on its own transfer and refund records, and uses them to commit, cancel, or revert ledger entries.
* The Midaz transaction carries correlation keys in its metadata: filter by `metadata.endToEndId` for cash-outs and cash-ins, or by `metadata.originalEndToEndId` / `metadata.returnIdentification` for refunds. The transaction `code` is the common fallback. It carries the E2E ID on transfers and the return identification on refunds.

> [!NOTE]
>
> Custom `metadata` you pass when processing a cash-out is stored with the plugin's transfer record and returned by the plugin's own API. It is not copied onto the Midaz transaction. The plugin fixes the Midaz metadata keys above.

## When a transfer gets stuck

***

If the settlement call to BTG times out before BTG confirms, a transfer can stay in `PROCESSING` with its funds on hold. The plugin provides an **unblock** operation. Unblock re-checks the transfer with BTG and drives it to the correct final state. It settles the transfer if BTG confirms, or releases the hold if BTG never received it.

> [!NOTE]
>
> Unblock doesn't apply to intra-PSP transfers. There is no BTG transaction to re-check. For the full unblock behavior and its options, see [Refund operations](/en/interfaces/pix-btg/indirect-pix-refund-operations).

## Next steps

***

* [Intra-PSP transfers](/en/interfaces/pix-btg/indirect-pix-intra-psp): Internal P2P settlement
* [QR Codes](/en/interfaces/pix-btg/indirect-pix-qrcodes): Generating and decoding QR codes
* [Refund operations](/en/interfaces/pix-btg/indirect-pix-refund-operations): Refunds and unblocking
* [Webhooks](/en/interfaces/pix-btg/indirect-pix-webhooks): Cash-out and cash-in event handling
* [API reference](/en/reference/interfaces/pix-btg/initiate-a-pix-transfer): Full request/response details, headers, and field schemas


# Webhooks
Source: https://docs.lerian.studio/en/interfaces/pix-btg/indirect-pix-webhooks

Configure and consume webhooks for the Pix Indirect Plugin via BTG: DICT claim, infraction, refund, transfer, and MED 2.0 event types.

Webhooks are the primary mechanism the Pix Indirect Plugin (BTG) uses to notify you about Pix-related events in real time.

You receive asynchronous, event-driven callbacks when changes occur in Pix operations: transfers, refunds, key claims, or MED events.

> [!WARNING]
>
> These webhooks apply only to the Indirect Pix model via BTG.
>
> Direct Pix webhooks can differ by connectivity model. A separate page documents them.

# Prerequisites

***

Before you configure webhooks, make sure you have:

* The Pix Indirect Plugin configured and running (see [How indirect participation works](/en/interfaces/pix/pix-overview))
* An HTTPS endpoint ready to receive webhook requests
* Basic understanding of Pix event lifecycle and transaction flows

# What webhooks give you

***

Webhooks are not optional in Pix Indirect operations.

Pix is an asynchronous, multi-party system.

An API request can succeed before the transaction reaches its final state. The system confirms that state later, after settlement and counterparty acknowledgment.

Webhooks allow your system to:

* Track authoritative transaction status
* React to refunds, reversals, and MED events
* Maintain ledger and operational consistency
* Reduce polling and operational overhead

# Event types

***

You receive events grouped by **flow** and **entity**, aligned with BACEN (Banco Central do Brasil) domains.

| Flow | Entity | Description |
| - | - | - |
| DICT | CLAIM | Pix key portability and ownership claim events |
| DICT | INFRACTION\_REPORT | MED (Mecanismo Especial de Devolução) infraction reports and dispute lifecycle |
| DICT | REFUND | MED refund request events |
| DICT | FUNDS\_RECOVERY | MED 2.0 Funds Recovery entity status changes (DB-backed) |
| DICT | FUNDS\_RECOVERY\_EVENTS | MED 2.0 Funds Recovery lifecycle events (pass-through) |
| DICT | RECONCILIATION\_JOB | DICT reconciliation job status changes |
| TRANSFER | CASHIN | Incoming Pix payment status updates |
| TRANSFER | CASHOUT | Outgoing Pix payment status updates |
| REFUND | CASHIN | Incoming Pix refund status updates |
| REFUND | CASHOUT | Outgoing Pix refund status updates |
| RECURRING | AUTHORIZATION\_REQUEST · AUTHORIZATION · CHARGE | Pix Automático authorization and charge events |
| SCHEDULE | CASHOUT | Scheduled Pix payment events |
| REPORT | TEMPOSTRANSACOES | Transaction-time report job events |

Each event reflects a state transition in the Pix ecosystem. Treat each event as the source of truth.

> [!NOTE]
>
> The two MED 2.0 entities behave differently. The plugin emits `FUNDS_RECOVERY` after it updates its local record. `FUNDS_RECOVERY_EVENTS` is a pass-through of BTG lifecycle events with no database update. See [MED 2.0: Funds Recovery](/en/interfaces/pix-btg/indirect-pix-med-2-funds-recovery) for the full flow.

> [!NOTE]
>
> **DICT** (Diretório de Identificadores de Contas Transacionais) is the BACEN directory that manages Pix keys and related operations like claims, infractions, and refunds.

# Webhook configuration

***

To enable webhooks, configure the destination URLs and select which event types your system receives.

## Environment variables

***

You can configure webhook endpoints at **entity**, **flow**, or **global** level.

| Flow | Entity | Entity-level URL variable |
| - | - | - |
| DICT | CLAIM | `WEBHOOK_DICT_CLAIM_URL` |
| DICT | INFRACTION\_REPORT | `WEBHOOK_DICT_INFRACTION_REPORT_URL` |
| DICT | REFUND | `WEBHOOK_DICT_REFUND_URL` |
| TRANSFER | CASHIN | `WEBHOOK_TRANSFER_CASHIN_URL` |
| TRANSFER | CASHOUT | `WEBHOOK_TRANSFER_CASHOUT_URL` |
| REFUND | CASHIN | `WEBHOOK_REFUND_CASHIN_URL` |
| REFUND | CASHOUT | `WEBHOOK_REFUND_CASHOUT_URL` |

The other entities follow the same pattern, for example `WEBHOOK_DICT_FUNDS_RECOVERY_EVENTS_URL` or `WEBHOOK_SCHEDULE_CASHOUT_URL`.

Each flow also has a **flow-level URL** for all its entities, `WEBHOOK_<FLOW>_URL`. The plugin uses it when no entity-level URL exists, for example `WEBHOOK_DICT_URL` or `WEBHOOK_TRANSFER_URL`.

> [!WARNING]
>
> The plugin delivers only the events of the entities you configure. Set at least one `WEBHOOK_<FLOW>_<ENTITY>_*` variable per entity you want to receive, for example `WEBHOOK_DICT_CLAIM_URL` or `WEBHOOK_DICT_CLAIM_ENABLED=true`. A flow-level or default URL alone does not turn on an entity.

## URL resolution priority

***

When you configure multiple URLs, the plugin resolves them in this order:

1. **Entity-level URL**

   Example: `WEBHOOK_DICT_CLAIM_URL`

2. **Flow-level URL**

   Example: `WEBHOOK_DICT_URL`

3. **Default URL**

   `WEBHOOK_DEFAULT_URL`

# Request format

***

## Headers

***

Every webhook request includes standardized headers for traceability.

| Header | Description |
| - | - |
| `Content-Type` | `application/json` |
| `X-Request-ID` | Unique request identifier |
| `X-Entity-Type` | Event entity (e.g. `INFRACTION_REPORT`) |
| `X-Flow-Type` | Source domain (e.g. `DICT`) |
| `Idempotency-Key` | Unique event identifier for deduplication |

## Body structure

***

```json theme={null}
{
  "entityType": "INFRACTION_REPORT",
  "flowType": "DICT",
  "payload": {
    ...
  }
}
```

| Field | Description |
| - | - |
| `entityType` | Event entity |
| `flowType` | Pix domain |
| `payload` | Event-specific data |

The payload schema varies per event type but always represents a state change.

# Responses and retry behavior

***

## Expected response

***

Your endpoint must return an **HTTP 2xx** status to confirm successful delivery.

| Response | Result |
| - | - |
| 2xx | Delivered successfully |
| Non-2xx | Retried automatically |

## Retry strategy

***

The plugin retries failed deliveries automatically with **exponential backoff** (default multiplier `2`):

| Attempt | Delay |
| - | - |
| 1 | 1 second |
| 2 | 2 seconds |
| 3 | 4 seconds |

**Defaults**

* Max attempts: 10
* Timeout per request: 10 seconds (`WEBHOOK_WORKER_TIMEOUT`)

After the last attempt fails, the plugin moves the event to a **dead-letter queue** for operational follow-up. To list failed events and send one again, use `GET /v1/webhooks/outbound` and `POST /v1/webhooks/outbound/{id}/retry`.

### Custom backoff

You can change the backoff multiplier per entity:

```bash theme={null}
WEBHOOK_DICT_INFRACTION_REPORT_BACKOFF_MULTIPLIER=3
```

## Circuit breaker protection

***

A **circuit breaker** protects webhook delivery and prevents cascading failures.

When the Pix Plugin detects repeated delivery failures (by default, 5 consecutive `5xx` responses or connection errors), it temporarily pauses webhook calls for that flow and entity.

After a configurable cooldown period (default 30 seconds), the system retries the endpoint to check whether it has recovered.

When the endpoint returns successful responses, the plugin resumes normal delivery automatically.

> [!NOTE]
>
> The circuit breaker works alongside retries and exponential backoff.

## Inspect and retry webhooks

***

The plugin stores the webhooks it receives from BTG (inbound) and the webhooks it sends to you (outbound). Use these endpoints to find a webhook and process or send it again:

| Endpoint | What it does |
| - | - |
| `GET /v1/webhooks/inbound` | Lists inbound webhooks. The `entity_type` query parameter is required. |
| `GET /v1/webhooks/inbound/{id}` | Returns one inbound webhook. |
| `POST /v1/webhooks/inbound/{id}/retry` | Processes a `FAILED` inbound webhook again. Returns `202 Accepted`. |
| `GET /v1/webhooks/outbound` | Lists outbound webhooks. The `flow_type` query parameter is required. A webhook in the dead-letter queue has the status `DEAD_LETTER`. |
| `GET /v1/webhooks/outbound/{id}` | Returns one outbound webhook. |
| `POST /v1/webhooks/outbound/{id}/retry` | Sends a `FAILED`, `SENT`, or `DEAD_LETTER` outbound webhook again. Returns `202 Accepted`. |

> [!TIP]
>
> **API reference:** [List inbound webhooks](/en/reference/interfaces/pix-btg/list-inbound-webhooks) · [Get an inbound webhook](/en/reference/interfaces/pix-btg/get-an-inbound-webhook) · [Retry an inbound webhook](/en/reference/interfaces/pix-btg/retry-an-inbound-webhook) · [List outbound webhooks](/en/reference/interfaces/pix-btg/list-outbound-webhooks) · [Get an outbound webhook](/en/reference/interfaces/pix-btg/get-an-outbound-webhook) · [Retry an outbound webhook](/en/reference/interfaces/pix-btg/retry-an-outbound-webhook)

## Transport errors and orphan events

***

When the plugin receives a MED refund request, it looks up the original transfer along the cash-in → cash-out chain. If no local source matches, the plugin persists the refund as an **orphan record** for BACEN auditability. It does not drop the refund, so the record stays visible for reconciliation and follow-up. If a source lookup fails at the transport layer, the plugin skips that source and continues. When no source resolves, the plugin records the refund as an orphan.

`originalEndToEndId` is the canonical key for all refund lookups. The plugin resolves refunds from both the cash-in → refund and cash-out → refund directions with this field. Always key refunds by `originalEndToEndId` (the original transfer's end-to-end ID), not by a single direction-specific lookup path.

# Internal transaction reports (intra-PSP)

***

The plugin settles intra-PSP (P2P) transfers internally. They never reach BTG for settlement, but the plugin still reports them to BACEN through the **TRCK002** abstraction. BTG confirms report status through a **CAMT025** webhook that carries the entity `PixInternalTransactionsReport`.

| Field | Description |
| - | - |
| `pactualId` | BTG-assigned report identifier |
| `clientRequestId` | Your idempotency key, sent during report submission |
| `entity` | Always `PixInternalTransactionsReport` |
| `status` | `PROCESSING`, `CONFIRMED`, or `ERROR` |
| `errorCode` / `errorDescription` | Populated when `status = ERROR` |

The plugin updates the report status when the CAMT025 report webhook confirms or fails. The outbound webhooks fire earlier, when the intra-PSP transfer settles: `TRANSFER` / `CASHIN` for the cash-in leg and `TRANSFER` / `CASHOUT` for the cash-out leg. For the full internal flow, see [Intra-PSP transfers](/en/interfaces/pix-btg/indirect-pix-intra-psp).

To list the transaction reports, use `GET /v1/transaction-reports`. If the worker did not submit a report, submit it with `POST /v1/transaction-reports/{id}/submit`. The plugin does not change a report that is already `PROCESSING` or `CONFIRMED`. The CAMT025 webhook delivers the result.

> [!TIP]
>
> **API reference:** [List transaction reports](/en/reference/interfaces/pix-btg/list-transaction-reports) · [Submit a transaction report](/en/reference/interfaces/pix-btg/submit-a-transaction-report)

# Transaction-time reports (TemposTransacoes)

***

The plugin computes the BACEN TemposTransacoes payer-experience percentiles for a closed reference month. To start the computation, send `POST /v1/statistics/tempos-transacoes/jobs` with the `referenceMonth` in `YYYY-MM` format. The job starts in `PENDING`, then moves to `RUNNING` and ends in `COMPLETED` or `FAILED`. A reference month can have one `PENDING` or `RUNNING` job at a time.

To read the job of a month, use `GET /v1/statistics/tempos-transacoes/jobs/{referenceMonth}`. When the status is `COMPLETED`, the `result` field carries the percentiles. The plugin also sends a `REPORT` / `TEMPOSTRANSACOES` webhook with the result when the job completes.

> [!TIP]
>
> **API reference:** [Create a job](/en/reference/interfaces/pix-btg/create-transaction-times-job) · [List jobs](/en/reference/interfaces/pix-btg/list-transaction-times-jobs) · [Get a job](/en/reference/interfaces/pix-btg/get-transaction-times-job) · [Cancel a job](/en/reference/interfaces/pix-btg/cancel-transaction-times-job)

# Best practices

***

| Practice | Why it matters |
| - | - |
| **Ignore unknown fields** | Remain forward-compatible as new fields are added |
| **Idempotent processing** | Use `Idempotency-Key` to avoid processing duplicates |
| **Fast acknowledgment** | Return `202 Accepted` and process asynchronously |
| **Async processing** | Avoid blocking the webhook thread |
| **Handle compression** | Payloads >1KB are gzip-compressed. Check the `Content-Encoding` header and decompress accordingly |

# Event examples

***

Expand each entry to see an example payload for that event type. Each example shows the main fields. A payload can carry more.

> **DICT claim**
>
> Ownership or portability lifecycle events. Use these to track Pix key disputes across institutions.
>
> ```json theme={null}
> {
>   "entityType": "CLAIM",
>   "flowType": "DICT",
>   "payload": {
>     "id": "0193a1b2-7c3d-7e4f-8a5b-6c7d8e9f0a1b",
>     "accountId": "01989f9e-6508-79f8-9540-835be49fbd0d",
>     "externalId": "7f8a9b2c-1234-5678-abcd-ef0123456789",
>     "type": "PORTABILITY",
>     "status": "CONFIRMED",
>     "keyValue": "+5511999998888",
>     "keyType": "PHONE",
>     "donorParticipant": "87654321",
>     "createdAt": "2024-01-15T10:30:00Z",
>     "updatedAt": "2024-01-15T14:45:00Z",
>     "resolutionPeriodEnd": "2024-01-22T14:45:00Z",
>     "completionPeriodEnd": "2024-01-29T14:45:00Z"
>   }
> }
> ```

> **DICT infraction report (MED)**
>
> Dispute and fraud signaling events aligned with BACEN MED rules.
>
> ```json theme={null}
> {
>   "entityType": "INFRACTION_REPORT",
>   "flowType": "DICT",
>   "payload": {
>     "id": "0193a1b2-8d4e-7f50-9b6c-7d8e9f0a1b2c",
>     "externalId": "3e4f5a6b-7890-1234-cdef-567890abcdef",
>     "accountId": "01989f9e-6508-79f8-9540-835be49fbd0d",
>     "transactionId": "E12345678202401151030ABCDEFGHIJK",
>     "reason": "REFUND_REQUEST",
>     "situationType": "SCAM",
>     "status": "OPEN",
>     "reporterParticipant": "12345678",
>     "counterpartyParticipant": "87654321",
>     "createdAt": "2024-01-15T10:30:00Z",
>     "updatedAt": "2024-01-15T10:30:00Z"
>   }
> }
> ```

> **DICT refund (MED)**
>
> Refund requests and decisions related to MED cases.
>
> ```json theme={null}
> {
>   "entityType": "REFUND",
>   "flowType": "DICT",
>   "payload": {
>     "id": "0193a1b2-9e5f-7061-8c7d-8e9f0a1b2c3d",
>     "externalId": "9a8b7c6d-5432-1098-fedc-ba0987654321",
>     "accountId": "01989f9e-6508-79f8-9540-835be49fbd0d",
>     "transactionId": "E12345678202401151030ABCDEFGHIJK",
>     "infractionReportId": "3e4f5a6b-7890-1234-cdef-567890abcdef",
>     "refundReason": "FRAUD",
>     "refundAmount": "150",
>     "status": "OPEN",
>     "requestingParticipant": "12345678",
>     "contestedParticipant": "87654321",
>     "createdAt": "2024-01-16T09:00:00Z",
>     "updatedAt": "2024-01-16T09:00:00Z"
>   }
> }
> ```

> **DICT funds recovery (MED 2.0)**
>
> Funds Recovery entity status changes. The plugin updates its local record before it sends the event.
>
> ```json theme={null}
> {
>   "entityType": "FUNDS_RECOVERY",
>   "flowType": "DICT",
>   "payload": {
>     "id": "91d65e98-97c0-4b0f-b577-73625da1f9fc",
>     "externalId": "ca1b9c01-ff9e-4a58-90ab-d31512e15ce0",
>     "rootTransactionId": "E9999901012341234123412345678900",
>     "situationType": "SCAM",
>     "status": "CREATED",
>     "reporterParticipant": "99999010",
>     "reportDetails": "Details to help receiving participants",
>     "createdAt": "2020-01-17T10:00:00.000Z",
>     "updatedAt": "2020-01-17T10:00:00.000Z"
>   }
> }
> ```
>
> Lifecycle events arrive as `entityType: FUNDS_RECOVERY_EVENTS` (pass-through, no DB update), with `payload.body.event` values such as `FUNDS_RECOVERY_ANALYSED` and `FUNDS_RECOVERY_COMPLETED`.

> **Transfer cash-in and cash-out**
>
> Incoming and outgoing Pix transfer events.
>
> **Cash-in (incoming transfer):**
>
> ```json theme={null}
> {
>   "entityType": "CASHIN",
>   "flowType": "TRANSFER",
>   "payload": {
>     "id": "550e8400-e29b-41d4-a716-446655440010",
>     "amount": "250.00",
>     "endToEndId": "E87654321202401151030ABCDEFGHIJK",
>     "status": "COMPLETED",
>     "type": "CASHIN",
>     "source": {
>       "account": { "branch": "0001", "number": "987654", "participant": "87654321", "type": "CACC" },
>       "owner": { "document": "12345678901", "name": "João Silva", "type": "NATURAL_PERSON" }
>     },
>     "destination": {
>       "key": "maria@example.com",
>       "account": { "branch": "0001", "number": "123456", "participant": "12345678", "type": "CACC" },
>       "owner": { "document": "98765432100", "name": "Maria Santos", "type": "NATURAL_PERSON" }
>     },
>     "paymentType": "IMMEDIATE",
>     "initiationType": "KEY",
>     "urgency": "HIGH",
>     "purpose": "TRANSFER",
>     "accountId": "01989f9e-6508-79f8-9540-835be49fbd0d",
>     "createdAt": "2024-01-15T10:30:00Z",
>     "updatedAt": "2024-01-15T10:30:05Z"
>   }
> }
> ```
>
> **Cash-out (outgoing transfer):**
>
> ```json theme={null}
> {
>   "entityType": "CASHOUT",
>   "flowType": "TRANSFER",
>   "payload": {
>     "id": "550e8400-e29b-41d4-a716-446655440020",
>     "amount": "500.00",
>     "endToEndId": "E12345678202401151045ABCDEFGHIJK",
>     "status": "COMPLETED",
>     "type": "CASHOUT",
>     "source": {
>       "account": { "branch": "0001", "number": "123456", "participant": "12345678", "type": "CACC" },
>       "owner": { "document": "98765432100", "name": "Maria Santos", "type": "NATURAL_PERSON" }
>     },
>     "destination": {
>       "key": "12345678000199",
>       "account": { "branch": "0001", "number": "555000", "participant": "87654321", "type": "CACC" },
>       "owner": { "document": "12345678000199", "name": "Empresa ABC Ltda", "type": "LEGAL_PERSON" }
>     },
>     "paymentType": "IMMEDIATE",
>     "initiationType": "KEY",
>     "urgency": "HIGH",
>     "purpose": "TRANSFER",
>     "accountId": "01989f9e-6508-79f8-9540-835be49fbd0d",
>     "createdAt": "2024-01-15T10:45:00Z",
>     "updatedAt": "2024-01-15T10:45:03Z"
>   }
> }
> ```

> **Refund cash-in and cash-out**
>
> Refund settlement events for Pix transactions.
>
> **Refund cash-in (receiving a refund):**
>
> ```json theme={null}
> {
>   "entityType": "CASHIN",
>   "flowType": "REFUND",
>   "payload": {
>     "id": "550e8400-e29b-41d4-a716-446655440030",
>     "originalEndToEndId": "E12345678202401151045ABCDEFGHIJK",
>     "returnEndToEndId": "D87654321202401161000ABCDEFGHIJK",
>     "amount": "500.00",
>     "status": "COMPLETED",
>     "type": "CASHIN",
>     "accountId": "01989f9e-6508-79f8-9540-835be49fbd0d",
>     "createdAt": "2024-01-16T10:00:00Z",
>     "updatedAt": "2024-01-16T10:00:02Z"
>   }
> }
> ```
>
> **Refund cash-out (sending a refund):**
>
> ```json theme={null}
> {
>   "entityType": "CASHOUT",
>   "flowType": "REFUND",
>   "payload": {
>     "id": "550e8400-e29b-41d4-a716-446655440040",
>     "originalEndToEndId": "E87654321202401151030ABCDEFGHIJK",
>     "returnEndToEndId": "D12345678202401161015ABCDEFGHIJK",
>     "amount": "250.00",
>     "status": "COMPLETED",
>     "type": "CASHOUT",
>     "accountId": "01989f9e-6508-79f8-9540-835be49fbd0d",
>     "createdAt": "2024-01-16T10:15:00Z",
>     "updatedAt": "2024-01-16T10:15:04Z"
>   }
> }
> ```

# Next steps

***

* [Pix main domains: transfers](/en/interfaces/pix/main-domains-transactions): Transfer operations in detail
* [Pix main domains: DICT](/en/interfaces/pix/main-domains-dict): Understanding DICT operations and key management
* [Pix main domains: MED](/en/interfaces/pix/main-domains-med): MED dispute and refund handling
* [MED 2.0: Funds Recovery](/en/interfaces/pix-btg/indirect-pix-med-2-funds-recovery): Cross-account fraud recovery and its webhooks
* [Intra-PSP transfers](/en/interfaces/pix-btg/indirect-pix-intra-psp): Internal P2P settlement and TRCK002 reporting
* [API reference](/en/reference/interfaces/pix-btg/create-entry): Full API documentation for DICT, Claims, Transactions, QR Codes, and MED operations


# The direct and indirect model
Source: https://docs.lerian.studio/en/interfaces/pix-jd/direct-and-indirect-model

How direct and indirect Pix participation works on this rail: what an ISPB identifies, who holds the settlement account at the Banco Central, where an indirect participant's money lives, and how the direct participant controls each position.

Every institution on Pix participates in one of two ways. A **direct participant** has its own connection to the Banco Central's settlement infrastructure, and it settles Pix in its own right. An **indirect participant** has no connection of its own. It contracts a direct participant and operates through the connection of that participant.

This rail makes your institution the direct participant. With [Hosting indirect participants](/en/interfaces/pix-jd/hosting-indirect-participants), other institutions can reach Pix through you.

## Every participant has its own ISPB

***

Direct or indirect, every participant carries an **ISPB**. The ISPB is the eight-digit code that the Banco Central gives to every institution. Two facts about it decide most of what follows:

* **The ISPB gives identity and routing.** The ISPB of an indirect participant names it on every Pix message. An inbound credit uses it to find the right institution. An outbound order uses it to say on whose behalf the money moves.
* **The ISPB is not settlement.** The direct participant that hosts an indirect participant settles its Pix. An ISPB does not give an institution a settlement account at the Banco Central.

On this rail, the two ISPBs live in different places, on purpose. Your own ISPB is the identity of the deployment. You write it once, in the systemplane key `tenancy/jd_integration_binding`. The ISPB of each indirect participant goes in its registration, and nowhere else. [Hosting indirect participants](/en/interfaces/pix-jd/hosting-indirect-participants) tells what happens when you confuse the two.

## One settlement account, three layers of position

***

The account that settles Pix at the Banco Central is the **Conta PI**, the Pix settlement account. There is exactly one per direct participant. A deployment can operate several participants through the organization catalog. Then each participant holds its own Conta PI. An indirect participant has no Conta PI. That is what makes it indirect.

The position of an indirect participant exists in three layers, and a different party holds each layer:

| Layer | Held at | What it is |
| - | - | - |
| 1 | the Banco Central | part of the direct participant's Conta PI. The Banco Central sees one balance, yours. The money of every hosted institution is inside it |
| 2 | JD | an internal limit and balance per indirect participant, which you administer. The connectivity layer uses it to know how much each hosted institution can move |
| 3 | your Midaz ledger | the position account `@pi_` followed by the ISPB of the institution. There is one per indirect participant, and the plugin creates it when you register the institution |

Segregation happens at the third layer. Each indirect participant settles on its own `@pi_{ispb}` account. The money of one institution never mixes with the money of another, or with your own book. [Indirect participants](/en/reference/interfaces/pix-jd/indirect-participants) tells what a registration creates and how the plugin derives the alias.

Your ledger is the layer that authorizes a payment. The rail refuses a payment that exceeds the Midaz balance before it sends anything to JD. A balance at the other layers authorizes nothing by itself. That includes the Conta PI at the Banco Central and the limit of an institution at JD. When the ledger says no, the order never leaves your side.

## How you control each position

***

The direct participant owns the lifecycle of every position, from start to end:

1. **Registration creates the position.** `POST /v1/indirects` creates the `@pi_{ispb}` account in Midaz before it writes the participation row. You never create the account yourself.
2. **You fund it.** The position starts at zero. The initial load comes from the external clearing account (for example, `@external/BRL`), with the same posting mechanics as any opening balance. Until the position holds funds, the rail refuses every payment that leaves through that indirect participant, for insufficient balance. For the procedure, see [fund the position](/en/interfaces/pix-jd/hosting-indirect-participants#step-5-fund-the-position).
3. **Cash-in credits it.** An inbound Pix for a customer of an indirect participant posts to the `@pi_{ispb}` of that institution. The money stops with you. After your notice, the institution credits its own customer in its own core.
4. **Cash-out debits it.** An outbound order on behalf of an indirect participant debits its `@pi_{ispb}`. It never debits your own accounts or the position of another indirect participant.
5. **A close needs a zero position.** The rail refuses `close` with `409 PIX-0096` while the `@pi` account still holds funds, and the answer names the cause. A closed position never traps money.

## Hosting indirect participants does not change your own book

***

A deployment with hosting enabled continues to operate as a plain direct participant. On every inbound credit, the resolver asks its questions in this order:

1. **"Is this receiver ISPB our own?"** If yes, the credit is for your book. The account resolves through the CRM, as on a deployment that hosts nobody.
2. **Only then: "Does it match an indirect participation?"** If an `ACTIVE` participation matches, the credit posts to the `@pi_{ispb}` of that institution.
3. **Neither?** The rail refuses the credit. It guesses nothing and posts nothing blindly.

The order is a protection, not a preference. Credits for your own customers can never go into the position of a hosted institution, even through a participation that you registered incorrectly. When you enable the feature, nothing changes on the flow of your own book.

## A different axis: several direct participants on one deployment

***

Hosting indirect participants is not the only way that a second institution appears on this rail. Do not confuse the two. An economic group can run both of its institutions as direct participants on one deployment, through the [organization catalog](/en/interfaces/pix-jd/multi-organization-and-ledgers). For example, a holding can operate a payment institution and a credit fintech, each with its own ISPB.

The two axes differ in everything that matters:

| | An indirect participant | An additional organization |
| - | - | - |
| What it is | an institution that reaches Pix **through you** | a direct participant **in its own right**, operated by your group |
| Where its money lives | a `@pi_` position account inside **your** book | its **own** Midaz organization and ledgers |
| Who settles at the Banco Central | you, on your Conta PI | itself, on its own settlement account |
| Its credential at the connectivity layer | none (it rides yours) | its own, per ISPB |

An indirect participant is a position inside your book. An additional organization is another book entirely: a separate regulated institution, and its records never mix with yours. One deployment can do both at once. It can host indirect participants under one organization and operate several organizations of the same group.

## Where to go next

***

* **[Hosting indirect participants](/en/interfaces/pix-jd/hosting-indirect-participants)**: the provisioning. It covers the encryption key, the posture, the registration of each institution, and the funding of its position.
* **[Multi-organization and ledgers](/en/interfaces/pix-jd/multi-organization-and-ledgers)**: the other axis. It covers several direct participants, and several books per participant, on one deployment.
* **[Indirect participants](/en/reference/interfaces/pix-jd/indirect-participants)**: what a hosted participation is, how money gets to one, and its lifecycle.
* **[Setting up the rail](/en/interfaces/pix-jd/pix-jd-setup)**: the provisioning chain of the direct participant. Everything above builds on it.
* **[Pix via JD](/en/interfaces/pix-jd/direct-pix-via-jd)**: the overview of the rail and its domain map.


# Pix via JD
Source: https://docs.lerian.studio/en/interfaces/pix-jd/direct-pix-via-jd

Direct Pix participation on BACEN's SPI and DICT through JD's certified connectivity: one API for keys, payments, QR codes, webhooks, MED 2.0, Pix Automático, and the indirect participants you host.

**Direct Pix via JD** makes your institution a **direct participant** in Pix. Your institution is present at BACEN's settlement system (SPI) and key directory (DICT) in its own right. It connects through JD's certified infrastructure (JDPI). Your institution owns its Pix participation, and JD gives the regulated connectivity to BACEN's network. If the rail itself is new to you, start with [What is Pix?](/en/interfaces/pix/pix-overview). It explains modalities, SPI, DICT, and participation models.

When another core engine of your institution uses the same JD channel and ISPB, [JD Courier](/en/interfaces/jd-courier/what-is-jd-courier) shares the channel between the engines.

Everything that the rail does is one API. Its [OpenAPI specification](/en/openapi/v3-current/pix.yaml) is the source of this documentation. Every operation carries the rules that an integrator cannot guess from the schema alone.

> [!NOTE]
>
> On a self-hosted deployment, your team operates the service. On Lerian Cloud, Lerian runs the service and sets up the JD connection, the public QR domain, the CRM connection, and every service that the rail talks to. In both cases, the rest of the setup is yours to run: your books in Midaz, your holder records in the CRM, your accounting routes, and the rail settings.

## The tenant and its direct participants

***

A tenant holds **one or more direct participants**. By default, it holds the single institution that its binding names. With the organization catalog, it can hold the several regulated institutions of one economic group. Each of them is a direct participant in its own right, with its own books. See [Multi-organization and ledgers](/en/interfaces/pix-jd/multi-organization-and-ledgers).

Every call is authenticated with the tenant's own machine-to-machine credentials. The tenant comes from the validated bearer, never from a payload or a path.

The institutions you host as **indirect participants** live inside your tenant and never hold a credential of their own. An indirect's id on a request serves as routing data. It decides which settlement position the money moves on. The guarantee that the request really belongs to that institution is yours to make before you send it. The one anonymous exception is the public QR payload and JWKS routes. Their caller is the payer's PSP, a party that you never registered.

[The direct and indirect model](/en/interfaces/pix-jd/direct-and-indirect-model) explains the two participation types. It also shows who holds the settlement account at the Banco Central, and where each hosted institution's money lives.

## The domain map

***

Each domain below is a section of the API reference. This page gives one sentence per domain. The reference has the full contract: when to call each operation, which side calls it, and what it refuses. Each link opens a typical operation of its section.

* **[Key entries](/en/reference/interfaces/pix-jd/list-keys)**: register, change, and remove the Pix keys of your accounts in the DICT. It also has batch verification and the two bulk-removal flows, for account closure and for holder removal.
* **[Key claims](/en/reference/interfaces/pix-jd/create-claim)**: the BACEN process to take a key from another PSP. It covers portability of your own key and ownership claims, with both sides of the negotiation.
* **[Banks](/en/reference/interfaces/pix-jd/list-pix-participant-bank-ids)**: the national SPI participant catalog, read live from JDPI.
* **[Transactions](/en/reference/interfaces/pix-jd/create-transaction)**: outbound payments over SPI (two-phase, asynchronous), or settled on your own book when the payee is on-us. It also has the read surface that closes the loop.
* **[Refunds](/en/reference/interfaces/pix-jd/create-refund)**: the devolução of a payment that you received, started by the payee. Each one is a new transaction row, capped at the original amount.
* **[Limits](/en/reference/interfaces/pix-jd/retrieve-transaction-limits)**: per-account outbound transaction limits. The account's first outbound payment creates them, and the rail applies them before any money moves.
* **[QR codes](/en/reference/interfaces/pix-jd/create-dynamic-qr-code)**: static and immediate dynamic codes with self-hosted signed payloads, decode, and listing. The section's introduction documents the anonymous public payload and JWKS routes.
* **[Webhooks](/en/reference/interfaces/pix-jd/process-an-inbound-upstream-cash-in)**: the inbound routes that JDPI calls on you. They cover cash-in, the devolução started by the payee's bank, and account validation, synchronous and asynchronous.
* **[Indirect participants](/en/reference/interfaces/pix-jd/indirect-participants)**: the registry of the institutions that reach SPI through your ISPB. It covers their lifecycle, settlement positions, delivery notices, and the reconciliation feed.
* **MED 2.0**: BACEN's special return mechanism. It covers [infraction reports](/en/reference/interfaces/pix-jd/list-med-infractions), [refund requests](/en/reference/interfaces/pix-jd/open-a-med-refund-request) in both roles, creator-side [value recoveries](/en/reference/interfaces/pix-jd/create-a-med-value-recovery), and [fraud markers](/en/reference/interfaces/pix-jd/register-a-med-fraud-marker). The credit of a refund that you won arrives on the [devolução webhook](/en/reference/interfaces/pix-jd/process-a-payee-bank-initiated-pix-devolu-o), with return code BE08 or FR01.
* **[Pix Automático](/en/reference/interfaces/pix-jd/request-a-pix-automatico-authorization)**: recurring authorizations, their schedules, and composite QR codes. It also has the inbound registration, settlement, and event routes that JDPI calls on you.
* **[Systemplane](/en/reference/platform/systemplane/overview)**: the runtime-configuration surface for operators. Payment clients never need it. The platform documentation covers its routes, and this reference does not.

## Payment orders and devoluções

***

These rules apply to every client that sends money through the rail:

* **Send the `X-Idempotency` header** on every payment order (`POST /v1/transactions`) and every devolução (`POST /v1/refunds`). Use a stable business string of 255 bytes or less. Without it, the rail answers `400 PIX-0061` before any ledger or JDPI call.
* **A resend under a recorded key moves no money.** It answers `409 PIX-0029`. A payment order with the `endToEndId` of a recorded order gets the same answer. Read the outcome of the first request with a `GET`.
* **A resend under the key of a refused order answers `409 PIX-0133`.** JD refused or never received that order, so no money moved. To pay, send a new order under a new key.
* **The key belongs to the payer.** The payer is the organization that pays, plus the indirect participant on an indirect order or devolução. Two payers can use the same key value.
* **A payment order does not carry the payer's Pix key.** A body with a top-level `key` field answers `400 PIX-0061`. The payee's key, `payee.key`, does not change.
* **A devolução of a Pix that an indirect participant received carries its `indirectId`.** Otherwise the rail answers `422 PIX-0135`. See [Indirect participants](/en/reference/interfaces/pix-jd/indirect-participants#returning-a-pix-that-an-indirect-participant-received).
* **A Pix Automático debit posts on the account that the authorization names.** When the authorization names no account, the debit uses the payer's only account. A payer with two or more accounts and no account on the authorization gets `400 PIX-0061`, before any posting.

## Pix by key to a third party

***

To pay a Pix key held at any institution, look the key up first and pay with what the lookup returns:

1. **Look up the receiver's key** with [Look up a Pix key before paying it](/en/reference/interfaces/pix-jd/look-up-a-pix-key-before-paying-it) (`GET /v1/entries/{entryId}/lookup`). `entryId` is the key value, URL-encoded. `account_id` is the **payer's** account, the one the payment leaves from. The DICT lookup is made on behalf of the payer: DICT counts it against the payer's CPF or CNPJ. When this deployment acts as several direct participants, `ispb` names the one that pays. When the payment goes through an indirect participant, send its `indirectId`, the same one that the payment order carries. DICT then mints the `endToEndId` under the ISPB of that participant. With `indirectId`, omit `ispb`.
2. **Read the answer.** It returns an `endToEndId` and a `payee` block with exactly the fields that `POST /v1/transactions` expects. The account number comes whole in `payee.accountNumber`, as the DICT returns it, and `payee.accountDigit` is empty.
3. **Pay** with `POST /v1/transactions`, sending that `endToEndId` and that `payee` as they are. The payment goes to JD as a payment initiated by key. Without the `endToEndId`, it goes out as a manually typed order.

One lookup serves one payment. Look the key up again before every payment, and only when the payer is about to pay: a lookup that is not followed by a payment still spends the payer's and the institution's DICT budget. To check that a list of keys exists, use `POST /v1/entries/verification`.

The lookup answers these errors:

| Status | Code | When |
| - | - | - |
| `400` | `PIX-0061` | `account_id` is missing, or `ispb` is not 8 digits. |
| `404` | `PIX-2016` | `account_id` does not resolve to an account. |
| `404` | `PIX-1011` | The DICT holds no such key. |
| `404` | `PIX-0095` | `indirectId` names no indirect participant of this tenant. |
| `422` | `PIX-0127` | This deployment acts as several direct participants, `ispb` is missing, and there is no `indirectId`. |
| `422` | `PIX-0128` | `ispb` names a participant that this deployment does not act as, and there is no `indirectId`. |
| `422` | `PIX-0100` | The indirect participant that `indirectId` names is not `ACTIVE`. |
| `422` | `PIX-0102` | `ispb` names a participant other than the one that hosts the indirect participant. |
| `422` | `PIX-0111` | The request has `indirectId`, and `plugin-br-pix-jd.indirects/enabled` is `false`. |
| `429` | `PIX-0009` | The payer account reached this deployment's lookup limit. The response carries `Retry-After`. |
| `429` | `PIX-1008` | The DICT refused the lookup for its own limit. |
| `503` | `PIX-1050` | JD is unavailable. |
| `503` | `PIX-1054` | JD cannot be reached. |
| `504` | `PIX-1051` | JD did not answer in time. |

**The lookup limit.** By default, a payer account can make 100 lookups per 60 seconds. The limit applies always, apart from the general request limits. The operator tunes it in the systemplane namespace `plugin-br-pix-jd.http`, with the keys `rate_limit.key_lookup.max` and `rate_limit.key_lookup.window_sec`.

**A payment by key to a payee at your own institution is checked against the DICT.** Before the payment settles on your book, the rail compares the payee's ISPB, branch, account, account type, and document with the account that the DICT binds the key to. A field that differs answers `422 PIX-0033`, naming the field, and no money moves. Send the `payee` that the lookup returned and the check passes.

> [!WARNING]
>
> The lookup route requires the access permission `entries-lookup` (action `get`), which the Pix roles receive from the Access Manager. On a self-hosted (BYOC) deployment, make sure that the Pix roles have this permission **before** you upgrade the Pix plugin to 1.1.0 or later. Otherwise the route answers `403`.

## Money: one API, two units

***

This API's own contract gives every money field as an **int64 count of centavos**. For example, `110001` means R\$ 1.100,01. That rule covers JSON bodies, query, path, and header.

JDPI authors some bodies: the webhook routes and the Pix Automático inbound, settlement, and event routes. On those bodies, every money field is a **JSON number in reais** (`1100.01`). That is JD's contract on the payloads that JD sends. The rail converts to centavos at the boundary.

The side that authored the body sets the unit, never the field's language. Portuguese-named fields on this API's own write surfaces still carry integer centavos. Each field's description in the reference gives its unit.

## English field names

***

In MED 2.0, Pix Automático, and the key lookup, a field that earlier versions accepted under two names, an English one and a deprecated Portuguese one, now has only its English name. For example: `recoveryId` (was `idRecValores`), `recurrenceId` (was `idRecorrencia`), `cancellationId` (was `idCancelamento`), `taxId` (was `cpfCnpj`), and `payee.accountNumber` on the key lookup (was `nrConta`). The reference gives each field's name.

* **A request body with a Portuguese name is refused** with `400 PIX-0061`, as any field that the API does not declare. Nothing is recorded. Send the English name.
* **A query parameter with a Portuguese name is ignored.** A listing filtered by one comes back unfiltered. Check every filter name against the reference.
* **Responses carry each field once**, under its English name.
* **The MED value-recovery routes** are `GET /v1/med/recoveries/awaiting-return` and `POST /v1/med/recoveries/{idRecValores}/return`. The `awaiting-devolver` and `devolver` paths no longer exist.

The bodies that JDPI authors keep JD's field names: the webhook routes and the Pix Automático inbound, settlement, and event routes.

## Errors

***

Errors are RFC 9457 `application/problem+json`. Every error carries a `PIX-XXXX` taxonomy code in the `code` member. Match on the code, never on the human-readable text.

The [Pix JD error list](/en/reference/interfaces/pix-jd/pix-jd-error-list) has every code, with the exact `detail` of each one.

## How Pix movements land in Midaz

***

The direct participation plugin posts every settled Pix movement to Midaz as a ledger transaction. The external leg goes against the clearing account (for example, `@external/BRL`). Settled movements include cash-out, cash-in, refunds (devolução), MED effectuation legs, and Pix Automático settlement. Midaz records the accounting entry. The payer and payee identity (bank, branch, account, holder name and document, Pix key) lives only in the plugin's own transaction record. Every BACEN reference lives only in that record.

Correlation between the two systems works through identifiers, not metadata:

* The **end-to-end ID (E2E)** is the idempotency key of the Midaz posting, so a retried settlement can never double-post to the ledger.
* The plugin stores the **Midaz posting ID** on its own transaction record. It uses that ID to commit or cancel the pending debit of a two-phase cash-out.

To see the banking detail behind a ledger entry, query the plugin's transaction API by the plugin transaction id or the E2E ID. The ledger stays pure accounting.

## Where to start

***

1. **[Setting up the rail](/en/interfaces/pix-jd/pix-jd-setup)**: the setup trail, in the order you act, for a service that is already running. It covers the prerequisites, payment-order signing, the Midaz ledger and CRM records, the accounting routes, the plugin settings, and the checks that prove each step. Follow it from top to bottom.
2. **[Payment-order signing](/en/interfaces/pix-jd/payment-order-signing)**: step 2 of the trail, only if JD requires signed payment orders for your institution.
3. **[Environment variables](/en/interfaces/pix-jd/pix-jd-environment-variables)**: the deployment variables of the service, with their format and default.
4. **[The direct and indirect model](/en/interfaces/pix-jd/direct-and-indirect-model)**: the two participation types, and where an indirect participant's money lives. Then read **[Hosting indirect participants](/en/interfaces/pix-jd/hosting-indirect-participants)**, with the extra steps for a deployment that settles Pix for other institutions. Skip both if you settle only the Pix of your own customers.
5. **The [API reference](#the-domain-map)**: pick your domain in the map above. Each link opens a typical operation of its section.

> [!NOTE]
>
> Lerian provisions the provider-specific configuration for direct participation via JD with your integration. To set up direct Pix participation, [get in touch with our team](https://lerian.studio/contact).


# Hosting indirect participants
Source: https://docs.lerian.studio/en/interfaces/pix-jd/hosting-indirect-participants

The provisioning steps a deployment adds when it settles Pix on behalf of other institutions: the delivery-secret encryption key, the hosting posture, registering each indirect participant, its own QR certificate, funding its settlement position, and the systemplane keys of the indirects namespace.

To settle a Pix at the Banco Central, an institution needs a connection to the National Financial System infrastructure. That connection is expensive and slow to get, and not every institution has one. An institution without it uses the connection of another institution. It becomes an **indirect participant**, and a direct participant settles for it and **hosts** it. [The direct and indirect model](/en/interfaces/pix-jd/direct-and-indirect-model) explains that arrangement: who holds the settlement account, and where each institution's money lives.

A tenant that hosts indirect participants is a direct participant first. Finish steps 1 to 7 of [Setting up the rail](/en/interfaces/pix-jd/pix-jd-setup) exactly as that page says. This page is its step 8 for a deployment that settles Pix for other institutions. If your deployment settles only the Pix of its own customers, skip this page.

| # | Step | When |
| - | - | - |
| 1 | **the delivery-secret encryption key** | once per deployment, before the first registration. On SaaS, Lerian does it |
| 2 | **the hosting posture, `indirects/enabled = true`** | once per tenant |
| 3 | **registering the indirect participant** | once per indirect participant |
| 4 | **its own QR certificate** | only for an indirect participant that has its own QR certificate at JD |
| 5 | **funding its settlement position** | once per indirect participant, before its first outbound payment |

> [!WARNING]
>
> Do step 1 before step 3. Without the encryption key, every registration fails. Do step 2 before step 4: with the posture off, the certificate step is refused with `422 PIX-0111`. Do step 4 and step 5 after step 3, because both act on the participation that the registration creates. Steps 4 and 5 do not depend on each other.

> [!NOTE]
>
> This page covers provisioning. [Indirect participants](/en/reference/interfaces/pix-jd/indirect-participants) explains what a hosted participation is, how an inbound credit reaches one, how its lifecycle behaves, and every refusal it can answer.

### Step 1: the delivery-secret encryption key

> [!NOTE]
>
> **On SaaS, there is nothing to do in this step.** Lerian configures the key for your tenant. Go to step 2. The rest of this step applies to a self-hosted deployment.

**Why this step exists.** When you register an indirect participant, you supply a **delivery secret**. The plugin signs every notice it sends to that institution's endpoint with it. It is how the institution knows the notice really came from you. That secret is stored encrypted, and the key that encrypts it does not come from the database. It comes from outside.

**If the key is not configured, every registration that carries a secret fails.** That failure covers the whole write surface of the indirect flow.

```text theme={null}
409  PIX-0107  "Indirect Delivery Encryption Not Provisioned"
     "No delivery-secret encryption key is provisioned for this tenant, so the
      indirect participant was not saved and no secret was stored. ..."
```

The message guarantees that no secret was stored. Encryption fails before any write, so there is no half-created row with a plaintext secret to go and clean up. Fix the key and repeat the `POST`. That is the whole recovery.

> [!NOTE]
>
> **This `409` means "provision it", not "try again later".** The rail looked for the key and found that it does not exist. Only an operator can add it. A repeat of the call without that change fails the same way. That is why the code is a `409` and says nothing about a retry.
>
> Its sibling is `503 PIX-0123`, *"Indirect delivery key source unavailable"*. You get it when the rail **could not read** the key, because its key source refused or did not answer. The rail then does **not** know that the key does not exist, because the read did not complete. The response names the dependency that failed, and a retry is the right action. Both codes refuse the registration and store nothing. The pair lets you tell an incomplete setup from an outage.

> [!WARNING]
>
> The plugin starts without the key, and it does not refuse to boot. The process logs a warning at startup and comes up healthy. At startup, nothing tells a deployment that will host indirect participants from one that never registers one. So the symptom arrives on the first registration, not on deploy. If you did not read the startup log, the refusal is your first notice.

**Where it lives, and why it is not in the systemplane.** This contrast explains where each kind of value belongs on this rail.

| | The ISPB (`tenancy/jd_integration_binding`) | The encryption key |
| - | - | - |
| What it is | **identity**: the number that identifies you at BACEN | **a credential**: cryptographic material |
| Is it a secret? | no. An ISPB, an organization id, and a ledger id are not credentials | yes |
| Where it lives | the **systemplane**, so you can read and write it over the admin API | **outside** the systemplane |
| Where it comes from | the systemplane admin API | on SaaS, Lerian. Self-hosted, the `INDIRECTS_DELIVERY_ENCRYPTION_KEY` deployment variable |

> [!WARNING]
>
> Do not put the encryption key in the systemplane. The systemplane is the live configuration plane, readable over the admin API, and that is the right home for everything that is **not** a secret. Credential material does not go there, and the rail separates the two on purpose.
>
> Do not commit it either: not in a versioned `.env`, not in a `values.yaml`, not in a compose file.

**The format: exactly 64 hex characters.** It is an AES-256 key (32 bytes), hex-encoded. That is **64 hex characters**, not 63 and not 65.

```bash theme={null}
openssl rand -hex 32
```

Generate one per deployment. Do not copy another environment's key and do not reuse another service's.

> [!NOTE]
>
> An absent, blank, or malformed value all produce the same `409 PIX-0107`. There is no default and no degradation to storing the secret in the clear. That is deliberate: a silent default here would store customer secrets encrypted with a key everybody knows.

On a self-hosted deployment, set the deployment variable:

```bash theme={null}
# in the process environment — never in a versioned file
INDIRECTS_DELIVERY_ENCRYPTION_KEY="paste-the-64-hex-characters-here"
```

That placeholder is deliberately not a valid key. Pasted as-is, it fails closed with the refusal above. It does not encrypt your customers' secrets with a value published on a documentation page.

The plugin reads the key at startup, so a change needs a process restart. The ISPB binding is different: the plugin reads it on every call, and a change takes effect without a restart.

> [!WARNING]
>
> Do not type the value on a command line. It ends up in your shell history and in CI logs. Read it from a vault, or type it with `read -rs`, which does not echo.

**How to check it landed.** No route reads the key back, because it is a secret. There are two signals.

*The startup log.* With the key resolvable, the "key unavailable" warning does not appear. If it does appear, no registration carrying a secret will pass.

*The behavior.* Register an indirect participant. The response changes from `409 PIX-0107` to `201`.

> [!WARNING]
>
> Think before you use the behavioral check. A registration is permanent. There is no delete route, and the only exit is `close`, which keeps the row and holds the ISPB. In a production environment, do not use a throwaway registration to test the key. Use an ISPB that you plan to operate. The startup log saves you that cost.

### Step 2: declare that this tenant hosts indirect participants

Set `plugin-br-pix-jd.indirects/enabled` to `true`. This is a configuration write, so it needs **Plugin PIX JD Editor**.

```bash theme={null}
curl -s -o /dev/null -w '%{http_code}\n' -X PUT \
  -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \
  -d '{"value":true}' \
  "$PIX_JD_BASE_URL/system/plugin-br-pix-jd.indirects/enabled"
```

The plugin answers `204` when it accepts the value. The value is a JSON boolean, without quotes: `{"value":"true"}` answers `400`.

Registration works with the posture off, so you can register participants before you enable it. The posture gates the money paths and the own QR certificate of step 4. With the posture off, step 4 answers `422 PIX-0111`. [Before you register anyone](/en/reference/interfaces/pix-jd/indirect-participants#before-you-register-anyone) shows what each half does.

> [!NOTE]
>
> The read fails closed. When a money path "goes back to direct behavior" and nobody changed the key, this is the cause. Look at the systemplane.

### Step 3: register an indirect participant

One call does the whole assembly. It checks the ISPB, creates the `@pi_{ispb}` settlement account in Midaz, and marks the participation active. It needs **Plugin PIX JD Contributor** or **Plugin PIX JD Editor**.

```bash theme={null}
# The signing secret must never appear in a process argument list: `ps` and
# command logging expose arguments. Read it silently, export it, let jq pull it
# from the environment, and have curl read the body from standard input.
IFS= read -r -s -p 'delivery secret for this participant: ' INDIRECT_DELIVERY_SECRET; printf '\n'
export INDIRECT_DELIVERY_SECRET

jq -n '{
  name: "Indirect PSP Ltda",
  ispb: "87654321",
  messagingMode: "raw",
  delivery: { endpointUrl: "https://indirect.example.com/pix", secret: env.INDIRECT_DELIVERY_SECRET }
}' | curl -s -X POST "$PIX_JD_BASE_URL/v1/indirects" \
  -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \
  --data-binary @-
unset INDIRECT_DELIVERY_SECRET
# -> {"indirectId": "...", "piAccountAlias": "@pi_87654321", "status": "ACTIVE", ...}
#    keep indirectId as $INDIRECT_ID
```

| Field | Rule | If it is wrong |
| - | - | - |
| `name` | 1 to 120 characters | `422 PIX-0098` |
| `ispb` | exactly 8 digits: the **indirect institution's** ISPB, not yours | `422 PIX-0098` |
| `delivery.endpointUrl` | the URL where the notices go | `422 PIX-0098` |
| `delivery.secret` | the symmetric signing secret, agreed with that institution | `422 PIX-0098` if absent |
| `messagingMode` | `raw`, the only accepted value | `422 PIX-0098` |

A `201` means that the participation is ready to use. The `status` is always `ACTIVE`. You do not need to poll.

> [!WARNING]
>
> Do not write an indirect participant's ISPB into `tenancy/jd_integration_binding`. That key is the identity that the plugin presents to JD. A third party's ISPB there makes the plugin introduce itself as another institution. Nothing warns you: the plugin accepts 8 valid digits, and the write answers `204`. The key is one per tenant, not one per indirect participant. Every indirect participant that you host reaches the SPI through your ISPB.

> [!WARNING]
>
> **Registration is permanent.** There is no `DELETE` on `/v1/indirects`, and `CLOSED` is terminal. A mistaken registration in a live tenant stays there. Its ISPB stays held against the uniqueness rule until somebody closes it. Check the name, the ISPB, and the endpoint before you call. Rehearse on a disposable environment.

[Indirect participants](/en/reference/interfaces/pix-jd/indirect-participants) has the refusals, the lifecycle actions, and how to read the registry back.

### Step 4: configure its own QR certificate, if it has one

**Skip this step** for an indirect participant that has no QR certificate of its own at JD. Its dynamic QR codes are then signed with your certificate and served on your host, as for your own customers.

**Why this step exists.** Some indirect participants have their own QR certificate at JD. JD then signs their dynamic QR codes with that certificate. The payer's app checks the signature against the key set that it finds on the same host as the QR payload. So the payload and the key set of that participant must be on the participant's own host, not on yours.

**Access:** **Plugin PIX JD Contributor** or **Plugin PIX JD Editor**.

**1. Name the participant's host**

Send `PATCH /v1/indirects/{indirectId}` with the `indirectId` from the registration:

```bash theme={null}
curl -s -X PATCH "$PIX_JD_BASE_URL/v1/indirects/$INDIRECT_ID" \
  -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \
  -d '{"qrCertificate":{"ownCertificate":true,"publicBaseUrl":"pix.indirect.example.com"}}' | jq '.qrCertificate'
```

| Field | Rule |
| - | - |
| `qrCertificate.ownCertificate` | `true`. With `false`, the participant goes back to your certificate and your host, and the plugin discards `publicBaseUrl` |
| `qrCertificate.publicBaseUrl` | required with `true`. The participant's public host, without `https://`, with an optional path. At most 37 characters |

**The 77-character budget.** JD caps the URL of a QR payload at 77 characters. The plugin builds it as `publicBaseUrl`, then `QRCODE_PAYLOAD_PATH`, then, on SaaS, your institution's 8-digit ISPB, then the type of the charge and an identifier of up to 22 characters. With the default `QRCODE_PAYLOAD_PATH`, `qr`, 37 characters are left for the host. A deployment with a longer `QRCODE_PAYLOAD_PATH` leaves fewer. Then each dynamic QR code for this participant answers `422 PIX-0112`. Choose the host against that budget before you register it.

A `200` returns the participation. Check that `qrCertificate.ownCertificate` is `true` and `qrCertificate.publicBaseUrl` is the host that you sent.

| Response | What it means |
| - | - |
| `422 PIX-0111` | the hosting posture of step 2 is off. The plugin refuses the whole `PATCH`, with any other field in it |
| `422 PIX-0098` | the host is missing, has a scheme, is not a host with an optional path, is longer than 37 characters, or is not a public host. An IP address, a private host, and an internal name are refused |
| `404 PIX-0095` | no participation with that `indirectId` in this tenant |

**2. Publish the participant's key set on its host**

The participant cannot make its key set itself, because JD holds the certificate and signs. Read the key set from the plugin:

```bash theme={null}
curl -s -D - "$PIX_JD_BASE_URL/v1/indirects/$INDIRECT_ID/jwks" \
  -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -o indirect-jwks.json
```

The answer is an `application/jwk-set+json` document. Serve those bytes as they are, with that media type, at `https://` plus the participant's host plus `/` plus `QRCODE_JWK_PATH`. With the default `QRCODE_JWK_PATH`, that is `https://pix.indirect.example.com/v1/qrcodes/jwks`. On SaaS, the path ends with one more segment: your institution's 8-digit ISPB, for example `https://pix.indirect.example.com/v1/qrcodes/jwks/12345678`. Read the key set again each time JD rotates the participant's certificate.

The `X-JWK-Set-Freshness` header says `fresh` or `stale`. `stale` means that JD did not answer and the plugin served its last copy. Read it again before you publish.

| Response | What it means |
| - | - |
| `422 PIX-0111` | the hosting posture of step 2 is off |
| `422 PIX-0114` | this participant has no own certificate: `ownCertificate` is `false`. It uses your key set, which the plugin already serves on your host |
| `404 PIX-0095` | no participation with that `indirectId` in this tenant |
| `503 PIX-1050` | JD is unavailable and the plugin has no copy. Retry |

**The payloads go to the participant's host too.** When you create a dynamic QR code with this participant's `indirectId`, the plugin does not serve its payload. The response carries `payloadJws`, and the participant serves it at `payloadUrl` on its own host. [Create a dynamic QR code](/en/reference/interfaces/pix-jd/create-dynamic-qr-code) describes that response, and how to recover a payload that you did not receive.

### Step 5: fund the position

The registration creates the `@pi_{ispb}` account **empty**. Inbound Pix credits it, but an outbound payment needs balance first. **Without funds, every payment that leaves through that indirect participant fails for insufficient balance.** You make the initial load. It mirrors the arrangement: at JD you administer that institution's limit, and in your ledger you load its position.

The mechanics are the same as the funding step of [Setting up the rail](/en/interfaces/pix-jd/pix-jd-setup). Post a Midaz transaction from `@external/BRL`, with the same variables as that page. Only the destination changes, to the `piAccountAlias` from the registration. It is a Midaz transaction, so it needs **Midaz Editor** or **Midaz Contributor**.

```bash theme={null}
curl -s -X POST "$MIDAZ_URL_TRANSACTION/v1/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/transactions/json" "${MIDAZ_HEADERS[@]}" -d '{
  "description": "opening position - Indirect PSP Ltda",
  "send": {
    "asset": "BRL",
    "value": "1000.00",
    "source":     { "from": [ { "accountAlias": "@external/BRL",
                                "amount": { "asset": "BRL", "value": "1000.00" } } ] },
    "distribute": { "to":   [ { "accountAlias": "@pi_87654321",
                                "amount": { "asset": "BRL", "value": "1000.00" } } ] }
  }
}'
```

> [!WARNING]
>
> If you lose the response to a top-up, send the exact same body again within 300 seconds. Midaz then posts it once. After that window, check the position balance before you send the top-up again.
>
> Change the `description` only for a **new** top-up. A new `description` on a real retry adds a second credit by mistake.

The position also controls the participation's exit. The plugin refuses `close` with `409 PIX-0096` while the `@pi` account holds funds, available or on hold, and names the cause. Bring the position to zero before you close. A funded position keeps the participation open until you do.

**How to check.** Read the account's balance back in Midaz. The surest check is behavior: an outbound payment through the indirect participant stops its refusals for insufficient balance.

### Return a Pix that an indirect participant received

A Pix for a customer of an indirect participant lands on that participant's `@pi_{ispb}` position. To return it, send `POST /v1/refunds` with the `indirectId` of that participant. The devolução then debits that position.

The plugin refuses the devolução with `422 PIX-0135` in three cases, and moves no money:

* the original Pix landed on an indirect participant's position, and the refund has no `indirectId`.
* the refund names another indirect participant.
* the original Pix landed on a direct account, and the refund has an `indirectId`.

The `indirectId` passes the same checks as on a payment order. The hosting posture must be on, and the participation must be `ACTIVE`.

### The systemplane keys of the `indirects` namespace

There are five keys, all in `plugin-br-pix-jd.indirects`, and all of them always exist. The three delivery and resolution keys take effect only when `enabled` is `true`, because they tune the money paths. `validate_ispb_on_jd` is the exception. It gates a step of **registration**, which works while `enabled` is still `false`.

| Key | Type | Range | Default | What it is |
| - | - | - | - | - |
| `enabled` | boolean | — | `false` | the hosting posture |
| `delivery_concurrency` | integer | 1–256 | `8` | how many delivery `POST`s run in parallel. Isolation is per participant: one stuck endpoint occupies at most one slot and never blocks the others |
| `delivery_max_attempts` | integer | 1–64 | `8` | the retry budget before a delivery row ends up `INVALID`. Recovery from there is manual |
| `resolution_cache_ttl_sec` | integer | 0–86400 | `30` | how long a resolution stays in the cache. `0` disables the cache, which is why the minimum is 0 |
| `validate_ispb_on_jd` | boolean | — | `false` | with `true`, registration queries JD's participant directory and **fails retryably** if JD is down |

```bash theme={null}
PUT() { curl -s -o /dev/null -w "$1 -> %{http_code}\n" -X PUT \
          -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \
          -d "$2" "$PIX_JD_BASE_URL/system/$1"; }

PUT plugin-br-pix-jd.indirects/enabled                  '{"value":true}'
PUT plugin-br-pix-jd.indirects/delivery_concurrency     '{"value":8}'
PUT plugin-br-pix-jd.indirects/delivery_max_attempts    '{"value":8}'
PUT plugin-br-pix-jd.indirects/resolution_cache_ttl_sec '{"value":30}'
PUT plugin-br-pix-jd.indirects/validate_ispb_on_jd      '{"value":false}'
```

The plugin answers `204` when it accepts a value and `400` when the validator refuses it. Booleans and integers go without quotes. A value outside the range answers `400`. The plugin does not clamp it.

> [!NOTE]
>
> The two steps that can stop the indirect flow on their own are not in this namespace. Identity is the systemplane key `tenancy/jd_integration_binding`. Without it, every payment fails with `409 PIX-0092`. The encryption key comes from a deployment variable or a secret store. Without it, every registration fails with `409 PIX-0107`.


# Multi-organization and ledgers
Source: https://docs.lerian.studio/en/interfaces/pix-jd/multi-organization-and-ledgers

Run several direct participants and several books on one Pix Direct via JD deployment: what the organization catalog is, why an economic group needs it, how to activate it as a feature toggle, and how money routes once it is on.

A fresh deployment of this rail posts every Pix movement into **one** Midaz organization and **one** ledger: the pair that its binding names. That pair is the default. One deployment can also serve an **economic group**. For example, a holding can operate a payment institution, a credit fintech, and a bank. Each regulated institution keeps its own organization, and each organization keeps as many ledgers as it needs.

The whole feature is a toggle in a single systemplane key. While that key is empty, the rail behaves exactly as it did before the key existed. A deployment that is one institution with one book does not need this page. For that deployment, [Setting up the rail](/en/interfaces/pix-jd/pix-jd-setup) is enough.

## One roof, several cabinets, several drawers

***

Think of the deployment as a back office with a wall of filing cabinets. Each **cabinet** belongs to one regulated institution. Its files never mix with the files of another institution, because a regulator audits each institution separately.

Inside a cabinet, **drawers** separate lines of business: one for the wallet product, one for the credit product. On the wall hangs an **index card** that lists the cabinets and drawers. A clerk files money movements only into a drawer on the index. The clerk hands back a movement for a drawer that is not on the index, and never files it in a "close enough" drawer.

The rail's vocabulary maps one to one:

| In the analogy | On the rail | What it is |
| - | - | - |
| the back office | the tenant | one deployment, one economic group. It holds the database and the Midaz connection for everyone under the roof |
| a cabinet | a Midaz **organization** | exactly one direct participant: one ISPB, the 8-digit identity from the Banco Central. One organization is one regulated institution, never two |
| a drawer | a **ledger** | one book of that institution. An organization holds one or many, for example one per product, or one per wallet family |
| the index card | the **organization catalog** | the systemplane key `tenant_policy/organizations`. It declares every *additional* participant and book that this tenant posts for |

Two results come from the model:

* **Every posting carries its scope.** The rail writes each transaction into the organization and ledger that it resolved to. Each institution's records are therefore complete on their own. Regulatory and accounting reports come out per institution, with no shared book to separate.
* **The rail never guesses a scope.** It checks a movement's organization and ledger against the catalog. If it cannot prove them, it refuses the movement before any posting. The design exists to make it impossible for money to land in the ledger of the wrong institution.

## The toggle: an empty key means off

***

The catalog key starts empty, and empty means **not provisioned**. The tenant then posts only into the organization and ledger that its binding names, as before the key existed. A catalog write turns the feature on. The pair that the binding names stays the **default**: the scope of every flow that does not resolve another one.

> [!NOTE]
>
> The default organization and ledger are **never** in the catalog. Their accounting routes stay in the `routing.*` keys, and their asset and clearing account stay in the `midaz.*` keys. [Setting up the rail](/en/interfaces/pix-jd/pix-jd-setup) shows how to provision them. The catalog declares only what the binding does not. A copy of the default ledger in the catalog would give one book two sources of truth, so the rail refuses that catalog.

**The deployment sets how far the toggle reaches.** A self-hosted deployment is one direct participant. Its catalog can add **ledgers** of its own organization: more books of the same institution. An entry carrying any other ISPB is refused at read time, because a self-hosted deployment holds one JD credential and cannot authenticate as a second institution. To act as **several participants**, with several ISPBs under one roof, talk to Lerian about Lerian Cloud, where each additional participant gets a JD credential of its own.

## Activate it, step by step

***

**1. Complete the ordinary setup first**

The catalog extends a working deployment. It does not replace the setup. Run [Setting up the rail](/en/interfaces/pix-jd/pix-jd-setup) from start to end. The binding that you write there makes your institution the **default** participant and its ledger the default book. If your deployment is one institution with one book, stop there. While the catalog key is empty, nothing on this page changes anything.

**2. Provision the additional book in Midaz and the CRM**

Provision each additional ledger with the same steps as the setup page, on the new book:

1. **The organization and the ledger.** An additional ledger of your own institution goes under your existing organization. An additional *participant* gets its own organization, because each Midaz organization holds exactly one regulated institution.
2. **The asset and the accounts** on the new ledger, with its own external clearing account. An alias such as `@external/BRL` is unique within a ledger, so each book needs its own.
3. **The operation routes** on the new ledger: one credit-and-debit pair for each money profile of the book. These UUIDs do not go into the `routing.*` keys. They go inside the catalog document in the next step.
4. **The holder records and aliases in the CRM**, with the `X-Organization-Id` of the organization that owns the book. The alias's `ledgerId` tells the rail which book an account banks in. On an organization with more than one ledger, every alias must name its ledger.

**3. Write the catalog**

Write the catalog with one call to `PUT /system/tenant_policy/organizations`. The wrapper is the same as for the binding. The body is `{"value": ...}`, and `value` is a **string** whose content is a JSON document. The document is a list with one entry per catalog **organization**. Each entry names its participant's ISPB, its Midaz organization, and that organization's ledgers with their routes.

Your own organization is in the catalog only when it has additional ledgers, and never with the default ledger. An additional participant's organization is always in it.

This is the document, unwrapped, with placeholder identifiers:

```json theme={null}
[
  {
    "ispb": "12345678",
    "organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "ledgers": [
      {
        "ledgerId": "9c858901-8a57-4791-81fe-4a34d4dd8ab5",
        "externalAlias": "@external/BRL",
        "asset": "BRL",
        "routes": {
          "in":       { "operationDebitRoute": "1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a01", "operationCreditRoute": "1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a02" },
          "inQrCode": { "operationDebitRoute": "1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a03", "operationCreditRoute": "1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a04" },
          "out":      { "operationDebitRoute": "1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a05", "operationCreditRoute": "1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a06" }
        }
      }
    ]
  }
]
```

On a **self-hosted** deployment, the entry has your own ISPB and your own organization id, and the ledgers are the additional books.

Each profile is a pair of Midaz operation route UUIDs.

Only `in` and `inQrCode` are mandatory, because every catalog ledger exists to receive. A book that cannot serve either inbound leg shows a provisioning mistake. The other nine are optional. Without `refundSent`, a devolução that you send posts on `out`. Any other flow that needs an absent profile refuses with `409 PIX-0105`, and the response names the profile, the organization, and the ledger. An unset `routing.*` key on the default book behaves the same way.

Two fields are optional:

* **`transactionRoute`**, inside a profile: the UUID of the Midaz transaction route that this ledger's postings of the profile name. Set it when the ledger validates routes. Without it, such a ledger refuses the posting. Without the field, the posting carries no transaction route.
* **`sharedIspbGate`**, on an entry: `true` declares that this participant shares its ISPB with another core. Its on-us transfers then ask the Courier ownership map first. The default organization declares the same fact with the key `tenant_policy/onus.shared_ispb_gate_enabled`. See [Courier ownership map](/en/interfaces/pix-jd/pix-jd-environment-variables#courier-ownership-map).

Let `jq` do the string escaping, as with the binding:

```bash theme={null}
# CATALOG_DOCUMENT holds the JSON document above, with your own identifiers.
CATALOG_DOCUMENT='[{"ispb":"12345678","organizationId":"...","ledgers":[...]}]'

curl -s -o /dev/null -w '%{http_code}\n' -X PUT \
  -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \
  -d "$(jq -nc --arg document "$CATALOG_DOCUMENT" '{value:$document}')" \
  "$PIX_JD_BASE_URL/system/tenant_policy/organizations"
```

A successful write answers `204`. Read the key back as you read the binding back. The value comes back as a quoted string with your document:

```bash theme={null}
curl -s -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" \
  "$PIX_JD_BASE_URL/system/tenant_policy/organizations" | jq
```

The key reloads without a restart. Write it while the app runs, and the running deployment uses it, with no restart and no redeploy.

**4. Know what the validators refuse, and when**

The rail checks the catalog two times. The write validator catches every error that the document alone shows. The admin surface therefore refuses a malformed catalog before any payment finds it.

**The write refuses these values**, with `400 validation_error`:

* a `value` other than a string, or anything after the first JSON document.
* an unknown field at any depth. A mistyped route-profile name is an unknown field too, so a typo cannot pass as an absent profile.
* an `ispb` that is not exactly 8 digits.
* an `organizationId`, `ledgerId`, route leg, or `transactionRoute` that is not a non-zero UUID.
* an empty `externalAlias` or `asset`, a route pair without one of its legs, or an organization without a ledger.
* a ledger without the `in` or the `inQrCode` profile.
* the same `ispb`, `organizationId`, or `ledgerId` two times anywhere in the document.

A `403` means a missing permission, never a refused value.

**The read refuses other cases**, because only the running rail knows your binding and mode. The refusals come on the money path, before any posting:

| The rail answers | When |
| - | - |
| `500 PIX-0125` | the catalog contradicts the binding, or the stored document no longer parses. Examples: it repeats the default ledger, puts your own ISPB under another organization, gives your organization to another participant, or names a foreign ISPB on a self-hosted deployment. Only an operator can fix it, so the rail refuses the payment and does not misfile it |
| `503 PIX-0122` | the rail could not **read** the catalog. Nothing is known to be wrong with it, so the refusal is retryable and clears on its own |
| `500 PIX-0120` | the catalog is valid, but this movement resolved to a scope that it does not declare. One example is an account record with no usable ledger on an organization that has several |

**5. Understand how money routes once it is on**

* **Every transaction goes into its scope.** The posting carries the organization and ledger that it resolved to. Each institution's book therefore stays complete and auditable on its own.
* **An inbound credit finds its own book.** The receiver ISPB picks the organization. The account's CRM record picks the ledger. An organization with a single ledger accepts a record that names no ledger, because it has no choice to make. An organization with several ledgers refuses that record with `500 PIX-0120` and does not guess.
* **An outbound order names the paying participant when the tenant is several.** `POST /v1/transactions` takes an optional `payerIspb`. A tenant that acts as one participant omits it. A tenant that acts as several must send it. Without it, the order answers `422 PIX-0127`. An ISPB that the tenant does not act as answers `422 PIX-0128`. An arbitrary payer could debit the customer of another institution.
* **Between two ledgers of the same organization, the transfer is internal.** An alias is unique within a ledger, so one posting cannot hold both legs. The rail reserves the amount on the payer's ledger against its clearing account. It then posts the credit on the payee's ledger against *that* ledger's clearing account. Last, it commits the reserve. Both legs use each ledger's own `intraPsp` route pair, and each book stays double-entry on its own.
* **Between two organizations of the same tenant, the payment is ordinary Pix.** Two organizations mean two regulated participants. The money therefore goes over the settlement rail (SPI), as a payment to any other institution does. The same tenant is never "the same book".
* **Each additional participant authenticates as itself.** Orders that leave an additional organization are sent to JD under that participant's own credential, provisioned per ISPB. A participant whose credential is not provisioned refuses its first order with `409 PIX-0092` and releases the hold, and the readiness probe reports it down naming that ISPB before traffic reaches it.

## Turning it off

***

You can write an empty string back to `tenant_policy/organizations`. The tenant then goes back to the default-only behavior, as before activation. This does not undo anything already booked. Money posted in an additional scope stays in that ledger, and this rail can no longer reach it. A flow that resolves to a scope that the catalog no longer declares refuses with `500 PIX-0120` before it touches the ledger.

So empty the key only when nothing routes to the additional books. That means no accounts whose records point at them, no payments in flight, and no hosted participant on an additional organization. To retire one book and keep the feature, remove that ledger's entry and keep the rest of the catalog. The same read-time proof applies, scope by scope.

## Where to go next

***

> **[Setting up the rail](/en/interfaces/pix-jd/pix-jd-setup)**
>
> The provisioning chain that this page extends: the ledger objects, the CRM records, the routing keys, and the binding that names the default pair.

> **[The direct and indirect model](/en/interfaces/pix-jd/direct-and-indirect-model)**
>
> How this axis differs from hosting indirect participants. An indirect is a position inside your book. An additional organization is a direct participant with books of its own.

> **[Environment variables](/en/interfaces/pix-jd/pix-jd-environment-variables)**
>
> The deploy-time configuration, and the values that live in systemplane keys instead.

> **[Pix JD error list](/en/reference/interfaces/pix-jd/pix-jd-error-list)**
>
> Every `PIX-NNNN` code that this page names, with its status and the `detail` text of the response.


# Payment-order signing
Source: https://docs.lerian.studio/en/interfaces/pix-jd/payment-order-signing

Configure the Pix plugin to sign outbound payment orders when JD requires a signed payment order: create the key and the certificate, register the certificate in JDPI Cabine, check the files, configure the plugin, confirm, and replace the key.

This page sets up payment-order signing in the Pix plugin (the rail). It is optional. You need it only if payment-order signature is enabled for your institution at JD, as defined in JD's JDPI manual (security mechanisms). Confirm this with JD. Without the signing values, nothing changes.

## Set up signing

**1. Create the key and the certificate**

Choose the algorithm. Use the default unless you have a reason to change it.

| Algorithm | Key |
| - | - |
| `ECDSA_P256_SHA256` (default) | ECDSA on the P-256 curve |
| `ECDSA_P384_SHA384` | ECDSA on the P-384 curve |
| `RSA_PKCS1_SHA256` | RSA, 3072 bits or more |

Each direct participant signs its payment orders with its own key pair. The Pix plugin signs every payment order sent through your JD connection, including those of the indirect participants you host. A self-signed certificate is accepted. Run the block for your algorithm. Each block writes the private key to `payment-signing.key` and the certificate to `payment-signing.crt`.

**ECDSA P-256 (default)**

```bash theme={null}
openssl ecparam -name prime256v1 -genkey -noout \
  | openssl pkcs8 -topk8 -nocrypt -out payment-signing.key
openssl req -new -x509 -key payment-signing.key -sha256 -days 730 \
  -subj "/CN=Example Institution Pix payment signing" -out payment-signing.crt
```

**ECDSA P-384**

```bash theme={null}
openssl ecparam -name secp384r1 -genkey -noout \
  | openssl pkcs8 -topk8 -nocrypt -out payment-signing.key
openssl req -new -x509 -key payment-signing.key -sha384 -days 730 \
  -subj "/CN=Example Institution Pix payment signing" -out payment-signing.crt
```

**RSA 3072**

```bash theme={null}
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out payment-signing.key
openssl req -new -x509 -key payment-signing.key -sha256 -days 730 \
  -subj "/CN=Example Institution Pix payment signing" -out payment-signing.crt
```

The rail reads a private key in PKCS#8, SEC 1, or PKCS#1 format. The commands above write PKCS#8. The key type must agree with the algorithm.

Before you register the certificate, make sure that the private key is the key of the certificate:

```bash theme={null}
key_pub=$(openssl pkey -in payment-signing.key -pubout) \
  && cert_pub=$(openssl x509 -in payment-signing.crt -noout -pubkey) \
  && [ -n "$key_pub" ] && [ "$key_pub" = "$cert_pub" ] \
  && echo "the key matches the certificate" \
  || echo "the key does NOT match the certificate"
```

If the output is `the key does NOT match the certificate`, the key and the certificate do not agree, or a file cannot be read. Create the pair again. The rail refuses a pair that does not agree with `409 PIX-0136`, before it calls JD.

**2. Register the certificate at JD**

The Pix plugin signs each payment order. For JD to accept it, JD must know your certificate: register it in JDPI Cabine. Upload only the certificate, which is public.

1. In JDPI Cabine, open **Gestão de Certificados**.
2. Click **Incluir**.
3. In **Tipo Certificado**, select **Certificados Hash – Assinatura Payload**.
4. Upload `payment-signing.crt`.
5. Write down the thumbprint that JDPI Cabine shows for the certificate.

Give the Pix plugin the same certificate in step 4. More than one certificate can be active at the same time, which lets you replace a key with no interruption. See [Replace the key](#replace-the-key).

**3. Check the thumbprint**

Make sure that the certificate that you give to the rail is the one registered in JDPI Cabine. Calculate its thumbprint:

```bash theme={null}
openssl x509 -in payment-signing.crt -noout -fingerprint -sha1
```

The output has the form `sha1 Fingerprint=40:C0:3F:...`. Remove the colons. The result must be the same as the thumbprint in JDPI Cabine. To get the value without colons directly:

```bash theme={null}
openssl x509 -in payment-signing.crt -outform DER | openssl dgst -sha1 -r | cut -d' ' -f1 | tr a-f A-F
```

**4. Configure the Pix plugin**

The configuration has three values. Set the key and the certificate together, or neither. With only one of them, the rail refuses each payment to another institution with `409 PIX-0136`. A PEM value can have real line breaks, or be on one line with a literal `\n` at each line break.

**Self-hosted (single-tenant)**

Set the three environment variables on the API. All three are optional. The worker does not send payment orders, so it does not need them.

| Variable | Required | Default | Description |
| - | - | - | - |
| `JD_PAYMENT_SIGNING_PRIVATE_KEY` | Optional. Set it together with the certificate | — | PEM of the private key. A secret. |
| `JD_PAYMENT_SIGNING_CERTIFICATE` | Optional. Set it together with the key | — | PEM of the certificate registered in JDPI Cabine for that key. |
| `JD_PAYMENT_SIGNING_ALGORITHM` | Optional | `ECDSA_P256_SHA256` | `ECDSA_P256_SHA256`, `ECDSA_P384_SHA384`, or `RSA_PKCS1_SHA256`. |

Keep the private key in a secret, never in plain configuration.

The values take effect when the API starts.

**Lerian-hosted**

Give Lerian the same three values during setup: the private key, the certificate that you registered in JDPI Cabine, and the algorithm if it is not `ECDSA_P256_SHA256`. Lerian applies them when it provisions the service for your tenant. You do not deploy or restart anything.

Send the private key only through the secure channel that Lerian gives you for credentials during setup.

**5. Confirm that it works**

Send a Pix to another institution. Make sure that it settles. If the payment is refused or ends in `ERROR`, see [If something fails](#if-something-fails).

## If something fails

| What you see | Cause | What to do |
| - | - | - |
| `409 PIX-0136` | A signing value is missing or not usable. For example: only the key or only the certificate is set, the algorithm is not one of the three, the key does not agree with the algorithm, or the certificate is not the certificate of the key. | Read the message. It names the value to correct. |
| The transaction ends in `ERROR` with `JDPISPI017`, or the API answers `422 PIX-1035` | JD did not accept the signature. | Calculate the thumbprint of the configured certificate and compare it with the certificates in JDPI Cabine. A difference means that the rail signs with a certificate that JD does not know. If signing is not configured, configure it. |
| The transaction ends in `ERROR` with `JDPISPI018`, or the API answers `422 PIX-1035` | JD blocks the debits of your institution after repeated signature failures. | Correct the cause of `JDPISPI017` first. More orders do not end the block sooner. |

In each case, the rail releases the amount that it reserved, and no money moves. The rail does not send the refused order again. `409 PIX-0136` refuses only payment orders. The other JD calls, such as DICT and QR codes, continue to work.

## Replace the key

JDPI Cabine accepts more than one active certificate. Replace the key in this sequence, so that no order goes out with a certificate that JD does not know:

1. Create a new key and a new certificate.
2. Register the new certificate in JDPI Cabine. Keep the old certificate active.
3. Give the new key and the new certificate to the rail. On a Lerian-hosted deployment, give them to Lerian.
4. Wait until the change takes effect. On a self-hosted deployment, restart every running API instance, so none keeps signing with the old key. On a Lerian-hosted deployment, wait until Lerian confirms the change.
5. Send a Pix to another institution. Make sure that it settles.
6. Wait until every Pix sent before the change has a final status.
7. Delete the old certificate from JDPI Cabine.

## Related pages

* [Environment variables](/en/interfaces/pix-jd/pix-jd-environment-variables)
* [Setting up the rail](/en/interfaces/pix-jd/pix-jd-setup)
* To deploy the plugin, see the [plugin-br-pix-jd chart README](https://github.com/LerianStudio/helm/tree/main/charts/plugin-br-pix-jd).


# Environment variables
Source: https://docs.lerian.studio/en/interfaces/pix-jd/pix-jd-environment-variables

Configure the Pix Direct via JD rail: JD OAuth and JDPI endpoints, JDPI timeouts, dynamic QR code hosting with JWS, the Midaz and CRM connections, the Courier ownership map and claims, the permission declaration, and the values that live in the systemplane instead.

Pix Direct via JD connects your ledger straight to the Pix arrangement through JD's DICT and SPI gateway. DevOps sets its behavior through environment variables at deploy time. To change a variable, restart the service. This page covers the variables **distinctive to this rail**. For the datastore, streaming, telemetry, and authentication knobs that every Lerian Go service shares, see [BYOC configuration essentials](/en/reference/byoc-configuration).

> [!NOTE]
>
> These variables describe a **BYOC deployment**. On Lerian Cloud, you do not set them.

> [!NOTE]
>
> In the tables below, the **Default / Required** column shows the default value. A bold qualifier (for example **Required**) marks variables you must set. `—` means no default. `🔒` marks a **secret**. Inject it at deploy time from your secret store, and never commit it. This page lists variable names and behavior only. It prints no secret values.

## Server and port

The service listens on the address in `SERVER_ADDRESS` (default `:8080`). The liveness, readiness, and version probes bind this same port. See [Server](/en/reference/byoc-configuration#server) for the shared server knobs and [Default network ports](/en/reference/default-network-ports).

## Connections without TLS

| Variable | Default / Required | Description |
| - | - | - |
| `ALLOW_INSECURE_TLS` | `false` | Set `true` to let the rail use `http://` addresses, in every environment. It covers `MIDAZ_URL_TRANSACTION`, `PLUGIN_AUTH_HOST` for the outbound tokens, `COURIER_URL`, and the `delivery.endpointUrl` of each indirect participant. In multi-tenant mode, it also covers the Tenant Manager and the JD and JD Courier addresses of each tenant. For its effect on the datastores, see [BYOC configuration essentials](/en/reference/byoc-configuration). |

> [!WARNING]
>
> With `true`, Pix JD accepts `http://` addresses for these connections in every environment, production included. Traffic on an `http://` connection is not encrypted, and it carries credentials or Pix data. Pix JD logs a warning at startup when the value is `true`. Keep the value `false` when every connection serves https.

## JD integration

Credentials, endpoints, retries, and time limits for JD's OAuth-secured API and its Pix (JDPI) surface.

| Variable | Default / Required | Description |
| - | - | - |
| `JD_BASE_URL` | **Required** | Base URL of the JD API. |
| `JD_CLIENT_ID` | **Required** | OAuth client ID for the JD API. |
| `JD_SECRET` | 🔒 **Required** | OAuth client secret for the JD API. |
| `JD_GRANT_TYPE` | `client_credentials` | OAuth grant type used against JD. |
| `JD_USE_SERVICE_SEGMENTS` | `false` | How the rail builds JD addresses. Set `true` when JD gives you a gateway address, where each JD service has its own path segment after `JD_BASE_URL`. Keep `false` when JD gives you the direct address, where every path starts with `<JD_BASE_URL>/jdpi/`. Ask JD which address type you have. |
| `JDPI_MAX_RETRIES` | `2` | Retry attempts on a failed JDPI call. |
| `JDPI_RETRY_BASE_DELAY_MS` | `100` | Base backoff delay in milliseconds between JDPI retries. |
| `JDPI_CALL_TIMEOUT_MS` | `30000` | Time limit of one JDPI HTTP attempt, in milliseconds. |
| `JDPI_TOTAL_TIMEOUT_MS` | `50000` | Time limit of one whole JDPI call from the API, in milliseconds: the token, every attempt, and every wait between attempts. |

The two timeouts apply in both deployment modes. A value of `0` or less gives the default. Keep `JDPI_TOTAL_TIMEOUT_MS` below the timeout of your ingress. Then, on a client request, a JD that does not answer gets `504 PIX-1051` from the rail, not a timeout from the proxy.

> [!WARNING]
>
> **Your own ISPB is not an environment variable.** It comes from the systemplane key `tenancy/jd_integration_binding`, field `ispb`. There is no environment fallback.
>
> While that key is empty, the rail starts and answers its health probe. It refuses **every** payment on **every** money route with `409 PIX-0092`. Write the key and the next request passes, with no restart. For the steps, see [Setting up the rail](/en/interfaces/pix-jd/pix-jd-setup).

## Payment-order signing

The key that signs each outbound payment order. They are optional: you need them only when your JD environment requires signed orders. The API reads these variables. The worker does not.

| Variable | Default / Required | Description |
| - | - | - |
| `JD_PAYMENT_SIGNING_PRIVATE_KEY` | 🔒 — | PEM of the private key that signs the payment order. |
| `JD_PAYMENT_SIGNING_CERTIFICATE` | — | PEM of the certificate registered in JDPI Cabine for that key. |
| `JD_PAYMENT_SIGNING_ALGORITHM` | `ECDSA_P256_SHA256` | `ECDSA_P256_SHA256`, `ECDSA_P384_SHA384`, or `RSA_PKCS1_SHA256`. |

Leave all three empty and the rail sends unsigned orders. Set only some of them, or a value that is not usable, and the rail refuses each payment to another institution with `409 PIX-0136` before it calls JD. For the key, the certificate, and JDPI Cabine, see [Payment-order signing](/en/interfaces/pix-jd/payment-order-signing).

## Dynamic QR code hosting

The rail hosts signed (JWS) dynamic-QR payloads and the JWK set that verifies them. It serves those documents under the host in `QRCODE_PUBLIC_BASE_URL`. The [QR codes reference section](/en/reference/interfaces/pix-jd/create-dynamic-qr-code) gives the public route shapes, the host form without a scheme, and the 77-character payload-URL limit from BACEN. The variables below set the parts that this deployment controls.

| Variable | Default / Required | Description |
| - | - | - |
| `QRCODE_PUBLIC_BASE_URL` | **Required** | Host (FQDN) without a scheme, where the plugin serves dynamic-QR payloads and the JWK set. |
| `QRCODE_PAYLOAD_PATH` | `qr` | Path segment where the plugin serves signed QR payloads. Each extra character uses the same 77-character limit as the host. |
| `QRCODE_JWK_PATH` | `v1/qrcodes/jwks` | Path segment where the plugin serves the JWK set. |
| `QRCODE_JWS_CONTENT_TYPE` | `application/jose` | `Content-Type` of the signed payload. |
| `QRCODE_JWKS_CONTENT_TYPE` | `application/jwk-set+json` | `Content-Type` of the JWK set. |

> [!WARNING]
>
> Do not change `QRCODE_PAYLOAD_PATH` after go-live. A printed or displayed QR code carries the old URL, and nothing redirects it.

## Midaz ledger connection

The ledger service endpoints and the machine-to-machine credentials.

| Variable | Default / Required | Description |
| - | - | - |
| `MIDAZ_URL_TRANSACTION` | **Required** | Midaz transaction service URL. |
| `MIDAZ_CLIENT_ID` | — | OAuth client ID for Midaz M2M. |
| `MIDAZ_CLIENT_SECRET` | 🔒 — | OAuth client secret for Midaz M2M. |
| `MIDAZ_TIMEOUT` | `30000` | Midaz request timeout in milliseconds. |
| `MIDAZ_FEE_MODE` | `auto` | The Midaz transaction API that the rail posts on. `auto` reads the ledger version and uses the API that applies Midaz fees when the ledger has it (Midaz 4.1 or later). `legacy` always uses the earlier API. `native` always uses the API that applies fees. Any other value stops the startup. |
| `MIDAZ_FEE_MODE_REFRESH` | `5m` | How often `auto` reads the ledger version again, as a Go duration. A failed read keeps the last mode. |

> [!NOTE]
>
> There is no separate Access Manager address for Midaz. The rail mints its outbound Midaz token against the same Access Manager it validates inbound bearers with, `PLUGIN_AUTH_HOST`. See [BYOC configuration essentials](/en/reference/byoc-configuration).

**The ledger identity is not an environment variable.** Four values tell the rail where it posts. All four come from the systemplane, in both deployment modes:

| Value | Systemplane source |
| - | - |
| the Midaz organization | `tenancy/jd_integration_binding`, field `organizationId` |
| the Midaz ledger | `tenancy/jd_integration_binding`, field `ledgerId` |
| the posting asset, as its code (for example `BRL`) | `tenant_policy/midaz.asset_id` |
| the external clearing account, as its alias (for example `@external/BRL`) | `tenant_policy/midaz.external_id` |

The two `tenant_policy` keys start empty. Until you write both of them, the rail refuses every posting, refund, and inbound credit with `409 PIX-0106`. For the steps, see [Setting up the rail](/en/interfaces/pix-jd/pix-jd-setup).

> [!WARNING]
>
> The rail no longer reads `MIDAZ_ORGANIZATION_ID`, `MIDAZ_LEDGER_ID`, `MIDAZ_ASSET_ID`, and `MIDAZ_EXTERNAL_ID`. A value left in one of them gives one startup warning and has no effect.

## Accounting routes

The rail books each Pix flow onto a pair of Midaz operation routes, one credit leg and one debit leg. The route identifiers are **not** environment variables. They live in the systemplane keys `tenant_policy/routing.<profile>.operation_credit_route` and `tenant_policy/routing.<profile>.operation_debit_route`. There is no environment fallback.

Each profile also has an optional transaction-route key, `tenant_policy/routing.<profile>.transaction_route`. The rail sends its value as the route of every posting of that profile. A Midaz ledger that validates routes refuses a posting without one. The rail then answers `PIX-4011`. When the key is empty, the posting carries no transaction route.

> [!WARNING]
>
> The `TRANSACTION_ROUTE_*` and `OPERATION_ROUTE_*` variables no longer exist. A leftover value gives one startup warning and has no effect. A missing leg of one of the six payment profiles refuses every payment flow with `409 PIX-0105`. A missing MED or Pix Automático leg refuses only that flow. When one flow fails and the others work, look here first.

For the profiles, the exact key names, and how to write them, see [Setting up the rail](/en/interfaces/pix-jd/pix-jd-setup).

## Jobs

| Variable | Default / Required | Description |
| - | - | - |
| `JOBS_CRON` | `*/10 * * * * *` | Cron expression that sets how often the worker runs its periodic jobs. |
| `JOBS_RECONCILE_STUCK_THRESHOLD_SEC` | `80` | Age in seconds after which the rail reports a pending cash-out as stuck. |

> [!NOTE]
>
> The daily window for transaction limits is **not** an environment variable. It lives in the systemplane keys `tenant_policy/transaction_limits.daily_period_init` and `tenant_policy/transaction_limits.daily_period_end`, in both deployment modes. Each key takes a clock hour from 0 to 23. The rail ignores the old `TRANSACTION_LIMIT_DAILY_PERIOD_INIT` and `TRANSACTION_LIMIT_DAILY_PERIOD_END` variables.

## Pix Automático

JD's Pix Automático has two optional steps that stay off until your institution turns them on. The debit itself always runs.

| Variable | Default / Required | Description |
| - | - | - |
| `PIX_AUTOMATICO_BLOQUEAR_ENABLED` | `false` | Set `true` to accept the hold (bloqueio) that JD places on the payer's balance before a Pix Automático debit. |
| `PIX_AUTOMATICO_ESTORNO_ENABLED` | `false` | Set `true` to accept the reversal (estorno) of a Pix Automático debit. |

Turn each one on only after your institution agrees with JD to use that step. The rail reads both at startup, so a change needs a restart.

## Notifications

Optional end-customer notifications for Pix events. Leave the provider blocks unset to disable that channel.

| Variable | Default / Required | Description |
| - | - | - |
| `SENDGRID_API_KEY` | 🔒 — | SendGrid API key for email notifications. |
| `SENDGRID_FROM_EMAIL` | — | Sender address for email notifications. |
| `SENDGRID_FROM_TEMPLATE` | — | SendGrid template ID for the message body. |
| `TWILIO_ACCOUNT_SID` | 🔒 — | Twilio account SID for SMS notifications. |
| `TWILIO_AUTH_TOKEN` | 🔒 — | Twilio auth token for SMS notifications. |
| `TWILIO_PHONE_NUMBER` | — | Sender phone number for SMS notifications. |

## CRM

| Variable | Default / Required | Description |
| - | - | - |
| `CRM_URL` | — | CRM service URL for counterparty lookups. |
| `CRM_CLIENT_ID` | — | OAuth client ID for CRM M2M. |
| `CRM_CLIENT_SECRET` | 🔒 — | OAuth client secret for CRM M2M. |

## Courier ownership map

Some institutions share one ISPB between two core systems. JD Courier keeps an ownership map that tells which core holds each account. The rail asks that map in one case only. The payee of an outbound Pix names the paying participant's own ISPB, and you declare that ISPB as shared.

| Variable | Default / Required | Description |
| - | - | - |
| `COURIER_URL` | — | Base URL of the Courier process that runs the `admin` role. Only that role answers the ownership lookup. |
| `COURIER_CLIENT_ID` | — | The Courier client ID. |
| `COURIER_CLIENT_SECRET` | 🔒 — | The Courier client secret. |

Pix JD exchanges `COURIER_CLIENT_ID` and `COURIER_CLIENT_SECRET` with Access Manager for a token, and sends that token on each call to JD Courier.

You declare a shared ISPB in the systemplane. The key `tenant_policy/onus.shared_ispb_gate_enabled` covers your default organization, and its default is `false`. An organization in the [organization catalog](/en/interfaces/pix-jd/multi-organization-and-ledgers) uses its `sharedIspbGate` field. While the declaration is `false`, the rail does not ask the map.

When the declaration is `true`, these refusals apply to an outbound Pix to an account at your own ISPB:

| Condition | Response |
| - | - |
| `COURIER_URL` is empty, or the Courier does not give an answer | `503 PIX-0130`. You can retry |
| The Courier answers, but the rail cannot use the answer. A Courier process in a role other than `admin` gives this result | `502 PIX-0131` |
| The payee's branch or account on record cannot form a lookup | `422 PIX-0132` |

The rail refuses before it reserves a balance, so a refusal moves no money.

Three systemplane keys set the time limits of the lookup. They apply in both deployment modes:

| Systemplane key | Default | Range | What it limits |
| - | - | - | - |
| `tenant_policy/courier.lookup.timeout_ms` | `2000` | 100–30000 | one attempt, in milliseconds |
| `tenant_policy/courier.lookup.max_retries` | `1` | 0–3 | the retries after the first attempt |
| `tenant_policy/courier.lookup.total_budget_ms` | `4500` | 100–60000 | all attempts and the waits between them, in milliseconds |

### Claims on the Courier

See [Connecting an engine](/en/interfaces/jd-courier/jd-courier-engine-integration).

When the Courier is configured, the worker claims on the Courier the Pix Automático recurrences that the rail accepted as the payer's institution. It sends up to 100 claims on each pass. When a claim fails, the worker sends it again on a later pass. The worker does not send again a claim that the Courier refuses with a conflict. The worker reads the Courier settings from the same place as the API.

Before the Courier starts to receive your Pix, call [the Courier ownership route](/en/reference/interfaces/pix-jd/tell-the-jd-courier-which-pix-automatico-traffic-is-this-engine-s) (`POST /v1/pix-automatico/courier-ownership`). It claims the recurrences that already exist, and it declares the debit blocks and the schedules of the payments in progress. Call it again after the Courier starts to receive your Pix, to declare the legs that opened between the two calls. The route also claims again the recurrences that the Courier refused before.

`heldElsewhere` in the answer lists the keys that the Courier refused with a conflict. An operator resolves each one.

## Indirect participants

Only relevant if this deployment settles Pix on behalf of other institutions.

| Variable | Default / Required | Description |
| - | - | - |
| `INDIRECTS_DELIVERY_ENCRYPTION_KEY` | 🔒 **Required** to host indirect participants | AES-256 key that encrypts each indirect participant's delivery secret at rest. Exactly 64 hex characters (32 bytes), from `openssl rand -hex 32`. No default. |

> [!WARNING]
>
> Without this key, **every** indirect-participant registration is refused with `409 PIX-0107`. The refusal comes before any write, so no plaintext secret is ever stored. An absent, blank, or malformed value all produce the same refusal: there is no default and no degradation to storing the secret in the clear. The `409` means "provision it", not "try again": its retryable sibling is `503 PIX-0123`, which is what a key that could not be **read** answers.
>
> The rail starts without it. Startup logs a warning and the process comes up healthy, so the symptom arrives on the first registration, not on deploy. Read at startup, so a change needs a restart.
>
> See [Hosting indirect participants](/en/interfaces/pix-jd/hosting-indirect-participants) for the onboarding that requires this key.

## Runtime configuration (systemplane)

This rail mounts the systemplane admin API on its main port. `SYSTEMPLANE_ENABLED` turns it on.

| Variable | Default / Required | Description |
| - | - | - |
| `SYSTEMPLANE_ENABLED` | `false` | Enable the systemplane runtime-configuration admin API. |

When you enable it, the service exposes an authenticated plane to read and write runtime configuration. See [Systemplane](/en/reference/platform/systemplane/overview) for the API, namespaces, and required permissions.

The rail reads several values **only** from that plane, in both deployment modes. A deployment that leaves them unset starts healthy and refuses money:

| Systemplane key | What it carries | Unset |
| - | - | - |
| `tenancy/jd_integration_binding` | your own ISPB and your default Midaz organization and ledger, as a JSON **string** | `409 PIX-0092` on every money route |
| `tenant_policy/midaz.asset_id`, `tenant_policy/midaz.external_id` | the posting asset and the external clearing account | `409 PIX-0106` on every posting |
| `tenant_policy/routing.<profile>.operation_{credit,debit}_route` | the accounting route legs | `409 PIX-0105` on every payment flow when a leg of the six payment profiles is missing, and on that flow only for MED and Pix Automático. A devolução that you send posts on `out` while `refund_sent` is empty |
| `tenant_policy/routing.<profile>.transaction_route` | the optional transaction route of each profile | `PIX-4011` only when the ledger validates routes |
| `tenant_policy/transaction_limits.daily_period_{init,end}` | the daily limit window | limit accounting has no window |
| `plugin-br-pix-jd.indirects/enabled` | whether this tenant hosts indirect participants | indirect resolution stays off |
| `tenant_policy/organizations` | the catalog of **additional** organizations and ledgers this tenant posts for, as a JSON **string** | the rail posts only into the default organization and ledger. See [Multi-organization and ledgers](/en/interfaces/pix-jd/multi-organization-and-ledgers) |

> [!NOTE]
>
> With `SYSTEMPLANE_ENABLED=false`, the service does not mount the `/system` route group. Every configuration write then answers `404`. A money path that cannot read its configuration answers the retryable `503 PIX-0051`, not a provisioning refusal. The write permission is `systemplane:write`. Without it, the writes answer `403`.

[Setting up the rail](/en/interfaces/pix-jd/pix-jd-setup) shows each of these keys, the exact body of each write, and how to confirm it.

## Permission declaration

At startup, the service can publish its permission declaration to the Access Manager.

| Variable | Default / Required | Description |
| - | - | - |
| `IDP_DECLARATION_ENABLED` | `false` | Set `true` to publish the permission declaration at startup. The declaration also publishes the Pix JD scope catalog with the partner opt-in. Until Pix JD publishes a scope catalog, you cannot give a [partner](/en/platform/access-manager/features/partners/overview) permissions on Pix JD. |
| `IDP_HOST` | — | Absolute `http` or `https` URL of the Access Manager Identity service. |
| `IDP_M2M_CLIENT_ID` | — | The client ID that the service publishes with. |
| `IDP_M2M_CLIENT_SECRET` | 🔒 — | The client secret that the service publishes with. |

With `IDP_DECLARATION_ENABLED=true`, the service does not start when one of the other three variables is empty, when `IDP_HOST` is not valid, or when `PLUGIN_AUTH_ENABLED` is not `true`. When the Access Manager refuses the publication or does not answer, the service still starts.

## Upgrade from an earlier version

Do the steps for each version that you pass on the way to the version that you install.

**To 1.2.1.** The rail no longer reads `MULTI_TENANT_ALLOW_INSECURE_HTTP`. In multi-tenant mode with an `http://` Tenant Manager, set `ALLOW_INSECURE_TLS=true` on the API and on the worker before the upgrade. Otherwise the service does not start. If your deployment already sets `ALLOW_INSECURE_TLS=true`, Pix JD 1.2.1 and later also accept `http://` addresses for the connections in [Connections without TLS](#connections-without-tls), in every environment.

**To 1.2.0.** On a self-hosted deployment, before the upgrade, make sure that the Pix roles in the Access Manager have the permission `courier-ownership` (action `post`), and give the application that `COURIER_CLIENT_ID` names the `ownership:write` permission in JD Courier. The Courier ownership route of this version needs `courier-ownership`, and it answers `403` without it. On a single-tenant deployment, also set the `CRM_*` variables, and with JD Courier the `COURIER_*` variables, on the worker. See [Claims on the Courier](#claims-on-the-courier).

**To 1.1.1.** No step is required. The three payment-order signing variables are new and optional. Set them only if JD requires signed payment orders for your institution. See [Payment-order signing](/en/interfaces/pix-jd/payment-order-signing).

**To 1.1.0.** Before the upgrade, make sure that the Pix roles in the Access Manager have the permission `entries-lookup` (action `get`). The key lookup route of this version needs it, and it answers `403` without it.

**To 1.0.0, from the earlier Pix plugin.**

1. Before the upgrade, write `tenant_policy/midaz.asset_id` and `tenant_policy/midaz.external_id`. Use the values from `MIDAZ_ASSET_ID` and `MIDAZ_EXTERNAL_ID`. Without them, the upgraded rail refuses every posting with `409 PIX-0106`.
2. Read `tenancy/jd_integration_binding` back. Make sure that `organizationId` and `ledgerId` name the organization and the ledger that this deployment posts into. The rail reads them on every call.
3. Before you upgrade, set `MIDAZ_FEE_MODE=legacy` on the API and on the worker. The default is `auto`. Change the value to `auto` only after both of these are true:

   * No pod of the earlier release serves any tenant.
   * You reviewed your fee packages. A fee package with no transaction route can charge a fee on every Pix flow.

   Add a `refundSent` entry to the organization catalog only after no pod of the earlier release serves the tenant.
4. With event streaming on, the service does not start while its outbox holds undelivered events in an earlier event format. Deliver those events with the build that wrote them before you upgrade.
5. After the upgrade, remove the four `MIDAZ_*` identity variables from your environment.

## Health and readiness

The rail exposes `GET /health` (liveness) and `GET /readyz` (readiness) on the main port, plus `/metrics` and `/version`. See [Health and readiness](/en/reference/health-and-readiness) for the response shape.


# Setting up the rail
Source: https://docs.lerian.studio/en/interfaces/pix-jd/pix-jd-setup

Set up Direct Pix via JD from zero on a running service, in the order you act: the prerequisites, payment-order signing, the Midaz ledger and CRM records, the accounting routes, the plugin settings, the payment that creates the limit rows, and the checks that prove each step landed.

A fresh Direct Pix via JD deployment starts, responds to its health probe, and refuses every payment. Nothing is broken. The rail needs a chain of objects before it can move money. Until they exist, it refuses the payment and does not guess.

This page gives that chain as one trail, in the order you act, for a service that is already installed and running, with the failure that each missing link causes. Lerian runs this setup with you during onboarding. Use the page to know what must exist, what each value means, and how to prove that it landed.

> [!NOTE]
>
> On Lerian Cloud, Lerian runs the service. You give Lerian the signing values of step 2, only if JD requires them. Every other step on this page is yours to run, because it creates your own books and your own settings.

> [!NOTE]
>
> The order is a dependency chain. Midaz refuses each link while the previous one does not exist. The limits step sends a payment, so it comes after the settings. Where a step can run in any order, the page says so.

## The trail

1. [Check the prerequisites](#step-1-check-the-prerequisites), and grant access to whoever runs the setup.
2. [Set up payment-order signing](#step-2-set-up-payment-order-signing-if-jd-requires-it), only if JD requires it for your institution.
3. [Provision the ledger and the holder records](#step-3-provision-the-ledger-and-the-holder-records) in Midaz and in the CRM.
4. [Create the accounting routes](#step-4-create-the-accounting-routes) in Midaz.
5. [Configure the rail](#step-5-configure-the-rail): the plugin settings.
6. [Send the payment that creates the limit rows](#step-6-create-the-transaction-limit-rows-with-one-small-payment).
7. [Prove the setup is complete](#step-7-prove-the-setup-is-complete), up to a registered Pix key.
8. [Add the optional capabilities](#step-8-add-the-optional-capabilities) that your institution needs.

## Step 1: Check the prerequisites

You talk to three services. Do not confuse them. That is the most common first mistake.

| Service | Address | Routes start with | Extra header |
| - | - | - | - |
| Ledger (Midaz) | `MIDAZ_URL_ONBOARDING`, `MIDAZ_URL_TRANSACTION` | `/v1/organizations/...` | — |
| CRM (account holders) | `CRM_URL` | `/v1/holders`, `/v1/aliases` | `X-Organization-Id` |
| The plugin's admin plane | the plugin's own address | `/system/...` | — |

You also need:

* The Pix plugin running. The plugin's settings API must be enabled (`SYSTEMPLANE_ENABLED=true`). Without it, every configuration call of step 5 answers `404`. On SaaS, Lerian enables it.
* On a self-hosted deployment, the permission of the key lookup route, `entries-lookup` (action `get`), on the Pix roles in the Access Manager. With JD Courier, also `courier-ownership` (action `post`), for the Courier ownership route. Without its permission, each route answers `403`.
* A bearer token for the ledger, one for the CRM, and one for the plugin, issued by the Access Manager. They can come from different audiences.
* The right access for whoever runs the setup. The [access step](#grant-access-to-whoever-runs-the-setup) below lists the groups. Without it, the calls answer `403`.
* Your institution's **ISPB**: the 8-digit identifier of your accreditation at BACEN.

The examples below use these shell variables. Where the rail already has a name for a value, the variable has that same name. Every UUID, document, and ISPB is a placeholder. Use the values from your own environment.

```bash theme={null}
# Addresses. MIDAZ_URL_TRANSACTION and CRM_URL are this rail's own deployment variables.
MIDAZ_URL_ONBOARDING="https://midaz-onboarding.example.com"
MIDAZ_URL_TRANSACTION="https://midaz-transaction.example.com"
CRM_URL="https://crm.example.com"
PIX_JD_BASE_URL="https://pix-jd.example.com"       # this deployment's own address

# Three different bearers. They are not interchangeable.
MIDAZ_BEARER_TOKEN="..."                           # for the ledger
CRM_BEARER_TOKEN="..."                             # for the CRM
PIX_JD_BEARER_TOKEN="..."                          # for the plugin, needs Plugin PIX JD Editor

MIDAZ_HEADERS=(-H "Authorization: Bearer $MIDAZ_BEARER_TOKEN"
               -H 'Content-Type: application/json')
```

> [!NOTE]
>
> Midaz has an onboarding surface and a transaction surface. When one address serves both, give the two variables the same value. The calls below follow the object that each one creates.

> [!WARNING]
>
> The CRM requires the `X-Organization-Id` header on every collection route. Without it, the CRM does not scope a query to your organization. You then get another record, or nothing at all.

### Grant access to whoever runs the setup

**Why this step exists.** Setting up Pix touches three products: the ledger (Midaz), the account holder records (CRM), and the Pix JD plugin itself. Each one checks its own permission. Without it, the call answers `403` and nothing is written.

**If you are an administrator, you already have everything.** The **Administrator** group (`admin-group`) has full access to the three products. Go on to the next step.

**To let someone else run the setup without being an administrator,** add that person to the groups below in the Access Manager, through the console or through [Update a User](/en/reference/platform/access-manager/update-user). This is the minimum access that covers every step on this page:

| Group in the console | Identifier in the API | What for |
| - | - | - |
| **Plugin PIX JD Editor** | `plugin-br-pix-jd-editor-group` | Write the Pix configuration: the binding with your ISPB, the routing, the daily window, and the switch for indirect participants. Apart from the administrators, it is the only group that can change this configuration. |
| **Midaz Editor** | `midaz-editor-group` | Create the organization, ledger, asset, accounts, balances, and accounting routes, and delete the probe account of the final check. |
| **Plugin CRM Contributor** | `plugin-crm-contributor-group` | Create the holder and link the holder to the account. |

**After the setup, reduce the access.** For day-to-day operation (payments, limits, indirect participants), **Plugin PIX JD Contributor** (`plugin-br-pix-jd-contributor-group`) is enough. It cannot change the Pix configuration, so an operating mistake does not change how your money is routed. For someone who only reads, use **Plugin PIX JD Viewer** (`plugin-br-pix-jd-viewer-group`).

**Prove that the access is right before you go on.** With that person's token:

* `GET /system/-/catalog` must answer `200`.
* The first write under `/system`, the integration binding in step 5, must answer `204 No Content`. A `403` there means the person is not in **Plugin PIX JD Editor**.

```bash theme={null}
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" \
  "$PIX_JD_BASE_URL/system/-/catalog"
```

## Step 2: Set up payment-order signing, if JD requires it

JD can require a signature on each payment order for your institution. Confirm this with JD. If JD requires it, follow [Payment-order signing](/en/interfaces/pix-jd/payment-order-signing) now, before any payment. If JD does not require it, skip this step.

> [!WARNING]
>
> Do this step before step 6. Step 6 sends a payment. If JD requires signed orders and the order is not signed, JD refuses it. After repeated refusals, JD blocks all debits of your institution.

## Step 3: Provision the ledger and the holder records

These steps run against Midaz and the CRM. They create the accounts that the rail posts to, and the holder records that it reads counterparties from.

**Access:** **Midaz Editor** for the ledger steps, and **Plugin CRM Contributor** for the two CRM steps.

**1. Create the organization and the ledger**

The organization is your institution in the books. The ledger is the book it posts to. An institution can hold more than one ledger. This rail posts to the **default** one: the pair that you create here and name in the binding of step 5. Every flow uses that pair until you declare more books in the organization catalog. For the catalog, see [Multi-organization and ledgers](/en/interfaces/pix-jd/multi-organization-and-ledgers).

```bash theme={null}
curl -s -X POST "$MIDAZ_URL_ONBOARDING/v1/organizations" "${MIDAZ_HEADERS[@]}" -d '{
  "legalName": "Example Institution",
  "legalDocument": "12345678000199",
  "address": { "country": "BR" }
}'
# -> {"id": "..."}  keep it as $MIDAZ_ORGANIZATION_ID

curl -s -X POST "$MIDAZ_URL_ONBOARDING/v1/organizations/$MIDAZ_ORGANIZATION_ID/ledgers" "${MIDAZ_HEADERS[@]}" -d '{
  "name": "Pix ledger"
}'
# -> {"id": "..."}  keep it as $MIDAZ_LEDGER_ID
```

A `201` with no `id` in the body is not a success. Nothing can address the new object, not you and not a later cleanup. Stop there. Do not carry an empty id into the next step.

**2. Create the BRL asset, and wait for it to appear**

The asset is the currency of the records. For Pix it is `BRL`.

```bash theme={null}
curl -s -X POST "$MIDAZ_URL_ONBOARDING/v1/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/assets" "${MIDAZ_HEADERS[@]}" -d '{
  "name": "BRL",
  "type": "currency",
  "code": "BRL"
}'
```

Both `201` and `409` are good answers. A ledger addresses an asset by its code, so "already exists" means the same as success.

Two things happen here:

1. The ledger starts to accept accounts in that asset. Before this, it refuses every account with `0034 Asset Code Not Found`.
2. Midaz creates the **`@external/BRL`** account with the asset. It is the one account in a book that you can debit before any credit. The opening balance comes from it. It is also the counterparty of every settlement with the outside world.

> [!WARNING]
>
> The `201` arrives before the asset shows in the listing. A script that creates the asset and then creates an account on the next line fails from time to time. Poll the listing until the code appears, with a deadline:
>
> ```bash theme={null}
> deadline=$(( $(date +%s) + 12 ))
> until curl -s "$MIDAZ_URL_ONBOARDING/v1/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/assets" "${MIDAZ_HEADERS[@]}" \
>       | jq -e '.items[]? | select(.code=="BRL")' >/dev/null; do
>   if [ "$(date +%s)" -ge "$deadline" ]; then
>     echo "aborted: BRL did not appear in the listing within 12s" >&2
>     echo "do not create the account: it would be refused with 0034" >&2
>     exit 1
>   fi
>   sleep 0.15
> done
> ```

**3. Create one account per role**

Create one account for each role that your environment uses: payer, payee, and the other roles of your product.

```bash theme={null}
curl -s -X POST "$MIDAZ_URL_ONBOARDING/v1/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/accounts" "${MIDAZ_HEADERS[@]}" -d '{
  "name": "payer account",
  "assetCode": "BRL",
  "type": "deposit",
  "alias": "@payer",
  "status": { "code": "ACTIVE" }
}'
# -> {"id": "..."}  keep it as $MIDAZ_ACCOUNT_ID
```

You use the account id two times later: in the CRM link below, and as the `accountId` of the business calls you make to the plugin. The **alias** (`@payer`) is the short name that the book reads and posts by. It comes back in the next step.

**4. Create the holder in the CRM**

The holder owns the account. The plugin reads **who** a counterparty is from the CRM, not from the ledger.

```bash theme={null}
curl -s -X POST "$CRM_URL/v1/holders" \
  -H "Authorization: Bearer $CRM_BEARER_TOKEN" -H 'Content-Type: application/json' \
  -H "X-Organization-Id: $MIDAZ_ORGANIZATION_ID" -d '{
  "type": "NATURAL_PERSON",
  "document": "12345678909",
  "name": "Example Person",
  "externalId": "@payer",
  "addresses": { "primary": { "city": "SAO PAULO" } }
}'
# -> {"id": "..."}  keep it as $CRM_HOLDER_ID
```

Four fields need care:

* **`document` must be a valid CPF or CNPJ, with correct check digits.**
* **`type` follows the document length.** Use `NATURAL_PERSON` for a CPF (11 digits) and `LEGAL_PERSON` for a CNPJ (14). The plugin turns this type into the number that goes to JD. A wrong type files the party as the wrong kind of person.
* **`externalId` holds the account's ledger alias** (`@payer`). The CRM calls it an external correlation identifier, so it looks optional. For this rail it is not. A Pix key registration for a holder without `externalId` answers `422 PIX-0108`.
* **`addresses.primary.city` is required for QR codes and Pix Automático.** It is the receiver city in the code. Without it, the plugin refuses to generate a QR and answers `422 PIX-0033` for `payee.city`. No payment path reads the field, so its absence shows only when someone generates a QR.

**5. Link the holder to the account**

The holder and the ledger account both exist, but nothing joins them yet. This step is the join. The plugin uses it to find **where to credit** an incoming Pix and which account a payment debits.

```bash theme={null}
curl -s -X POST "$CRM_URL/v1/holders/$CRM_HOLDER_ID/aliases" \
  -H "Authorization: Bearer $CRM_BEARER_TOKEN" -H 'Content-Type: application/json' \
  -H "X-Organization-Id: $MIDAZ_ORGANIZATION_ID" -d '{
  "ledgerId":  "'"$MIDAZ_LEDGER_ID"'",
  "accountId": "'"$MIDAZ_ACCOUNT_ID"'",
  "bankingDetails": {
    "branch":      "0001",
    "account":     "12345675",
    "type":        "CACC",
    "openingDate": "2020-01-02",
    "bankId":      "12345678"
  }
}'
```

| Field | What it is | If it is missing |
| - | - | - |
| `ledgerId`, `accountId` | the book and the account from the previous steps | the link addresses nothing |
| `branch`, `account` | branch and account, the coordinates that resolve an incoming Pix. `account` holds the number and the check digit together, with no separator: account 1234567-5 is `12345675`. A [Pix to a payee at your own institution](/en/reference/interfaces/pix-jd/create-transaction) joins `accountNumber` and `accountDigit` and looks up exactly that value | the credit finds no destination, and a Pix to your own institution answers `404 PIX-2016` |
| `type` | `CACC` checking, `SLRY` salary, `SVGS` savings, `TRAN` payment | `400 PIX-0061` on Pix key operations, because the Pix account type is unknown |
| `openingDate` | the account opening **date**, not an instant | `400 PIX-0061`, which says that the opening date is unknown, on key registration and on claim opening |
| `bankId` | your own institution's 8-digit ISPB | see the warning below |

> [!WARNING]
>
> Never send `bankId` as an empty string. An empty string is a value. It records "this account belongs to the institution whose ISPB is empty", which is worse than no value. If you do not have the ISPB yet, omit the field.

Check what the CRM recorded, and always filter. An unfiltered query returns the first link in the organization. That is how a check can approve the account of somebody else:

```bash theme={null}
curl -s -G "$CRM_URL/v1/aliases" \
  -H "Authorization: Bearer $CRM_BEARER_TOKEN" -H "X-Organization-Id: $MIDAZ_ORGANIZATION_ID" \
  --data-urlencode 'document=12345678909' \
  --data-urlencode 'banking_details_branch=0001' \
  --data-urlencode 'banking_details_account=12345675' | jq
```

**6. Fund the accounts**

A new account holds zero, and you cannot pay from an empty account. The opening credit comes from `@external/BRL`, which Midaz created with the asset, two steps above.

> [!NOTE]
>
> In production, you do not load a direct participant's customer account this way. Money enters as a real inbound Pix, or as an inflow that the customer makes. The `@external/BRL` load has two uses. One is the `@pi` settlement position of a hosted indirect participant. The other is a test or homologation environment, where no real Pix arrives. See [The direct and indirect model](/en/interfaces/pix-jd/direct-and-indirect-model) for what each position is.

```bash theme={null}
curl -s -X POST "$MIDAZ_URL_TRANSACTION/v1/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/transactions/json" "${MIDAZ_HEADERS[@]}" -d '{
  "description": "opening balance",
  "send": {
    "asset": "BRL",
    "value": "100.00",
    "source":     { "from": [ { "accountAlias": "@external/BRL",
                                "amount": { "asset": "BRL", "value": "100.00" } } ] },
    "distribute": { "to":   [ { "accountAlias": "@payer",
                                "amount": { "asset": "BRL", "value": "100.00" } } ] }
  }
}'
```

> [!WARNING]
>
> Two identical bodies sent within 300 seconds make one posting. Midaz collapses the repeat: the second `POST` answers `201` with the first posting's id, and nothing moves. Use that property when you **retry**.
>
> A retry of a top-up whose response you lost must send the **exact same body**, `description` included, within 300 seconds. The account then cannot get two credits. After that window, read the account balance before you send the top-up again. Change the `description` only for a **new** top-up. A new `description` on a real retry adds a second credit by mistake.

You can name `@external/BRL` in a body, but not in a path. The alias contains a slash, and the ledger route does not decode it. A balance read by path answers `404` or an empty `200`. Posting from it is normal. Reading it that way is not.

## Step 4: Create the accounting routes

Each money path on this rail has its own pair of Midaz operation routes: one credit leg and one debit leg. Step 5 stores the UUIDs of the routes in the plugin.

**Access:** **Midaz Editor**.

**Which pairs you need.** You do not create eleven pairs. Create one pair for each of the six payment profiles. The other profiles reuse a pair, or stay empty:

| Profile | When the rail uses it | Pair |
| - | - | - |
| `in` | a credit received | its own pair. Required |
| `out` | a payment sent | its own pair. Required |
| `out_reversal` | a payment that you sent and that comes back | its own pair. Required |
| `in_qrcode` | a credit received through a QR code | its own pair. Required |
| `intra_psp` | a payment between two accounts at your own institution | its own pair. Required |
| `intra_psp_reversal` | the reversal of that payment | its own pair. Required |
| `med_credit` | the credit leg of a MED (fraud) refund | only if you use MED. Reuse the `in` pair |
| `med_debit` | the debit leg of a MED (fraud) refund | only if you use MED. Reuse the `out` pair |
| `pixautomatico_debit` | the Pix Automático debit | only if you use Pix Automático. Reuse the `out` pair |
| `pixautomatico_reversal` | the Pix Automático reversal | only if you use Pix Automático. Reuse the `in` pair |
| `refund_sent` | a devolução that you send over SPI | optional. While both legs are empty, the rail posts it on the `out` routes |

So the minimum is six pairs, twelve routes. A profile can reuse the pair of another profile only when the money moves in the same direction. A MED refund and a Pix Automático reversal bring money in, like `in`. A MED debit and a Pix Automático debit take money out, like `out`.

Create each leg with one call:

```bash theme={null}
# a CREDIT leg -> operationType "destination" (money ARRIVES)
curl -s -X POST "$MIDAZ_URL_ONBOARDING/v1/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/operation-routes" "${MIDAZ_HEADERS[@]}" -d '{
  "title": "pix-jd out credit",
  "description": "Pix JD accounting route",
  "operationType": "destination"
}'

# a DEBIT leg -> operationType "source" (money LEAVES)
curl -s -X POST "$MIDAZ_URL_ONBOARDING/v1/organizations/$MIDAZ_ORGANIZATION_ID/ledgers/$MIDAZ_LEDGER_ID/operation-routes" "${MIDAZ_HEADERS[@]}" -d '{
  "title": "pix-jd out debit",
  "description": "Pix JD accounting route",
  "operationType": "source"
}'
```

Each call returns `{"id": "..."}`. Keep each id with its profile and its leg. Step 5 writes them.

> [!WARNING]
>
> You can invert the direction, and nothing warns you. A debit **leaves** the payer, so it is the `source` leg. A credit **arrives**, so it is the `destination` leg. If you swap them, every posting still answers success, in the wrong direction. No status code reports this.

Look up a route by title before you create it. With two routes of the same title, the next lookup can pick either one. If you provision the same book more than once, list first.

If your ledger validates routes, also create one Midaz transaction route per profile that you use. A ledger that validates routes refuses a posting that names no transaction route. See [Transaction routing entities](/en/products/midaz/transaction-routing-entities) for how to create one.

## Step 5: Configure the rail

The plugin keeps its live configuration in its **systemplane**. You write these values over the admin API, and they take effect without a redeploy or a restart. Every write is a `PUT` to `/system/<namespace>/<key>` with a `{"value": ...}` body. A success answers `204 No Content`, with no body.

The tenant comes from the validated bearer, never from the URL or the body.

**Access:** every write below needs **Plugin PIX JD Editor**. These values decide which institution the plugin presents to JD and which accounts it posts to, so only that group and the administrators can change them. Any Pix JD group can read them.

> [!NOTE]
>
> Ask the plugin what it expects. Do not trust a copy. `GET /system/-/catalog` lists every key with its type and description, and `GET /system/-/catalog/<namespace>/<key>` describes one key. The catalog is the source of truth. This page is a copy of it, and copies age.

**1. Write the JD integration binding**

**What it is.** The binding is one document with three fields. The ISPB is the 8-digit number that identifies your institution at the Banco Central. It goes on every Pix message, and the plugin cannot sign as your institution without it. The other two fields name your **default** Midaz organization and ledger, from step 3.

**Where it lives.** None of the three is a deployment variable. They come from the systemplane key `tenancy/jd_integration_binding`, with no environment fallback. While the key is empty, the plugin starts and answers its health probe. It refuses **every** payment on **every** money route.

**What breaks without it.** `409 PIX-0092`, *"Tenant Pix integration not provisioned"*. The response text asks you to contact support and does not name the key. Search for the code.

> [!WARNING]
>
> A restart does not help. The plugin reads the key on every call, not at boot. A deployment with no ISPB still has no ISPB after a restart. Write the key while the app runs, and the next request passes, with no redeploy.

**The value is a JSON document inside a string.** The body is always `{"value": ...}`. Here `value` is not an object. It is a **string**, and its content is a JSON document. The plugin stores it with the inner quotes escaped:

```text theme={null}
"{\"ispb\":\"12345678\",\"organizationId\":\"...\",\"ledgerId\":\"...\"}"
```

| Form | Result |
| - | - |
| `{"value":"{\"ispb\":\"12345678\",...}"}`, a string | correct |
| `{"value":{"ispb":"12345678",...}}`, an object | refused |

Let `jq` do the escaping:

```bash theme={null}
# Replace all three with your own values before you run this.
INSTITUTION_ISPB="12345678"                                    # 8 digits, your institution's ISPB
MIDAZ_ORGANIZATION_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6"   # the organization from step 3
MIDAZ_LEDGER_ID="9c858901-8a57-4791-81fe-4a34d4dd8ab5"         # the ledger from step 3

# 1) build the document
BINDING_DOCUMENT="$(jq -nc \
        --arg ispb   "$INSTITUTION_ISPB" \
        --arg orgId  "$MIDAZ_ORGANIZATION_ID" \
        --arg ledgerId "$MIDAZ_LEDGER_ID" \
        '{ispb:$ispb, organizationId:$orgId, ledgerId:$ledgerId}')"

# 2) wrap the document as a STRING inside {"value": ...} and write it
curl -s -o /dev/null -w '%{http_code}\n' -X PUT \
  -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \
  -d "$(jq -nc --arg document "$BINDING_DOCUMENT" '{value:$document}')" \
  "$PIX_JD_BASE_URL/system/tenancy/jd_integration_binding"
```

| Field | Rule | Required on write | Read at run time |
| - | - | - | - |
| `ispb` | exactly 8 digits, `0`–`9`, no mask and no spaces | yes | yes, on every call |
| `organizationId` | a valid, non-zero UUID (the plugin refuses the all-zeros UUID) | yes | yes, on every call |
| `ledgerId` | a valid, non-zero UUID | yes | yes, on every call |

> [!NOTE]
>
> The binding names your **default** organization and ledger. Every flow posts in that pair unless it resolves another one through the [organization catalog](/en/interfaces/pix-jd/multi-organization-and-ledgers). If `organizationId` or `ledgerId` is absent or unusable, the plugin refuses every posting, refund, and inbound credit with `409 PIX-0106`.

> [!WARNING]
>
> The decoder is strict. It refuses an unknown field, and that refusal stops the whole write. This includes the old `routeProfiles` field, because the accounting routes moved to the `routing.*` keys below. A document from an old configuration therefore fails. The decoder also refuses anything after the first JSON document.

**How to check it.** Read the key back. It holds no secret, so the value comes back in the clear:

```bash theme={null}
curl -s -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" \
  "$PIX_JD_BASE_URL/system/tenancy/jd_integration_binding" | jq
```

```json theme={null}
{
  "namespace": "tenancy",
  "key": "jd_integration_binding",
  "value": "{\"ispb\":\"12345678\",\"organizationId\":\"...\",\"ledgerId\":\"...\"}"
}
```

If `value` comes back as an object and not as a quoted string, you wrote the wrong form. If it comes back `""`, the write did not happen. Check the status code of the `PUT`. The real proof is that money routes stop their `409 PIX-0092` answers.

You cannot store a malformed ISPB through this route. The write validator uses the same decoder as the read. It refuses a 7-digit ISPB or a broken UUID at once, with `400 validation_error`. You do not find the error on the first payment.

> [!NOTE]
>
> So you do not see `409 PIX-0121`, *"Tenant Pix integration ISPB invalid"*, when you follow this page. That code means that the binding exists and its `ispb` is not 8 digits, and this route cannot create that state. It shows only when a value reached the key by another path. Examples are a direct write to the plugin's database, or a write from before the validator. Its message names both the key and the field to correct.

> [!WARNING]
>
> A `400` here is not a permission problem. A missing permission answers `403`. This `400` means that the value is wrong. The response does not say which field, so check the 8 digits first. That is the most common mistake.

| Response | What it means |
| - | - |
| `204` | written |
| `400 validation_error` | the plugin refused the format of the **value**. This is not a permission problem |
| `400 unknown_key` | the key or namespace name is wrong |
| `401` | the bearer did not authenticate |
| `403` | authenticated, but without `systemplane:write`. Add the person to **Plugin PIX JD Editor** |
| `404` | the `/system` group is not mounted, because `SYSTEMPLANE_ENABLED` is false |
| `503` | the configuration plane is unavailable |

The plugin accepts the empty string, which means "not provisioned". If you write it, the deployment goes back to `409 PIX-0092`. Do not do it in an environment that pays.

**2. Check the connection to JD**

**Why this step exists.** The binding is the last piece that the plugin needs to talk to JD as your institution. Before any money moves, prove that the conversation works: ask JD for the list of Pix participants.

**Access:** any Pix JD group, **Plugin PIX JD Viewer** included.

```bash theme={null}
curl -s -w '\n%{http_code}\n' \
  -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" \
  "$PIX_JD_BASE_URL/v1/banks"
```

The plugin asks JD on every call, with no cache, so the answer is current. [List Pix participant bank IDs](/en/reference/interfaces/pix-jd/list-pix-participant-bank-ids) describes the response.

A `200` with the participant list, like this one (trimmed), proves that the plugin reached JD and received the participant catalog:

```json theme={null}
{
  "data": [
    { "ispb": "00000000", "name": "BCO DO BRASIL S.A." },
    { "ispb": "00360305", "name": "CAIXA ECONOMICA FEDERAL" }
  ]
}
```

If you get a different response, redo the previous steps, starting with access and the integration binding. If the response is still different, contact our support team.

**3. Write the routing keys**

**What it is.** For each profile, the UUID pair of the Midaz operation routes from step 4. All the keys live in the `tenant_policy` namespace. Each one holds a string: the UUID of a route that exists in Midaz.

```
tenant_policy/routing.<profile>.operation_credit_route
tenant_policy/routing.<profile>.operation_debit_route
```

**What breaks without it.** The rail reads the six payment profiles together on every payment. A missing leg of any of the six refuses **every** payment flow with `409 PIX-0105`: sent, received, QR code, and between your own accounts. A missing MED or Pix Automático leg refuses only that flow. `refund_sent` is the exception. While both of its legs are empty, the rail posts a devolução that you send on the `out` routes.

```bash theme={null}
# OPERATION_ROUTES is the table YOU fill with the UUIDs that step 4 returned:
# one line per profile and leg, "<profile> <leg> <operation route UUID>".
# The six payment profiles have their own pair. MED and Pix Automatico reuse
# the pair of "in" or "out". refund_sent stays empty and posts on "out".
OPERATION_ROUTES="
in                     credit 1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a01
in                     debit  1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a02
out                    credit 1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a03
out                    debit  1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a04
out_reversal           credit 1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a05
out_reversal           debit  1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a06
in_qrcode              credit 1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a07
in_qrcode              debit  1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a08
intra_psp              credit 1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a09
intra_psp              debit  1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a10
intra_psp_reversal     credit 1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a11
intra_psp_reversal     debit  1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a12
med_credit             credit 1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a01
med_credit             debit  1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a02
med_debit              credit 1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a03
med_debit              debit  1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a04
pixautomatico_debit    credit 1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a03
pixautomatico_debit    debit  1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a04
pixautomatico_reversal credit 1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a01
pixautomatico_reversal debit  1f0a4c2e-5b91-4d77-9a10-6c3b8e2f0a02
"

operation_route_id() {
  printf '%s\n' "$OPERATION_ROUTES" | awk -v profile="$1" -v leg="$2" \
    '$1 == profile && $2 == leg { print $3 }'
}

for profile in in out out_reversal in_qrcode intra_psp intra_psp_reversal \
               med_credit med_debit pixautomatico_debit pixautomatico_reversal; do
  for leg in credit debit; do
    uuid="$(operation_route_id "$profile" "$leg")"
    if [ -z "$uuid" ]; then
      echo "MISSING the UUID for $profile.$leg — if $profile is one of the six payment profiles, every payment flow refuses with PIX-0105; otherwise only this flow does" >&2
      continue
    fi
    curl -s -o /dev/null -w "$profile/$leg -> %{http_code}\n" -X PUT \
      -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \
      -d "{\"value\":\"$uuid\"}" \
      "$PIX_JD_BASE_URL/system/tenant_policy/routing.$profile.operation_${leg}_route"
  done
done
```

**How to check.** Each write answers `204`. If you do not use MED or Pix Automático, leave their profiles empty. That flow then refuses, which is better than a posting on an undefined route.

**The transaction route of each profile.** Each profile also has an optional key, `tenant_policy/routing.<profile>.transaction_route`. Fill it when your ledger validates routes. The plugin then names that transaction route on every posting of the profile. Without it, such a ledger refuses the posting, and the plugin answers `PIX-4011`. When your ledger does not validate routes, leave these keys empty.

```bash theme={null}
curl -s -o /dev/null -w '%{http_code}\n' -X PUT \
  -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \
  -d '{"value":"2a1b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"}' \
  "$PIX_JD_BASE_URL/system/tenant_policy/routing.out.transaction_route"
```

> [!WARNING]
>
> The empty string means "not yet provisioned", and the plugin accepts it. The plugin refuses the all-zeros UUID. That UUID has a valid format, but it is never a real Midaz identifier. Do not fill unused routes with zeros as a "safe empty". Use the empty string.

**4. Set the posting asset and the clearing account**

**What it is.** The asset of every posting, and the external account that stands for the world outside your institution. Two systemplane keys in the `tenant_policy` namespace hold them, in both deployment modes:

| Key | What to write |
| - | - |
| `tenant_policy/midaz.asset_id` | the asset **code**: `BRL` |
| `tenant_policy/midaz.external_id` | the clearing account **alias**: `@external/BRL` |

Both values are plain strings:

```bash theme={null}
PUT() { curl -s -o /dev/null -w "$1 -> %{http_code}\n" -X PUT \
          -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \
          -d "$2" "$PIX_JD_BASE_URL/system/$1"; }

PUT tenant_policy/midaz.asset_id    '{"value":"BRL"}'
PUT tenant_policy/midaz.external_id '{"value":"@external/BRL"}'
```

> [!WARNING]
>
> Write the code and the alias, not the Midaz UUIDs of the asset and the account. The key names end in `_id`, but the plugin puts the value in the posting as it is.

**What breaks without it.** Both keys start empty. Until you write both, the plugin refuses every posting, refund, and inbound credit with `409 PIX-0106`, *"Tenant ledger configuration missing"*. The response names the binding fields and the two keys. This code is not `PIX-0105`. A tenant can have all route legs and still refuse every posting, because the asset or the clearing account is empty.

The deployment variables `MIDAZ_ASSET_ID` and `MIDAZ_EXTERNAL_ID` no longer exist. The plugin ignores them.

**5. Set the daily window**

These are the two ends of the window for transaction limits. Both are integers from 0 to 23. They are clock hours, not timestamps. Both are systemplane keys in **both** deployment modes.

```bash theme={null}
PUT tenant_policy/transaction_limits.daily_period_init '{"value":6}'
PUT tenant_policy/transaction_limits.daily_period_end  '{"value":20}'
```

**Why this step exists.** Each institution picks the hours when its daily transaction-limit window opens and closes. The plugin cannot guess them.

The values above are an example. Use your own. The JSON type stays the same: an integer, without quotes. A value outside the range answers `400`. The plugin does not clamp it to the bound.

**6. Declare whether this deployment hosts indirect participants**

`plugin-br-pix-jd.indirects/enabled` declares what the tenant **is**. A plain direct participant sets it to `false`.

```bash theme={null}
curl -s -o /dev/null -w '%{http_code}\n' -X PUT \
  -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \
  -d '{"value":false}' \
  "$PIX_JD_BASE_URL/system/plugin-br-pix-jd.indirects/enabled"
```

This is a configuration write, so it needs **Plugin PIX JD Editor**. The value is a JSON boolean, without quotes. `{"value":"true"}` answers `400`. If this deployment settles Pix for other institutions, step 8 sets it to `true`.

## Step 6: Create the transaction limit rows with one small payment

The product has no route to create what this step needs.

**What you expect.** You provision an account and read its available limit.

**What happens.** `GET /v1/limits/available` answers `404 PIX-0063`, *"The specified transaction limit was not found in the system. Please verify the identifier and try again."* `GET /v1/limits` answers `{"data":[]}`. The account looks broken, but it is not. This is the normal first state of an account that never sent a payment.

`PIX-0063` names the thing that the plugin looked up. The [error list](/en/reference/interfaces/pix-jd/pix-jd-error-list) shows its generic form, *"The specified entity was not found in the system"*. This route puts `transaction limit` in it. The code and the `404` stay the same.

**Why you cannot create the rows.** There is no creation route. `PATCH /v1/limits` updates rows that already exist. Only the limit check of an **outbound** payment creates the rows. When an account sends its first payment, the plugin finds no rows. It creates the defaults, reads them again, and continues.

**So send one small outbound payment.** One cent is enough.

> [!WARNING]
>
> If JD requires signed payment orders for your institution, finish [step 2](#step-2-set-up-payment-order-signing-if-jd-requires-it) first. Otherwise JD refuses this payment. After repeated refusals, JD blocks all debits of your institution.

**Access:** the payment needs **Plugin PIX JD Contributor** or **Plugin PIX JD Editor**. Changing a limit later with `PATCH /v1/limits` needs the same.

> [!WARNING]
>
> An account with no limit rows does not have an unlimited limit. If the plugin cannot create the limits, it **refuses** the payment.
>
> Do not try to force the rows with an amount above the ceiling. The **balance** check runs before the limit check. A large amount fails for insufficient funds before the limit check, and no rows appear. Send an ordinary payment that fits the balance.

**How to check.** `GET /v1/limits` changes from `{"data":[]}` to a list. `/v1/limits/available` changes from `404` to `200`.

Do this step after every step above. The payment must post, so it needs every value of steps 3 to 5. Without a route, for example, it fails with `PIX-0105`.

## Step 7: Prove the setup is complete

Run these checks in order. Each one fails for a different reason. That makes the sequence more useful than a single smoke test.

1. **The ledger accepts an account.** Create a disposable account and delete it. If the book refuses, the refusal names the missing link. Without this check, the same problem comes back later as "account not found" inside a payment flow, three layers from its cause. Do not fund the probe account: Midaz refuses to delete an account with a balance. The delete needs **Midaz Editor**.
2. **The binding reads back as a quoted string** with your ISPB, your organization, and your ledger, as shown in step 5.
3. **`GET /v1/banks` answers `200`** with the list of Pix participants, as in the connection check of step 5.
4. **The two `tenant_policy/midaz.*` keys read back** with the asset code and the clearing account alias.
5. **The alias query returns your account**, filtered by document, branch, and account number.
6. **A money route stops its `409 PIX-0092` and `409 PIX-0106` answers.** Use the call that you already make. You need no test harness.
7. **`GET /v1/limits` returns a list** for the account that sent the payment of step 6.
8. **A Pix key registers and shows in the account's list.** This check goes through the CRM, the binding, and the DICT at JD.

For the last check, register a random key for the account. Send `keyType` `4` and no `key`: the DICT creates the key value. A random key needs no confirmation code, so it goes to the DICT on the first call:

```bash theme={null}
curl -s -X POST "$PIX_JD_BASE_URL/v1/entries" \
  -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \
  -d '{"keyType":4,"accountId":"'"$MIDAZ_ACCOUNT_ID"'"}'
```

Then list the account's keys:

```bash theme={null}
curl -s -G "$PIX_JD_BASE_URL/v1/entries" \
  -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" \
  --data-urlencode "account_id=$MIDAZ_ACCOUNT_ID" | jq
```

The key is in the list. A CPF or CNPJ key also goes to the DICT on the first call. An email key or a phone key also needs the 6-digit code that the plugin sends through the notification provider of [Environment variables](/en/interfaces/pix-jd/pix-jd-environment-variables#notifications). [Register a Pix key entry](/en/reference/interfaces/pix-jd/create-key) describes every answer. Remove a test key when you are done with `DELETE /v1/entries/{entryId}`.

## Step 8: Add the optional capabilities

Your setup ends at step 7 if your institution is one direct participant with one book, and it settles only the Pix of its own customers. Otherwise, continue on the page that applies:

* **Several books, or several direct participants on one deployment.** Follow [Multi-organization and ledgers](/en/interfaces/pix-jd/multi-organization-and-ledgers).
* **Settling Pix for other institutions.** Follow [Hosting indirect participants](/en/interfaces/pix-jd/hosting-indirect-participants). It adds the encryption key, the hosting posture, the registration of each indirect participant, its own QR certificate if it has one, and the funding of its settlement position.

## What each skipped step looks like

Every refusal below is a `409`, except the limits one. None of them goes away if you wait. Each one goes away when you provision the missing value.

| Missing | Response | What you see |
| - | - | - |
| the binding | `409 PIX-0092` | every money route refuses. The text asks you to contact support and names no key |
| a leg of one of the six payment profiles | `409 PIX-0105` | every payment flow refuses |
| a MED or Pix Automático leg | `409 PIX-0105` | only that flow refuses. The others keep working |
| the posting asset or the clearing account | `409 PIX-0106` | every posting refuses, and the response names the values to set |
| the transaction limit rows | `404 PIX-0063` | *"The specified transaction limit was not found in the system. Please verify the identifier and try again."* |
| the delivery encryption key (indirect flow only) | `409 PIX-0107` | every indirect registration refuses, and nothing is stored |

> [!NOTE]
>
> When `PIX-0092` stops, payments do not always pass. It is only the first barrier. With the binding in place, an empty accounting route still answers `PIX-0105`. A missing asset or clearing account still answers `PIX-0106`. Three codes have three causes and three different fixes.

### Do not retry a `409`. Do retry its `503` sibling

The status tells you if the problem is your setup or an outage.

A `409` above is **positive knowledge of absence**. The rail read your configuration and found nothing there. Only an operator can supply the value, so a repeat of the request gets the same answer. A client that retries on this code loops forever. Each of those responses names what to set.

Most of those conditions have a **`503` sibling**. It applies when the rail could not read the configuration at all. The rail knows nothing about what you provisioned. The response names the dependency that failed, and a retry is the right action.

| Your setup is incomplete. Provision, do not retry | The source did not answer. Retry |
| - | - |
| `409 PIX-0092` the tenant's Pix integration is not provisioned | `503 PIX-0051` the tenant's Pix integration could not be reached |
| `409 PIX-0121` the binding exists and its `ispb` is not 8 digits | `503 PIX-0051` (the same sibling: the binding could not be read) |
| `409 PIX-0106` the posting asset or the clearing account is not provisioned | `503 PIX-0122` a piece of the tenant configuration could not be read |
| `409 PIX-0107` the delivery-secret encryption key is not provisioned | `503 PIX-0123` the key could not be read from its key source |

> [!WARNING]
>
> **The accounting routes are the exception.** `PIX-0105` has no `503` sibling. A route leg that is absent, empty, malformed, the all-zeros UUID, **or unreadable** gives the same `409`. So a `PIX-0105` alone does not tell "this leg has no value" from "the configuration plane did not answer". Read the legs back before you decide that it is an outage.

> [!NOTE]
>
> Both codes of each pair refuse the operation. Neither one posts or stores anything. The difference is only your next action, so they are separate codes.
>
> `PIX-0121` is a special case. You cannot cause it through the admin API, because the write validator refuses a malformed `ispb` before it is stored. It shows only when a value reached the key by another path. See the binding in step 5.

Two more codes name a service that the rail depends on. They are not about your setup. Retry them:

| Response | The service that did not answer |
| - | - |
| `504 PIX-3007` | the Access Manager, when the rail asks for its own token. It did not answer in time |
| `503 PIX-3008` | the Access Manager is unavailable |

The [Pix JD error list](/en/reference/interfaces/pix-jd/pix-jd-error-list) has every code, with the exact `detail` of each one.

## Where to go next

> **[Environment variables](/en/interfaces/pix-jd/pix-jd-environment-variables)**
>
> The deploy-time configuration of this rail: JD connectivity, the ledger and CRM endpoints, QR hosting, and the notification providers.

> **[Multi-organization and ledgers](/en/interfaces/pix-jd/multi-organization-and-ledgers)**
>
> Extend this setup to several books, or several direct participants, on the same deployment: the organization catalog, as a feature toggle.

> **[Indirect participants](/en/reference/interfaces/pix-jd/indirect-participants)**
>
> What a hosted participation is, how an inbound credit reaches one, its lifecycle, and every refusal it can answer.

> **[Direct Pix via JD](/en/interfaces/pix-jd/direct-pix-via-jd)**
>
> How settled Pix movements land in Midaz, and how the two systems correlate.

> **[Pix JD error list](/en/reference/interfaces/pix-jd/pix-jd-error-list)**
>
> Every `PIX-NNNN` code, its status, and the `detail` text of the response.


# Pix Lerian
Source: https://docs.lerian.studio/en/interfaces/pix-lerian

Use the Pix Lerian v1.0.0 plugin to test Pix keys, payments, collections, and dispute flows with Midaz and the supplied mock provider.

Pix Lerian v1.0.0 is a plugin for integrating Pix business flows with Midaz. It exposes DICT, SPI, COB, and Pix Automático APIs and records the money movement required by each supported flow in Midaz.

> [!NOTE]
>
> This release supports integration and testing with the supplied mock provider. It does not make a native rail connector available for use and does not promise production connectivity through an arbitrary provider.

## What the plugin does

* **DICT:** manage Pix keys, claims, MED 2.0 cases, fraud markers, and VSync reconciliation.
* **SPI:** initiate cash-outs, process payments, schedule payments, receive adapter callbacks, create refunds, and manage MED 2.0 balance holds.
* **COB:** create static BR Codes plus immediate and due-date collections.
* **Pix Automático:** decide recurring-payment authorization requests for the payer, manage authorizations, and cancel scheduled debits.
* **Midaz integration:** validate the account context and create the debit, credit, hold, release, or reversal required by the flow.

Start with [Integrating with Pix Lerian](/en/interfaces/pix-lerian/pix-lerian-integration), then use the functional guides for [DICT](/en/interfaces/pix-lerian/pix-lerian-dict), [SPI](/en/interfaces/pix-lerian/pix-lerian-spi), [COB](/en/interfaces/pix-lerian/pix-lerian-cob), and [Pix Automático](/en/interfaces/pix-lerian/pix-lerian-pix-automatico).

## Plugin, mock, and rail connectivity

The plugin is the application layer. It owns its local operation state and calls Midaz for ledger work. The supplied mock provider simulates the external side and sends asynchronous callbacks so you can test the complete integration path.

Native SPI messaging integration is a separate connectivity capability. It is not available for use in this v1.0.0 integration path. Do not use the mock as evidence that a production provider or direct participation has been certified or enabled.

## Who uses Pix Lerian

Pix Lerian is a technology plugin for institutions that own their ledger and account rules. It is not a PSP or a PSTI. The institution remains responsible for its regulatory participation and connectivity arrangement. This v1.0.0 documentation covers the plugin and its mock-provider test path. It does not cover native SPI messaging integration.

Midaz is mandatory for the plugin's account validation and accounting effects. The plugin coordinates the Pix operation and records the corresponding debit, credit, hold, release, or reversal through Midaz. The plugin does not replace the institution's ledger.

## Deployment model

Deploy Pix Lerian in the institution's BYOC environment and operate its dependencies there. Your team owns deployment, observability, access control, and continuity. The mock provider is the supported external-side simulator for v1.0.0 integration testing.

## Choose a functional path

| Need | Start here |
| - | - |
| Register, resolve, or move a Pix key | [DICT guide](/en/interfaces/pix-lerian/pix-lerian-dict) |
| Send a Pix, receive a cash-in, or return a transfer | [SPI guide](/en/interfaces/pix-lerian/pix-lerian-spi) |
| Create a QR payload or a collection | [COB guide](/en/interfaces/pix-lerian/pix-lerian-cob) |
| Accept or reject a recurring-payment authorization as the payer | [Pix Automático guide](/en/interfaces/pix-lerian/pix-lerian-pix-automatico) |
| Understand request headers, replays, and callback boundaries | [Integration guide](/en/interfaces/pix-lerian/pix-lerian-integration) |
| Observe asynchronous states and recover test failures | [Operations guide](/en/interfaces/pix-lerian/pix-lerian-operations) |

## API reference

Use the generated reference for request and response schemas:

* [DICT endpoints](/en/reference/interfaces/pix-lerian/dict/create-entry)
* [SPI transfer endpoints](/en/reference/interfaces/pix-lerian/spi/initiate-transfer)
* [COB immediate collection endpoints](/en/reference/interfaces/pix-lerian/cob/create-immediate-collection)
* [Pix Automático endpoints](/en/reference/interfaces/pix-lerian/pix-automatico/decide-authorization-request)
* [Pix Lerian errors](/en/reference/interfaces/pix-lerian/pix-lerian-error-list)

The functional guides explain sequencing and ownership. The API reference remains the contract for field validation and per-operation responses.


# Use COB with Pix Lerian
Source: https://docs.lerian.studio/en/interfaces/pix-lerian/pix-lerian-cob

Create static BR Codes and immediate or due-date Pix collections in a Pix Lerian v1.0.0 test integration.

COB creates Pix payment payloads and tracks collection state. Use it with the supplied mock provider for v1.0.0 integration testing.

## Create a static BR Code

Use [Create static BR Code](/en/reference/interfaces/pix-lerian/cob/create-static-brcode) when you need a reusable BR Code. The returned resource contains the encoded payment payload. Keep its identifier and use [Get static BR Code](/en/reference/interfaces/pix-lerian/cob/get-static-brcode) or [List static BR Codes](/en/reference/interfaces/pix-lerian/cob/list-static-brcodes) to retrieve it later.

A static BR Code is not a collection settlement record. Use a collection when you need to track a charge lifecycle.

## Create an immediate collection

1. Call [Create immediate collection](/en/reference/interfaces/pix-lerian/cob/create-immediate-collection) with a new idempotency value.
2. Save the collection identifier, BR Code payload, location, and expiration returned by the API.
3. Read it through [Get immediate collection](/en/reference/interfaces/pix-lerian/cob/get-immediate-collection) or [List immediate collections](/en/reference/interfaces/pix-lerian/cob/list-immediate-collections).
4. With `MOCK_TEST_ENDPOINTS_ENABLED=true`, the mock provider can simulate a payment. Its callback records payment only when its amount matches the immediate collection amount. An identical callback is a safe replay. A callback with conflicting payment data is not a safe replay.
5. If the charge must end without payment, use [Cancel immediate collection](/en/reference/interfaces/pix-lerian/cob/cancel-immediate-collection). Cancelling an already cancelled collection returns the existing terminal result.

## Create a due-date collection

A due-date collection requires the due-date calendar and debtor data. It can also carry value modifiers such as fine, interest, abatement, or discount.

1. Call [Create due-date collection](/en/reference/interfaces/pix-lerian/cob/create-due-date-collection). The plugin validates the Pix key before it creates the collection.
2. Save the identifier and payment payload. Read it with [Get due-date collection](/en/reference/interfaces/pix-lerian/cob/get-due-date-collection), or find it through [List due-date collections](/en/reference/interfaces/pix-lerian/cob/list-due-date-collections).
3. Apply only the documented due-date revision contract when a permitted value modifier must change. It uses JSON Merge Patch. Do not send a full replacement body by default.
4. Cancel through [Cancel due-date collection](/en/reference/interfaces/pix-lerian/cob/cancel-due-date-collection) when the collection must no longer be payable.

The collection callback is internal to the plugin. Your test client confirms payment by reading the public collection resource after the mock outcome, not by posting a payment callback itself.

## Avoid unsupported assumptions

This page covers static BR Codes and collections. For scheduled payments, see the scheduled-payment operations in the SPI API reference. This page does not establish a production provider path or native SPI messaging integration.


# Use DICT with Pix Lerian
Source: https://docs.lerian.studio/en/interfaces/pix-lerian/pix-lerian-dict

Manage Pix keys, claims, MED 2.0, fraud markers, and VSync in a Pix Lerian v1.0.0 test integration.

DICT manages the Pix key directory and related dispute workflows. Use the public API for client actions. The plugin coordinates provider calls and local state.

## Register and resolve a key

1. Create an entry with [Create entry](/en/reference/interfaces/pix-lerian/dict/create-entry). Send the account scope, required reason, and idempotency headers.
2. Save the entry identifier and read it with [Get entry](/en/reference/interfaces/pix-lerian/dict/get-entry).
3. Resolve a key with [Lookup key](/en/reference/interfaces/pix-lerian/dict/lookup-key) before a key-based payment, or use [Check keys existence](/en/reference/interfaces/pix-lerian/dict/check-keys-existence) for a batch check.
4. Update or delete only through the entry's public lifecycle routes. Do not treat a lookup as ownership proof for another account.

Entry creation and update can fail closed when their replay store is unavailable. A `503` in that condition is not a safe prompt to repeat the business action under a new key.

## Move a key through a claim

Claims cover ownership and portability. A client flow is:

1. Open the claim with [Create claim](/en/reference/interfaces/pix-lerian/dict/create-claim).
2. Read it with [Get claim](/en/reference/interfaces/pix-lerian/dict/get-claim).
3. Use the transition that matches the claim role and state: [confirm](/en/reference/interfaces/pix-lerian/dict/confirm-claim), [complete](/en/reference/interfaces/pix-lerian/dict/complete-claim), [acknowledge](/en/reference/interfaces/pix-lerian/dict/acknowledge-claim), or [cancel](/en/reference/interfaces/pix-lerian/dict/cancel-claim).

Claim mutations other than cancellation are unavailable while VSync reconciles. Claim cancellation is intentionally separate: it remains an exit for an active claim rather than a new source of directory drift.

## Work a MED 2.0 case

A funds recovery opens a tracked case. It does not itself prove that funds were returned.

1. Open it with [Create funds recovery](/en/reference/interfaces/pix-lerian/dict/create-funds-recovery) and keep the returned internal identifier.
2. Read the case, its related infraction reports, and its tracking graph through the corresponding reference operations.
3. Update only mutable contact or report fields with the documented merge-patch contract.
4. When the case reaches the state that permits it, initiate its refund through the documented funds-recovery refund operation. Read the case again to observe the new state.
5. Cancel only when its current state allows cancellation.

The plugin scopes funds recoveries to the authenticated participant. You must not use a not-found response to distinguish another participant's resource from an unknown identifier.

## Record and cancel a fraud marker

Use [Create fraud marker](/en/reference/interfaces/pix-lerian/dict/create-fraud-marker) with a caller-created request identity. A replay with the same identity and payload returns the same marker. A different payload is rejected. Use [List fraud markers](/en/reference/interfaces/pix-lerian/dict/list-fraud-markers) or [Get fraud marker](/en/reference/interfaces/pix-lerian/dict/get-fraud-marker) to inspect it, and [Cancel fraud marker](/en/reference/interfaces/pix-lerian/dict/cancel-fraud-marker) when the marker should no longer apply.

## Let VSync protect key consistency

VSync reconciles local key state against the directory by scope. It progresses from verification to event synchronization and, when needed, file reconciliation. VSync is an internal operational surface in v1.0.0. Client applications observe its effect through the `503` gate on protected mutations. They do not call its state, job, log, or reconciliation-action routes.

While a scope reconciles, DICT refuses protected mutations with `503` rather than accepting a change that could add new drift. Wait for the scope to become available. Ask the operator to inspect VSync state if the gate persists. Do not bypass the gate with adapter callbacks or direct storage changes.

For disputed-payment holds and refunds, continue with [SPI and the Block Balancer](/en/interfaces/pix-lerian/pix-lerian-spi).


# Environment variables
Source: https://docs.lerian.studio/en/interfaces/pix-lerian/pix-lerian-environment-variables

Environment variables for deploying and operating Pix Lerian: identity, persistence, integrations, connectivity, and events.

Pix Lerian components include the SPI, DICT Hub, COB Hub, Pix Automático API, their workers, and the connectivity adapter. This page lists the deployment inputs that the v1.0.0 release reads. Use the tables to see which values components share and which belong to one component.

To install or upgrade Pix Lerian, see the [Pix Lerian chart README](https://github.com/LerianStudio/helm/tree/main/charts/plugin-br-pix-lerian).

> [!NOTE]
>
> Values shown here are placeholders. Inject credentials and license material from your secret store. Never commit real secrets. `SYSTEMPLANE_SECRET_MASTER_KEY` and `VALKEY_URL` are not part of the v1.0.0 contract.

## Configuration model

Each component loads bootstrap values from its environment. The SPI, DICT Hub, COB Hub, Pix Automático API, and DICT VSync worker also consume runtime configuration from their Systemplane store after initialization. The mock provider adapter reads its configuration from the environment only and keeps its state in memory.

Configure each component separately. Their ports, stores, and required dependencies differ.

> [!WARNING]
>
> Pix Lerian v1.0.0 is available for integration and testing with the mock provider adapter. The native SPI messaging integration is not available for use in this release. Do not configure the mock adapter as a production rail.

## Shared identity and deployment

| Variable | Components | Contract |
| - | - | - |
| `APPLICATION_NAME` | All | Component identity used in logs, telemetry, and licensing. Keep the value supplied by the release configuration. |
| `SERVER_ADDRESS` | All HTTP components | Listen address in `host:port` format. The port must match the component service and probe configuration. |
| `DEPLOYMENT_MODE` | API components and workers | `local`, `saas`, or `byoc`. The default is `local` when the value is absent. |
| `REQUEST_TIMEOUT_SEC` | HTTP components | Per-request timeout in seconds. The default is `30`. |
| `LICENSE_KEY` | Licensed components | Optional in `local`; required in non-local deployment modes. Inject it as a secret. |
| `ORGANIZATION_IDS` | Licensed components | License scope, such as `global` or a comma-separated organization list. |
| `SWAGGER_ENABLED` | API components | Strict boolean. When unset, the runtime OpenAPI and Scalar surface is enabled outside production and disabled in production. |

`PLUGIN_AUTH_ENABLED` controls inbound route authentication. `PLUGIN_AUTH_HOST` is the Access Manager base address used by the shared auth integration and OAuth client-credentials flows. It must be a base address only, without an OAuth path, query, fragment, or embedded credentials. Use `https://` outside local development.

The mock provider adapter requires `SPI_BASE_URL`, `PROVIDER_CLIENT_ID`, and `PROVIDER_CLIENT_SECRET` at boot. `MOCK_TEST_ENDPOINTS_ENABLED=true` turns on test routes that can forge provider callbacks. The mock adapter has no route authorization: keep it unreachable from untrusted callers, whatever this switch says.

## Persistence and Valkey

| Variable | Components | Contract |
| - | - | - |
| `DATABASE_URL` | SPI, DICT Hub, COB Hub, Pix Automático API, and VSync | PostgreSQL DSN for the component's business store. It is required where that component persists business data. |
| `SYSTEMPLANE_POSTGRES_DSN` | Systemplane consumers | PostgreSQL DSN for the runtime configuration store. It falls back to `DATABASE_URL` in the API components when unset. |
| `REDIS_HOST`, `REDIS_PORT`, `REDIS_USER`, `REDIS_PASSWORD`, `REDIS_DB` | API components and VSync | Structured Valkey connection settings. Do not replace them with the retired `VALKEY_URL` variable. |
| `REDIS_TLS`, `REDIS_PROTOCOL`, `REDIS_CA_CERT` | API components and VSync | Valkey transport security. A private or self-signed certificate requires `REDIS_CA_CERT`; there is no skip-verification switch. |
| `KEY_CACHE_TTL_SEC` | DICT Hub | Pix-key cache TTL in seconds. The default is `60`. |

Valkey behavior differs by component. SPI, DICT Hub, and COB Hub can degrade selected idempotency or cache paths when you do not configure Valkey. Some SPI, DICT, and COB mutations fail closed with `PIX-0032` when no durable replay backstop exists. DICT VSync treats Valkey as a hard dependency because it coordinates the cross-pod mutation gate. A configured but malformed `REDIS_*` value fails boot rather than silently selecting a different endpoint.

The v1.0.0 Systemplane implementation does not use `SYSTEMPLANE_SECRET_MASTER_KEY`. Protect Systemplane database access, backups, and disk storage through the deployment environment.

## Institution and service integrations

| Variable | Components | Contract |
| - | - | - |
| `ORGANIZATION_ID` | SPI, DICT Hub, COB Hub | Midaz organization the components use. |
| `ISPB` | SPI, DICT Hub, COB Hub | Participant identifier. The API validates the participant header or resolves the value from tenant configuration. |
| `ADAPTER_BASE_URL` | SPI, DICT Hub, COB Hub, VSync | Connectivity adapter base URL. For local integration, point it at the mock provider adapter. |
| `MIDAZ_BASE_URL` | SPI | Midaz base URL for onboarding and transaction operations. |
| `MIDAZ_LEDGER_ID` | SPI | Ledger identifier used for accounting operations. |
| `MIDAZ_CLIENT_ID`, `MIDAZ_CLIENT_SECRET` | SPI | OAuth client credentials for Midaz calls. |
| `CRM_BASE_URL`, `CRM_CLIENT_ID`, `CRM_CLIENT_SECRET` | SPI, DICT Hub, VSync | CRM integration used by flows that validate accounts, holders, or orphaned entries. |
| `DICT_BASE_URL`, `DICT_CLIENT_ID`, `DICT_CLIENT_SECRET` | SPI and COB Hub | DICT Hub or proxy address and credentials. `DICT_ROUTING_MODE` selects `hub` or `proxy`; keep the URL consistent with that choice. |
| `COB_BASE_URL`, `COB_CLIENT_ID`, `COB_CLIENT_SECRET` | SPI | COB Hub or proxy address and credentials. `COB_ROUTING_MODE` selects `hub` or `proxy`; keep the URL consistent with that choice. |
| `SPI_BASE_URL`, `SPI_CLIENT_ID`, `SPI_CLIENT_SECRET` | DICT Hub | SPI address and credentials used for transfer lookups and MED 2.0 balance-lock operations. |

These are service-to-service settings. They do not make the native SPI connector available. That integration is not part of the usable v1.0.0 release surface.

## DICT VSync

The DICT VSync worker reconciles DICT state and requires its own worker configuration:

| Variable | Default | Contract |
| - | - | - |
| `VSYNC_ENABLED` | `true` | Enables the worker scheduler. |
| `VSYNC_FILE_RECON_ENABLED` | `true` | Enables file-based reconciliation. |
| `VSYNC_CHUNK_PROCESSING_DEADLINE_MIN` | `30` | Chunk processing deadline in minutes. |
| `VSYNC_MAX_JOB_ATTEMPTS` | `3` | Maximum attempts for a reconciliation job. |
| `VSYNC_EVENTSYNC_MAX_PAGES` | `100` | Maximum pages in event synchronization. |
| `VSYNC_GATE_TTL_SEC` | `3600` | Mutation-gate lease TTL in seconds. |
| `VSYNC_STUCK_JOB_SWEEP_TICK_SEC` | `120` | Interval between stuck-job scans in seconds. |
| `RABBITMQ_URI` | — | RabbitMQ URI for the file-reconciliation queue. Use `amqps://` outside local development. |
| `RABBITMQ_ENABLED` | component-dependent | Enables the DICT Hub jobs publisher. The VSync worker itself requires its queue configuration. |

`VSYNC_ENABLED` and `VSYNC_FILE_RECON_ENABLED` can be hot-reloaded through the worker's runtime configuration. The remaining tuning values are read at boot and require a restart.

## Pix Automático API

The Pix Automático API sends settlement commands to the SPI and reads these variables:

| Variable | Contract |
| - | - |
| `ORGANIZATION_ID` | Organization that the component acts for in single-tenant mode. The component reads its runtime configuration first and uses this value only when that configuration has none. When `MULTI_TENANT_ENABLED=true`, the component refuses to start if this value is set. |
| `SPI_BASE_URL` | SPI address for Pix Automático settlement. Include the SPI `/spi` path segment. A malformed value stops the component at startup. |
| `SPI_CLIENT_ID`, `SPI_CLIENT_SECRET` | Client credentials for the settlement call. In multi-tenant mode, the component resolves the credentials per tenant and does not use these values. |
| `REGULATORY_DISPATCH_ENABLED` | Turns on the dispatcher that sends regulatory intents to the provider adapter. The default is `false`. |
| `REGULATORY_DISPATCH_BASE_URL` | Provider adapter address that the dispatcher posts to. When dispatch is on and this value is empty, the component refuses to start. |

## Streaming and observability

The notification-outbox relay is disabled by default. To enable it, set `STREAMING_ENABLED=true` and provide `STREAMING_BROKERS`. The shared CloudEvents source, when configured, must identify the Pix Lerian service. The component also validates the streaming broker's TLS/SASL settings and the optional `STREAMING_DATASCHEMA_BASE_URL`.

Set `ENABLE_TELEMETRY=true` to turn on OpenTelemetry. The `OTEL_*` variables configure it. See [BYOC configuration](/en/reference/byoc-configuration) for shared telemetry and broker transport parameters.

## Health and readiness

Probe paths and route prefixes belong to the component deployment configuration. Do not assume that every component exposes unprefixed `/health` or `/readyz`. Use the paths in the release chart and component bootstrap configuration.


# Integrating with Pix Lerian
Source: https://docs.lerian.studio/en/interfaces/pix-lerian/pix-lerian-integration

Set up a Pix Lerian v1.0.0 test integration, apply request conventions, and follow public API flows without calling adapter-only callbacks.

Pix Lerian v1.0.0 is ready to integrate and test with the supplied mock provider. Your application calls the public DICT, SPI, COB, and Pix Automático APIs. The plugin calls Midaz and the mock provider. The mock returns asynchronous callbacks to the plugin.

> [!NOTE]
>
> The callback routes are adapter-only. Do not call them from a client application. Native rail connectivity and production provider availability are outside this release's supported integration path.

## Build your test path

1. Deploy the plugin dependencies, including Midaz and the mock provider, in a test environment.
2. Obtain an access token when authentication is enabled and identify the account that owns each request.
3. Test a public flow: [a key](/en/interfaces/pix-lerian/pix-lerian-dict), [a transfer](/en/interfaces/pix-lerian/pix-lerian-spi), or [a collection](/en/interfaces/pix-lerian/pix-lerian-cob).
4. Keep the operation identifier returned by the create request. Read that operation until it reaches a terminal state after the mock callback.
5. Record the Midaz posting and operation result together in your test evidence.

## Request conventions

Use the per-operation reference as the final authority. These conventions recur across the plugin:

| Concern | Use |
| - | - |
| Authentication | Send a bearer token in `Authorization` when Access Manager authentication is enabled. |
| Account scope | Send `X-Account-Id` on account-scoped public operations. The plugin uses it to enforce account ownership. |
| Mutation replay | Send a new `X-Idempotency` value for each intended write, then reuse that exact value only to retry the same request. Most public POST operations require it. |
| Business justification | Send `X-Reason` where the DICT operation requires a reason, such as entry mutation. |
| Content type | Use `application/json` for JSON bodies. A JSON merge patch requires `application/merge-patch+json`. |

A missing or invalid idempotency header is a client error. Reusing a key with a different payload is a precondition failure, except when you create an immediate or due-date collection: those two routes return the existing collection with `200`.

## Read state after an asynchronous write

A successful request can mean that the plugin accepted work, not that the external payment or collection completed. For SPI, use the returned transfer or refund identifier with the [transfer](/en/reference/interfaces/pix-lerian/spi/get-transfer) or [refund](/en/reference/interfaces/pix-lerian/spi/get-refund) read endpoint. For collections, read the collection by its identifier.

Treat these results differently:

* **Validation or authorization error:** correct the request or token. Do not retry unchanged input.
* **Replay response:** keep the original result. Do not create a second business operation.
* **Conflict:** read the resource and choose the next legal transition.
* **Temporary dependency error:** preserve the idempotency value before retrying. A route that documents a fail-closed dependency will continue to refuse the write until that dependency is restored.

## Keep boundaries clear

Your client owns public API calls and reads. The mock provider owns simulated external outcomes. The plugin owns callback processing and Midaz posting. This separation prevents a test client from manufacturing settlement states or bypassing the account and provider checks.

Continue with [SPI flows](/en/interfaces/pix-lerian/pix-lerian-spi) for payment sequencing, [DICT flows](/en/interfaces/pix-lerian/pix-lerian-dict) for keys and MED 2.0, or [COB flows](/en/interfaces/pix-lerian/pix-lerian-cob) for BR Codes and collections.


# Operating Pix Lerian
Source: https://docs.lerian.studio/en/interfaces/pix-lerian/pix-lerian-operations

Operate a Pix Lerian v1.0.0 test integration by observing asynchronous state, preserving replay keys, and separating plugin operations from connectivity operations.

Operate Pix Lerian as a stateful application with Midaz postings and asynchronous provider outcomes. In v1.0.0, exercise this model with the supplied mock provider only.

## Observe the operation, not only the HTTP response

A create response can acknowledge accepted work before the mock provider reports a terminal outcome. Store the resource identifier, request correlation data, and idempotency value. Then read the resource until its state is terminal.

* Use [SPI transfer reads](/en/reference/interfaces/pix-lerian/spi/get-transfer) and [refund reads](/en/reference/interfaces/pix-lerian/spi/get-refund) for payment flows.
* Use the DICT and COB resource reads returned by the generated reference for their respective flows.
* Match the final plugin state to the expected Midaz debit, credit, hold, release, or reversal in your test evidence.

Do not infer settlement from a successful submit alone.

## Preserve safe retry behavior

Keep `X-Idempotency` with the original request payload and response. Reuse it only to retry that request. The plugin rejects a divergent reuse, except on the two collection-create routes: they return the existing immediate or due-date collection.

A dependency failure is not a signal to invent a terminal state. Restore the dependency, preserve the same retry identity when the contract allows it, and read the resource before sending a new business request.

## Handle reconciliation and MED 2.0

DICT can temporarily gate selected key and claim mutations while VSync reconciles a scope. A `503` from that gate means reconciliation is active. Inspect its state and retry only after the scope is available. Cancellation remains distinct from mutations that can introduce drift.

MED 2.0 holds and refunds have their own state transitions. Use the [SPI guide](/en/interfaces/pix-lerian/pix-lerian-spi) and [DICT guide](/en/interfaces/pix-lerian/pix-lerian-dict) to determine whether a hold should be settled, compensated, released, or reviewed. Do not turn operational overrides into ordinary client flows.

## Respect the connectivity boundary

The plugin and Midaz are the components under test. The supplied mock provider simulates the provider outcome and invokes internal callbacks. A client must not invoke callback, override, or recovery routes directly.

Native SPI messaging integration is not available for use in this release. These pages do not establish production connectivity or a provider selection model.

## Test-operating checklist

1. Verify the authenticated account scope before a write.
2. Save the request, `X-Idempotency` value, and returned resource identifier.
3. Wait for and observe the mocked asynchronous outcome through a public read.
4. Verify the expected Midaz posting or compensating posting.
5. For a non-terminal result, read state first. Only then follow the documented retry or recovery action.

See [Integration](/en/interfaces/pix-lerian/pix-lerian-integration) for client boundaries and request conventions.


# Use Pix Automático with Pix Lerian
Source: https://docs.lerian.studio/en/interfaces/pix-lerian/pix-lerian-pix-automatico

Decide Pix Automático authorization requests, manage payer authorizations, and cancel scheduled debits with the Pix Lerian v1.0.0 payer API.

The Pix Automático API serves the payer side of recurring Pix payments. With it, the payer accepts or rejects an authorization request, manages the authorization, and cancels scheduled debits.

## Call the API from your backend

The caller is your PSP backend, authenticated with an application token. The token identifies your application, not one of your customers. Your backend authenticates the payer and authorizes the payer for the account before it calls the API.

* Send the payer account in `X-Account-Id` on account-scoped operations. [Create authorization request from QR code](/en/reference/interfaces/pix-lerian/pix-automatico/create-authorization-request-from-qr-code) takes the account in the `payerAccountId` body field instead.
* A resource that belongs to a different account than the one you send returns `404`.
* Send `X-Idempotency` on each write. Reuse the value only to retry the same request.

## Start an authorization from a QR code

1. Call [Create authorization request from QR code](/en/reference/interfaces/pix-lerian/pix-automatico/create-authorization-request-from-qr-code). Send the raw QR code content in `qrCodePayload` and the payer account in `payerAccountId`.
2. The API decodes the QR code, detects the journey, and reads the recurrence payload from the receiving PSP over HTTPS.
3. On journey 3, send `immediatePayment.result` as `SETTLED`. On journey 4, a `FAILED` result stops the journey.
4. Keep the `authorizationRequestId` from the response. The request waits for the payer's decision until `expiresAt`.

If the API cannot read the recurrence payload, the journey stops with an error and the API creates no request.

On journey 1, the request comes from the receiving PSP. It also appears in the list of pending requests.

## Decide a pending request

1. Call [List authorization requests](/en/reference/interfaces/pix-lerian/pix-automatico/list-authorization-requests) to get the requests that wait for the payer's decision. A request leaves this list when the payer accepts or rejects it, when the receiving PSP cancels it, or when it expires.
2. Call [Decide authorization request](/en/reference/interfaces/pix-lerian/pix-automatico/decide-authorization-request) with `decision` set to `ACCEPT` or `REJECT`. Use the exact `authorizationRequestId` that the API returned.
3. To accept, you can also send the payer parameters. A parameter that you do not send takes its default: notifications on, credit line on, and no maximum amount.
4. To reject, send `rejectionReason` as `NotRecognizedByDebtor` or `RejectedByDebtor`.
5. Call [Get authorization request](/en/reference/interfaces/pix-lerian/pix-automatico/get-authorization-request) to read the outcome. It returns the request in any state.

The decision is a single command. There is no second confirmation step. The API sends the decision to the receiving PSP asynchronously. The receiving PSP does not answer a rejection.

## Manage authorizations

* [List authorizations](/en/reference/interfaces/pix-lerian/pix-automatico/list-authorizations) returns the authorizations that have not ended: `APPROVED` and `AWAITING_CONCLUSION`. Send `include_terminated=true` to also get `REJECTED`, `EXPIRED`, and `CANCELLED` authorizations.
* An `AWAITING_CONCLUSION` authorization is not active at BACEN until the receiving PSP concludes the process. Filter on `status=APPROVED` to get only the authorizations in force.
* [Get authorization](/en/reference/interfaces/pix-lerian/pix-automatico/get-authorization) returns one authorization in any state.
* [List authorization history](/en/reference/interfaces/pix-lerian/pix-automatico/list-authorization-history) returns the audit of state transitions. Each entry has the previous state, the new state, the time, and the actor.

### Change the payer parameters

[Update authorization parameters](/en/reference/interfaces/pix-lerian/pix-automatico/update-authorization-parameters) applies a JSON merge patch (RFC 7386) to the three payer parameters: `maximumAmount`, `schedulingNotificationsEnabled`, and `creditLineEnabled`. Send the body as `application/merge-patch+json`.

* Omit a parameter to keep its value.
* Set a parameter to `null` to reset it to its default. The two switches default to enabled, so a reset does not turn them off.
* A change applies to debits that are scheduled after it. A debit that is already scheduled keeps the maximum amount that was in force when it was scheduled.

## Cancel an authorization

[Cancel authorization](/en/reference/interfaces/pix-lerian/pix-automatico/cancel-authorization) ends the authorization at the payer's request. The cancellation is immediate. It also cancels the debits scheduled under the authorization, including retries after the due date. Debits due for settlement on the day of the cancellation stay scheduled and settle that day.

The response reports `cancelledScheduledPayments` and `preservedScheduledPayments`. A preserved count above zero is correct behavior, not a partial failure.

The `reason` field is a free-text note for the payer's audit trail. The receiving PSP gets the code `SLDB`, which the response returns in `counterpartyReason`.

## Cancel one scheduled debit

1. Call [List scheduled payments](/en/reference/interfaces/pix-lerian/pix-automatico/list-scheduled-payments) to get the identifier of the debit. This list also keeps settled and cancelled debits.
2. Call [Cancel scheduled payment](/en/reference/interfaces/pix-lerian/pix-automatico/cancel-scheduled-payment) with that identifier.

Cancelling one debit does not change the authorization. The authorization stays in force, and the next debits are still scheduled. To end the authorization, cancel the authorization.

The API refuses the cancellation with `409` in these cases:

* The request arrives at or after 00:00 on the settlement date, in the America/Sao\_Paulo time zone (`PIX-0825`).
* The debit comes from a retry after the due date, purpose `NTAG` (`PIX-0826`).
* The debit is no longer `SCHEDULED`.

For the Pix Lerian request conventions, see [Integrating with Pix Lerian](/en/interfaces/pix-lerian/pix-lerian-integration).


# Use SPI with Pix Lerian
Source: https://docs.lerian.studio/en/interfaces/pix-lerian/pix-lerian-spi

Test Pix Lerian v1.0.0 cash-out, cash-in callback, refund, and MED 2.0 balance-hold behavior with Midaz and the supplied mock provider.

SPI manages Pix transfers, refunds, asynchronous outcomes, and the MED 2.0 Block Balancer. It calls Midaz for the ledger action that corresponds to the operation.

> [!NOTE]
>
> Cash-in and cash-out callback routes are adapter-only. In this release, the supplied mock provider is the supported way to exercise them. A client application must not post a callback or claim a provider settlement result.

## Send a cash-out in two stages

A cash-out is intentionally split into initiation and processing.

1. Call [Initiate transfer](/en/reference/interfaces/pix-lerian/spi/initiate-transfer) with a new `X-Idempotency` value. The plugin validates the request and creates a transfer initiation.
2. Call [Process transfer](/en/reference/interfaces/pix-lerian/spi/process-transfer) for that initiation. The plugin performs the required Midaz debit and submits work to the mock provider.
3. Read the transfer with [Get transfer](/en/reference/interfaces/pix-lerian/spi/get-transfer). Processing acceptance is not a final payment result.
4. Let the mock provider deliver the terminal callback. Read again until the transfer reaches a completed, rejected, or other terminal state under the response contract.

Keep the same idempotency value only for a retry of the same call. A new business payment needs a new value.

## Receive a cash-in through the adapter boundary

The adapter receives the external-side event, calls the plugin's internal approval and settlement callbacks, and the plugin validates and credits the destination through Midaz. Your application observes this flow through public transfer reads. It does not invoke approval or settlement callbacks.

A cash-in that cannot be approved or settled is not a client-side retry decision. Inspect the public operation state and the mock test evidence before taking another action.

## Create and observe a refund

Use [Create refund](/en/reference/interfaces/pix-lerian/spi/create-refund) against an eligible transfer, then read it through [Get refund](/en/reference/interfaces/pix-lerian/spi/get-refund). A refund follows its own asynchronous lifecycle. Do not mark it complete until the plugin records the terminal provider outcome and the matching Midaz effect.

## Use the MED 2.0 Block Balancer

The Block Balancer holds funds for a contested transaction before a refund decision. It is a controlled operational flow, not a shortcut for ordinary transfers.

1. Create a hold for the contested transaction. The plugin places a pending Midaz hold from the available balance into the configured blocking account. A replay of the same `request_ref` returns the existing hold.
2. If the case ends before settlement, release a `PENDING` hold. You cannot release a hold that is already in settlement.
3. Start **Phase 1** settlement for one hold or an eligible group. The hold becomes `SETTLING`. The branch either returns the pending hold and submits a refund, or commits the hold, handles any surplus, and submits the required payment.
4. Complete **Phase 2** only from the linked operation's observed outcome. A success makes the hold `SETTLED`. A failure compensates it to `PENDING`.
5. Use manual close, surplus return, and audit functions only through authorized operational controls. They are not normal application endpoints.

The Block Balancer enforces a ceiling across its own settlements and regular outbound refunds for the same original transaction. Do not try to calculate around that protection in the client.

For the DICT-side infraction and funds-recovery workflow, see [DICT](/en/interfaces/pix-lerian/pix-lerian-dict).


# DICT
Source: https://docs.lerian.studio/en/interfaces/pix/main-domains-dict

Learn how DICT, BACEN's Pix key directory, handles CPF, email, phone, and EVP key registration, portability claims, and account ownership.

The **DICT (Directory of Transactional Account Identifiers)** is the national registry of the Central Bank of Brazil (BACEN). It manages Pix keys and provides secure, interoperable addressing for the Pix ecosystem.

Pix keys let users receive payments with simple identifiers, such as a phone number or email. Users do not expose full banking details. DICT keeps these keys unique, auditable, portable, and correctly linked to the legitimate account holder.

This page gives an overview of DICT: key types, lifecycle, claims, validation rules, and the compliance rules for institutions that integrate Pix.

# What DICT does

***

DICT provides:

### Addressing

Maps each Pix key to a specific transactional account.

### Uniqueness

Prevents duplicate registrations across the entire Brazilian financial system.

### Portability

Lets users move their keys between institutions and keep the same identifier.

### Ownership integrity

Supports dispute flows when a key links to the wrong user.

### Regulated lookup

Institutions can securely fetch recipient information before they process a transfer.

> [!WARNING]
>
> **One key, one account.**
>
> In Pix, a Pix key links to only one transactional account at a time. You cannot reuse the same key across multiple accounts or institutions at the same time.
>
> DICT enforces this strict one-to-one rule. The rule is fundamental to:
>
> * prevention of fund misrouting
> * clear ownership
> * system-wide consistency and auditability

# Key types

***

Pix keys are **unique identifiers** that link a user’s bank account to the Pix payment system.

They let others send or receive instant payments without full account details. The sender uses an alias such as a CPF, email, phone number, or random key (EVP).

BACEN defines four official key types:

## 1. CPF / CNPJ (Registration Number / Tax Identifier)

***

### What it is:

Uses the customer’s **official tax identification number** (CPF for individuals, CNPJ for businesses) as the Pix key.

### Format:

* **CPF:** 11 digits → 12345678901
* **CNPJ:** 14 digits → 12345678000195

### Characteristics:

* No confirmation required
* One key per document
* Easily identifiable but exposes personal data

### Validation:

* Must match the account owner’s legal document
* Follows BACEN validation algorithms

## 2. Email

***

### What it is:

Links a **valid email address** to the customer’s Pix account.

### Format:

* Up to 77 characters
* Follows standard format → [user@domain.com](mailto:user@domain.com)
* Case-insensitive

### Characteristics:

* Requires **token confirmation** to the email address
* Easy to share and remember
* Does not expose personal data

### Registration flow:

1. The customer requests an email key through Pix Lerian
2. The institution sends a confirmation token to the email address
3. The customer confirms the token
4. The key becomes active in DICT

### Validation:

* Requires confirmation within **5 calendar days**
* Token is unique per request

### Best for:

* Freelancers or professionals (e.g., [payments@studio.com](mailto:payments@studio.com))
* Companies with multiple email addresses

## 3. Phone number

***

### What it is:

Uses a **mobile number** in international format as a Pix key.

### Format:

* E.164 international standard → +5511987654321
* +55 (country) + area code + number

### Characteristics:

* Requires confirmation via **SMS token**
* Widely recognized and easy to use
* Doesn’t expose personal data

### Rules:

* Accepts only **mobile phones** (no landlines)
* Requires confirmation within **5 calendar days**
* Can register multiple numbers per account

### Common use cases:

* Small business owners or service providers
* Customers who prefer simplicity (“Pix to my phone number”)

## 4. Random key (EVP)

***

### What it is:

A **system-generated unique identifier** (UUID v4) for maximum privacy.

### Format:

123e4567-e89b-12d3-a456-426614174000

### Characteristics:

* No confirmation required
* Does not reveal any personal or business data
* Available instantly
* Hard to memorize manually

### When to use:

* Privacy-focused users
* Large companies or franchises that need **separate receiving accounts**
* One-off or temporary payment flows

### Rules:

* Generated automatically by the provider
* Unique and non-reusable
* Up to **five keys per account** for a natural person and **20** for a legal person, across all types (BACEN regulation)

## Key limits and rules (BACEN Regulation)

***

| Type | Limit |
| - | - |
| Total Pix keys per account | **5** (natural person), **20** (legal person) |
| CPF / CNPJ | **1 per account** |
| Phone | 1 per number |
| Email | 1 per address |
| EVP | Unlimited, within the account limit |

# Key lifecycle

***

A Pix key follows a standardized lifecycle from BACEN. The lifecycle keeps consistency, security, and interoperability across all participating institutions.

### 1. Registration

A user or institution registers a Pix key. The request associates an identifier (a CPF, email, phone number, or random key) with a specific transactional account.

At this stage, the key enters a **pending state**. It waits for validation according to its type.

### 2. Confirmation

Some Pix keys require explicit confirmation of ownership before they become active:

* **Email / Phone number** → Confirmation token sent to the contact method
* **CPF / CNPJ** → Automatically validated and confirmed
* **EVP (Random key)** → Automatically generated and confirmed

This step makes sure the identifier belongs to the user.

### 3. Activation

Once confirmed, the Pix key becomes **active**.

At this point, the key can:

* Appear in DICT lookups
* Receive Pix transfers
* Work with QR Codes and payment flows

### 4. Update

Certain changes may require new validations or confirmations. Examples include a change to the linked account or the ownership details. The exact requirement depends on the key type and the update.

### 5. Removal

Two parties can remove a Pix key:

* The user removes it voluntarily.
* The institution removes it for compliance, account closure, or regulatory reasons.

Once removed, the key becomes unavailable for new transactions.

### 6. Synchronization

Institutions must continuously synchronize their local state with the **BACEN DICT**.

This guarantees that:

* Key status remains consistent across the ecosystem
* Portability and ownership claims stay correct
* No outdated or invalid keys remain active

Ongoing synchronization is mandatory for regulatory compliance and operational reliability.

![Flow for creating a Pix key and registering it in DICT so key status stays consistent across the ecosystem](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/key-creation-flow.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=22b566462e1314a3d7dff287d15c5285)

Figure 1. Pix key creation flow

# Portability & Ownership claims

***

Pix key **claims** are official requests in the **BACEN DICT**. A claim modifies the ownership or association of a Pix key.

They keep every key (phone, email, CPF, or CNPJ) correctly linked to its legitimate owner and financial institution.

**Pix Lerian** automates the claim process, from request to confirmation. It provides secure ownership validation, institutional interoperability, and traceability under the **BACEN DICT standard**.

## Claim types

***

There are two types of claims:

### Portability (`PORTABILITY`)

**What it is:**

Applies when a customer wants to transfer an existing Pix key (an email, phone number, CPF, or CNPJ) from one financial institution (**Bank A**) to another (**Bank B**).

**Goal:**

Keep the same Pix key identifier and change the linked institution. This is similar to **mobile number portability**.

**Example:**

A user closes their account at Bank A and opens a new account at Bank B.

They want to keep the same phone number as their Pix key.

→ Bank B initiates a **portability claim** with DICT.

→ DICT notifies Bank A to release the key.

→ Once confirmed, ownership moves to Bank B.

**Key points:**

* Requires customer confirmation in the original institution.
* Involves both institutions (old and new).
* Result: the key changes institution but keeps the same identifier.

### Ownership (`OWNERSHIP`)

**What it is:**

Applies when a Pix key links to the wrong account or institution. This is a dispute over who truly owns the key.

**Goal:**

Correct an erroneous key registration so the legitimate owner regains control of the identifier.

**Example:**

The telecom provider recycles a phone number that belonged to a user.

When a new user registers the same number, DICT identifies that the number already belongs to someone else.

→ The institution initiates an **ownership claim** to check and correct the key’s rightful owner.

**Key points:**

* Focused on **ownership integrity**, not migration.
* Starts from a system validation or a user report.
* May require verification documents or confirmation from both parties.
* Result: the key moves to the claimant's account, at the claimant's institution.

### Claim type reference

| **Claim Type** | **Purpose** | **Triggered by** | **Result** |
| - | - | - | - |
| **PORTABILITY** | Move key from one institution to another. | Customer request at new institution. | Key transferred to new institution. |
| **OWNERSHIP** | Correct ownership when a key is wrongly linked. | Conflict detection or customer report. | Key moves to the claimant's account. |

![Decision path for choosing between a portability claim and an ownership claim when moving or correcting a Pix key](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/portability-or-ownership.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=a0ec383c605173f2105387e52c572536)

Figure 2. How to choose the right claim type

## Claim flow: Portability & Ownership

***

Pix **claims** manage key reassignment and portability requests within **BACEN’s DICT**.

They keep every Pix key correctly linked to its legitimate owner and financial institution.

**Pix Lerian** handles two types of claims:

* **Portability:** transfers a Pix key between institutions and keeps the same holder.
* **Ownership Claim:** corrects the key’s ownership when it links to the wrong user.

Both processes share the **same DICT API flow and endpoints**. They differ only in **business logic** and **validation rules**.

### Participants

* **Claimant Institution (Bank B):** initiates the claim, either to transfer a key (Portability) or to correct ownership (Ownership Claim).
* **Current Institution (Bank A):** receives the DICT notification and must confirm or reject the request.

### Scenario 1: You are the Claimant Institution (Bank B)

In this case, the customer belongs to **Bank B** (you), which will receive the key.

Bank B creates, tracks, and cancels the claim when necessary.

**1. Create Claim**

The customer requests a Pix key change. The change transfers the key from another institution or corrects its ownership.

Bank B initiates the claim in DICT.

**Result:**

* The claim starts with status OPEN.
* DICT notifies **Bank A** (current owner) to validate or reject the request.

**2. Monitor Claim status**

Bank B tracks the claim lifecycle through periodic queries or webhook notifications from DICT.

Possible transitions:

OPEN → WAITING\_RESOLUTION → CONFIRMED → COMPLETED

**3. Complete Claim**

After approval, DICT finalizes the process and synchronizes the change across institutions.

* For **Portability**, the key becomes inactive in Bank A and active in Bank B.
* For **Ownership Claim**, the key remains in the same institution, but ownership moves to the legitimate owner.

**4. Cancel Claim (optional)**

If the customer or institution decides not to proceed, they can cancel the claim while it waits for resolution.

![How Bank B initiates a Pix key claim, from requesting it through DICT to its approval, completion, or optional cancellation](https://mintcdn.com/lerian-49cb71fc/SFzzdxyH5SN7w_fC/images/en/d2/bankb-claim-request.svg?fit=max\&auto=format\&n=SFzzdxyH5SN7w_fC\&q=85\&s=7a4e24f317d630029938dac977f08191)

Figure 3. Bank B request for Pix key claim

### Scenario 2: You are the Current Institution (Bank A)

In this scenario, the customer belongs to **Bank A** (you). Bank A currently holds the key that another institution requests.

Bank A must validate the claim request from DICT.

**1. Receive notification**

DICT notifies **Bank A** about the claim request from **Bank B**.

The claim appears with status WAITING\_RESOLUTION.

**2. Validate Claim**

When DICT notifies Bank A of an incoming claim, the institution must check the request.

The claim type sets the next step. It may require **customer confirmation** or **document review**.

**Result:**

* If approved → DICT transfers the key to Bank B.
* If denied → the claim status becomes CANCELLED.

**3. Completion**

After approval, DICT finalizes the process and synchronizes the change across institutions.

* For **Portability**, the key becomes inactive in Bank A and active in Bank B.
* For **Ownership Claim**, the key remains in the same institution, but ownership moves to the legitimate owner.

![How Bank A, the institution currently holding the key, handles an incoming Pix key claim through to completion and cross-institution synchronization](https://mintcdn.com/lerian-49cb71fc/SFzzdxyH5SN7w_fC/images/en/d2/banka-claim-request.svg?fit=max\&auto=format\&n=SFzzdxyH5SN7w_fC\&q=85\&s=e1d005fcbe602e51cbbb1cd4eaad6270)

Figure 4. Bank A handling Pix key claim

# Security requirements (BACEN + Market Standards)

***

Institutions must enforce:

* End-to-end encryption of key data
* Rate limits for registration attempts
* Token expiration and one-time usage
* Strict validation of CPF/CNPJ, phone, and email
* Internal audit logs for all DICT operations
* Event tracking for confirmation, cancellation, and deletion

Institutions must minimize PII exposure in logs and user interfaces.

# Synchronization & Reconciliation

***

DICT requires strong consistency between institutions and BACEN.

Institutions must implement:

### Periodic Sync

Pull updates for all keys that belong to the institution.

### Event-Driven Sync

Listen to DICT notifications for:

* Key activation
* Key deletion
* Claim creation/resolution

### Conflict Resolution

If a mismatch appears:

* Institution must update its records
* The institution must replace older or conflicting data
* Audit logs must record the transition

# Use cases

***

### Registering a Pix Key

A freelancer registers an email key for business payments.

### Porting a Key

A user moves a phone number key from one institution to another during a bank switch.

### Correcting Ownership

The institution reassigns a recycled mobile number to the new legitimate owner.

### Removing an Old Key

Business updates its EVP keys for accounting segmentation.

> [!TIP]
>
> **Regulatory reference**
>
> This page gives a practical overview of how Pix works. For deeper technical, legal, and regulatory details, always refer to the [official documentation](https://www.bcb.gov.br/estabilidadefinanceira/pix-normas) from the **Central Bank of Brazil (BACEN)**. It covers rule changes, deadlines, and official requirements.
>
> BACEN’s materials are the authoritative source for Pix regulations. They contain the most complete and current specifications.


# MED
Source: https://docs.lerian.studio/en/interfaces/pix/main-domains-med

Learn how the Pix MED process handles fraud, unauthorized transactions, and operational errors under BACEN deadlines, with pacs.004 refunds through SPI.

MED (Mecanismo Especial de Devolução) is the special refund mechanism of the **Central Bank of Brazil (BACEN)**. It defines how institutions investigate a disputed Pix transaction, communicate with each other, decide the outcome, and execute a refund.

MED is mandatory and follows one standard. It protects the consumer and keeps the process consistent and auditable across every institution.

# When MED applies

***

A Pix transaction enters the MED process when a financial institution needs a formal, regulated investigation. Common cases include:

* **Fraud** (phishing, account takeover, social engineering)
* **Unauthorized transactions** (the user did not approve the payment)
* **Operational errors** (duplicate sends, wrong recipient, wrong amount)
* **System or processing failures** that cause financial impact

MED runs independently of the standard Pix refund flows. A standard refund is voluntary. MED is mandatory and follows BACEN rules.

# Regulatory MED lifecycle

***

Every MED case runs as an **infraction report** with a fixed set of states. The report opens as `OPEN`, moves to `ACKNOWLEDGED`, and ends as `CLOSED` or `CANCELLED`. Each state carries its own BACEN deadline and response requirement.

### Lifecycle overview

![Stages and transitions of the Pix MED infraction-report lifecycle: OPEN, ACKNOWLEDGED, CLOSED, and CANCELLED](https://mintcdn.com/lerian-49cb71fc/Cb_meREQqa6luqbJ/images/en/d2/med-lifecycle.svg?fit=max\&auto=format\&n=Cb_meREQqa6luqbJ\&q=85\&s=500ab069c5c4e882282ef6587b8a63b9)

Figure 1. MED infraction-report lifecycle stages and transitions

# Integration points

***

MED is a regulatory process, but it works with the core Pix components:

| Component | Role |
| - | - |
| **DICT** | Provides fraud markers, key metadata, and ownership information |
| **SPI (pacs.004)** | Executes the refund movement between institutions |
| **Midaz Ledger** | Records the balance movements when a refund settles |
| **Pix Lerian services** | Coordinate the case lifecycle, deadlines, and notifications |

# Compliance expectations

***

An institution that runs MED must:

* Meet every regulatory deadline
* Keep a full audit trail with timestamps and event logs
* Send standardized MED messages to the counterpart institution
* Track each case status and its SLA
* Notify the customer consistently
* Use the correct dispute categories and reason codes

# Relationship with refunds and reversals

***

A **refund** and a **reversal** are standard Pix operations. MED provides the regulated mechanism for these cases:

* The refund is tied to fraud or unauthorized activity
* The originating institution disputes the transaction
* The case needs extra evidence and regulated communication

In these cases, the MED decision drives the refund. The institution does not process it as a voluntary action.

# Infraction reports

***

An infraction report is the formal way a Pix participant reports suspected fraud or unauthorized activity on a transaction. It is the entry point of the MED dispute-resolution process.

## When to file an infraction report

A Pix participant files an infraction report when a customer reports fraud or unauthorized activity. The report names the counterparty and starts the investigation. Pix Lerian receives the report as the counterparty. It can also cancel a report that it filed as the reporter.

An infraction report carries a **situation type** that classifies the dispute:

| Situation type | Meaning |
| - | - |
| `SCAM` | The customer was tricked into authorizing the payment |
| `ACCOUNT_TAKEOVER` | A third party took control of the account |
| `COERCION` | The customer paid under coercion |
| `FRAUDULENT_ACCESS` | The payment came from unauthorized channel access |
| `OTHER` | Another situation, described in the report details |
| `UNKNOWN` | The situation is not one of the categories above (BACEN catch-all) |

## Time limits and deadlines

An infraction report follows strict regulatory deadlines:

| Rule | Time limit |
| - | - |
| Transaction age limit | A report applies only to a transaction from the **last 80 days** |
| Analysis period | The counterparty has **7 calendar days** to analyze and close the report |
| Refund request window | After an `AGREED` close, the reporter has **72 hours** to create a refund request |
| Fund release | The blocked funds release when no refund request arrives within 72 hours |

## Infraction report lifecycle

An infraction report moves through these statuses:

| Status | Description |
| - | - |
| `OPEN` | The report is filed and waits for analysis |
| `ACKNOWLEDGED` | The counterparty received and acknowledged the report |
| `CLOSED` | Analysis is complete and the report closes with an `AGREED` or `DISAGREED` result |
| `CANCELLED` | The reporter cancelled the report (from `OPEN`, `ACKNOWLEDGED`, or `CLOSED` status) |

## Closure and automatic fraud markers

When an infraction report closes with an `AGREED` result, the system creates a **fraud marker** for the affected individual automatically. This links the investigation to the anti-fraud system and tracks the flagged individual across the Pix ecosystem.

## Available operations

* **List**: Query infraction reports with filters (status, situation type, linked funds recovery)
* **Retrieve**: Get the full details of one report
* **Acknowledge**: Acknowledge an `OPEN` report as the receiving counterparty
* **Close**: Submit the analysis with an `AGREED` or `DISAGREED` result
* **Cancel**: Cancel a report you filed (from `OPEN`, `ACKNOWLEDGED`, or `CLOSED` status)

# Refund requests

***

A refund request returns funds to the original sender after the participant confirms an infraction. It is the financial execution step of the MED process.

## When to create a refund request

You create a refund request after the participant investigates and closes an infraction report. The rules depend on the reason:

| Reason | Prerequisite |
| - | - |
| `FRAUD` | Needs a closed infraction report with an `AGREED` result. Create it within **72 hours** of closure. |
| `OPERATIONAL_FLAW` | Needs no prior infraction report. Use it for a processing error or operational issue. |

## Time limits

| Rule | Time limit |
| - | - |
| Transaction age | Create a refund request within **80 days** of the original transaction (**30 days** if the original was itself a refund) |
| Post-infraction window | For the `FRAUD` reason, create it within **72 hours** after the infraction closes |
| Monitoring period | For a partial refund or an insufficient-balance rejection, monitor the account and process more partial refunds as funds arrive |

## Analysis outcomes

When the counterparty analyzes a refund request, one of three outcomes applies:

| Result | Description |
| - | - |
| `TOTALLY_ACCEPTED` | The full refund is approved and executed |
| `PARTIALLY_ACCEPTED` | A partial refund is approved, for example on insufficient funds |
| `REJECTED` | The refund is denied, with a rejection reason |

A rejection carries one of these reasons: `NO_BALANCE` (insufficient funds), `ACCOUNT_CLOSURE` (a closed account), `INVALID_REQUEST` (a request that does not meet the rules), `PARTICIPANT_EXCLUSION` (the participant is excluded from settlement), or `OTHER`.

## Available operations

* **Create**: Open a new refund request for a transaction
* **List**: Query refund requests with filters (status, refund reason, transaction, infraction report, participant)
* **Retrieve**: Get the full details of one request
* **Close**: Submit the closure decision with the analysis result
* **Cancel**: Cancel a refund request before processing (only from `OPEN` status)

# Fraud markers

***

A fraud marker flags an individual (by CPF/CNPJ) and a Pix key as linked to fraudulent activity. It is part of the Pix anti-fraud ecosystem, managed through BACEN's DICT.

## How fraud markers are created

A fraud marker starts in one of two ways:

1. **Directly**: A participant registers a fraud marker for a tax ID and a Pix key through the API
2. **Automatically**: When an infraction report closes with an `AGREED` result, the system creates a fraud marker for the affected individual

## Fraud classification types

When an infraction report closes with `AGREED`, the reporter records a fraud classification:

| Type | Description |
| - | - |
| `APPLICATION_FRAUD` | Identity theft or a false application |
| `MULE_ACCOUNT` | An account used to receive and move illicit funds |
| `SCAMMER_ACCOUNT` | An account used to scam victims |
| `OTHER` | A fraud type outside the specific categories |

## Fraud marker lifecycle

| Status | Description |
| - | - |
| `ACTIVE` | The marker is active and visible in anti-fraud queries across the ecosystem |
| `INACTIVE` | The marker is cancelled and no longer active |

Only the participant that created a fraud marker can cancel it. A cancelled marker stays inactive. Create a new marker if you need one again.

## Available operations

* **Create**: Register a new fraud marker for a tax ID and a Pix key
* **List**: Query fraud markers
* **Retrieve**: Get the full details of one marker
* **Cancel**: Cancel a marker (only from `ACTIVE` status)

# Statistics and risk assessment

***

The MED statistics capabilities return aggregated anti-fraud and transaction data for risk assessment. This data helps an institution evaluate the risk of a person or a Pix key before it processes a transaction.

## What statistics are available

Statistics come at two levels:

### Person statistics (by CPF/CNPJ)

This level aggregates data for one individual or entity. The provider returns:

* **Settlement history**: The count of settled transactions over each period
* **Fraud markers**: Counts by fraud type
* **Total fraud amounts**: The monetary impact of fraud-related transactions
* **Infraction reports**: Open and rejected report counts
* **Registered accounts**: The count of accounts with Pix keys linked to this person

### Key statistics (by Pix key)

This level covers one Pix key, plus the current owner's statistics:

* **Key-level data**: Settlement history, fraud markers, infraction reports, and account registrations for the key
* **Owner-level data**: The full person statistics for the key's current owner

## Time periods

The provider aggregates statistics over three time windows:

| Period | Code | Description |
| - | - | - |
| 90 days | `d90` | Recent activity, most relevant for active fraud detection |
| 12 months | `m12` | Medium-term view of behavior patterns |
| 60 months | `m60` | Long-term historical context |

## Use cases

* **Pre-transaction risk scoring**: Query the destination key statistics before you approve a cash-out
* **Onboarding verification**: Check person statistics during account opening or key registration
* **Monitoring dashboards**: Track fraud-marker trends across your portfolio
* **Regulatory compliance**: Show due diligence in fraud prevention to auditors and regulators

> [!TIP]
>
> **Regulatory reference**
>
> This page gives a practical overview of Pix. For deeper technical, legal, and regulatory detail, always read the [official documentation](https://www.bcb.gov.br/estabilidadefinanceira/pix-normas) from the **Central Bank of Brazil (BACEN)**. It covers rule changes, deadlines, and official requirements.
>
> BACEN's materials are the authoritative source for Pix rules. They hold the most complete and current specifications.


# Main domains
Source: https://docs.lerian.studio/en/interfaces/pix/main-domains-overview

Explore Pix's four core domains (DICT keys, transactions, QR Codes, and MED refunds) plus BACEN principles for interoperability, security, and settlement.

Each domain owns a specific part of the instant payment flow. Together, the domains provide interoperability, security, and real-time execution across the ecosystem.

This overview introduces the four core domains of Pix.

Each child page in this section gives more detail.

## Core Pix domains

***

### DICT (Pix Key Directory)

The DICT is the national registry of Pix keys.

It maps simple identifiers (CPF/CNPJ, phone, email, random key) to transactional accounts. Users send and receive Pix without full bank details.

### Pix Transactions

This domain manages the execution lifecycle of an instant payment: authorization, validation, settlement, status updates, and traceability.

Every transaction flows through regulated paths and must settle within seconds in the SPI infrastructure.

### QR Codes

Pix supports static and dynamic QR Codes for payment initiation.

Static codes are reusable. Pix generates a dynamic code for each transaction. The dynamic code can carry the amount, metadata, and expiration.

### MED (Special Refund Mechanism)

The *Mecanismo Especial de Devolução* governs fraud-related refund scenarios.

It defines mandatory rules, timelines, and workflows for disputes, error handling, and fraud investigation across institutions.

## Additional Pix characteristics

***

Pix also follows system-wide principles for safety, inclusiveness, and nationwide compatibility.

### Universal interoperability

Every participant in Pix communicates through shared standards. Pix has no closed networks and no proprietary protocols.

Any participant can send and receive Pix with any other.

### Regulatory standardization

BACEN defines the rules, message formats, limits, fraud controls, and operational requirements.

All participants must follow the same specifications.

### Open participation model

Pix supports many types of institution:

* Banks
* Payment institutions
* Fintechs
* Digital wallets
* Cooperatives
* Government entities

### Security posture

Pix enforces a strict security framework with:

* Strong encryption
* Standardized authentication and authorization
* Mandatory fraud-prevention processes
* Full auditability and traceability of every event


# QR Codes
Source: https://docs.lerian.studio/en/interfaces/pix/main-domains-qrcodes

How Pix QR Codes work in Brazil: static BR Codes, dynamic immediate, cobrança with due date, Pix Automático recurrence, and Pix Saque withdrawal.

Pix QR Codes let users pay across apps, websites, and physical points of sale. Every Pix participant reads the same format, so the codes work across institutions.

Pix uses **EMV®-based structured payloads** that BACEN standardizes. Any institution can encode payment instructions in this scannable, machine-readable format.

Pix Lerian generates, decodes, and validates EMV Pix QR Codes, and it tracks each collection payment.

# Types of Pix QR Codes

***

Pix defines two primary categories of QR Codes:

* **Static QR Code** → reusable, fixed structure
* **Dynamic QR Code** → generated per transaction, with metadata, reconciliation, and expiration

The sections below describe each type against BACEN standards and common market usage.

# Static QR Code

***

### What it is

A reusable Pix QR Code holds a fixed payload tied to a Pix key (email, phone, CPF/CNPJ, EVP).

It does not expire. You can print, share, or display it, and it fits simple, low-volume payment scenarios.

### Characteristics

* Permanent and reusable
* Can embed a fixed `amount`. Omit it when you create an open-value QR Code, where the payer enters the amount.
* Simplest form of Pix acceptance
* Works offline (print, sticker, image)
* Complies with the EMV Pix static format

### Typical use cases

* Street vendors, cafés, kiosks
* Professionals (delivery drivers, barbers, tutors, freelancers)
* Donation campaigns
* One payment point shared by many payers

### Static QR Code payment flow

1. The merchant creates the QR Code once.
2. The customer scans it with any Pix-enabled app.
3. The payment follows the standard Pix flow: validation → SPI → credit.
4. Settlement happens instantly.

### Benefits

* Easy to create and deploy
* Reusable without limit
* Works well in physical settings
* Needs no extra infrastructure

### Limitations

* No automatic reconciliation

# Dynamic QR Codes

***

Each dynamic QR Code applies to one transaction and carries a structured payload with:

* predefined amount
* expiration time
* reconciliation identifiers
* metadata (order ID, description, payer details)

They add automatic reconciliation and traceability, which suits digital commerce.

Pix Lerian generates dynamic immediate charges. It does not yet generate due-date, recurring, withdrawal, or change QR Codes.

## Dynamic (Immediate)

***

### What it is

A one-time QR Code for instant payments, with:

* a preset amount
* a short expiration window
* a unique transaction correlation ID

### Ideal for

* E-commerce checkout
* Delivery apps
* POS systems
* Restaurants (per table or command)

### Characteristics

* Strong metadata and reconciliation support
* Expires automatically
* One-time use only
* Real-time webhook confirmation

## Pix Cobrança (Dynamic with Due Date)

***

### What it is

A dynamic QR Code for payments with a due date, similar to an invoice.

It carries:

* due date
* interest and late fees
* discounts or abatements
* payer identification

### Ideal for

* Schools and universities
* Condominium or association fees
* Subscription or recurring billing
* Professional invoices

### Characteristics

* Holds full billing information
* Stays valid until expiration
* Automatic reconciliation uses the charge ID

## Pix Automático (Recurrent)

***

Pix Automático sets up recurring collection authorizations.

The QR Code is the initial consent request for periodic debits.

### Ideal for

* Subscriptions
* Utility bills
* Monthly services

## Pix Saque (Withdraw)

***

### What it is

A QR Code that lets a customer withdraw cash from an authorized merchant.

### Ideal for

* Retail stores that offer ATM-like convenience
* Pharmacies, supermarkets, or convenience stores

## Pix Troco (Change)

***

### What it is

A QR Code for when the customer pays more than the purchase amount. The customer receives the product and gets the difference back as a Pix.

### Ideal for

* Supermarkets
* Gas stations
* Convenience stores

# Payment flow (all QR types)

***

![Payment flow for a Pix QR code, covering both static and dynamic QR types from scan to settlement](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/payment-qrcode-flow.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=665bb7d589132ef1c76b23aa3ea3f2fd)

Figure 1. Pix QR Code payment flow

## End-to-end Pix QR Code flow

***

1. **QR Code creation**

   The merchant or system creates a Pix QR Code, either static (reusable) or dynamic (transaction-specific).

   For a dynamic QR Code, the payload may hold a predefined amount, an expiration, and reconciliation identifiers.

2. **Payment initiation by the payer**

   The payer scans the QR Code with any Pix-enabled bank or wallet app. The payer reviews the payment details before confirmation.

3. **Pre-transaction validation by the payer’s institution**

   Before it sends the payment, the payer’s institution runs mandatory checks. These cover account status, available balance, transaction limits, and internal risk.

4. **Settlement through the Pix infrastructure**

   After approval, BACEN’s SPI routes the payment instruction for real-time settlement.

   If both accounts belong to the same institution, the institution may settle internally without crossing the SPI.

5. **Instant credit to the receiving institution**

   The receiving institution credits the funds to the beneficiary’s account right after settlement. This completes the payment.

6. **Confirmation and reconciliation**

   Pix Lerian emits webhook notifications with the payment result to merchant or system backends. The backends then reconcile automatically, confirm the order, and update accounting.

# Typical use cases

***

### Static

* A bakery prints a single QR Code for the counter
* A barbershop shares its QR Code on WhatsApp
* A street vendor displays a laminated QR Code

### Dynamic Immediate

* E-commerce checkout (one QR per order)
* Restaurants that generate a code per table
* Delivery apps that present a QR for each drop-off

### Dynamic Due Date

* Schools that generate a monthly QR Code invoice
* Condominium fees with interest or discount rules
* Freelancers that issue billed invoices

### Withdraw / Change

* A store offers Pix Saque at the counter
* A customer pays R$ 120 for a R$ 98 purchase and gets R\$ 22 back as Pix Troco

# Regulatory notes (BACEN)

***

Pix QR Codes must comply with:

* **EMV® Merchant-Presented Mode (MPM) specification**
* Pix “Iniciação por QR Code” rules
* Mandatory CRC validation
* A defined field structure for dynamic charges
* Expiration and billing rules for Cobrança (due-date QR)
* Transaction limits and the night window (when it applies)

> [!TIP]
>
> **Regulatory reference**
>
> Always refer to the [official documentation](https://www.bcb.gov.br/estabilidadefinanceira/pix-normas) from the **Central Bank of Brazil (BACEN)** for technical, legal, and regulatory details. BACEN publishes rule changes, deadlines, and official requirements there.
>
> BACEN’s materials are the authoritative source for Pix regulations. They hold the most complete and current specifications.


# Transactions
Source: https://docs.lerian.studio/en/interfaces/pix/main-domains-transactions

Follow a Pix transaction end-to-end: initiation, authentication, SPI settlement, E2E ID, and instant credit, plus cash-in and cash-out patterns.

Pix transactions represent the real-time movement of funds between accounts across all Pix participants. They follow the technical and regulatory standards of the Central Bank of Brazil (BACEN).

Pix transactions target speed, traceability, and interoperability. They keep consistent behavior regardless of the institution or front-end channel.

# Key characteristics

***

Pix transactions share a common foundation across all institutions:

### Instant settlement

Funds typically settle within **10 seconds**. SPI guarantees completion or handles the timeout transparently.

### 24/7 availability

Pix operates continuously, including weekends, holidays, and outside business hours.

### Irrevocability

After a Pix completes and credits the receiver, only regulated flows can reverse it (Refunds, Devoluções, MED).

### End-to-End ID (E2E)

Each Pix transaction receives a unique E2E identifier for auditability, reconciliation, and dispute handling.

### Interoperability

Any Pix participant can send or receive Pix from any other, independent of institution, platform, or channel.

### Configurable limits

Institutions must enforce regulatory and internal limits for security and fraud control.

# How a Pix transaction works (End-to-End Flow)

***

![End-to-end flow of a Pix transaction between the paying and receiving institutions](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/transaction-flow.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=4b06a6106ca1c059a3dca7ca7da2c915)

Figure 1. Pix Transaction Flow

A simplified cross-institution view of a Pix transaction follows:

1. **Initiation**

   The user starts a Pix transfer using one of the available addressing methods:

   * Pix key
   * QR Code (static or dynamic)
   * Manual bank details
   * Copy-and-paste EMV code

> [!NOTE]
>
> To learn more about Pix QR codes, visit the [QR Codes documentation](/en/interfaces/pix/main-domains-qrcodes).

1. **Authentication & authorization**

   The sending institution must authenticate the user with strong mechanisms (e.g., biometrics, 2FA, device trust).

   User consent is mandatory.

2. **Validation & risk checks**

   Before it sends anything to SPI, the institution must validate:

   * Account condition (active, not blocked, KYC verified)
   * Balance availability
   * Limits (transaction, daily, nightly, monthly)
   * Pix key validity (if applicable)
   * Risk assessments (anti-fraud indicators, velocity checks)

3. **Settlement attempt (SPI)**

   The institution submits the transfer to **SPI (BACEN’s Instant Payment System)**, which:

   * Validates the message
   * Routes it to the receiving institution
   * Settles the transaction between institutions

4. **Credit to receiver**

   The receiving institution must credit the account immediately, even if:

   * It occurs outside business hours
   * Systems are under load
   * Amount is high (except for flagged anti-fraud cases)

5. **Notifications & E2E generation**
   * Both institutions receive the updated transaction status
   * The transaction receives a unique **E2E ID**
   * Webhooks or internal notifications update systems and users

# Pix Transaction types

***

Pix transactions fall into a few standardized categories governed by BACEN.

## 1. Cash-Out (Send Pix)

The payer sends funds to another account using a Pix key, QR code, or bank details.

**Flow (summary):**

1. User initiates transfer
2. Institution checks balance + limits + key
3. Institution sends the transaction to SPI
4. Receiver credits instantly
5. Both parties receive updates + E2E ID

Common scenarios:

* P2P transfers
* Merchant payments
* Bill splitting
* Marketplace split payments (when paired with Pix Cobrança)

## 2. Cash-In (Receive Pix)

The customer receives a Pix transfer from any other institution.

**Flow (summary):**

1. SPI notifies the receiving institution
2. The institution must credit the account immediately
3. The institution dispatches notifications for reconciliation
4. The institution records the transaction with an E2E ID

Common scenarios:

* Salary or corporate disbursements
* Merchant settlements
* Recurring customer payments

## 3. Refund (Devolução)

Regulated flow that allows institutions to return funds to the original sender.

The following can trigger a refund:

* Customer request
* Merchant refunds
* Duplicate payments
* Operational errors
* Fraud-related MED cases

A refund must:

* Use BACEN standard messaging
* Link to the original transaction
* Follow value and eligibility rules

## 4. Reversal (Chargeback / pacs.004)

Used in special regulated cases, often tied to MED or operational corrections.

Reversals follow strict BACEN rules and are not the same as merchant refunds.

# Cash-out: two-phase transfer pattern

***

The Lerian platform processes a Pix cash-out in a **two-phase pattern** that separates validation from fund movement.

## Why two phases

A Pix transfer involves multiple validations: key lookup, account verification, balance checks, limit enforcement, and anti-fraud evaluation. A single step that runs all of them creates risk. If something fails after partial execution, reversal becomes complex.

The two-phase pattern solves this by splitting the process:

1. **Phase 1 (Initiate)**: Create an initiation and resolve destination details without moving funds
2. **Phase 2 (Process)**: Execute the fund transfer using the validated data

This separation provides several advantages:

* **User confirmation**: The initiating application can display validated destination details to the user before they confirm the transfer
* **Idempotency support**: The application can retry each phase independently, with no duplicate transfers
* **Compliance**: The platform completes and records regulatory validations before fund movement begins

## How it works

### Phase 1: Initiate

The initiation phase creates a transfer record. It retrieves and validates the destination information. No funds move at this stage.

The platform supports three initiation types:

| Type | Description | Input |
| - | - | - |
| `MANUAL` | Full destination account details provided directly | Bank, branch, account number, document, name |
| `DICT` | Destination resolved via Pix key lookup (DICT) | Pix key value (CPF, email, phone, EVP) |
| `QR_CODE` | Destination extracted from a QR code payload | BR Code (EMV) string |

For `DICT` and `QR_CODE` initiations, the platform queries DICT to resolve the destination account. The initiation returns the account holder name, document, and institution, which the application can display for user confirmation.

The initiation returns a unique identifier and an expiration timestamp. The application uses this identifier in the next phase.

### Phase 2: Process

The process phase takes the validated initiation and executes the actual fund movement:

* Verifies the initiation is still valid (not expired, not already processed)
* Debits the source account in the ledger
* Submits the payment to the Pix settlement infrastructure (SPI)
* Records the transfer with full traceability (end-to-end ID, timestamps, status)

After processing begins, the transfer follows the standard Pix settlement flow. You cannot cancel it. The regulated refund process is the only way to reverse it.

## Lifecycle summary

| Step | What happens | Funds moved? |
| - | - | :-: |
| **Initiate** | Validate destination, check key/QR, resolve account details | No |
| **User confirms** | Application displays details, user approves the transfer | No |
| **Process** | Debit source account, submit to SPI, credit destination | Yes |
| **Complete** | End-to-end ID assigned, both parties notified | — |

# Validation layers (Regulatory + Operational)

***

Every Pix transaction goes through multiple validations before it reaches SPI:

### 1. Account checks

* Account active
* Not blocked
* KYC complete

### 2. Funds availability

* Sufficient balance
* Temporary holds released

### 3. Pix key validation

If the user pays with a key, the institution must fetch and confirm the recipient’s details from DICT.

### 4. Regulatory limits

* Per transaction
* Daily limit
* Nightly limit (mandatory)

### 5. Risk & fraud checks

Institutions may enforce:

* Velocity checks
* Device fingerprinting
* Behavioral analytics
* Known-fraud markers

### 6. Idempotency

Each Pix transfer must have a unique transaction ID.

This avoids duplicate transfers during retries.

# Operational controls and safety

***

### Authentication requirements

Strong customer authentication is mandatory for all Pix send operations.

### Notifications & Webhooks

After crediting, institutions must notify systems and users.

Webhooks allow real-time reconciliation.

### Error handling

Common error categories include:

* Timeout
* Invalid key
* Insufficient funds
* Daily/nightly limit exceeded
* Suspicious transaction blocked

### Auditability

Pix mandates full traceability:

* Logs
* Timestamps
* E2E ID
* Account metadata

# Transaction limits (BACEN Rules)

***

Pix transaction limits exist to reduce fraud risk, protect end users, and maintain operational safety across the instant payment ecosystem. BACEN defines minimum security standards, and institutions may add restrictions depending on their risk appetite.

Pix limits fall into two groups: **mandatory regulatory limits** and **institution-defined limits**.

## 1. Mandatory regulatory limits (BACEN)

### Nighttime limit (Per-Transaction Cap)

Institutions must enforce a lower maximum limit between **20:00 and 06:00**.

Regulatory requirements:

* Default maximum: **R\$ 1.000**
* Institutions may set a lower default (e.g., R$ 500 or R$ 200)
* Customers may reduce this limit instantly
* Customers may increase this limit **only after a minimum wait of 24 hours**
* Customers may adjust the nighttime window (e.g., extend to 18h–08h)

This rule applies to:

* Pix transfer (cash-out)
* Pix QR Code payment
* Pix Saque/Troco
* Pix Cobrança payments initiated at night

Its purpose is to prevent fraud during higher-risk hours.

### Allowance for Customer-Controlled limits

Institutions must offer customers the ability to configure their own limits, per:

* Transaction
* Day
* Nighttime maximum
* Other forms of risk-based segmentation

These changes must respect BACEN timing rules:

* **Reductions** → must take effect immediately
* **Increases** → can only take effect **after a minimum of 24 hours** (security delay)

### Obligation to analyze requests for limit increase

Every institution must:

* Accept customer requests to increase limits
* Evaluate them through risk criteria
* Grant or deny based on fraud policy
* Apply increases only **after the regulatory waiting period (24h+)**

### Saque/Troco limits (Cash-Out at merchants)

Pix Saque and Pix Troco have their own caps:

* Default: **R\$ 500** per transaction
* Institutions may voluntarily offer up to **R\$ 3.000** per transaction
* Customers may reduce this limit instantly
* Increases follow the same 24h rule

These limits do not affect normal transfers. They are specific to cash withdrawal modalities.

### Credit obligations (independent of limits)

Even if a transfer exceeds the limits, after the receiver gets the credit:

* The transaction becomes irrevocable
* Only MED or refund flows can reverse it
* Institutions cannot “undo” a completed Pix on their own initiative

## 2. Institution-defined limits (Configurable)

Beyond mandatory rules, institutions may add their own controls, such as:

### Per-Transaction limit

Maximum allowed amount for a single Pix operation.

### Daily limit

Cap on total Pix amount per user per calendar day.

### Monthly limit (optional)

Used mainly by corporate accounts or fintech risk models.

### Risk-based segmentation

Institutions may offer:

* Stricter limits for new customers (ex.: first 7 days)
* Different limits for high-risk users or flagged accounts
* Dynamic limits adjusted by customer behavior

These internal controls must never conflict with BACEN requirements. They only complement them.

## 3. Operational rules required by BACEN

### Immediate limit reduction

Customers can lower their limits instantly.

### Delayed limit increase

All increases must respect:

* **24 hours minimum** before becoming effective
* Optional additional waiting period (institution’s choice)

### Peak risk hours

Nighttime limits apply specifically to cash-out flows, as they represent the main vector for fraud losses.

### Real-time enforcement

Institutions must check limits before they send a transaction to SPI.

The institution must reject a Pix that violates limits locally, before it reaches SPI.

## 4. Limit behavior in transaction lifecycle

### During a Pix initiation

The sending institution must verify:

* Available balance
* Transaction limit
* Daily limit
* Nighttime limit
* Saque/Troco limit (if applicable)
* Fraud/velocity limits
* Customer-configured limits

If a transaction violates any rule, the institution must reject it with an appropriate code.

### During retries

The institution must validate the limits again.

Idempotency prevents duplicate transfers but does not bypass limit checks.

### During merchant flows

Dynamic QR Codes must also respect:

* Customer limits
* Time-of-day rules
* Saque/Troco caps

Even if the merchant sets an amount, the payer’s institution decides whether to approve.

## 5. Recommended customer communication

BACEN requires institutions to:

* Explain limits clearly
* Offer customer self-service to adjust limits
* Show pending increases and activation dates
* Notify customers in case of suspicious behavior

## 6. Summary table

| Limit Type | Mandatory? | Default (BACEN) | Customer Controls | Activation Rules |
| - | - | - | - | - |
| Per-transaction | Optional | Institution-defined | Increase/reduce | Reduce = immediate / Increase = 24h |
| Daily | Optional | Institution-defined | Increase/reduce | Reduce = immediate / Increase = 24h |
| Nighttime (20h–06h) | **Yes** | **Max R\$ 1.000** | Customer customizable | Increase = 24h delay |
| Saque/Troco | **Yes** | R\$ 500 default | Customer configurable | Increase = 24h delay |
| Monthly | Optional | Institution-defined | Increase/reduce | Institution-defined |

> [!TIP]
>
> **Regulatory reference**
>
> This page provides a practical overview of how Pix works. For deeper technical, legal, and regulatory details, always refer to the [official documentation](https://www.bcb.gov.br/estabilidadefinanceira/pix-normas) published by the **Central Bank of Brazil (BACEN)**. It covers rule changes, deadlines, and official requirements.
>
> BACEN’s materials are the authoritative source for Pix regulations and contain the most complete and up-to-date specifications.


# Midaz with Pix Transaction Routes
Source: https://docs.lerian.studio/en/interfaces/pix/midaz-for-pix-transaction-routes

Model reusable Pix transfer flows in Midaz with Transaction Routes and Operation Routes, and enforce account and fee rules directly in the ledger.

Every Pix transaction follows a pattern: debit the sender, credit the receiver, and sometimes collect a fee. When that pattern lives only in application code, every team that touches Pix re-implements the same validation logic. Each implementation is another chance for inconsistency.

Transaction Routes move that pattern into the ledger. You define the rules once, and Midaz enforces them on every transaction. The result is a single source of truth for how Pix money flows through your system.

This page walks through two scenarios: a simple peer-to-peer transfer and a transfer with a fee. Each scenario shows how to set up the routes and what your team gains from them.

## What Transaction Routes give your teams

***

For **product and operations teams**, Transaction Routes give you auditable Pix flows without application-level enforcement. Every transaction carries a reference to the route it followed, so compliance reviews and incident investigations stay simple.

For **engineering teams**, routes remove repetitive validation code. You configure the account and fee rules once. Midaz then enforces them at the ledger level on every Pix integration.

| Without Routes | With Routes |
| - | - |
| Each integration must enforce its own account rules | Define the rules once, reuse across all Pix transactions |
| No automatic validation. Constraints live in application code | Midaz rejects transactions that don't match the route's rules |
| Adding fees requires changes across every Pix integration | Add a new Operation Route, create a new Transaction Route variant |
| Hard to trace which pattern a transaction was supposed to follow | Every transaction stores its route ID, so audits are straightforward |

For a deeper look at how Transaction Routes and Operation Routes work, see [Accounting Routes](/en/products/midaz/transaction-routing-entities).

## Prerequisites

***

Both scenarios assume a Midaz environment with the following structure already in place:

| Entity | Alias | Type | Purpose |
| - | - | - | - |
| Alice's account | `@alice_checking` | `checking` | Sender: Alice's main checking account |
| Bob's account | `@bob_checking` | `checking` | Receiver: Bob's main checking account |
| BRL asset | — | — | Brazilian Real, registered as the operating asset |

> [!NOTE]
>
> Values in Midaz are decimal amounts. For BRL, `150.00` means R\$ 150.00.

## Scenario 1: Simple Pix transfer

***

Alice sends R\$ 150.00 to Bob via Pix. The money moves from one checking account to another, with no fees and no splits.

### The goal

* Debit Alice's checking account by R\$ 150.00
* Credit Bob's checking account by R\$ 150.00
* Validate that both accounts are of type `checking` before processing
* Make this pattern reusable for every Pix transfer between checking accounts

### Setting up the routes

**1. Create the source Operation Route**

This route defines the debit side of the transfer. The `account_type` rule accepts any account of type `checking` as a source. The route does not hardcode a specific sender.

```json theme={null}
POST /v1/organizations/{org_id}/ledgers/{ledger_id}/operation-routes

{
  "title": "Pix - Debit Sender",
  "description": "Debits the sender's checking account in a Pix transfer",
  "code": "PIX-SEND-SRC",
  "operationType": "source",
  "account": {
    "ruleType": "account_type",
    "validIf": ["checking"]
  },
  "metadata": {
    "payment_method": "pix",
    "direction": "outbound"
  }
}
```

Save the returned `id`. You need it when you build the Transaction Route.

**2. Create the destination Operation Route**

This route defines the credit side. It uses the same rule type: any `checking` account qualifies as a valid receiver.

```json theme={null}
POST /v1/organizations/{org_id}/ledgers/{ledger_id}/operation-routes

{
  "title": "Pix - Credit Receiver",
  "description": "Credits the receiver's checking account in a Pix transfer",
  "code": "PIX-SEND-DST",
  "operationType": "destination",
  "account": {
    "ruleType": "account_type",
    "validIf": ["checking"]
  },
  "metadata": {
    "payment_method": "pix",
    "direction": "inbound"
  }
}
```

**3. Create the Transaction Route**

Group both Operation Routes into a single Transaction Route. This route represents "Pix Transfer" in your system.

```json theme={null}
POST /v1/organizations/{org_id}/ledgers/{ledger_id}/transaction-routes

{
  "title": "Pix Transfer",
  "description": "Standard Pix transfer between two checking accounts",
  "operationRoutes": [
    "<pix-send-src-id>",
    "<pix-send-dst-id>"
  ],
  "metadata": {
    "payment_rail": "pix",
    "spi_message_type": "pacs.008",
    "regulation": "BCB_PIX"
  }
}
```

Replace the placeholder IDs with the actual Operation Route IDs from the previous steps.

### Executing a Pix transfer

With the route in place, every Pix transfer references the Transaction Route ID in the `routeId` field. Midaz validates that the accounts match the route's rules before it processes the transaction.

```json theme={null}
POST /v1/organizations/{org_id}/ledgers/{ledger_id}/transactions/json

{
  "chartOfAccountsGroupName": "PIX",
  "description": "Pix transfer from Alice to Bob",
  "code": "PIX-20260306-001",
  "routeId": "<pix-transfer-route-id>",
  "send": {
    "asset": "BRL",
    "value": "150.00",
    "source": {
      "from": [
        {
          "accountAlias": "@alice_checking",
          "amount": { "asset": "BRL", "value": "150.00" },
          "description": "Pix sent to Bob",
          "routeId": "<pix-send-src-id>"
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@bob_checking",
          "amount": { "asset": "BRL", "value": "150.00" },
          "description": "Pix received from Alice",
          "routeId": "<pix-send-dst-id>"
        }
      ]
    }
  },
  "metadata": {
    "pix_end_to_end_id": "E123456782026030614300000000001",
    "pix_key_type": "cpf",
    "pix_key": "123.456.789-00"
  }
}
```

### How Midaz validates the transaction

**1. Midaz receives the transaction**

The request carries the Transaction Route ID in the `routeId` field. Midaz loads the route configuration.

**2. Source validation**

For each `from` entry, Midaz checks the account against the source Operation Route rules. Alice's account is type `checking`, so it matches the `account_type` rule. Validation passes.

**3. Destination validation**

For each `to` entry, Midaz checks the account against the destination Operation Route rules. Bob's account is type `checking`, so validation passes.

**4. Midaz processes the transaction**

Both validations pass, so Midaz creates the transaction atomically. It debits `@alice_checking` by R\$ 150.00 and credits `@bob_checking` by R\$ 150.00.

> [!TIP]
>
> If Alice sends from a `savings` account instead, Midaz rejects the transaction. The route accepts only `checking` accounts as sources, and you write no application-side validation.

## Scenario 2: Pix transfer with fee collection

***

This flow matches Scenario 1, but now the bank charges a R\$ 1.50 fee on each Pix transfer. The flow adds a third Operation Route for the fee destination, and Alice's total debit rises to R\$ 151.50.

### What changes

You already have the source and destination Operation Routes from Scenario 1. You add one Operation Route for the fee and a new Transaction Route that groups all three.

| Entity | Alias | Type | Purpose |
| - | - | - | - |
| Fee revenue account | `@revenue_pix_fees` | `revenue` | Internal account that collects Pix transfer fees |

### Setting up the fee route

**1. Create the fee Operation Route**

The previous routes use `account_type`. This one uses the `alias` rule type instead. It targets one specific account, `@revenue_pix_fees`, and no other account qualifies.

```json theme={null}
POST /v1/organizations/{org_id}/ledgers/{ledger_id}/operation-routes

{
  "title": "Pix - Fee Collection",
  "description": "Credits the bank's revenue account with the Pix transfer fee",
  "code": "PIX-FEE-DST",
  "operationType": "destination",
  "account": {
    "ruleType": "alias",
    "validIf": "@revenue_pix_fees"
  },
  "metadata": {
    "fee_type": "pix_transfer_fee"
  }
}
```

**2. Create the Transaction Route with fee**

This route groups the original source and destination routes with the new fee route. It is a separate Transaction Route from the simple transfer, so your system can offer both variants.

```json theme={null}
POST /v1/organizations/{org_id}/ledgers/{ledger_id}/transaction-routes

{
  "title": "Pix Transfer with Fee",
  "description": "Pix transfer between checking accounts with fee collection",
  "operationRoutes": [
    "<pix-send-src-id>",
    "<pix-send-dst-id>",
    "<pix-fee-dst-id>"
  ],
  "metadata": {
    "payment_rail": "pix",
    "includes_fee": true
  }
}
```

### Executing a Pix transfer with fee

Alice sends R\$ 150.00 to Bob. The bank collects R\$ 1.50. Alice's total debit is R\$ 151.50.

```json theme={null}
POST /v1/organizations/{org_id}/ledgers/{ledger_id}/transactions/json

{
  "chartOfAccountsGroupName": "PIX",
  "description": "Pix transfer from Alice to Bob (with fee)",
  "code": "PIX-20260306-002",
  "routeId": "<pix-transfer-with-fee-route-id>",
  "send": {
    "asset": "BRL",
    "value": "151.50",
    "source": {
      "from": [
        {
          "accountAlias": "@alice_checking",
          "amount": { "asset": "BRL", "value": "151.50" },
          "description": "Pix sent to Bob + transfer fee",
          "routeId": "<pix-send-src-id>"
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "@bob_checking",
          "amount": { "asset": "BRL", "value": "150.00" },
          "description": "Pix received from Alice",
          "routeId": "<pix-send-dst-id>"
        },
        {
          "accountAlias": "@revenue_pix_fees",
          "amount": { "asset": "BRL", "value": "1.50" },
          "description": "Pix transfer fee",
          "routeId": "<pix-fee-dst-id>"
        }
      ]
    }
  },
  "metadata": {
    "pix_end_to_end_id": "E123456782026030614300000000002",
    "fee_amount": "1.50"
  }
}
```

**Result:** Midaz debits Alice R\$ 151.50. Bob receives R\$ 150.00. The bank collects R\$ 1.50. All of this happens in one atomic transaction, balanced and auditable.

### What the fee route gives you

* **Transparent fee collection**: the fee is a first-class ledger entry, not hidden metadata. Finance and compliance teams see exactly where the R\$ 1.50 went.
* **Reusable building blocks**: the simple and fee variants share the source and destination Operation Routes. You add only what changes.
* **Route-level control**: your system can offer both "Pix Transfer" and "Pix Transfer with Fee" as distinct products, each backed by its own Transaction Route.
* **Easy evolution**: to add a percentage-based fee or a split across revenue accounts, create new Operation Routes and compose a new Transaction Route. Existing flows stay untouched.

## Understanding rule types

***

The two rule types serve different purposes. The right choice depends on whether the account in a route is dynamic or fixed.

| Rule type | `validIf` format | Behavior | When to use |
| - | - | - | - |
| `account_type` | **Array of strings** (e.g., `["checking"]` or `["checking", "savings"]`) | Accepts any account that matches one of the specified types | Dynamic participants: the sender or receiver can be any account of that type |
| `alias` | **String** (e.g., `"@revenue_pix_fees"`) | Must target a specific account by its alias | Fixed participants: the route always hits the same account, like a fee or settlement account |

> [!TIP]
>
> You can combine both rule types within a single Transaction Route. Scenario 2 uses `account_type` for the dynamic sender and receiver and `alias` for the fixed fee account.

## What you need to get started

***

| Requirement | Details |
| - | - |
| **Midaz** (v3.x.x+) | Core ledger with Transaction Route validation enabled |
| **Route validation config** | Enable route validation via the Ledger Settings API: `PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings` with `{"accounting": {"validateRoutes": true}}` |
| **Accounts and asset** | At minimum: two customer accounts and a BRL asset registered in the ledger |
| **Operation Routes** | One per operation leg (source, destination, fee) |
| **Transaction Route** | Groups the Operation Routes into a reusable pattern |

> [!NOTE]
>
> You must enable Transaction Route validation for each ledger. See [Working with Accounting Routes](/en/products/midaz/transaction-routing-entities#working-with-accounting-routes) for the configuration steps.

## Next steps

***

> **[Accounting Routes](/en/products/midaz/transaction-routing-entities)**
>
> Understand how Operation Routes and Transaction Routes work at a deeper level.

> **[Transactions](/en/products/midaz/transactions)**
>
> Learn about Midaz's double-entry transaction model and N:N capabilities.

> **[Pix with automated fees](/en/interfaces/pix/midaz-for-pix-with-fees)**
>
> Combine the Pix Plugin with the Fees Engine for automated fee management.

> **[Pix Lerian](/en/interfaces/pix-lerian)**
>
> Explore the unified interface for payments, keys, collections, and refunds.


# Midaz with Pix and automated fees
Source: https://docs.lerian.studio/en/interfaces/pix/midaz-for-pix-with-fees

Launch Pix with automated fees by combining Midaz, the Pix Plugin, and the Fees Engine for cash-in and cash-out with full double-entry audit trails.

To turn a payment rail into a product, you manage fees, split revenue, and keep a clear audit trail for every transaction.

You combine **Midaz** (the ledger), the **Pix Plugin** (Pix application orchestration), and the **Fees Engine** (automated fee logic, part of Midaz). Together they provide Pix operations with fee management and ledger postings in the same platform. Pix Lerian v1.0.0 is available for integration and testing with the mock provider adapter. The native SPI connector is not available for production use in this release.

This page walks through two scenarios.

## What each component does

***

Each component solves a specific layer of the problem:

| Component | Role |
| - | - |
| **Midaz** | Core ledger that records every debit, credit, and fee movement with double-entry precision |
| **Pix Plugin** | Pix application layer that handles transaction orchestration, DICT, QR Codes, and settlement-facing provider workflows. Pix Lerian v1.0.0 uses the mock provider for integration and testing; Pix BTG and Pix JD are separate deployed interfaces for production connectivity. |
| **Fees Engine** | Fee automation that calculates, splits, and routes fees based on configurable packages |

Together, these three parts connect the Pix application flow, fee calculation, and ledger postings. Validate the exact fee behavior and posting shape against the Fees Engine contract for your deployment.

## Choosing your Pix participation model

***

The Pix Plugin's application contract is designed for both participation models defined by BACEN. The fee integration and ledger flow on this page apply to both. For v1.0.0, use the mock provider adapter for integration and testing. The mock adapter is the only supported Pix Lerian integration path in this release.

| | Indirect Pix | Direct Pix |
| - | - | - |
| **How it connects** | Through a Direct Participant (e.g., BTG) | Through a certified PSTI (e.g., JD); the native Lerian SPI connector is not available in Pix Lerian v1.0.0 |
| **Best for** | Fintechs, payment institutions seeking fast onboarding | Banks and regulated FIs with full operational autonomy |
| **Regulatory burden** | Shared with the Direct Participant | Fully owned by the institution |
| **Time to market** | Weeks | Longer, but with maximum control |
| **Fees Engine integration** | Native | Native |
| **Midaz integration** | Mandatory | Mandatory |

> [!TIP]
>
> **Indirect Pix via BTG** is production-ready. Your institution connects through BTG's infrastructure, so you skip ISPB certification and direct BACEN connectivity.
>
> **Direct Pix via JD**: explore its capabilities in the [direct participation guide](/en/interfaces/pix-jd/direct-pix-via-jd).

For a detailed comparison, see [Pix participation models](/en/interfaces/pix/pix-modalities).

## Scenario 1: Fintech launching Pix with automated fees

***

A fintech plans to offer Pix to its customers. It wants to charge a flat fee on every incoming Pix (cash-in). The fee covers operational costs and adds revenue without extra complexity for the customer.

The fee logic and ledger structure stay the same for both models. This holds whether the fintech is an indirect participant (via BTG) or a direct participant (via JD).

### The business goal

* Offer instant Pix payments to end customers
* Charge a transparent, configurable fee on incoming transfers
* Record every fee in the ledger for compliance and financial reporting
* Launch quickly, without custom fee logic or reconciliation pipelines

### Setting up with Midaz

The fintech first structures its Midaz environment:

**1. Create the Organization**

Register the fintech as an Organization in Midaz. This is the top-level entity that owns all ledgers, accounts, and transactions.

**2. Set up the Ledger**

Create a Ledger to track all customer transactions and fee movements. The Pix Plugin and the Fees Engine share this ledger.

**3. Define the Asset**

Register **BRL** as the operating asset. All Pix transactions and fee calculations use this asset.

**4. Create customer accounts**

Each customer gets an account under the ledger. These accounts receive Pix credits and follow the fee rules.

**5. Create fee destination accounts**

Set up internal accounts to receive fee credits, for example a "Pix Fee Revenue" account. The Fees Engine package configuration references these accounts.

**6. Organize with Segments**

Use Segments to group customers by tier (e.g., Standard, Premium). This lets you apply different fee packages to different groups.

### Configuring the Fees Engine

With the ledger structure in place, the fintech configures a fee package:

* **Fee type**: Flat fee of R\$ 1.50 per incoming Pix
* **Scope**: Applied to all cash-in transactions on the main ledger
* **Routing**: The Fees Engine routes fee credits to the "Pix Fee Revenue" internal account
* **Exemptions**: Add Premium-tier accounts to the waived accounts list

The Fees Engine supports multiple calculation methods: flat fees, percentage-based fees, or a "max between" rule that applies whichever is greater. For this scenario, a flat fee keeps pricing predictable for customers.

> [!NOTE]
>
> You configure fee packages once, and the Fees Engine applies them automatically. When a Pix transaction matches the package criteria (ledger, segment, amount range), the Fees Engine calculates and routes the fee without any manual step.

### How a transaction flows

When a customer receives a Pix transfer, here is what happens:

**1. Pix arrives**

The sending institution initiates a Pix. Your connectivity provider (BTG for indirect, JD for direct) receives the transaction and notifies the Pix Plugin.

**2. Transaction is validated**

The plugin validates the recipient: it checks that the account exists, is active, and can receive funds. The plugin also checks CRM data and the Pix key validity.

**3. Settlement begins**

After the plugin confirms the transaction, settlement starts. The plugin fetches the destination account details from Midaz.

**4. Fees are calculated automatically**

The Fees Engine evaluates the transaction against available fee packages. It finds a matching package and calculates the R\$ 1.50 flat fee.

**5. Ledger records the full picture**

Midaz records the transaction with the fee distribution in a single operation:

* Midaz credits the customer's account with the **net amount** (gross minus fee).
* Midaz credits the fee destination account with **R\$ 1.50**.
* Every movement is traceable, with double-entry precision.

**6. Transaction is complete**

The customer sees the Pix credit in their account. The ledger records the fee for reporting and reconciliation.

### What the fintech gets

* **No custom fee logic**: the Fees Engine handles calculation, routing, and exemptions.
* **Accurate ledger**: every fee is a ledger entry. Auditors see the same numbers your finance team sees.
* **Customer segmentation**: the Fees Engine exempts Premium customers automatically through waived accounts.
* **Fee flexibility**: change fee values, add percentage-based fees, or introduce amount-based thresholds without changes to your transaction pipeline.

## Scenario 2: Marketplace with Pix and proportional fees

***

A B2B marketplace connects buyers and sellers. Buyers pay via Pix, and the marketplace charges a service fee on each transaction before it distributes the rest to sellers.

### The business goal

* Accept Pix payments from buyers
* Charge a percentage-based service fee on each payment
* Distribute the net amount proportionally across multiple sellers when a single payment covers goods from different sellers
* Maintain a clear audit trail for every split and fee

### Setting up with Midaz

The marketplace structures its Midaz environment to reflect the multi-party nature of its operations:

**1. Create the Organization**

Register the marketplace as an Organization in Midaz.

**2. Set up the Ledger**

Create a single Ledger to manage all payment flows: buyer payments, seller credits, and marketplace fees.

**3. Define the Asset**

Register **BRL** as the operating asset.

**4. Create seller accounts**

Each seller gets an account in the ledger. When a buyer pays via Pix, Midaz distributes the net amount across the relevant seller accounts.

**5. Create the marketplace fee account**

An internal account (e.g., "Marketplace Service Fee") receives the fee portion of every transaction.

**6. Use Segments for seller tiers**

Group sellers into segments (e.g., Standard Sellers, Partner Sellers) to apply different fee rates per group.

### Configuring the Fees Engine

The marketplace configures a fee package with proportional distribution:

* **Fee type**: 3% of the transaction value
* **Scope**: Applied to all incoming Pix payments on the marketplace ledger
* **Distribution**: The Fees Engine splits fees proportionally across source accounts when a single transaction covers multiple sellers
* **Routing**: Fee credits go to the "Marketplace Service Fee" account
* **Deductible**: The Fees Engine deducts the fee from the sellers' amount (`isDeductibleFrom: true`), so the buyer always sends the full amount

### How a transaction flows

A buyer purchases R\$ 1,000 worth of goods from three sellers:

| Seller | Share | Gross amount |
| - | - | - |
| Seller A | 50% | R\$ 500.00 |
| Seller B | 30% | R\$ 300.00 |
| Seller C | 20% | R\$ 200.00 |

**1. Buyer sends Pix**

The buyer scans a QR Code or uses a Pix key to send R\$ 1,000 to the marketplace.

**2. Pix arrives at the Plugin**

The connectivity provider processes the transaction and notifies the Pix Plugin.

**3. Fees are calculated with proportional split**

The Fees Engine calculates a 3% fee (R\$ 30.00) and distributes it proportionally:

* Seller A: R$ 15.00 fee (R$ 485.00 net)
* Seller B: R$ 9.00 fee (R$ 291.00 net)
* Seller C: R$ 6.00 fee (R$ 194.00 net)

**4. Ledger records every movement**

Midaz creates the transaction with full distribution:

* Seller A's account: credited R\$ 485.00
* Seller B's account: credited R\$ 291.00
* Seller C's account: credited R\$ 194.00
* Marketplace fee account: credited R\$ 30.00
* Total: R\$ 1,000.00 (fully balanced)

**5. Sellers and marketplace are settled**

Each seller sees their net credit. The marketplace sees the fee revenue. Every number ties back to a ledger entry.

### What the marketplace gets

* **Automated revenue split**: the Fees Engine handles proportional distribution across any number of accounts.
* **Transparent pricing for sellers**: each seller sees the exact fee and the reason for it.
* **Balanced ledger**: gross amount in equals the sum of all credits out. No rounding gaps, no manual adjustments.
* **Configurable rates**: change the fee percentage, add flat minimums, or exempt specific partners, all through fee package configuration.

## What you need to get started

***

To run this setup, your institution needs:

| Requirement | Details |
| - | - |
| **Midaz** (v4.x.x+) | Core ledger for account management and transaction recording |
| **Pix Plugin** | Pix application orchestration. Use the mock adapter for v1.0.0 integration/testing. Pix BTG and Pix JD are separate interfaces for production connectivity |
| **Fees Engine** | Automated fee calculation and routing (a Midaz Enterprise capability, deployed independently) |
| **CRM** | Customer and account data for Pix validation (part of Midaz) |
| **Infrastructure** | Self-managed cloud (BYOC) or on-premise environment |
| **Connectivity contract** | Agreement with BTG (indirect) or JD/PSTI (direct) depending on your model |

> [!NOTE]
>
> The Pix Plugin and the Fees Engine require a valid Lerian license. The Fees Engine falls under the Midaz Enterprise tier. For license details, see the [License documentation](/en/start-here/evaluate-and-deploy/lerians-license).

## Estimating before going live

***

Before you process real transactions, use the Fees Engine estimate to check your fee configuration.

The estimate lets you:

* Preview the exact fee for a given transaction amount
* Check that exemptions work as expected
* Confirm proportional splits produce the correct distribution
* Test edge cases like boundary amounts and waived accounts

This helps most during onboarding, before you set final fee structures with business stakeholders.

> [!TIP]
>
> Use the [Estimate Transaction Fees](/en/reference/products/midaz/v2/estimate-fee-calculation) endpoint to test specific fee packages without writing to the ledger.

## Next steps

***

> **[Fees Engine overview](/en/products/midaz/fees/fees-engine-overview)**
>
> Understand fee packages, calculation rules, and routing options.

> **[Using Fees Engine](/en/products/midaz/fees/using-fee-engine)**
>
> Step-by-step guide to creating packages and processing fees.

> **[Direct vs. Indirect Pix](/en/interfaces/pix/pix-modalities)**
>
> Compare participation models and choose the right connectivity path.

> **[Pix Lerian](/en/interfaces/pix-lerian)**
>
> Explore the unified interface for payments, keys, collections, and refunds.


# Best practices
Source: https://docs.lerian.studio/en/interfaces/pix/pix-best-practices

Best practices for reliable Pix integrations: idempotent endToEndId keys, webhook confirmation, HMAC signatures, and retry and observability patterns.

Following the practices below helps ensure predictable behavior, operational safety, and compliance with BACEN’s expectations, especially under volume, network instability, or dispute scenarios.

These recommendations apply to all Pix use cases: wallets, merchant payments, cash-outs, QR Code flows, recurring operations, and internal transfers.

# 1. Use an idempotent payment key

***

On the Pix payment flow, the BACEN `endToEndId` is your **idempotency key**. It is a unique, immutable 32-character identifier that you supply, or that Pix Lerian generates. You can retry safely only when you own the value.

Treat the `endToEndId` as your **idempotency key**:

* If you retry a request after a timeout, **reuse the same `endToEndId`**.
* If the first attempt already created the payment, Pix Lerian replays the existing one.
* If the first attempt failed before processing, the retry creates the payment exactly once.

This prevents:

* Duplicate ledger postings
* Double debits
* Manual operational fixes
* Reconciliation inconsistencies

**Never generate a new `endToEndId` for a retry.**

For the header-level idempotency behavior of each Lerian product, see [Retries and idempotency](/en/reference/retries-idempotency).

# 2. Rely on webhooks for final transaction status

***

A `200 OK` from the API **does not guarantee the Pix was completed**.

It only means the request entered the orchestration flow.

Confirm the final status through a webhook or [Get Transfer](/en/reference/interfaces/pix-lerian/spi/get-transfer):

* Persist webhook status in your system
* Handle both success and failure notifications

Waiting for the webhook aligns your UI to SPI-confirmed settlement. This reduces disputes and false positives.

# 3. Validate webhook authenticity

***

Every webhook includes an HMAC signature (e.g., `X-Signature`).

Best practices:

* Store the secret in a vault
* Recompute the HMAC using the **raw request body**
* Compare with the header
* Reject and log mismatches

This protects against:

* Fake callbacks
* Tampered payloads
* Unauthorized requests hitting your endpoint

Webhook security is a PSP-level requirement.

# 4. Design for failure and retries

***

Pix is instant, but the network around it is not.

Expect failures in:

* PSTI / direct provider connectivity
* Telecom / SMS delivery (for key confirmation)
* Network timeouts
* Internal ledger validations
* Limit and anti-fraud checks (regulated)

Recommended approach:

* Implement clear retry policies (exponential backoff, controlled loops)
* Never retry blindly
* Surface actionable messages to the user
* Log all failures with correlation IDs
* Treat “pending” as a normal intermediary state

# 5. Monitor pending transactions & background jobs

***

A Pix can enter **PENDING** while waiting for:

* Provider processing
* SPI acknowledgment
* Webhook delivery
* Retry cycles

Pix Lerian runs background workers to guarantee eventual consistency:

* Retry callbacks
* Reconcile intermediate states
* Detect stuck operations

Your responsibilities:

* Monitor pending transactions regularly
* Configure alerts for excessive retry attempts
* Integrate logs, metrics, and traces for observability

**Pending ≠ failure**, but prolonged pending requires investigation.

# 6. Keep Pix keys and customer data synchronized

***

Because keys are tied to identity:

* If a user changes phone/email → update or remove associated Pix keys
* Keep CRM records aligned with DICT data
* Remove outdated keys to avoid misrouting
* For institutions using DICT:

  Ensure portability and ownership claims follow BACEN rules

This reduces:

* Payments to wrong recipients
* MED cases due to incorrect keys
* Support friction

Keep CRM, DICT, and Pix Lerian consistent with each other.

# 7. Respect SLA expectations and time windows

***

Pix settlement occurs in **up to 10 seconds**, but legal SLAs matter too.

Design your UX to respect:

* Maximum SPI tolerances
* Nighttime limit adjustments (20:00–06:00)
* Customer-driven limit reduction delays (immediate)
* Customer-driven limit increases (may require authentication or waiting period)

Always display:

* “Processing…” while awaiting confirmation
* “Try again” guidance for limit breaches

Your UX must mirror Pix’s regulatory behavior.

# 8. Implement reconciliation and accounting validation

***

Reconciliation closes the loop between:

* Your system
* Pix Lerian
* SPI settlement
* Ledger postings (Midaz)

Recommended reconciliation cycle:

* Confirm every settled Pix using your webhook log
* Match every Pix ID with a ledger posting
* Compare daily summaries with provider/SPB outputs
* Flag any mismatch for manual review

This reduces operational noise and supports audit readiness.

# 9. Test end-to-end with realistic flows

***

Before going live, simulate:

* Cash-in and cash-out
* High-value limits
* Invalid keys
* Expired QR Codes
* Refunds (inbound + outbound)
* MED-related refund triggers
* Webhook downtime
* API timeout and retry patterns

Also test **intra-ledger Pix** scenarios when both accounts exist in Midaz.

Your validation checklist:

* Correct ledger postings
* Correct Pix status transitions
* Proper webhook handling
* Proper limit enforcement
* Proper accounting behavior

# 10. Prepare your support and operations teams

***

Support teams should understand:

* Pix timeframes (including night limit rules)
* Difference between “initiated”, “pending”, “completed”, “refunded”, “failed”
* How to read E2E IDs
* How to track DICT issues
* When MED applies vs normal refunds

Clear support flows reduce user friction and avoid false MED disputes.


# Pix glossary
Source: https://docs.lerian.studio/en/interfaces/pix/pix-glossary

Look up Pix terms and BACEN acronyms: DICT, SPI, ISPB, E2E ID, cobrança, portability, MED, and Direct and Indirect participant definitions.

Pix is governed and standardized by the Central Bank of Brazil (BACEN). This glossary consolidates concepts, infrastructure components, operational terms, regulatory definitions, and participant types used across the ecosystem.

Use this page as a quick reference while reading Pix documentation or integrating Pix into your financial system.

***

## A

***

### Account Identifier

The banking details used to receive or send a Pix without a Pix key.

Includes: bank (ISPB), branch, account number, and account type (CACC, SVGS, SLRY, TRAN).

### Alias (Pix Key)

See **Pix Key** below.

***

## B

***

### Bacen / BACEN

Banco Central do Brasil: the regulatory authority responsible for designing, operating, and supervising Pix.

### SPI Gateway Certification

A mandatory certification process required for participants that connect directly to the Pix infrastructure (SPI/DICT). Ensures cryptographic and operational compliance.

***

## C

***

### Cash-In

A Pix received from an external sender into the institution’s account.

### Cash-Out

A Pix sent from the institution to an external recipient.

### Charge (Pix Cobrança)

Payment request issued via Pix, often with due dates, penalties, and interest rules. Used mainly for invoices and billing.

### Claim (Portability & Ownership)

A regulatory workflow used to transfer or confirm ownership of a Pix key between institutions.

There are two types:

* **Portability** – moving a key to another institution
* **Ownership Claim** – asserting ownership when a key is registered inconsistently

Both require user approval and follow DICT rules.

### Confirmation Window

The allowed time for a user to approve or reject a Pix key portability or ownership claim.

### CICC / Câmaras Interbancárias

Clearing houses connected to BACEN systems. Some regulatory flows reference them.

***

## D

***

### DICT (Directory of Transactional Account Identifiers)

BACEN’s official directory of Pix keys.

Stores:

* key type
* owner (CPF/CNPJ)
* associated account
* creation & update history

DICT enables sending money using simple identifiers rather than full account details.

### Direct Participant

An institution that connects **directly** to SPI and DICT with its own certified infrastructure.

### Dynamic QR Code

A one-time-use QR Code containing full payment details, including value, expiration, and transaction metadata. Supports Cobrança Pix and automated reconciliation.

### Due Date Charge (Cobrança com Vencimento)

A Pix charge with a predefined due date and rules for penalties, discounts, and interest.

***

## E

***

### E2E ID (End-to-End Identifier)

A unique identifier generated for every Pix transaction.

Used for:

* traceability
* dispute resolution
* reconciliation
* fraud analysis

***

## F

***

### FRA (Fraud-Related Refund Request)

A special refund mechanism triggered when a transaction is identified as fraudulent. Governed by strict deadlines and workflows.

***

## G

***

### Gateway (SPI/DICT Gateway)

The secure communication channel used by direct participants to connect to BACEN’s Pix systems.

***

## I

***

### Immediate Pix

A transfer settled instantly (typically \< 10 seconds) through SPI.

### Indirect Participant

An institution that offers Pix through a **Direct Participant**, instead of connecting directly to BACEN.

### ISPB

Identificador de Sistema de Pagamentos Brasileiro: the unique numerical identifier of every financial institution in Brazil.

***

## K

***

### KYC (Know Your Customer)

Regulatory verification of customer identity used to prevent fraud and ensure DICT accuracy.

***

## L

***

### Limits (Pix Limits)

BACEN-defined and institution-defined rules restricting the maximum value a user can send or receive within certain windows (daytime, nighttime, custom limits).

***

## M

***

### MED (Mecanismo Especial de Devolução)

The Special Refund Mechanism for fraud or operational error cases.

Allows institutions to:

* request refunds
* analyze fraud claims
* return funds following mandatory rules

### Merchant Initiated Pix

When a business triggers a Pix charge using static or dynamic QR Codes.

***

## O

***

### Ownership Claim

A process for asserting that the customer is the rightful owner of a Pix key held by another institution.

***

## P

***

### Participant (Direct / Indirect)

Institutions authorized by BACEN to offer Pix services.

### Payer

The sender of a Pix transaction.

### Payee

The receiver of a Pix transaction.

### PSTI (Provedor de Serviços de Tecnologia da Informação)

BACEN-regulated technology provider that allows institutions to connect to the national financial network (RSFN) for Pix.

Used when the institution does not maintain its own direct infrastructure.

### Portability (Key Portability)

Moving a Pix key from one institution to another, with customer consent.

### Pix Key

A unique identifier used as a shortcut for receiving payments. Types include:

* CPF
* CNPJ
* Phone number
* Email
* EVP (random key)

### Pix Saque

Withdrawal of physical cash using Pix at ATMs or merchants.

### Pix Troco

Cash withdrawal combined with a purchase: customer pays more than the purchase amount via Pix and receives the difference in cash.

***

## Q

***

### QR Code: Static

Single QR Code reused for multiple payments. The customer enters the value manually.

### QR Code: Dynamic

Single-use QR Code containing full payment data. Automatically expires.

***

## R

***

### Refund (Devolução)

Reversing a Pix transaction.

Types include:

* standard refund
* partial refund
* special refund (MED)

### Reconciliation

Matching Pix events (sent, received, confirmed) across SPI, DICT, ledger, and internal records.

### RSFN (Rede do Sistema Financeiro Nacional)

The secure national network used for communication with BACEN systems.

***

## S

***

### SPI (Instant Payment System)

BACEN’s infrastructure that routes and settles Pix transactions in real-time.

### Static QR Code

Reusable QR Code linked to a Pix key. Does not expire.

### Settlement

The moment funds are transferred between institutions in SPI.

***

## T

***

### Transaction ID

Unique identifier created by the initiating institution to track a Pix payment.

### Transaction Status

Positions include:

* Pending
* In Analysis
* Completed
* Refunded
* Failed

### Transfer Window

The time window that affects Pix limits (daytime/nighttime).

***

## V

***

### Validation

Regulatory and operational checks performed before executing a Pix transaction, including limits, anti-fraud, key ownership, and account status.

***

## W

***

### Webhook

Callback mechanism used to deliver real-time transaction status to client systems.


# Jobs and retry logic
Source: https://docs.lerian.studio/en/interfaces/pix/pix-jobs-and-retry-logic

Recover Pix operations automatically with background jobs that retry failed events, reconcile refunds, and keep data consistent.

The Pix plugin recovers operations automatically with background jobs and retries. If a provider call times out or an event fails to process, the plugin retries and reconciles the data without manual work.

## Automatic retries

***

The plugin processes Pix events asynchronously. If it fails to process an event, the plugin retries in place, then captures the event to a dead-letter queue without loss. An operator replays a parked event, bounded to a maximum number of attempts. After the limit, the record stays parked for inspection and the plugin never drops it.

The plugin retries outbound calls to the provider on 5xx responses and timeouts. Each retry uses exponential backoff with jitter.

> [!TIP]
>
> The plugin deduplicates events by ID for a fixed time window. A retried or duplicate event never applies twice, so the jobs stay idempotent.

## Refund reconciliation

***

A refund can succeed at the provider but fail to record locally if the service crashes between the two steps. The refund reconciliation sweeper is a background safety net for this case.

The sweeper runs on a timer and finds refunds still stuck in pending. For each one, it re-drives the idempotent steps (settle, confirm, or close), which the provider deduplicates by refund reference. It parks a row still at the create step for an operator, because a blind create replay could cause a double refund.

```mermaid theme={null}
sequenceDiagram
  participant Sweeper
  participant Provider
  participant DB
  Sweeper->>DB: Find pending refund rows
  Sweeper->>Provider: Re-run the missing step
  alt Success
    Provider-->>Sweeper: confirmed
    Sweeper->>DB: Mark as done
  else Still failing
    Provider-->>Sweeper: error
    Sweeper->>DB: Record attempt and back off
  else Attempts exhausted
    Sweeper->>DB: Park row and raise alert
  end
```

Each failed attempt waits longer than the last, from one minute up to one hour. After a maximum number of attempts, the sweeper parks the record and raises an alert. It does not retry forever. The sweeper is optional and off by default.

## Configuration

***

You can tune retry and reconciliation behavior with environment variables:

| Variable | Description | Default |
| :- | :- | :- |
| `DLQ_REPLAY_MAX_ATTEMPTS` | Times an operator can replay a parked event before it stays parked | 3 |
| `CONSUMER_DEDUP_TTL_SEC` | Deduplication window, in seconds, that keeps event processing idempotent | 3600 |
| `REFUND_RECONCILIATION_SWEEPER_ENABLED` | Turns on the refund reconciliation sweeper | false |
| `REFUND_RECONCILIATION_SWEEPER_INTERVAL_SEC` | Time, in seconds, between sweeps | 30 |
| `REFUND_RECONCILIATION_SWEEPER_MAX_ATTEMPTS` | Attempts before the sweeper parks a record and raises an alert | 10 |

## What you need to do

***

The plugin manages retries and reconciliation for you. The default settings fit most deployments. To keep operations healthy:

* Use unique, traceable IDs for your transactions and accounts.
* Monitor event delivery and transaction status.
* Contact Lerian for job visibility or event replay support.


# Pix modalities
Source: https://docs.lerian.studio/en/interfaces/pix/pix-modalities

Compare Pix modalities defined by BACEN: standard transfer, static and dynamic QR Codes, Pix Saque, Pix Troco, Pix Cobrança, and Pix Automático.

Pix supports multiple modalities. They range from instant transfers to QR code payments, cash withdrawals, and invoice-based collections. Each modality has its own rules, requirements, and operational flows. The national payment system standardizes all of them.

This page describes the core Pix modalities and how they operate within the BACEN regulatory framework.

# 1. Pix Transfer (Standard transfer)

***

Pix Transfer is the most common modality, an instant transfer between two accounts. The payer identifies the recipient with one of these:

* Pix keys (CPF/CNPJ, phone, email, EVP)
* Manual entry (bank, branch, account, and recipient name)
* Copy-and-paste codes (BR Code string)

**Use cases**

* Person-to-person transfers
* Merchant payments without QR codes
* Internal and external account movements

**Requirements**

* Sender must authenticate
* Recipient must be a Pix participant
* Transaction must pass fraud and risk checks

**Rules & limitations**

* Instant settlement (seconds)
* Available 24/7
* Daily or nightly limits may apply (risk-based)

**Flow (simplified)**

1. The sender authenticates and initiates the payment.
2. The institution validates the account, balance, limits, and risk indicators.
3. SPI settles the transaction.
4. The receiver's account receives the credit instantly.

# 2. Pix QR Code

***

Pix supports QR codes for payment initiation. They follow BACEN's BR Code standard and fall into two categories:

## Static QR Code

***

A reusable QR code that contains:

* Fixed recipient information
* Optional fixed amount
* Optional additional reference

**Typical uses**

* Small merchants
* Donation links
* Informal commerce

**Characteristics**

* The same QR code serves all payments
* The payer can edit the amount
* Minimal update requirements

## Dynamic QR Code

***

The recipient's PSP generates a dynamic QR code for **each transaction**. It provides more features and security.

Two official types:

### Dynamic Immediate

* One-time use
* Predefined amount
* Expiration timestamp
* Additional data fields for reconciliation

Use cases: e-commerce checkout, POS systems, service providers.

### Dynamic with Due Date

* Support for future due dates
* Multiplier fields
* Penalties, fines, interest
* Updates via additional Pix Cobrança APIs

Use cases: billing, invoicing, utilities, subscription payments.

**Rules & limitations**

* QR codes follow BACEN's BR Code standard, based on the EMV QR Code specification
* Every BR Code carries a CRC16 checksum in the CRC field. A dynamic QR code also references a payload that the payer's app retrieves from a URL

# 3. Pix Saque and Pix Troco

***

Pix Saque and Pix Troco enable cash withdrawal at participating merchants.

## Pix Saque

***

The customer sends a Pix transfer to withdraw cash.

Flow:

1. The customer initiates Pix Saque.
2. The merchant receives the Pix.
3. The merchant hands over the equivalent cash.

Use cases: cash access in areas without ATMs.

## Pix Troco

***

The customer pays a value *higher* than the purchase and receives the difference in cash.

Example: item costs R$70 → customer sends R$100 → receives R\$30 in cash.

**Requirements**

* Merchant must opt into Pix Saque/Troco
* Merchant must publish maximum withdrawal thresholds

**Limits (BACEN)**

* Daily and per-transaction limits may vary
* Typically higher limits during daytime

# 4. Pix Cobrança (Invoice-Based Pix)

***

Pix Cobrança is Pix's equivalent of billing.

It supports:

* Charge requests with or without due dates
* Automatic calculation of penalties, fines, and interest
* Updates to charges
* Cancellation and reconciliation flows

Two formats:

### Cobrança Imediata (Immediate Charge)

The payer must pay instantly. This format applies to POS or service scenarios.

### Cobrança com Vencimento (Due Date Charge)

This format supports future dates. Use it for:

* Utilities
* Tuition
* Subscriptions
* Merchant billing

**Rules**

* Each charge must contain a unique transaction ID
* Penalties must follow the configured rules
* Expired charges accept payments only if the configuration allows it

# 5. Pix Agendado (Scheduled Pix)

***

*(If the institution supports it)*

Pix Agendado allows the payer to schedule a Pix payment for a future date.

Use cases:

* Bill payments
* Recurring transfers
* Salary disbursements (internal)

**Characteristics**

* The institution must allow scheduling
* The institution validates Pix Agendado at scheduling time and at execution time
* The payer can cancel according to institutional rules

# 6. Pix Automático (Automatic Pix)

***

Pix Automático will support registered agreements. Under an agreement, the system debits the payer's account automatically.

Expected features:

* Mandate-based authorization
* Automatic recurring debits
* Pre-notification of due charges
* Cancellation support

Ideal for:

* Subscriptions
* Utility bills
* Tuition
* Insurance premiums

# 7. Pix Internacional (Cross-Border Pix)

***

Pix Internacional aims to enable instant payments between Brazil and partner jurisdictions.

Expected characteristics:

* Currency conversion
* Risk and AML checks
* SPI interoperability with partner infrastructures
* Transparent end-to-end flow

The characteristics above reflect the intended design of this modality.

# 8. When to use each modality

***

### Use standard Pix transfer for:

P2P transfers, small purchases, splitting bills.

### Use static QR for:

Small merchants, service providers, simple collection.

### Use dynamic QR for:

E-commerce, delivery, POS, billing.

### Use Pix Saque/Troco for:

Extending cash withdrawal coverage.

### Use Pix Cobrança for:

Recurring billing, utilities, formal invoicing.

### Use Pix Agendado for:

Future payments without immediate settlement.

### Use Pix Automático for:

Recurring agreements (subscriptions, utilities).

### Use Pix Internacional for:

Cross-border instant transfers (when released).

> [!TIP]
>
> **Regulatory reference**
>
> This page provides a practical overview of how Pix works. For deeper technical, legal, and regulatory details, refer to the [official documentation](https://www.bcb.gov.br/estabilidadefinanceira/pix-normas) published by the Central Bank of Brazil (BACEN). These materials keep you up to date with rule changes, deadlines, and official requirements.
>
> BACEN's materials are the authoritative source for Pix regulations and contain the most complete and up-to-date specifications.


# Plugin use cases
Source: https://docs.lerian.studio/en/interfaces/pix/pix-use-cases

Explore end-to-end Pix use cases combining Midaz with the Pix Plugin, Fees Engine, and Transaction Routes to automate fees and enforce ledger rules.

Plugins extend Midaz with domain-specific capabilities: Pix application orchestration, bank transfers, and more. The use cases below show how these plugins work with the core ledger to build complete financial workflows.

Each use case describes a scenario. It covers the entities involved, the transaction flow, and what your team gains.

### Pix

Pix is Brazil's instant payment system. To build a Pix product, you connect to BACEN's infrastructure. Institutions must also calculate and route fees, enforce consistent transaction patterns, and keep a clear audit trail for every movement.

* **[Pix with automated fees](/en/interfaces/pix/midaz-for-pix-with-fees)**: Combine the Pix Plugin with the Fees Engine. Launch Pix with automatic fee calculation, splitting, and double-entry recording, with no custom middleware.
* **[Pix with Transaction Routes](/en/interfaces/pix/midaz-for-pix-transaction-routes)**: Define reusable transfer patterns in the ledger with Transaction Routes and Operation Routes. Midaz then enforces the rules on every Pix transaction.

> [!TIP]
>
> For use cases that focus on Midaz Core without plugins, see [Midaz use cases](/en/products/midaz/use-cases).


# Accounting Routes
Source: https://docs.lerian.studio/en/interfaces/ted-jd/console/bt-accounting-routes

Bind each organization, ledger, and transfer type to the Midaz accounting routes that the Bank Transfer plugin posts with, and check cutover readiness in Lerian Console.

The **Accounting Routes** page of the **Bank Transfer** plugin binds each organization, ledger, and transfer type to the Midaz accounting routes that the plugin posts with. The combination of organization, ledger, and transfer type is a **scope**.

You create the routes in Midaz. This page only brings them in. See [Managing accounting routes](/en/products/midaz/console/managing-accounting-routes).

Each Bank Transfer screen needs the `bank-transfer` permission: `get` to see it, `post` to act on it, `patch` to change settings and the routing document, and `delete` to delete a webhook.

> [!WARNING]
>
> The plugin has no fallback route. It refuses the outgoing transfers of a scope without a binding. It holds the incoming credits of that scope, and does not return them on its own.

## Accessing the page

***

**1. Open Bank Transfer**

From the Midaz Module sidebar, expand **Bank Transfer**.

**2. Click Accounting Routes**

Select **Accounting Routes** in the submenu.

The page has two parts: **Cutover readiness** at the top, and **Bindings** below it.

## Cutover readiness

***

**Cutover readiness** is the report of the plugin on the stored bindings. The plugin reads Midaz back to check that the routes of each binding exist.

The panel shows the state of the stored document: **Never written**, **Not migrated**, **Written, no bindings**, or **Written**. When the plugin still holds initiations frozen before ledger routing existed, the panel counts them. The plugin refuses to process them, so start them over.

### Coverage by scope

The label **Required for chargeback refunds** marks the inbound scope that a ledger with outgoing transfers needs for chargeback refunds.

| Column | Values |
| - | - |
| Organization, Ledger, Type | The scope. |
| Coverage | **Covered** or **Not covered**. A scope that is not covered says what happens to its money. |
| Routes | **Routes verified**, **Route not in this ledger**, **Route points the wrong way**, or **Midaz could not be read**. |
| Membership | **Members verified** or **Members unchecked**. |
| Transfers | The number of transfers of the scope. |
| Last transfer | The date of the last transfer of the scope. |

If the plugin cannot produce the report, the panel says so. The bindings below still show what is stored, but nothing confirms that their routes exist. This message is not an all-clear.

## Bindings

***

The **Bindings** table shows the stored document. A tenant holds at most 100 bindings.

| Column | Description |
| - | - |
| Organization | The organization of the scope. |
| Ledger | The ledger of the scope. |
| Type | `P2P`, `TED_OUT`, or `TED_IN`. |
| Mode | **Posts with routes** or **Posts without routes**. |
| Transaction route | The Midaz transaction route. |
| Source operation route | The operation route of the source leg. |
| Destination operation route | The operation route of the destination leg. |

Instead of the table, the page can show one of these states:

| State | What it means |
| - | - |
| **No routing document yet** | Nothing was ever written for the tenant. No scope is covered. |
| **The document covers nothing** | The document has no bindings. No scope is covered. |
| **The stored document cannot be read** | Every scope that the stored document was meant to cover is uncovered. The page does not overwrite it. Repair it through the plugin admin API. |

## Add or edit a binding

***

Your edits stay on the page until you save. A save replaces the whole document.

**1. Open the binding form**

Click **Add binding**. To change a binding, click the edit icon () on its row.

**2. Choose the scope**

Select the **Organization**, the **Ledger**, and the **Transfer type**. When you edit a binding, you cannot change its scope. To move a binding, remove it and add another.

**3. Choose the mode**

In **Mode**, keep **Posts with routes**, or select **Posts without routes**.

**4. Choose the routes**

With **Posts with routes**, select the **Transaction route**, then the **Source operation route** and the **Destination operation route**. Each leg lists the operation routes of its direction, plus the routes that serve both directions. To type an id that a list does not show, click **Enter id by hand** on that field.

**5. Save the document**

Click **Save** in the form. The binding goes into your draft. Then click **Save** on the page to send the document to the plugin. To drop your edits, click **Discard**.

> [!WARNING]
>
> **Posts without routes** sends the transfers of the scope with no accounting routes. Midaz accepts them only while route validation is off on the ledger. With validation on, Midaz refuses every transfer of the scope. The form asks you to confirm this mode.

### Remove a binding

Click the remove icon () on the row, confirm with **Remove binding**, then click **Save**. After the save, the scope is uncovered. The plugin refuses its outgoing transfers and holds its incoming credits.

### When someone else saved first

If another person saved the document after the page read it, the page shows **Someone else saved this document first**. Click **Reload and discard my changes** to read the stored document, then make your change again.

## Related pages

***

> **[TED IN operations](/en/interfaces/ted-jd/console/bt-ted-in-operations)**
>
> Inspect retained inbound messages and record where the money went.

> **[Managing accounting routes](/en/products/midaz/console/managing-accounting-routes)**
>
> Create the Midaz routes that a binding names.


# Cancelling a Transfer
Source: https://docs.lerian.studio/en/interfaces/ted-jd/console/bt-cancelling-a-transfer

Cancel a TED Out from its detail page in Lerian Console while the transfer is in Created or Pending state, using the Cancel Transfer button.

You can cancel a TED Out from its detail page while the transfer is in a state that allows cancellation. Cancelling releases the amount on hold. Cancellation is permanent. You cannot undo it.

## When a transfer can be cancelled

***

On a TED Out, the Console shows the **Cancel Transfer** button to users allowed to create transfers, while the transfer is in **Created** or **Pending** state. When the transfer advances beyond either state, the button disappears. You can no longer cancel the transfer through the Console.

> [!WARNING]
>
> Cancellation is permanent. You cannot reactivate a cancelled transfer. To retry, create a new transfer.

## Cancelling a transfer

***

**1. Open the transfer**

From the Transfers list, open the **Actions** menu on the transfer's row and click **See details**. The detail page opens.

**2. Click Cancel Transfer**

In the header, click the red **Cancel Transfer** button. A confirmation dialog appears.

**3. Confirm the cancellation**

The dialog title is **Cancel Transfer**. It names the transfer, the amount, and the recipient, and asks you to confirm. This action cannot be undone.

Click **Cancel Transfer** to proceed. To keep the transfer active, click **Cancel**.

On success, a toast confirms *Transfer cancelled successfully*. The detail page refreshes. The status updates to **Cancelled** and a new entry appears in the status timeline. The **Cancel Transfer** button disappears.

## Error handling

***

The request can fail. For example, the transfer advances to a non-cancellable state between the page load and your confirmation. In this case, the transfer stays in its current state. Refresh the page to see the current status before you try again.


# Checking Transfer Details
Source: https://docs.lerian.studio/en/interfaces/ted-jd/console/bt-checking-transfer-details

Inspect a single bank transfer in Lerian Console: amounts, sender and recipient, references, status timeline, and the Raw Data tab for debugging.

The **Transfer Detail** page shows everything recorded for a single bank transfer: amounts, sender and recipient information, references, and the full status history. It also has a **Raw Data** tab for debugging and advanced inspection.

## Opening the detail page

***

You can open the detail page in several ways:

* From the [Transfers list](/en/interfaces/ted-jd/console/bt-managing-transfers), open the **Actions** menu on the row you want and select **See details**. (List rows are not clickable. Use the **Actions** menu to open the detail page.)
* Click **View Transfer** on the success screen after you create a transfer.
* Use **See details** from a row on the [Reconciliation page](/en/interfaces/ted-jd/console/bt-managing-reconciliation).

If the transfer belongs to a ledger other than the selected one, the Console switches to that ledger and shows a message that names it. If you then select another ledger in the sidebar, the Console leaves the detail page and opens the Transfers list.

The detail page needs Bank Transfer 3.1.0 or later. With an earlier version, a version notice replaces it. See [Product versions](/en/platform/console/about-lerian-console#product-versions).

## Page header

***

The header shows the transfer identifier (truncated) and the creation date in local format. Next to the title, the page shows:

* A **status badge** for the current state (Created, Pending, Processing, Completed, Failed, and so on).
* An *Auto-refreshing...* hint that pulses while the transfer is still in flight.
* A **Cancel Transfer** button when the transfer is in a cancellable state (see [Cancelling a Transfer](/en/interfaces/ted-jd/console/bt-cancelling-a-transfer)).

> [!NOTE]
>
> Auto-refresh polls the transfer every five seconds while it is in flight. Once it reaches a terminal state (Completed, Failed, Cancelled, Rejected), polling stops.

## Tabs

***

The page has two tabs: **Summary** (the default) and **Raw Data**.

### Summary

The Summary tab arranges the transfer in sections.

#### Financial Summary

* **Amount**: the transfer amount.
* **Fee**: the total fee applied.
* **Total** (shown in bold): for TED In, the amount received. For TED Out and P2P, the amount debited from the sender's account.
* **Type**: the transfer type badge (TED Out, TED In, or P2P).
* **Description**: the description you provided, or *No description* if empty.

#### References

The page shows these fields only when at least one reference value exists:

* **Confirmation Number**: the reference returned at confirmation time.
* **Control Number**: the reference from the counterparty system.

#### Sender

* **Account ID**: the sender account identifier.

#### Recipient

* **Name**: the beneficiary's name.
* **Document**: the beneficiary's CPF/CNPJ, partially masked for privacy (the first three and the last three characters stay visible).
* **ISPB / Branch**: the beneficiary bank's ISPB and branch, shown as `ISPB / Branch`.
* **Account**: the beneficiary's account number.
* **Account Type**: the recipient account type the plugin returns.

#### Reconciliation

The page shows this section only for a transfer with reconciliation data: **Reconciliation status**, **Retry attempts**, **Last attempt**, **Reason code**, **Reason class**, and **JD rejection code**.

#### Dates

* **Created at**: the transfer's creation date and time.
* **Updated at**: the date and time of the last update.
* **Completed at**: the date and time the transfer reached a terminal state. The page shows this field only after completion.

#### Metadata

If the transfer carries custom metadata, the page lists each key-value pair here.

#### Status History

On the right-hand column of the Summary tab, a vertical timeline shows every status change for this transfer:

* The **status label** (Created, Pending, Processing, Completed, Failed, and so on).
* The **timestamp** of the change.
* An optional **reason** for the transition.

The timeline sorts entries from newest to oldest. If no status history exists yet, the card shows *No status history available*.

### Raw Data

The Raw Data tab shows the transfer as JSON, as the Console reads it. Use it to inspect fields the summary view does not show, or to share the transfer with support.

## Error state

***

A transfer sometimes fails to load, for example after a temporary backend error. The page then shows *Could not load* with a **Retry** button that requests the data again.


# Configuring Fee Policy
Source: https://docs.lerian.studio/en/interfaces/ted-jd/console/bt-configuring-fee-policy

Set the Bank Transfer fee policy in Lerian Console with the Fail Closed Default toggle and the maximum fee cap that guards against runaway fee rules.

The **Fee Policy** section controls how the plugin behaves when it cannot compute a fee. It also caps the maximum fee the plugin applies to a single transfer. These settings apply only in the `legacy` [fee mode](/en/interfaces/ted-jd/ted-configuration), where plugin-fees prices the fee. In `native` mode, the Midaz [Fees Engine](/en/products/midaz/fees/console/fees-engine-overview) prices the fee, and the plugin does not use these settings.

## Accessing the section

***

**1. Open Settings**

In the Bank Transfer sidebar, click **Settings**.

**2. Expand Fee Policy**

Click the section header to expand it.

## Fields

***

### Fail Closed Default

This toggle sets the plugin behavior when the fee service is unavailable. It applies to a timeout, a connection failure, or a server error from the fee service:

* **On (fail closed)**: the plugin refuses an outgoing transfer. For an incoming TED, it refuses the credit and returns the money to the sender (STR0010). Before it turns the toggle on, the Console asks you to confirm with **Yes, fail closed**.
* **Off (fail open)**: the transfer proceeds with no fee charged. This is the default.

> [!WARNING]
>
> The toggle applies to incoming and outgoing transfers together. With **Fail Closed**, every incoming TED that arrives while the fee service is down goes back to its sender, and you cannot undo that return.

### Max Fee Amount

This field sets the hard cap on the total fee for a single transfer. You enter it in currency units, for example `50.00`. The plugin stores the cap in cents.

If the calculated fee exceeds this cap, the plugin rejects an outgoing transfer. The plugin does not trim the fee to the cap. An incoming TED whose fee exceeds the cap is credited with no fee, or returned to the sender when **Fail Closed Default** is on. If you clear the field, the plugin applies the deployment default. Use the cap as a guardrail against misconfigured fee rules that produce oversized charges.

## Saving changes

***

Click **Save** in the toolbar at the top of the page.

## Tips

***

* Review the Fee Policy together with your plugin-fees packages. The cap blocks an outgoing transfer whose fee exceeds the limit. Still fix misconfigured fee rules at the source.
* Raise the cap only when you must. A higher cap allows a larger fee per transfer. Tell the team that operates the plugin first, so the team can review the change.


# Configuring JD Connection
Source: https://docs.lerian.studio/en/interfaces/ted-jd/console/bt-configuring-jd-connection

The deployment, not Lerian Console, sets the JD SPB connection of the Bank Transfer plugin: the JD base URL and your institution's ISPB.

Lerian Console has no JD Connection section. The deployment sets the connection:

* **JD base URL**: the `JD_BASE_URL` environment variable on BYOC. On Lerian Cloud, Lerian manages your JD settings.
* **Origin ISPB**: the plugin reads your institution's ISPB from the tenant policy `tenancy.ispb_organization_bindings`.

See [Environment variables](/en/interfaces/ted-jd/ted-environment-variables) and [Configuration](/en/interfaces/ted-jd/ted-configuration).


# Configuring JD Credentials
Source: https://docs.lerian.studio/en/interfaces/ted-jd/console/bt-configuring-jd-credentials

The deployment, not Lerian Console, sets the JD SPB credentials of the Bank Transfer plugin: legacy code, user code, password, and signing key.

Lerian Console does not edit JD credentials. The deployment sets them:

* **BYOC**: the `JD_LEGACY_CODE`, `JD_USER_CODE`, `JD_PASSWORD`, and `JD_PRIVATE_KEY_*` environment variables.
* **Lerian Cloud**: Lerian manages your JD credentials.

`JD_SIGNING_MODE` sets how the plugin signs JD messages. See [Environment variables](/en/interfaces/ted-jd/ted-environment-variables).


# Configuring Operating Hours
Source: https://docs.lerian.studio/en/interfaces/ted-jd/console/bt-configuring-operating-hours

Define the TED operating window in Lerian Console: open and close times, IANA timezone, and how the plugin handles transfers submitted outside the window.

The **Operating Hours** section sets the window when the plugin accepts TED Out transfers. The plugin rejects a TED Out that you submit outside this window. The rejection reports the next available time. P2P transfers ignore the window. The [Initiate](/en/interfaces/ted-jd/console/bt-initiating-a-transfer) page shows a banner when the current time is outside the window.

The section header shows a **Configured** or **Not Configured** badge. The badge reads **Not Configured** only when the plugin does not accept the stored window.

## Accessing the section

***

**1. Open Settings**

In the Bank Transfer sidebar, click **Settings**.

**2. Expand Operating Hours**

Click the section header to expand it.

## Fields

***

### Operating Window

The open and close times in one field, as `HH:MM-HH:MM` in 24-hour format (for example `06:30-17:00`). The open time must be earlier than the close time. `00:00-00:00` closes the window every day. If you clear the field, the plugin applies the default window.

### Timezone

The IANA timezone that the plugin uses to read the window, as a Region/City name (for example `America/Sao_Paulo`). The plugin makes all time comparisons in this timezone, not in the user or server timezone.

## Default behavior

***

If you do not configure Operating Hours, the plugin applies these defaults:

* **Operating Window:** `06:30-17:00`
* **Timezone:** `America/Sao_Paulo`
* **Days:** Monday through Friday, and never on a BACEN holiday (you cannot change the processing days in the Console)

## How the window is used

***

The Console uses the configured window to:

* Show an **Outside TED Operating Hours** banner on the Initiate page when the current time is outside the window.
* Warn you that the plugin rejects a TED Out submitted outside the window.

> [!NOTE]
>
> The banner only informs you. The Console does not block submission. If you submit a TED Out outside the window, the plugin rejects it and reports the next available time. The plugin does not queue the transfer for later. The default window is Monday through Friday, 06:30–17:00 (`America/Sao_Paulo`, UTC−3), and it excludes BACEN holidays.

## Saving changes

***

Click **Save** in the toolbar at the top of the page. The new window applies once the plugin picks up the change.


# Configuring Usage Limits
Source: https://docs.lerian.studio/en/interfaces/ted-jd/console/bt-configuring-usage-limits

Cap daily and monthly TED transfer volume in Lerian Console. Enable Usage Limits to stop runaway automations and comply with internal risk policies.

The **Usage Limits** section caps how much value each account can move in a given day or month. Use it to enforce operational guardrails: catch configuration mistakes, prevent runaway automations, and comply with internal risk policies.

The section header shows an **Enabled** or **Disabled** badge that matches the toggle below.

## Accessing the section

***

**1. Open Settings**

In the Bank Transfer sidebar, click **Settings**.

**2. Expand Usage Limits**

Click the section header to expand it.

## Fields

***

### Limits Enabled

Toggle that turns enforcement on or off. When the toggle is off, the Daily Limit and Monthly Limit fields are disabled. The plugin applies no cap until you turn the toggle on.

### Daily Limit

The maximum total value of transfers the plugin allows per day. Enter it in regular currency units, for example `100.00` for R\$ 100.00. The plugin stores the value internally in cents. You can edit this field only when you enable limits. If you clear the field, the plugin applies the deployment default.

### Monthly Limit

The maximum total value of transfers the plugin allows per month. It uses the same input format as the Daily Limit. You can edit this field only when you enable limits.

## How limits are applied

***

When you confirm a TED Out or P2P, the plugin adds up the amounts debited from the sender account for the day and for the month. It compares each total against the configured cap. If the transfer would push either total past its cap, the plugin rejects it with `BTF-0011` before it reaches JD. The day and the month roll over at 00:00 UTC.

> [!NOTE]
>
> Limits apply to the total value of transfers that you initiate through the plugin. The JD poller receives inbound TED transfers (TED In) passively, so they do not count against these caps.

## Saving changes

***

Click **Save** in the toolbar at the top of the page.

## Tips

***

* When you roll out the plugin, start with conservative limits. Raise them gradually as you gain confidence in the flow.
* If a limit blocks a legitimate operation, raise the cap, save, then retry the transfer. You cannot bypass a cap for a single transfer without first adjusting the setting.


# Initiating a Transfer
Source: https://docs.lerian.studio/en/interfaces/ted-jd/console/bt-initiating-a-transfer

Create a TED Out or P2P in Lerian Console with the two-step initiate-and-confirm wizard. Collect details, preview fees, and execute the transfer.

The **New Transfer** page creates a transfer in two steps. In step 1 you enter the transfer details and request a fee preview (**initiate**). In step 2 you review the transfer and confirm it (**process**). The Console shows step 1 as a form and step 2 as a review screen. The Console runs the transfer when you click **Confirm Transfer**.

> [!NOTE]
>
> The wizard does not ask for a transfer type. The plugin creates a **P2P** when **ISPB Code** is your institution's ISPB, and a **TED Out** for any other ISPB. Inbound TED (TED In) arrives from JD, so it has no manual creation step.

## Accessing the wizard

***

**1. Open the Transfers page**

In the Midaz Module sidebar, expand **Bank Transfer**. Click **Transfers**.

**2. Start a new transfer**

Click **New Transfer** at the top right of the page.

The page header shows **New Transfer**. The subtitle reads *Initiate a new bank transfer in two simple steps*. A stepper near the top shows your place in the flow: step 1 is the form and step 2 is the review. The success screen appears when the plugin accepts the transfer for processing.

## Operating hours banner

***

An amber **Outside TED Operating Hours** banner appears at the top when the current time is outside the configured TED operating window. The banner states the operating window: Monday through Friday, between the configured open and close times, in the configured timezone. A **TED Operating Window Closed** banner appears when the stored window closes every day, and a **TED Operating Window Misconfigured** banner when the plugin does not accept the stored window.

> [!WARNING]
>
> Do not submit a TED Out outside the operating window or on a BACEN holiday. The Console does not block the button, but the plugin rejects the request with a `422` error (`BTF-0010`). The response reports the next time the operating window opens. The default window is Monday through Friday, 06:30–17:00 (`America/Sao_Paulo`, UTC−3). P2P transfers ignore the window.

> **[Configuring Operating Hours](/en/interfaces/ted-jd/console/bt-configuring-operating-hours)**
>
> Adjust the operating window in Settings.

## Step 1: Collect details and initiate

***

The form has three sections. The Console marks all required fields. When you click **Continue**, the Console calls the backend `/initiate` endpoint with the values below. The `/initiate` endpoint computes the fees and returns a preview for the review screen.

### Source Account

* **Sender Account** *(required)*: choose the source account from the dropdown. The list holds the ledger accounts that allow sending. If the ledger has no eligible sender account, the field becomes a text input. You then type the account ID directly.

### Destination Account

* **Recipient Name** *(required)*: the beneficiary's full name, up to 200 bytes. An accented character counts as two.
* **CPF/CNPJ** *(required)*: the beneficiary's document. A CPF has 11 digits and a CNPJ has 14 digits.
* **Account Number** *(required)*: the beneficiary's account number.
* **Account Type** *(required)*: **Checking**, **Savings**, **Payment**, or **Salary**.
* **ISPB Code** *(required)*: the beneficiary bank's 8-digit ISPB.
* **Branch**: the beneficiary bank's branch code, 1 to 4 digits. The plugin accepts a TED without a branch.

### Transfer Details

* **Amount** *(required)*: the transfer amount, from 0.01 to 999,999.99, with at most two decimals.
* **Currency** *(required)*: fixed to **BRL**.
* **Purpose (SPB finality code)** *(required)*: the SPB finality code, 1 to 4 digits. `10` is a credit to account.
* **Description** *(optional)*: a free-text description up to 140 bytes. An accented character counts as two.

Click **Continue** to move to the review step. The `/initiate` response carries the initiation identifier, the fee breakdown, and the estimated completion. These values drive the next screen.

## Step 2: Review and confirm

***

The Console builds the review screen from the `/initiate` response in step 1. The initiation identifier, the fee breakdown, and the estimated completion carry over. Check the transfer before you run it. The screen shows:

* **Sender Account**, **Recipient Name**, **CPF/CNPJ**, **Recipient Account**, **Account Type**, **ISPB**, **Branch**, **Description**: exactly what you entered in step 1.
* **Amount**: the amount you entered.
* **Fee**: the total fee that the plugin computes.
* **Fee Breakdown**: one line per fee entry, with its label and its amount. A *Deductible* entry comes out of the transfer amount. Other entries add to it.
* **Total**: the final amount that the plugin debits from the sender.
* **Estimated Completion**: the timestamp when the transfer should complete.

> [!NOTE]
>
> Click **Back** to return to the form. The Console keeps your previous entries. When you click **Continue** again, the Console re-runs `/initiate` so the fee preview matches your changes.

When you click **Confirm Transfer**, the Console sends the reviewed transfer to the backend `/process` endpoint. This call creates and runs the transfer through the JD SPB integration. The button shows *Confirming…* while the call is in flight. The Console redirects to the success screen when the plugin accepts the transfer. Otherwise it shows one of these:

* *We could not confirm the outcome with the bank.*: the funds stay on hold and the transfer waits in the reconciliation queue. Do not send the transfer again.
* *Confirmation window expired* or *Signing data no longer matches*: nothing was sent. Click **Start over**.
* *Transfer already submitted*: click **View transfers** to find it.

## Success screen

***

After `/process` returns successfully, the Console shows a success screen with:

* **Transfer ID**: the identifier of the transfer.
* **Confirmation Number**: the reference that the JD integration returns.
* **Status**: the status after confirmation (typically **Created**, **Pending**, **Processing**, or **Completed**).
* **Fee** and **Total**: the applied values.

The success screen offers two actions:

* **View Transfer**: opens the [Transfer Detail page](/en/interfaces/ted-jd/console/bt-checking-transfer-details) for this transfer.
* **New Transfer**: opens the wizard again.


# Managing the Bank Transfer Dashboard
Source: https://docs.lerian.studio/en/interfaces/ted-jd/console/bt-managing-dashboard

Monitor the Bank Transfer plugin in Lerian Console: health status indicator, KPI cards, volume by TED Out, TED In, and P2P, plus recent activity.

The **Dashboard** is the first page under **Bank Transfer** in the sidebar. It gives you a quick view of the plugin health and activity. It shows the overall status indicator, headline counts, volume by transfer type, a health breakdown, and the most recent transfers.

## Accessing the Dashboard

***

**1. Open the Midaz Module**

From the Lerian Console home page, select the Midaz product card.

**2. Go to Bank Transfer**

In the left sidebar, expand the **Bank Transfer** section and click **Dashboard** (it is the first item).

## Page header

***

The page title **Bank Transfer** sits at the top left, with the subtitle *Dashboard overview*. Below the subtitle, a line states that counts, volume, health, and reconciliation cover the whole organization, not only the selected ledger. On the right, a status indicator and a status label summarize the current health.

| Indicator | Meaning |
| - | - |
| Healthy | No transfer is created, pending, or processing, and the fail rate is below the attention threshold. |
| Attention | At least one transfer is created, pending, or processing, or the fail rate reached the attention threshold. |
| Degraded | The fail rate or the processing count reached the degraded threshold, or the plugin could not count its in-flight transfers. |

Next to the status, a relative timestamp (*Updated just now*, *Updated 5m ago*) shows when the plugin last refreshed the summary. When the plugin does not answer, the header shows no indicator and the page shows *Dashboard unavailable* with a **Retry** button.

## Time window

***

Buttons above the cards select the period of the numbers: **Last 24 hours** (the default), **Last 7 days**, **Last 30 days**, or **All time**. **Refresh** reloads the numbers. If a refresh fails, the page keeps the previous numbers and shows *Last refresh failed at* with the time.

## Degradation banner

***

When the plugin reports degraded performance, a banner appears below the header. The banner warns that performance is degraded and some data may be stale, then lists the specific reasons.

> [!NOTE]
>
> The banner is informational. You can still use the plugin. Treat the listed reasons as signals that this page may not show the latest data.

## KPI cards

***

Seven cards summarize transfer activity for the current organization. Click a card to open the Transfers list filtered by its status, with three exceptions: **Total Transfers** opens the list unfiltered, **In flight** opens only *Processing* transfers, and **Failed / Rejected** opens only *Failed* transfers.

* **Total Transfers**: the total count.
* **Completed**: transfers in a successful terminal state, with its share of the total.
* **In flight (created + processing)**: transfers in *Created* or *Processing* status, with its share.
* **Pending**: transfers in *Pending* status, with its share.
* **Received**: inbound TEDs not yet credited, with its share.
* **Failed / Rejected**: transfers in a failed or rejected state, with its share.
* **Cancelled**: cancelled transfers, with its share.

## Transfer Volume by Type

***

A horizontal bar chart shows how many transfers fall under each type: **TED Out**, **TED In**, and **P2P**. Point to a bar to see the exact count.

If the plugin has no transfers yet, the card shows *No transfer data available*.

## System Health card

***

On the right, the **System Health** card shows a detailed breakdown:

* **Overall Status**: the same health value that the header shows.
* **Processing**: number of transfers in the *Processing* state.
* **Pending**: number of transfers in the *Pending* or *Created* state.
* **Terminal**: transfers that reached a terminal state.
* **Failures**: transfers that ended in a failure state.
* **Fail Rate**: percentage of terminal transfers that failed.

The degradation reasons appear only in the banner, not in this card.

## Reconciliation backlog

***

The **Reconciliation backlog** card counts transfers in **Awaiting reconciliation** and **Needs human review**. See [Managing reconciliation](/en/interfaces/ted-jd/console/bt-managing-reconciliation).

## Recent Transfers

***

The bottom of the page lists the five most recent transfers of the selected ledger. Its columns are **ID**, **Type**, **Amount**, **Fee**, **Total**, **Status**, and **Date**. Use the **View all transfers** link in the card header to open the Transfers list for the same time window. When the ledger has no transfer, the card shows *No transfers in the selected ledger yet*.

The card needs Bank Transfer 3.1.0 or later. With an earlier version, a version notice replaces it. See [Product versions](/en/platform/console/about-lerian-console#product-versions).

> [!NOTE]
>
> The Recent Transfers card auto-refreshes. While at least one transfer is in flight, it polls every five seconds. When all visible transfers reach a terminal state, it polls every thirty seconds instead.


# Managing Reconciliation
Source: https://docs.lerian.studio/en/interfaces/ted-jd/console/bt-managing-reconciliation

Review bank transfers pending reconciliation in Lerian Console with failure concentration cards, then retry or resolve a TED Out in manual review.

The **Reconciliation** page lists bank transfers that still need a reconciliation action:

* A TED Out whose outcome with JD is unknown and that the plugin still reconciles.
* A transfer in *Manual Review* that needs a person to decide.
* An inbound chargeback that the plugin reverses on the ledger.

The page header carries the subtitle *Transfers requiring manual review due to ambiguous failures*. A line under it states that the queue covers the whole organization, not only the selected ledger. The page also highlights the most common failure codes, so you can spot patterns at a glance.

## Accessing the Reconciliation page

***

**1. Open Bank Transfer**

From the Midaz Module sidebar, expand **Bank Transfer**.

**2. Click Reconciliation**

Select **Reconciliation** in the submenu.

## When there is nothing to reconcile

***

If no transfers need reconciliation, the page shows a green confirmation icon with two lines:

> **No transfers pending reconciliation**
>
> All transfers have been processed successfully or resolved.

An *Auto-refreshing...* hint in the toolbar indicates the page continues to check for new items in the background.

If the plugin has not answered yet, the page shows *Cannot verify the reconciliation queue* instead. This does not mean the queue is empty.

## Failure Concentration

***

When pending items exist, a row of cards at the top shows the most frequent failure codes. The row also shows how many transfers each code affects. Use it as a quick heat map of what fails today.

Each card shows:

* The **failure code** returned by the counterparty system.
* The **count** of transfers affected (formatted as *N transfer* or *N transfers*).

## Pending items table

***

Below the failure concentration, a table lists the individual transfers pending reconciliation:

| Column | Description |
| - | - |
| Transfer ID | Identifier of the transfer. |
| Type | Transfer type badge (TED Out, TED In, P2P). |
| Control # | Control number assigned by the counterparty system, when available. |
| Failure | Failure code, shown as a red badge. |
| System | Counterparty system that reported the failure. |
| Flagged | Timestamp when the transfer was flagged for reconciliation. |

The table shows up to 50 transfers. A footer line summarizes the total (*N transfer* or *N transfers* pending reconciliation).

### Actions

Each row has an **Actions** menu:

* **See details** opens the full [Transfer Detail page](/en/interfaces/ted-jd/console/bt-checking-transfer-details) for that transfer.
* **Retry** puts a TED Out in *Manual Review* back in the reconciliation queue, and the plugin queries its settlement again. No TED is sent again and the hold stays. Type a **Reason** of 1 to 500 characters, then click **Retry**.
* **Resolve** asks you to decide what happens to the money held for a TED Out in *Manual Review*. **Settle: commit the hold** debits the account and completes the TED. **Revert: return the money** cancels the hold, returns the money to the account, and fails the TED. Choose one, type a **Reason** of 10 to 500 characters, then confirm. The decision cannot be undone.

If the plugin refuses a decision, the dialog stays open and shows its reason.

Each Bank Transfer screen needs the `bank-transfer` permission: `get` to see it, `post` to act on it, `patch` to change settings and the routing document, and `delete` to delete a webhook.

Only users allowed to create transfers see **Retry**, **Resolve**, and **Run cycle now**. **Run cycle now**, in the toolbar, runs a reconciliation cycle at once. Outside the operating window, no cycle runs.

## Auto-refresh

***

While the page is open, it polls the backend every 30 seconds. An animated *Auto-refreshing…* label shows that the page refreshes the data. You do not need to take any manual action.

## Error state

***

If the page cannot load the reconciliation data, it shows *Could not load* with a **Retry** button. A page refresh usually resolves a transient issue. If the error persists, contact your administrator.


# Managing Bank Transfer Settings
Source: https://docs.lerian.studio/en/interfaces/ted-jd/console/bt-managing-settings

Overview of Bank Transfer settings in Lerian Console: operating hours, usage limits, and fee policy for your tenant.

The **Settings** page holds the Bank Transfer configuration you manage from the Console. It groups the settings into three sections. The settings apply to your whole tenant, not to one organization: the header reads *Tenant policy for tenant id* followed by your tenant ID.

## Accessing Settings

***

**1. Open Bank Transfer**

From the Midaz Module sidebar, expand **Bank Transfer**.

**2. Click Settings**

Select **Settings** in the submenu.

## Editing and saving

***

You expand or collapse each section independently. The **Save** button in the top toolbar submits only the fields you changed. If you made no edits, **Save** shows *No changes to save.*

* **Save**: saves each changed field on its own. If a field fails, the fields saved before it stay in force, and the Console tells you how many it saved.
* **Discard**: resets the form to the current saved values.

A toast confirms *Settings saved successfully* when the save completes. When the plugin refuses a value, the Console shows the plugin's reason.

Users without write permission see *You have read-only access. Contact your administrator for write permissions.* The fields and **Save** are then disabled.

The Console does not edit JD credentials or the JD connection. The deployment sets them. See [Environment variables](/en/interfaces/ted-jd/ted-environment-variables).

## The three configuration sections

***

> **[Usage Limits](/en/interfaces/ted-jd/console/bt-configuring-usage-limits)**
>
> Daily and monthly transfer caps.

> **[Operating Hours](/en/interfaces/ted-jd/console/bt-configuring-operating-hours)**
>
> The window when TED transfers run.

> **[Fee Policy](/en/interfaces/ted-jd/console/bt-configuring-fee-policy)**
>
> Fail-closed default and maximum fee amount.

Two sections display a status badge in their header:

* **Configured** / **Not Configured** for Operating Hours.
* **Enabled** / **Disabled** for Usage Limits.

The Fee Policy section does not show a status badge.


# Managing Transfers
Source: https://docs.lerian.studio/en/interfaces/ted-jd/console/bt-managing-transfers

Browse, filter, sort, and export bank transfers from the Lerian Console Transfers list: TED Out, TED In, and P2P with CSV export and status filters.

The **Transfers** page lists every bank transfer recorded for the current organization and ledger: TED Out, TED In, and P2P. Use it to filter, inspect, export, and create new transfers.

## Accessing the Transfers page

***

**1. Open Bank Transfer**

From the Midaz Module sidebar, expand **Bank Transfer**.

**2. Click Transfers**

Select **Transfers** in the submenu to open the list.

The page header shows the title **Transfers** and the subtitle *View, manage, and track the bank transfers of the selected ledger*.

The list and its CSV export need Bank Transfer 3.1.0 or later. With an earlier version, a version notice replaces the list, and the **Export CSV** button is hidden. See [Product versions](/en/platform/console/about-lerian-console#product-versions).

## Header actions

***

The header has two buttons:

* **Export CSV**: downloads up to 5,000 transfers with the current filters.
* **New Transfer**: opens the initiate wizard for a new TED Out or P2P. Only users allowed to create transfers see it.

> **[Initiating a Transfer](/en/interfaces/ted-jd/console/bt-initiating-a-transfer)**
>
> Step-by-step guide to creating a new transfer.

## Filters

***

The filter panel is collapsible. Expand it to narrow the list.

| Filter | Values |
| - | - |
| Type | All types, TED Out, TED In, P2P |
| Status | All Statuses, Created, Received, Pending, Processing, Completed, Failed, Rejected, Cancelled |
| Start Date | Date picker; transfers created on or after this date. |
| End Date | Date picker; transfers created on or before this date. |
| Min Amount | Numeric input; includes transfers with amount equal to or above. |
| Max Amount | Numeric input; includes transfers with amount equal to or below. |
| Reconciliation | All Reconciliation States, Awaiting Reconciliation, Resolved, Reversing, Reverted, Manual Review |

A toggle button in the filter toolbar switches the sort direction between **Newest First** and **Oldest First**. The backend default sets the initial order until you toggle it. The page-size control changes how many rows each page shows. The column visibility menu hides or shows columns.

Click **Clear filters** to reset all filters at once.

## Columns

***

By default, the table includes:

* **Type**: a colored badge (TED Out, TED In, P2P).
* **Amount**: transaction amount in the transfer currency.
* **Fee**: the fee the plugin applies (may be empty for inbound transfers).
* **Total**: for TED In, the amount received. For TED Out and P2P, the amount debited from the sender's account.
* **Status**: a colored badge for the current state.
* **Reconciliation**: the reconciliation status, when the transfer has one.
* **ID**: transfer identifier.
* **Date**: the creation timestamp.
* **Actions**: a kebab menu at the end of each row. Its **See details** item opens the [Transfer Detail page](/en/interfaces/ted-jd/console/bt-checking-transfer-details).

To open a transfer, use the **Actions** menu on its row and click **See details**.

## Exporting to CSV

***

**Export CSV** fetches up to 5,000 transfers under the current filters. It downloads a file named `bank-transfers-<date>.csv` with one row per transfer, in the order the list shows. When more transfers match, the file keeps the oldest ones and the Console tells you how many it left out. Narrow the filters to export the newer ones.

The CSV columns differ from the on-screen table. The file has no counterparty names.

| Column | Notes |
| - | - |
| ID | Transfer identifier. |
| Type | `TED_OUT`, `TED_IN`, or `P2P`. |
| Status | Current transfer status. |
| Reconciliation | Reconciliation status, when the transfer has one. |
| Amount | Transfer amount, with a dot as the decimal separator. |
| Fee | Fee amount. |
| Total | For TED In, the amount received. For TED Out and P2P, the amount debited from the sender's account. |
| Currency | Defaults to BRL when not set. |
| Created At | Creation timestamp. |
| Updated At | Last-update timestamp. |

## Empty state

***

If the list has no transfers and no active filters, the page shows an empty state. The empty state invites you to create the first transfer. If active filters make the list empty, clear them to see all transfers again.


# Bank Transfer in Lerian Console
Source: https://docs.lerian.studio/en/interfaces/ted-jd/console/bt-overview

Use the Bank Transfer plugin in Lerian Console via JD SPB: dashboard health, transfers list, reconciliation queue, TED IN operations, webhooks, settings, and accounting routes.

The **Bank Transfer** plugin in Midaz Module lets you initiate, track, and reconcile bank transfers through the **JD SPB** integration, directly from Lerian Console. From one place, you can monitor transfer health, operate TED flows, investigate failures, and configure the integration.

## What Bank Transfer covers

***

The plugin handles three transfer types, each with a different flow in the Console:

* **TED Out**: Outbound TED transfers to another institution. You create them on the **New Transfer** page.
* **TED In**: Inbound TED transfers received from JD. They appear in the transfers list. There is no manual creation step.
* **P2P**: Transfers between two accounts of your own institution. You create them on the **New Transfer** page.

> [!NOTE]
>
> The **New Transfer** page does not ask for a type. The plugin creates a P2P when the recipient ISPB is your institution's ISPB, and a TED Out for any other ISPB.

## Activating the plugin

***

Bank Transfer is an optional plugin. Enable it in **Midaz Settings → Plugins** before you use it.

> **[Managing Plugins](/en/platform/console/mc-console-plugins)**
>
> Learn how to enable, disable, and configure plugins in Midaz Module.

Once enabled, the **Bank Transfer** section appears in the **Plugins** group of the left sidebar with seven pages:

* **Dashboard**: health indicator, KPIs, transfer volume by type, and recent activity.
* **Transfers**: the transfers of the selected ledger, with filters and CSV export.
* **Reconciliation**: transfers whose outcome needs reconciliation, with failure concentration.
* **TED IN operations**: poll, replay, and resume the TED IN poller, and review reconciliation gaps, retained messages, and undeliverable credits.
* **Webhooks**: webhook registrations and failed deliveries.
* **Settings**: operating hours, usage limits, and fee policy.
* **Accounting Routes**: ledger routing readiness and the bindings that tie each organization, ledger, and transfer type to Midaz accounting routes.

> [!NOTE]
>
> Your environment also controls availability: beyond the in-Console **Settings → Plugins** toggle, a runtime plugin flag (`NEXT_PUBLIC_BANK_TRANSFER_ENABLED`) gates the plugin. The flag stays off by default. Bank Transfer becomes visible only when your administrator sets the flag to `true` for your environment. The Console reads the flag at runtime, so you set the environment variable and restart the Console container without a rebuild. If the **Bank Transfer (TED JD)** card does not appear in **Settings → Plugins**, the flag is off for your environment. See [Lerian Console via Helm](https://github.com/LerianStudio/helm/tree/main/charts/product-console).

Each Bank Transfer screen needs the `bank-transfer` permission: `get` to see it, `post` to act on it, `patch` to change settings and the routing document, and `delete` to delete a webhook. The **New Transfer** page needs `post` to open.

## Available pages

***

> **[Dashboard](/en/interfaces/ted-jd/console/bt-managing-dashboard)**
>
> Monitor system health, transfer volume, and recent activity.

> **[Transfers](/en/interfaces/ted-jd/console/bt-managing-transfers)**
>
> Browse, filter, and export transfers across all types and statuses.

> **[Reconciliation](/en/interfaces/ted-jd/console/bt-managing-reconciliation)**
>
> Review transfers flagged for reconciliation and their failure codes.

> **[TED IN operations](/en/interfaces/ted-jd/console/bt-ted-in-operations)**
>
> Run the inbound poller, inspect gaps, and record where retained money went.

> **[Webhooks](/en/interfaces/ted-jd/console/bt-webhooks)**
>
> Register webhook endpoints, rotate their signing secret, and retry failed deliveries.

> **[Settings](/en/interfaces/ted-jd/console/bt-managing-settings)**
>
> Configure operating hours, usage limits, and fee policy.

> **[Accounting Routes](/en/interfaces/ted-jd/console/bt-accounting-routes)**
>
> Bind each scope to the Midaz accounting routes that the plugin posts with.

## Transfer statuses

***

Transfers move through a set of lifecycle statuses. The Dashboard, the Transfers list, and the Transfer Detail page show the same statuses.

| Status | Meaning |
| - | - |
| Created | Transfer was created and is queued for processing. |
| Received | Inbound TED received from JD, before the credit. |
| Pending | TED Out with the amount on hold. JD has not received it yet, so you can still cancel it. |
| Processing | In flight with the counterparty. |
| Completed | Transfer finished successfully. |
| Failed | Processing failed. |
| Rejected | Counterparty rejected the transfer. |
| Cancelled | Cancelled by a user before completion. |


# TED IN Operations
Source: https://docs.lerian.studio/en/interfaces/ted-jd/console/bt-ted-in-operations

Run the inbound TED poller by hand, inspect reconciliation gaps, and record where retained inbound money went, from the Bank Transfer plugin in Lerian Console.

The **TED IN operations** page of the **Bank Transfer** plugin covers the inbound side of TED. Use it to run the inbound poller by hand and to inspect the gaps that stopped it. Use it also to record where inbound money went when the plugin neither credited nor returned it. A line under the page title states that reconciliation gaps, retained messages, and undeliverable credits cover every organization and ledger, not only the selected one.

Each Bank Transfer screen needs the `bank-transfer` permission: `get` to see it, `post` to act on it, `patch` to change settings and the routing document, and `delete` to delete a webhook.

## Accessing the page

***

**1. Open Bank Transfer**

From the Midaz Module sidebar, expand **Bank Transfer**.

**2. Click TED IN operations**

Select **TED IN operations** in the submenu.

## Poller actions

***

The **Poller actions** section has three actions.

| Action | What it does |
| - | - |
| **Poll now** | Runs one inbound cycle now, instead of waiting for the background worker. The result shows how many messages the cycle processed. |
| **Replay backlog** | Processes the inbound backlog of the organization on screen again. Select an organization first. |
| **Resume poller** | Restarts a poller that stopped on a reconciliation gap. The poller reads inbound messages again from its last checkpoint. |

Outside the inbound operating window, **Poll now** runs no cycle. The page then says that the cycle read nothing. This result is not an all-clear.

### Resume the poller

**1. Open the dialog**

Click **Resume poller**.

**2. Record why**

Optionally, type a **Note** of up to 500 characters. The note tells the next operator that a person reviewed the gap.

**3. Mark the gap when you reviewed it**

Select **I have reviewed the gap this poller latched on** to also mark the gap resolved. If you leave it clear, the poller resumes and the gap stays open.

**4. Resume**

Click **Resume**. The result tells you whether the reconciliation gap is still open.

## Reconciliation gaps

***

A reconciliation gap is a point where the inbound message stream lost continuity. The poller stops on a gap until a person resumes it. The **Reconciliation gaps** table lists the gaps, 50 per page:

| Column | Description |
| - | - |
| Gap ID | Identifier of the gap. |
| Latched at | When the poller stopped on the gap. |
| Transport reason | The reason that the transport reported. |
| Last checkpoint | The last position that the poller read before the gap. |
| Tenant | The tenant of the gap. |
| Organization | The organization of the gap. |

When the table is empty, the page shows **No reconciliation gaps**. If the plugin has not answered yet, the page shows **Cannot verify the inbound gaps** instead. This message does not mean that there are no gaps. When gap inspection is off in your deployment, the page shows the message of the plugin.

## Retained messages and undeliverable credits

***

Two lists show inbound money that the plugin did not deliver. Each list shows 50 rows per page.

**Retained messages** lists the inbound TEDs that the plugin neither credited nor returned, oldest first.

| Column | Description |
| - | - |
| Message ID | Identifier of the inbound message. |
| Reason | Why the plugin retained the message. |
| Amount | Amount of the TED. |
| Received at | When the plugin received the message. |
| Actions | **Close** appears when the plugin no longer retries the message. |

**Undeliverable credits** lists the inbound TEDs that could not reach their recipient, and how far each return has got.

| Column | Description |
| - | - |
| Control # | Control number of the TED. |
| Reason | Why the credit could not reach the recipient. |
| Status | The state of the return. |
| Amount | Amount of the TED. |
| Created at | When the plugin recorded the credit as undeliverable. |
| Actions | **Close** appears when the status is `RETAINED` or `FAILED`. |

If the plugin has not answered yet, a list says so. This message is not an all-clear.

### Record where the money went

**Close** records an act that a person already did outside the platform. No money moves. Nobody can change the record later.

**1. Open the dialog**

Click **Close** on the row. The dialog **Record where this money went** opens.

**2. Choose the outcome**

Select the outcome that matches what happened:

* `RETURNED`: a person sent the money back to the paying bank.
* `CREDITED`: a person credited the beneficiary.
* `ABSORBED`: the institution keeps money that reached neither end.

**3. Write the note**

Type a **Note** of 10 to 500 characters.

**4. Record the closure**

Click **Record closure**. If the plugin refuses the closure, the dialog stays open and shows its reason.

> [!WARNING]
>
> Record the outcome only after the money moved. The record is final, and the Console moves no money for it.

## Related pages

***

> **[Reconciliation](/en/interfaces/ted-jd/console/bt-managing-reconciliation)**
>
> Retry or resolve a TED Out in manual review.

> **[Accounting Routes](/en/interfaces/ted-jd/console/bt-accounting-routes)**
>
> Bind each scope to the Midaz accounting routes that the plugin posts with.


# Viewing Settings History
Source: https://docs.lerian.studio/en/interfaces/ted-jd/console/bt-viewing-settings-history

Lerian Console shows the current Bank Transfer settings only, with no change history.

Lerian Console does not show a change history for Bank Transfer settings. The [Settings](/en/interfaces/ted-jd/console/bt-managing-settings) page shows the current values only.


# Managing Webhooks
Source: https://docs.lerian.studio/en/interfaces/ted-jd/console/bt-webhooks

Register the endpoints that receive Bank Transfer events, rotate their signing secret, and retry failed deliveries, from the Bank Transfer plugin in Lerian Console.

The **Webhooks** page of the **Bank Transfer** plugin registers the endpoints that receive Bank Transfer events. It also lists the deliveries that failed. For the events, the signature, and the retry schedule, see [Webhooks](/en/interfaces/ted-jd/ted-webhooks).

Each Bank Transfer screen needs the `bank-transfer` permission: `get` to see it, `post` to act on it, `patch` to change settings and the routing document, and `delete` to delete a webhook. On this page, **Register webhook**, **Rotate signing secret**, and **Retry delivery** need `post`. **Edit**, **Enable**, and **Disable** need `patch`. **Delete** needs `delete`.

## Accessing the page

***

**1. Open Bank Transfer**

From the Midaz Module sidebar, expand **Bank Transfer**.

**2. Click Webhooks**

Select **Webhooks** in the submenu.

The page has two tabs: **Registrations** and **Failed deliveries**.

## Registrations

***

The **Registrations** tab lists your webhook registrations, 10 per page.

| Column | Description |
| - | - |
| Name | Name of the registration. |
| Endpoint | URL that receives the events. |
| Status | **Enabled** or **Disabled**. |
| Events | Number of event types that the registration receives. When the registration lists no event type, the column shows **All events**. |
| Updated | When the registration last changed. |
| Actions | **Edit**, **Enable** or **Disable**, **Rotate signing secret**, and **Delete**. |

### Register a webhook

**1. Open the form**

Click **Register webhook**.

**2. Fill in the fields**

* **Name**: a name for the registration.
* **Endpoint URL**: the URL that receives the events.
* **Enabled**: on by default.
* **Event types**: the events to receive. Leave the list empty to receive every event.

**3. Save**

Click **Save**.

**4. Copy the signing secret**

The **Signing secret** dialog shows the secret once. Copy it before you click **I've saved it**. Use the secret to verify the signature on every delivery.

If the copy fails, select the secret and copy it by hand before you close the dialog. If the dialog shows no secret, the plugin already made that secret available once. Rotate the signing secret to get a new one.

### Edit a webhook

Click **Edit** in the row actions. Change the fields, then click **Save**. The Console sends only the fields that you change.

### Enable or disable a webhook

Click **Disable** in the row actions of an enabled webhook, or **Enable** in the row actions of a disabled webhook.

### Rotate the signing secret

**1. Start the rotation**

Click **Rotate signing secret** in the row actions.

**2. Confirm**

Click **Rotate signing secret** in the dialog.

**3. Copy the new secret**

The **Signing secret** dialog shows the new secret once, as on registration.

> [!WARNING]
>
> Rotation invalidates the current secret at once. Deliveries fail verification until you deploy the new secret.

### Delete a webhook

Click **Delete** in the row actions, then confirm.

## Failed deliveries

***

The **Failed deliveries** tab lists the events that the plugin could not deliver after its automatic retries, 50 per page.

| Column | Description |
| - | - |
| Event | The event type. |
| Transfer | The transfer of the event. |
| Failure | Why the delivery failed. |
| Automatic retries | Number of automatic retries. |
| Manual retries | Number of manual retries. |
| Failed at | When the delivery failed. |
| Actions | **Retry delivery**. |

When the plugin does not expose the failed-delivery routes, the tab shows the message of the plugin instead of the list.

### Retry a delivery

**1. Start the retry**

Click **Retry delivery** in the row actions.

**2. Confirm**

Click **Retry delivery** in the dialog. The endpoint can receive the event more than once.

If the plugin refuses the retry because the delivery reached its maximum of manual retries, **Retry delivery** becomes unavailable on that row. Its hint reads **Maximum manual retries reached**.

## Related pages

***

> **[Webhooks](/en/interfaces/ted-jd/ted-webhooks)**
>
> Events, signature verification, and the retry schedule.

> **[Developer guide](/en/interfaces/ted-jd/ted-developer-guide)**
>
> Signature validation code and the integration checklist.


# Best practices
Source: https://docs.lerian.studio/en/interfaces/ted-jd/ted-best-practices

Practices for integrating Bank Transfer: show fees before confirmation, handle settlement windows, and reduce customer complaints.

This guide covers the key decisions your team makes when you integrate Bank Transfer. It also gives the best practices for a reliable and compliant customer experience.

## Product decisions

***

These are choices your product team makes in the customer-facing experience. They directly affect customer satisfaction and support volume.

### Show the fee before the customer confirms

The `initiate` step returns the fee amount before any funds move. Use this window to show a clear confirmation screen:

```
Confirm transfer

Recipient: Maria Silva — Bradesco (237)

Amount:   R$ 1,000.00
Fee:          R$ 1.50
─────────────────────
Total:    R$ 1,001.50

[ Cancel ]        [ Confirm ]
```

This reduces complaints and cancellations from customers surprised by fees after the fact.

### Handle operating hours gracefully

TED OUT is available Monday to Friday, 06:30–17:00 (Brasília time) by default. When a customer starts a transfer outside these hours, do not show only an error. Tell them when they can try again:

```
TED transfers are available Monday to Friday, 06:30 to 17:00.
Next available time: Monday at 06:30.
```

To avoid unnecessary round trips, validate operating hours on the client side before you call the API.

You do not need to maintain your own holiday list. The plugin blocks weekends and BACEN holidays automatically, from its built-in holiday calendar for 2026 to 2028.

When a holiday rejects a transfer, show that reason to the customer. Do not replicate the calendar on the client. Trust the plugin as the source of truth to avoid inconsistencies over time.

### Communicate transfer limits before customers hit them

Show the customer's remaining daily limit in your transfer UI. Show it before they attempt a transfer that the plugin rejects. The plugin counts the amount debited from the sender (`totalAmount`), and the day rolls over at 00:00 UTC (21:00 Brasília time). For example:

```
Daily limit: R$ 50,000.00
Used today:  R$ 45,000.00
Available:    R$ 5,000.00
```

### Show confirmation receipts after completion

After a TED OUT or P2P transfer completes, display (or offer to download) a receipt with:

* Transfer date and time
* Sender and recipient details
* Amount, fee, and total
* `confirmationNumber` (customer-facing reference)
* `controlNumber` (JD SPB reference, for TED OUT and TED IN)

When you provide this information early, you reduce "did my transfer go through?" support contacts.

### Keep customers informed in real time

Use webhooks to push transfer status updates to your UI as they happen. Do not make customers refresh or wonder if their transfer went through. See [TED webhooks](/en/interfaces/ted-jd/ted-webhooks) for setup.

## Compliance decisions

***

These are requirements that apply to your integration regardless of your product choices.

### LGPD and personal data

Transfer records contain personal data: customer names, CPF/CNPJ, and bank details. Make sure your privacy policy explicitly covers financial transaction data. Do not log CPF/CNPJ in plain text. Mask it in interfaces as `***.***.***-00`.

The plugin has no endpoint for LGPD right-to-erasure requests.

### Data retention

> [!WARNING]
>
> The plugin never deletes or expires transfer records, so you own their retention. Retain transfer and audit data for at least **5 years**, per BACEN record-keeping requirements for financial institutions.

### Audit trail and reconciliation

Every transfer generates two reference numbers you must store:

| Field | What it is | When to use |
| - | - | - |
| `transferId` | Internal Lerian identifier | API lookups, support cases |
| `confirmationNumber` | User-readable reference | Receipts, customer communication |
| `controlNumber` | JD SPB reference (TED OUT and TED IN) | BACEN audit trail, regulatory reporting |

Keep both the `transferId` and `confirmationNumber` in your own records for reconciliation. For TED OUT and TED IN, also store the `controlNumber`.

### Operating hours

BACEN mandates that TED operates Monday to Friday, 06:30–17:00 (Brasília time, UTC-3). The plugin enforces this window by default. An operator can change the window at runtime through the systemplane key `operating_hours.window`. Treat 06:30–17:00 as the norm and build your UX around it. See [Handle operating hours gracefully](#handle-operating-hours-gracefully) above.

> [!NOTE]
>
> P2P transfers are not subject to operating hour restrictions and work 24/7.

## Integration checklist

***

Before you go live, verify the following:

* [ ] **Idempotency keys on all write operations**: Send a UUID v4 `X-Idempotency` header on every call to `initiate`, `process`, and `cancel`. This prevents duplicate transfers from retries or double-clicks.
* [ ] **Webhook endpoint live before launch**: Deploy your webhook endpoint and make it reachable before you go live. Transfer events start firing immediately on the first real transaction.
* [ ] **Expiry handled**: An initiated transfer expires at `expiresAt`: after 24 hours, or for TED OUT at the close of that day's operating window. If your flow allows a customer to start a transfer and return later, handle the expiry case explicitly.
* [ ] **Read before you retry a 5xx**: A `5xx` leaves the outcome unknown. Read the transfer first, and retry with backoff (e.g., 2s, 4s, 8s) under a new `X-Idempotency` key only if the operation did not happen. JD SPB unavailability surfaces as `503` with `BTF-1000` or `BTF-1003`. Midaz ledger unavailability surfaces as `BTF-2000`. Do not retry immediately in a loop.
* [ ] **Operating hours validated client-side**: Check hours in the UI before you call the API. This reduces failed API calls and gives a better customer experience.
* [ ] **Both `transferId` and `confirmationNumber` stored**: Required for reconciliation and audit. For TED OUT and TED IN, also store `controlNumber`.

## Error handling

***

Use these error scenarios to map API errors to customer-friendly messages and define the correct recovery path.

| Scenario | Customer-facing message | Recovery |
| - | - | - |
| **Outside operating hours** (`BTF-0010`) | "TED transfers are available Monday–Friday, 06:30–17:00. Next available time: \[date/time]." | Recoverable. Wait for the next window |
| **Insufficient balance** (`BTF-2003`, HTTP `422`, the ledger refused the debit) | "Your account doesn't have enough balance for this transfer." | Recoverable. Customer adds funds or reduces the amount |
| **Limit reached** (`BTF-0011`) | "You've reached your \[daily/monthly] transfer limit of R\$ \[X]." | Recoverable. Wait for reset: 00:00 UTC for the daily limit, the first day of the month (UTC) for the monthly limit |
| **Invalid recipient** (`BTF-0500`) | "Destination account not found. Please check the account details and try again." | Recoverable. Customer corrects details |
| **Service unavailable** (`BTF-1000` or `BTF-1003`, HTTP `503`) | "Transfer service is temporarily unavailable. We will update you." | Read the transfer named in `transferId` before any retry |
| **Duplicate transfer** (`BTF-0012`) | "An identical transfer was sent recently. If this was intentional, wait a moment and try again." | Conditional. Wait for the deduplication window to clear |

For the complete list of error codes and their meanings, see the [TED error list](/en/reference/interfaces/ted-jd/ted-error-list).


# Configuration
Source: https://docs.lerian.studio/en/interfaces/ted-jd/ted-configuration

Configure Bank Transfer at the infrastructure and tenant levels, with limits, fee policies, operating hours, and ledger routing adjustable at runtime.

The Bank Transfer plugin splits configuration across two levels. You can change most business settings at runtime, with no service restart.

The tenant identity and the Midaz organization scope serve different purposes. Keep them distinct.

On Lerian Cloud, the `tenantId` JWT claim in the authenticated request context identifies your tenant, and Lerian isolates your data.

The `X-Organization-Id` header defines the Midaz organization scope inside that tenant. Every organization-scoped transfer route requires this header, in all deployment modes. A request returns `400` if it omits the header or sends a value that is not a valid UUID.

Background processes, such as the TED IN poller and reconciliation workers, do not receive request headers. With TED IN polling on, these processes use the `ORGANIZATION_ID` environment variable as the organization context.

## Configuration levels

***

The Bank Transfer plugin has two configuration levels:

* **Infrastructure configuration** (DevOps manages it) controls URLs, credentials, authentication settings, and timeouts. Changes need a service restart.
* **Runtime settings** (managed through the Admin API) control transfer limits, fee policies, operating hours, and ledger routing. Settings in the `tenant_policy` namespace apply to one tenant. Settings in the `runtime_config` namespace apply to the whole deployment. Changes take effect with no service restart.

## Business decisions you can configure

***

GPMs and product teams care about these settings. You manage them through the Admin API at runtime, with no deploy, except deploy-time variables such as `MIDAZ_FEE_MODE`, which change only at restart.

### Transfer limits

Set daily and monthly amount caps per tenant with `usage_limits.enabled`, `usage_limits.daily_limit_cents`, and `usage_limits.monthly_limit_cents`. The plugin applies the caps to each sender account, on the amount debited from the sender (`totalAmount`), when it processes a TED OUT or P2P transfer. The day and the month roll over at 00:00 UTC. A transfer over a cap is refused with `422 BTF-0011`.

### Fee policy

The deploy-time variable `MIDAZ_FEE_MODE` decides who prices and charges the fee of each TED OUT, TED IN, and P2P transfer:

* **`legacy`**: plugin-fees prices the fee from its own packages. `BTF_FEE_ENABLED` turns it on. With `false`, the default, the plugin does not call plugin-fees, and every transfer runs with fee 0.
* **`native`**: the [Fees Engine](/en/products/midaz/fees/fees-engine-overview) of Midaz 4.1.0 or later prices and charges the fee from the fee packages of the ledger. `BTF_FEE_ENABLED` does not turn this fee on or off. To stop a fee, disable its Midaz fee package with `enable: false`, or delete the package.
* **`auto`** (default): `native` on Midaz 4.1.0 or later, and `legacy` on an earlier version or when the first read of the version fails.

> [!WARNING]
>
> Under `auto`, an upgrade of Midaz to 4.1.0 or later moves Bank Transfer to `native` by itself. If your fee packages still live in plugin-fees, Midaz finds no package, and new transfers carry no fee. Set `MIDAZ_FEE_MODE=legacy` before you upgrade Midaz, then follow [Migrate Bank Transfer fees to Midaz](/en/products/midaz/fees/fees-migration-guide).

### Fail-open vs. fail-closed

In `legacy` mode, the tenant policy `fees.fail_closed_default` (default `false`) decides what a plugin-fees failure does:

* **TED OUT and P2P**: when plugin-fees is unavailable, the transfer proceeds with no fee (fail-open). With `true`, the plugin refuses the transfer (fail-closed). A fee that plugin-fees refuses always refuses the transfer.
* **TED IN**: any fee failure credits the funds with fee 0. With `true`, the plugin does not credit, and returns the transfer to the origin bank.

### TED IN receiving

TED IN polling is off by default. DevOps turns it on for the deployment with `JD_POLLING_ENABLED=true`, after the JD SPB credentials are in place.

When the plugin cannot find the recipient of a TED IN, the tenant policy `jd_polling.auto_return_authorized` (default `false`) decides whether it returns the funds to the origin bank or retains the message for an operator. See [Receive (TED IN)](/en/interfaces/ted-jd/ted-in#what-happens-when-a-recipient-isnt-found).

### Operating hours

Each tenant has one TED OUT window: `operating_hours.window` (`HH:MM-HH:MM`, default `06:30-17:00`) in `operating_hours.timezone` (default `America/Sao_Paulo`). The plugin refuses a TED OUT outside the window, on weekends, and on BACEN holidays with `422 BTF-0010`. P2P ignores the window.

### Ledger routing

The tenant policy `routing.ledger_bindings` is one JSON document that binds each Midaz organization, ledger, and transfer type to its accounting routes. A binding either names the Midaz transaction and operation routes to use, or sets `mode: omit` to post with no routes. There is no fallback from one binding to another. Without a binding:

* TED OUT and P2P are refused with `503 BTF-9015`. The error names the missing setting in `systemplaneKey` and the cause in `reason`.
* A TED IN is retained with reason `LEDGER_ROUTE_UNRESOLVED`. The plugin processes it again on each poll cycle and credits it once the binding exists.

## Infrastructure configuration

***

DevOps sets the deploy-time environment variables (URLs, credentials, TLS, persistence, integrations, security keys). These variables require a service restart. See the full reference in [Environment variables](/en/interfaces/ted-jd/ted-environment-variables).

## Runtime configuration (Admin API)

***

You manage runtime settings through the Admin API under `/system/:namespace/:key`, with no restart. Tenant policy keys live in the `tenant_policy` namespace. Deployment-wide keys live in `runtime_config`.

Configurable settings include:

* Transfer limits (daily and monthly, per tenant)
* Fee behavior (`fees.fail_closed_default`, `fees.max_fee_amount_cents`)
* Recipient-not-found returns for TED IN (`jd_polling.auto_return_authorized`)
* Operating hours (`operating_hours.window`, `operating_hours.timezone`)
* Ledger routing (`routing.ledger_bindings`)

### Systemplane-managed settings

The systemplane (Admin API) manages the settings below at runtime, not at deploy time. The plugin ignores these environment variables: if you set one, it logs the WARN `systemplane-managed environment variable is set and ignored`. Use the systemplane to change them.

| Area | Settings |
| - | - |
| Logging | `LOG_LEVEL` |
| Rate limiting | `RATE_LIMIT_ENABLED`, `RATE_LIMIT_MAX`, `RATE_LIMIT_EXPIRY_SEC` |
| CORS | `CORS_ALLOWED_ORIGINS`, `CORS_ALLOWED_METHODS`, `CORS_ALLOWED_HEADERS` (default origin is wildcard `*` when unconfigured; not validated at startup) |
| Fee policy | `FEES_FAIL_CLOSED_DEFAULT`, `FEES_MAX_FEE_AMOUNT_CENTS` |
| Usage limits | `USAGE_LIMITS_ENABLED`, `USAGE_LIMIT_DAILY_CENTS`, `USAGE_LIMIT_MONTHLY_CENTS` |
| Operating hours | `TRANSFER_OPERATING_OPEN`, `TRANSFER_OPERATING_CLOSE`, `TRANSFER_OPERATING_TIMEZONE` (replaced by `operating_hours.window` and `operating_hours.timezone`) |
| Idempotency / duplicate guard | `IDEMPOTENCY_REQUIRE_REDIS`, `DUPLICATE_GUARD_TTL_SEC` |
| Routing | `ROUTING_*` (the route IDs are replaced by `routing.ledger_bindings`) |
| JD timeout & retry tuning | `JD_TIMEOUT_MS`, `JD_MAX_RETRIES`, `JD_VALIDATE_EXTERNAL_SIGNATURE` |
| JD polling tuning | `JD_POLL_MAX_MESSAGES_PER_CYCLE`, `JD_POLL_RECOVERY_BATCH_SIZE`, `JD_POLL_DISABLE_OPERATING_HOURS_WINDOW` |
| Reconciliation tuning | `BTF_RECONCILIATION_BATCH_SIZE`, `BTF_RECONCILIATION_MAX_ATTEMPTS`, `BTF_RECONCILIATION_STALE_AFTER_SEC`, `BTF_RECONCILIATION_TICK_DEADLINE_SECONDS`, `RECONCILIATION_PENDING_ALERT_THRESHOLD` |
| RabbitMQ publish tuning | `RABBITMQ_MAX_RETRIES`, `RABBITMQ_PUBLISH_TIMEOUT_MS`, `RABBITMQ_RETRY_BACKOFF_MS`, `RABBITMQ_ROUTING_KEY_PREFIX` |
| Webhook delivery tuning | `WEBHOOK_TIMEOUT_MS`, `WEBHOOK_MAX_RETRIES`, `WEBHOOK_RETRY_BACKOFF_MS`, `WEBHOOK_ALLOW_UNSIGNED_BROKER_EVENTS`, `WEBHOOK_UNSIGNED_BROKER_EVENTS_GRACE_SEC` |

> [!WARNING]
>
> When CORS is unconfigured, the default allowed origin is the wildcard `*`. Any origin can then call the API, and the plugin does not validate it at startup. For production, set explicit origins through the systemplane key `cors.allowed_origins` instead of the wildcard.


# Data and reporting
Source: https://docs.lerian.studio/en/interfaces/ted-jd/ted-data-model

Reference the data fields and status lifecycles available for TED transfers, used for reconciliation, audit trails, and compliance reporting.

Every transfer generates a complete audit trail. This page describes the data available for reporting, reconciliation, and compliance.

## What data is recorded per transfer

***

| Field | What it means |
| - | - |
| `transferId` | Your internal reference for this transfer |
| `confirmationNumber` | Human-readable reference (e.g. 20260205001). Show this to customers |
| `controlNumber` | JD SPB reference. Use for bank reconciliation |
| `type` | TED OUT, TED IN, or P2P |
| `status` | Current state of the transfer |
| `organizationId` | The Midaz organization that the transfer is filed under |
| `ledgerId` | The Midaz ledger that the transfer is filed under |
| `amount` | Amount before fee. For TED IN, the amount credited after the fee |
| `feeAmount` | Fee charged |
| `totalAmount` | The amount debited from the sender: `amount` plus any fee charged on top of it. For TED IN, the amount received |
| `senderAccountId` | Sending account in your system. Always present. For TED IN, where the sender is an external bank with no local account, it is a synthetic identifier deterministically derived from the sender's document |
| `recipientAccountId` | Recipient account in Midaz, when the recipient is represented internally |
| `recipient` | Recipient bank, branch, account number, and holder name |
| `originalTransferId` | The original TED OUT transfer that a devolution (return) TED IN compensates |
| `devolutionCode` | BACEN devolution reason code, when applicable |
| `createdAt` | When the transfer was initiated |
| `completedAt` | When settlement was confirmed |

## Transfer status lifecycle

***

### TED OUT

![TED OUT state machine diagram](https://mintcdn.com/lerian-49cb71fc/0kJvev-xNu0CYwa1/images/en/d2/ted-state-machine-ted-out.svg?fit=max\&auto=format\&n=0kJvev-xNu0CYwa1\&q=85\&s=2ca05e4746f0835ad56259d05ed00814)

* **Customer confirmed** (`CREATED`): the plugin created the transfer and placed a hold on amount + fee
* **Preparing submission** (`PENDING`): the plugin prepares the message for JD
* **Bank processing** (`PROCESSING`): the plugin sent the transfer to JD and waits for the settlement result. A timeout keeps the transfer here while reconciliation asks JD for the outcome
* **Settled** (`COMPLETED`): the STR settled the transfer and the plugin committed the hold
* **Rejected** (`REJECTED`): JD or the STR rejected the transfer, and the plugin released the hold
* **Failed** (`FAILED`): the ledger refused the hold, or reconciliation could not settle the transfer. When reconciliation stops after its last attempt, the hold stays in place and an operator resolves the transfer (reconciliation status `MANUAL_REVIEW`)
* **Cancelled** (`CANCELLED`): the transfer was cancelled from `CREATED` or `PENDING`, and the plugin released the hold

### TED IN

![TED IN state machine diagram](https://mintcdn.com/lerian-49cb71fc/0kJvev-xNu0CYwa1/images/en/d2/ted-state-machine-ted-in.svg?fit=max\&auto=format\&n=0kJvev-xNu0CYwa1\&q=85\&s=242fc13578b92f6eb21c0f8e923eda17)

* **Transfer detected** (`RECEIVED`): incoming message persisted, pending internal processing
* **Recipient validated** (`PROCESSING`): the system credits the recipient account
* **Amount credited** (`COMPLETED`): recipient account successfully credited
* **Failed** (`FAILED`): the ledger refused the credit, or the sending bank charged back a completed credit

### P2P

![P2P state machine diagram](https://mintcdn.com/lerian-49cb71fc/0kJvev-xNu0CYwa1/images/en/d2/ted-state-machine-ted-p2p.svg?fit=max\&auto=format\&n=0kJvev-xNu0CYwa1\&q=85\&s=070c9a653297ff59f1da407fcd0b2393)

* **Confirmed** (`CREATED`): the customer confirmed the transfer between internal accounts
* **Processing** (`PROCESSING`): Midaz transaction in progress
* **Settled** (`COMPLETED`): both accounts updated successfully
* **Failed** (`FAILED`): the ledger refused the posting

## Fee review before confirmation

***

For TED OUT and P2P, customers go through a two-step flow:

![PaymentInitiation lifecycle diagram](https://mintcdn.com/lerian-49cb71fc/0kJvev-xNu0CYwa1/images/en/d2/ted-state-machine-initiation.svg?fit=max\&auto=format\&n=0kJvev-xNu0CYwa1\&q=85\&s=b07153b3f5d5c5c5f179abef2145a9dd)

* **Pending confirmation**: the plugin calculated and presented the fee. The customer has not confirmed it yet
* **Processed**: the customer confirmed and the plugin created the transfer
* **Expired**: the initiation expired without confirmation. An initiation is valid for 24 hours. A TED OUT initiation expires earlier, at the close of that day's operating window

Customers can review the fee before they confirm the transfer.

## Status history

***

The plugin records every status transition. [Get Transfer](/en/reference/interfaces/ted-jd/retrieve-transfer) returns them in `statusHistory`, each with the previous status, the new status, a timestamp, and a reason when one applies.

## Reconciliation fields

***

Use these fields to match transfer records against your bank statements:

| Field | Use for |
| - | - |
| `controlNumber` | Matching against JD SPB records |
| `confirmationNumber` | Customer-facing reference |
| `transferId` | Internal system lookups |
| `originalTransferId` | Link a devolution (return) TED IN to the original TED OUT it compensates |
| `devolutionCode` | Classify the BACEN reason for a devolution (return) |
| `createdAt` | Filtering by initiation date |
| `completedAt` | Filtering by settlement date |
| `reconciliationStatus` | Finding transfers that reconciliation holds, for example `MANUAL_REVIEW` |

## Data retention

***

> [!WARNING]
>
> Do not delete transfer records. The plugin never deletes or expires them, so you own their retention. Keep transfer and audit records for at least 5 years, per BACEN record-keeping requirements.

## Querying your data

***

Use [List Transfers](/en/reference/interfaces/ted-jd/list-transfers) to query transfers with the following filters:

* **By creation date**: `createdFrom` and `createdTo`
* **By type**: TED OUT, TED IN, or P2P
* **By status**: e.g., only `COMPLETED` transfers for reconciliation, or `FAILED` for investigation
* **By reconciliation status**: `reconciliationStatus`
* **By amount**: `minAmount` and `maxAmount`
* **By ledger**: `ledgerId`

## For developers

***

### Storage

The plugin stores transfer data in PostgreSQL. The `recipientAccountId` field references a Midaz account when the recipient is internal. The organization is the main filter.

### Incoming TED deduplication

Before it processes a TED IN transfer, the plugin stores the raw JD message. This lets the plugin recover incoming transfers if the service fails during processing.

Each stored message is unique by JD's `NumCabSeq`. If JD re-delivers the same message, the plugin identifies it as a duplicate and ignores it.

### What the plugin sends to Midaz

The plugin posts every settled movement to Midaz as a ledger transaction, but Midaz records the accounting entry, not the transfer's banking details. Counterparty identity (bank, branch, account, holder name and document) and BACEN references (`controlNumber`, `clearingControlNumber`) live only in the plugin's `Transfer` record. For a TED IN, the credit enters the ledger from the `@external/BRL` account. The sender's identity is not encoded into the Midaz transaction.

The Midaz transaction carries only correlation metadata:

| Metadata key | Value |
| - | - |
| `contractVersion` | `1` |
| `plugin` | `br-bank-transfer` |
| `rail` | `TED`, or `INTERNAL` for P2P |
| `flow` | `CASH_OUT` (TED OUT), `CASH_IN` (TED IN), `P2P`, or `REFUND` (a devolution refund or a chargeback compensation) |
| `direction` | `OUT` or `IN`. Absent on P2P |
| `aggregateId` | The plugin's transfer identifier: the pivot back to the full record |
| `originalAggregateId` | On `REFUND`, the transfer that the refund returns |
| `providerMessageId`, `providerMessageCode` | The JD message that produced a TED IN credit or a devolution refund |

Correlation works in both directions:

* The transfer record stores `midazTransactionId`, so [Get Transfer](/en/reference/interfaces/ted-jd/retrieve-transfer) returns the full banking detail for any ledger entry.
* The Midaz transaction stores the transfer identifier in `metadata.aggregateId`, so you can filter Midaz transactions by it to find the ledger entry for a transfer.

Custom metadata you pass when you initiate a TED OUT or P2P transfer never reaches Midaz. The plugin stores it on the transfer and returns it as `clientMetadata`.

### Entity relationships

The TED domain model follows these relationships:

* Each `Transfer` belongs to a single Midaz organization and can have multiple `TransferStatusHistory` records.
* TED OUT and P2P transfers originate from a `PaymentInitiation` in the two-step transfer flow.
* Each `JDIncomingMessage` can create at most one `Transfer` of type `TED_IN`.

![Entity relationships diagram](https://mintcdn.com/lerian-49cb71fc/0kJvev-xNu0CYwa1/images/en/d2/ted-entity-relationships.svg?fit=max\&auto=format\&n=0kJvev-xNu0CYwa1\&q=85\&s=d587bb875d1babf1e69e5f2ce568ebdf)


# Developer guide
Source: https://docs.lerian.studio/en/interfaces/ted-jd/ted-developer-guide

Implement Bank Transfer integrations correctly: idempotency, retry strategy, state handling, and webhook validation patterns for reliable transfers.

This guide is for developers who implement the Bank Transfer plugin integration. It covers the patterns and decisions that go beyond individual endpoint calls: idempotency, retry strategy, state handling, and webhook validation.

For endpoint parameters and response schemas, see the [API Reference](/en/reference/interfaces/ted-jd/initiate-transfer).

## Idempotency

***

Every mutating request (initiate, process, cancel) requires an `X-Idempotency` header. A request without it is refused with `400 BTF-0001`. If you send the same request twice under one key, the plugin returns the original response without creating a duplicate operation.

**Rules:**

* Use a UUID v4 or a unique business identifier (e.g. your internal order ID)
* Maximum length: 255 characters
* The plugin scopes each key to the effective organization. The same key from two organizations counts as two distinct requests.
* The plugin replays a successful response for 7 days. A replay carries the same status code and body, plus the header `X-Idempotency-Replayed: true`.
* A `4xx` answer does not spend the key: fix the request and send it again under the same key.
* After a `5xx` answer the outcome is unknown: read the resource first, and send the request again only under a new key. A key that the answer fenced (`X-Idempotency-Fenced: true`) is refused with `422 BTF-0014`. A `503 BTF-9000` or `503 BTF-9017` ran nothing: send it again under the same key.
* The same key with a different body is refused with `422 BTF-0017`. A resend while the first request still runs gets `409 BTF-0016` with `Retry-After`.
* Every idempotency refusal states its remedy in `detail`. Read it before you resend.

```http theme={null}
POST /v1/transfers/initiate
X-Organization-Id: 019c9ac2-3f5d-7df9-9215-bdccc1451def
X-Idempotency: 7f3d9a1b-4e2c-4f8a-b3d1-9e6f2a4c8b7e
```

> [!WARNING]
>
> Do not reuse idempotency keys across different operations. Do not reuse an initiate key to process or cancel the same transfer.

### Duplicate detection

Beyond idempotency keys, the plugin detects content-based duplicates. It builds a fingerprint from:

* `senderAccountId`
* recipient details (ISPB, branch, account, holder document)
* amount
* purpose

The plugin stores the fingerprint in Redis for 5 minutes. The default is 300 seconds. Operators tune it per tenant through the systemplane setting `idempotency.duplicate_guard_ttl_seconds`. The organization is not part of the fingerprint. Tenant isolation comes from the Redis key prefix. The plugin rejects the request with `409 BTF-0012` if the client already submitted a matching transfer inside the window.

This catches cases where the client sends the same transfer with a different idempotency key. One example is a retry after a timeout, when the client did not receive the original response.

## Retry strategy

***

Use exponential backoff for transient errors. Do not retry every error.

| HTTP status | Retry? | Notes |
| - | - | - |
| `400` | No | Validation error. Fix the request before retrying |
| `404` | No | Not found. The resource does not exist |
| `409` | Depends | `BTF-0016`: the first request is still running; resend under the same key after `Retry-After`. Any other `409`: do not resend |
| `410` | No | Expired. Create a new initiation |
| `422` | No | Business rule (operating hours, limits) or idempotency refusal. The condition must change first |
| `429` | Yes | Rate limit. Wait for the `Retry-After` header value (seconds) |
| `5xx` | Read first | The outcome is unknown. Read the transfer, then retry with backoff under a new key only if the operation did not happen. A `503 BTF-9000` or `503 BTF-9017` ran nothing: retry under the same key |

**Recommended backoff schedule for 5xx:** 0s, 5s, 25s, 60s, 120s (5 attempts total).

> [!NOTE]
>
> During `POST /v1/transfers/process`, when JD SPB is unavailable, the response is `HTTP 503` with `code` `BTF-1000`, or `BTF-1003` on a JD timeout. `upstream.code` carries JD's own code when JD returned one. `transferId` and `transferStatus` name the transfer. A transfer in `PROCESSING` keeps its hold while reconciliation asks JD for the outcome: do not process it again.

## State handling

***

### TED OUT state machine

Transfers follow a strict progression. You cannot cancel a transfer after it leaves `CREATED` or `PENDING`.

![TED OUT state machine](https://mintcdn.com/lerian-49cb71fc/0kJvev-xNu0CYwa1/images/en/d2/ted-state-machine-ted-out.svg?fit=max\&auto=format\&n=0kJvev-xNu0CYwa1\&q=85\&s=2ca05e4746f0835ad56259d05ed00814)

**What to do in each state:**

| State | Meaning | Recommended action |
| - | - | - |
| `CREATED` | Confirmed by user, queued for submission | Show "Processing" in UI; poll or wait for webhook |
| `PENDING` | The plugin prepares the submission to JD | Show "Processing"; cancellation is still possible |
| `PROCESSING` | Sent to JD, awaiting the settlement result | Show "Processing"; do not allow cancellation |
| `COMPLETED` | Settled | Show confirmation with `confirmationNumber` |
| `REJECTED` | JD rejected (invalid data, rule violation) | Show error to user; funds already released |
| `FAILED` | The ledger refused the hold, or reconciliation could not settle the transfer | Show error. If `reconciliationStatus` is `MANUAL_REVIEW`, the hold is still in place and an operator can still settle the transfer: do not offer a new transfer until it is resolved |
| `CANCELLED` | Cancelled before submission | Show cancellation confirmation |

### Initiation state machine

The initiate endpoint creates a `PaymentInitiation` entity. This entity has its own lifecycle before the plugin creates a `Transfer`.

![Initiation state machine](https://mintcdn.com/lerian-49cb71fc/0kJvev-xNu0CYwa1/images/en/d2/ted-state-machine-initiation.svg?fit=max\&auto=format\&n=0kJvev-xNu0CYwa1\&q=85\&s=b07153b3f5d5c5c5f179abef2145a9dd)

### TED IN state machine

![TED IN state machine](https://mintcdn.com/lerian-49cb71fc/0kJvev-xNu0CYwa1/images/en/d2/ted-state-machine-ted-in.svg?fit=max\&auto=format\&n=0kJvev-xNu0CYwa1\&q=85\&s=242fc13578b92f6eb21c0f8e923eda17)

### P2P state machine

P2P does not have a `PENDING` state. Settlement is atomic and instant.

![P2P state machine](https://mintcdn.com/lerian-49cb71fc/0kJvev-xNu0CYwa1/images/en/d2/ted-state-machine-ted-p2p.svg?fit=max\&auto=format\&n=0kJvev-xNu0CYwa1\&q=85\&s=070c9a653297ff59f1da407fcd0b2393)

### Polling vs. webhooks

Prefer webhooks for real-time status. If you have not configured webhooks yet, poll `GET /v1/transfers/{transferId}`. Use a maximum of 10 attempts with the same backoff schedule as retries. Flag the transfer for manual review after 10 minutes with no terminal state (`COMPLETED`, `REJECTED`, `FAILED`, `CANCELLED`).

See [Get Transfer](/en/reference/interfaces/ted-jd/retrieve-transfer) and [Webhooks](/en/interfaces/ted-jd/ted-webhooks).

## Webhook integration

***

For event payload schemas and the full list of events, see [Webhooks](/en/interfaces/ted-jd/ted-webhooks).

### Signature validation

Every webhook request includes headers your endpoint uses to verify authenticity:

* `X-Webhook-Signature`: versioned HMAC-SHA256 signature in the form `v1,sha256=<hex>`
* `X-Webhook-Timestamp`: Unix timestamp in seconds (UTC) when the plugin built the request
* `X-Webhook-Event`: the event type (for example, `transfer.completed`). This header is not part of the signature.

The plugin computes the signature as:

```
X-Webhook-Signature: v1,sha256=hex(HMAC_SHA256(signingSecret, "v1:" + <timestamp> + "." + <raw_body>))
```

The signed string has four parts in order: the prefix `v1:`, the timestamp value from `X-Webhook-Timestamp`, one ASCII dot (`.`), then the raw request body bytes. Use the body bytes exactly as they arrive on the wire. Do not parse or re-encode them first.

To validate:

1. Read `X-Webhook-Signature` and `X-Webhook-Timestamp` from the request headers.
2. Build the signed string: `"v1:" + timestamp + "." + rawBody`.
3. Compute `HMAC-SHA256` over the signed string with the `signingSecret` of the webhook registration, then hex-encode the result.
4. Prepend `v1,sha256=`, then compare against `X-Webhook-Signature` with a constant-time equality function.
5. Reject the request if the timestamp is outside an acceptable freshness window (a 5-minute tolerance is typical) to prevent replay.

> **JavaScript**
>
> ```javascript theme={null}
> const crypto = require('crypto');
> const express = require('express');
>
> const TOLERANCE_SECONDS = 300; // 5 minutes
>
> function validateWebhook(rawBody, timestamp, signature, secret) {
>   if (!timestamp || !signature) return false;
>
>   const ageSeconds = Math.abs(Math.floor(Date.now() / 1000) - parseInt(timestamp, 10));
>   if (Number.isNaN(ageSeconds) || ageSeconds > TOLERANCE_SECONDS) return false;
>
>   const signedPayload = Buffer.concat([
>     Buffer.from('v1:', 'utf8'),
>     Buffer.from(timestamp, 'utf8'),
>     Buffer.from('.', 'utf8'),
>     rawBody,
>   ]);
>
>   const expected = 'v1,sha256=' + crypto
>     .createHmac('sha256', secret)
>     .update(signedPayload)
>     .digest('hex');
>
>   const expectedBuf = Buffer.from(expected);
>   const receivedBuf = Buffer.from(signature);
>   if (expectedBuf.length !== receivedBuf.length) return false;
>
>   return crypto.timingSafeEqual(expectedBuf, receivedBuf);
> }
>
> // Use raw body — not req.body (parsed JSON)
> app.post('/webhooks/ted',
>   express.raw({ type: 'application/json' }),
>   (req, res) => {
>     const timestamp = req.headers['x-webhook-timestamp'];
>     const signature = req.headers['x-webhook-signature'];
>
>     if (!validateWebhook(req.body, timestamp, signature, process.env.TED_WEBHOOK_SIGNING_SECRET)) {
>       return res.status(401).send('Invalid signature');
>     }
>
>     const payload = JSON.parse(req.body.toString());
>     // process payload...
>     res.status(200).send('OK');
>   }
> );
> ```

> **Python**
>
> ```python theme={null}
> import hmac
> import hashlib
> import time
>
> TOLERANCE_SECONDS = 300  # 5 minutes
>
> def validate_webhook(raw_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
>     if not timestamp or not signature:
>         return False
>
>     try:
>         age = abs(int(time.time()) - int(timestamp))
>     except ValueError:
>         return False
>     if age > TOLERANCE_SECONDS:
>         return False
>
>     signed_payload = b"v1:" + timestamp.encode() + b"." + raw_body
>     expected = "v1,sha256=" + hmac.new(
>         secret.encode(),
>         signed_payload,
>         hashlib.sha256,
>     ).hexdigest()
>
>     return hmac.compare_digest(expected, signature)
> ```

> **Go**
>
> ```go theme={null}
> import (
>     "crypto/hmac"
>     "crypto/sha256"
>     "encoding/hex"
>     "strconv"
>     "time"
> )
>
> const toleranceSeconds = 300 // 5 minutes
>
> func validateWebhook(rawBody []byte, timestamp, signature, secret string) bool {
>     if timestamp == "" || signature == "" {
>         return false
>     }
>
>     ts, err := strconv.ParseInt(timestamp, 10, 64)
>     if err != nil {
>         return false
>     }
>     if diff := time.Now().Unix() - ts; diff < -toleranceSeconds || diff > toleranceSeconds {
>         return false
>     }
>
>     mac := hmac.New(sha256.New, []byte(secret))
>     mac.Write([]byte("v1:"))
>     mac.Write([]byte(timestamp))
>     mac.Write([]byte("."))
>     mac.Write(rawBody)
>     expected := "v1,sha256=" + hex.EncodeToString(mac.Sum(nil))
>
>     return hmac.Equal([]byte(expected), []byte(signature))
> }
> ```

### Idempotent webhook processing

Your endpoint may receive the same event more than once (at-least-once delivery). Use `transferId` + the `X-Webhook-Event` header as a composite key to deduplicate.

```javascript theme={null}
const alreadyProcessed = await db.webhookEvents.exists({
  transferId: payload.transferId,
  event: req.headers['x-webhook-event'],
});

if (alreadyProcessed) {
  return res.status(200).send('OK'); // acknowledge without reprocessing
}
```

## Error handling patterns

***

Map API error codes to user-facing actions. See the [full error list](/en/reference/interfaces/ted-jd/ted-error-list) for all codes.

| Scenario | User-facing message | Action |
| - | - | - |
| **Outside operating hours** (`BTF-0010`) | "Transfers available Mon–Fri, 06:30–17:00 (Brasília). Next window: " | Show next available time |
| **Usage limit exceeded** (`BTF-0011`) | "Transfer limit reached for this period." | Show `period`, `limit`, and `current` from the error |
| **Duplicate transfer** (`BTF-0012`) | "This transfer was already submitted." | Find the earlier transfer with List Transfers |
| **Invalid recipient data** (`BTF-0001`) | "Check recipient details and try again." | Highlight invalid fields |
| **Initiation expired** (`BTF-0202`) | "Session expired. Please start a new transfer." | Restart initiation flow |
| **JD SPB unavailable** (`BTF-1000` or `BTF-1003`, HTTP `503`) | "Transfer service temporarily unavailable. We will update you." | Read the transfer named in `transferId`; do not process it again |
| **Midaz unavailable** (`BTF-2000`) | "Service temporarily unavailable. Try again in a few minutes." | Retry with backoff |

Error responses are RFC 9457 problem documents (`application/problem+json`). Route-specific fields sit at the top level:

```json theme={null}
{
  "type": "https://errors.lerian.studio/v1/BTF-0010",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "transfers can only be initiated Monday-Friday between 06:30 and 17:00 America/Sao_Paulo time",
  "instance": "4bf92f3577b34da6a3ce929d0e0e4736",
  "code": "BTF-0010",
  "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f",
  "service": "plugin",
  "category": "deterministic",
  "currentTime": "2026-01-21T18:30:00-03:00",
  "nextAvailableTime": "2026-01-22T06:30:00-03:00",
  "openTime": "06:30",
  "closeTime": "17:00",
  "timezone": "America/Sao_Paulo"
}
```

## Go-live checklist

***

Before enabling the integration in production:

* [ ] Send `X-Idempotency` on every initiate, process, and cancel request
* [ ] Retry logic implemented with exponential backoff for 5xx/503 errors
* [ ] Webhook endpoint deployed and returning `200` within 5 seconds
* [ ] Signature validation active on the webhook endpoint
* [ ] Webhook event deduplication implemented using `transferId + event`
* [ ] Operating hours validated client-side before calling initiate (reduces unnecessary 422s)
* [ ] Both `transferId` and `confirmationNumber` stored for reconciliation
* [ ] Terminal states (`COMPLETED`, `REJECTED`, `FAILED`, `CANCELLED`) handled in UI
* [ ] Initiation expiry handled (`expiresAt`): prompt the user to restart when it passes
* [ ] Service readiness monitored in your alerting system for BYOC deployments
* [ ] Redis reachable and monitored: the service rejects requests when Redis is down
* [ ] `PLUGIN_AUTH_ENABLED=true` configured in production, with a valid `PLUGIN_AUTH_ADDRESS` (HTTPS)


# Environment variables
Source: https://docs.lerian.studio/en/interfaces/ted-jd/ted-environment-variables

Configure the Bank Transfer plugin via JD at deploy time: application, TLS and proxy headers, persistence, JD SPB integration, and security variables.

DevOps sets these variables at deploy time. A change requires a service restart. Runtime and business settings live in [Configuration](/en/interfaces/ted-jd/ted-configuration).

In the tables below, the **Default / Required** column shows the default value. A bold qualifier (for example **Required**, **Required in production**, **Required if enabled**) marks a variable you must set. `—` means no default.

## Infrastructure configuration

***

This section is for DevOps teams. DevOps sets these variables at deploy time. A change takes effect only after a service restart.

### Application

| Variable | Default / Required | Description |
| - | - | - |
| `ENV_NAME` | `development` | Environment (`development`, `staging`, `production`) |
| `DEPLOYMENT_MODE` | `byoc` | `byoc` (Bring Your Own Cloud) or `saas`. With `saas`, the plugin refuses to start unless PostgreSQL, Redis, MongoDB, RabbitMQ, and the streaming broker use TLS. |
| `SERVER_ADDRESS` | `:8080` | HTTP server address and port |
| `HTTP_BODY_LIMIT_BYTES` | `1048576` | Maximum HTTP request body size in bytes |
| `ALLOW_PRIVATE_UPSTREAMS` | `false` | ⚠️ Allow outbound adapters (CRM, Fees, JD, Midaz) to resolve to RFC1918/loopback IPs. Default `false` is fail-closed: production blocks DNS pivoting into private space. Enable in dev or in-cluster BYOC where upstreams legitimately live on private IPs. Refused in production. Cloud metadata endpoints stay blocked regardless of this flag. |
| `REQUIRE_UPSTREAM_HTTPS` | `false` | Refuse plain `http://` CRM and Fees Engine base URLs. Production already refuses them; use this in staging, homologation, and BYOC deployments that carry real client data. |

### TLS

| Variable | Default / Required | Description |
| - | - | - |
| `SERVER_TLS_CERT_FILE` | — | Path to TLS certificate file. Must be set together with `SERVER_TLS_KEY_FILE`. |
| `SERVER_TLS_KEY_FILE` | — | Path to TLS private key file. Must be set together with `SERVER_TLS_CERT_FILE`. |
| `TLS_TERMINATED_UPSTREAM` | `false` | Set to `true` when TLS is terminated by a load balancer or reverse proxy. |

### Proxy headers

Set these when the service runs behind a load balancer or reverse proxy. They let the service read the real client IP for rate limiting and audit logs.

| Variable | Default / Required | Description |
| - | - | - |
| `SERVER_PROXY_HEADER` | — | HTTP header carrying the real client IP (e.g. `X-Forwarded-For`, `X-Real-IP`). Empty disables proxy header parsing. |
| `SERVER_TRUSTED_PROXIES` | **Required if proxy header set** | Comma-separated list of trusted proxy IPs/CIDRs. Required when `SERVER_PROXY_HEADER` is set to prevent IP spoofing. |

### Authentication

This plugin delegates authorization to Access Manager. Configure the connection with the variables below.

| Variable | Default / Required | Description |
| - | - | - |
| `PLUGIN_AUTH_ENABLED` | `false` · **`true` required in production** | Enable authorization via Access Manager. The service refuses to start in production with `false`. |
| `PLUGIN_AUTH_ADDRESS` | **Required if enabled** | URL of the Access Manager auth service. Must use HTTPS in production. CRM and Fees Engine M2M tokens also come from this address. |

> [!WARNING]
>
> When `PLUGIN_AUTH_ENABLED=true`, `PLUGIN_AUTH_ADDRESS` must use HTTPS in production environments. The service rejects an HTTP address at startup.

### Organization scope

| Variable | Default / Required | Description |
| - | - | - |
| `ORGANIZATION_ID` | **Required with JD polling** | Midaz organization UUID injected into background-worker context (TED IN poller, reconciliation). Required when `JD_POLLING_ENABLED=true`. HTTP requests always carry the organization in the `X-Organization-Id` header instead. |
| `ORGANIZATION_IDS` | **Required in production** | Comma-separated list of Midaz organization UUIDs in the licensing scope. The license gateway validates `LICENSE_KEY` against these at startup. Also referenced under [License](#license). |

```bash theme={null}
# Organization injected into background workers (required when JD polling is enabled)
ORGANIZATION_ID=<your-midaz-organization-uuid>
# Licensing scope validated against LICENSE_KEY in production
ORGANIZATION_IDS=<your-midaz-organization-uuid>
```

### PostgreSQL

| Variable | Default / Required | Description |
| - | - | - |
| `POSTGRES_HOST` | `localhost` · **Required** | Primary PostgreSQL host. |
| `POSTGRES_PORT` | `5432` | Primary PostgreSQL port. |
| `POSTGRES_USER` | `plugin-br-bank-transfer` · **Required** | Database user. |
| `POSTGRES_PASSWORD` | **Required in production** | Database password. |
| `POSTGRES_DB` | `plugin-br-bank-transfer` · **Required** | Database name. |
| `POSTGRES_SSLMODE` | `require` | SSL mode. In production, must be `require`, `verify-ca`, or `verify-full`. |
| `POSTGRES_MAX_OPEN_CONNS` | `25` | Maximum open connections. |
| `POSTGRES_MAX_IDLE_CONNS` | `5` | Maximum idle connections. |
| `POSTGRES_CONN_MAX_LIFETIME_MINS` | `30` | Connection max lifetime in minutes. |
| `POSTGRES_CONN_MAX_IDLE_TIME_MINS` | `5` | Connection max idle time in minutes. |
| `POSTGRES_CONNECT_TIMEOUT_SEC` | `10` | Connection timeout in seconds. |

### PostgreSQL replica

Configure a read replica for query offloading. All fields fall back to primary values when unset.

| Variable | Default / Required | Description |
| - | - | - |
| `POSTGRES_REPLICA_HOST` | — | Replica host. Unset = no replica. |
| `POSTGRES_REPLICA_PORT` | — | Replica port. |
| `POSTGRES_REPLICA_USER` | — | Replica user. |
| `POSTGRES_REPLICA_PASSWORD` | — | Replica password. |
| `POSTGRES_REPLICA_DB` | — | Replica database name. |
| `POSTGRES_REPLICA_SSLMODE` | — | Replica SSL mode. Same production rule as `POSTGRES_SSLMODE`. |

### MongoDB

The service uses MongoDB to persist transfer audit events. It does not start without a valid MongoDB connection.

| Variable | Default / Required | Description |
| - | - | - |
| `MONGO_ENABLED` | `true` | Enable MongoDB connection. Must be `true`. |
| `MONGO_URI` | **Required** | MongoDB connection string (e.g. `mongodb://user:pass@host:27017`). In production, must include credentials and TLS (`tls=true` or `mongodb+srv`). |
| `MONGO_DATABASE` | **Required** | MongoDB database name. |
| `MONGO_MAX_POOL_SIZE` | `25` | Maximum connection pool size. |
| `MONGO_SERVER_SELECTION_TIMEOUT_MS` | `3000` | Server selection timeout in milliseconds. |
| `MONGO_HEARTBEAT_INTERVAL_MS` | `10000` | Heartbeat interval in milliseconds. |
| `MONGO_TLS_CA_CERT` | — | Base64-encoded CA certificate for MongoDB TLS. Use when MongoDB requires TLS with a custom CA (e.g. Atlas, private instances with self-signed certs). |

### Redis

| Variable | Default / Required | Description |
| - | - | - |
| `REDIS_HOST` | `localhost:6379` · **Required** | Redis host and port. |
| `REDIS_MASTER_NAME` | — | Redis Sentinel master name (if using Sentinel). |
| `REDIS_PASSWORD` | — | Redis password (if auth enabled). |
| `REDIS_DB` | `0` | Redis database number. |
| `REDIS_PROTOCOL` | `3` | Redis protocol version (2 or 3). |
| `REDIS_TLS` | `false` | Enable TLS for Redis connections. |
| `REDIS_CA_CERT` | — | CA certificate for Redis TLS. |
| `REDIS_POOL_SIZE` | `10` | Connection pool size. |
| `REDIS_MIN_IDLE_CONNS` | `2` | Minimum idle connections. |
| `REDIS_READ_TIMEOUT_MS` | `3000` | Read timeout in milliseconds. |
| `REDIS_WRITE_TIMEOUT_MS` | `3000` | Write timeout in milliseconds. |
| `REDIS_DIAL_TIMEOUT_MS` | `5000` | Dial timeout in milliseconds. |

> [!WARNING]
>
> Redis is a mandatory dependency. It caches idempotency keys and detects duplicates. If Redis is unavailable at startup, or becomes unreachable at runtime, the service reports as DOWN to the readiness probe. It then stops accepting requests.

### JD SPB connection

The plugin validates the JD variables only when `JD_BASE_URL` is set.

| Variable | Default / Required | Description |
| - | - | - |
| `JD_BASE_URL` | — | JD SPB API base URL. |
| `JD_SOAP_PATH` | `/soap` | JD SOAP endpoint path. |
| `JD_LEGACY_CODE` | **Required** | JD legacy system code (max 10 chars). |
| `JD_USER_CODE` | **Required** | JD user code (max 10 chars). |
| `JD_PASSWORD` | **Required** | JD password. |
| `JD_PRIVATE_KEY_PEM` | **Required for `local_pem`** | RSA private key PEM content (at least 3072 bits) for the XML signature, which uses PKCS#1 v1.5 with SHA-256. |
| `JD_PRIVATE_KEY_PEM_FILE` | — | Path to a file containing the RSA private key PEM. Alternative to inlining the key in `JD_PRIVATE_KEY_PEM`; read at startup. |
| `JD_PUBLIC_KEY_PEM` | **Required for `external_provided`** | Public key PEM that verifies the signatures your system provides. Required in `external_provided` mode while `jdspb.validate_external_signature` is on (default). |
| `JD_PRIVATE_KEY_KEYINFO` | **Required when signing** | Identifier of the signing key, in hex: a 40-character certificate thumbprint or a 64-character key identifier. |
| `JD_CERT_PEM` | — | Optional PEM-encoded X.509 certificate paired with the JD signing key. Used only by the cert-expiry metrics gauge, not the signing path; a malformed PEM is a startup error. |
| `JD_SIGNING_MODE` | `local_pem` | SOAP signing mode. `local_pem` signs locally with `JD_PRIVATE_KEY_PEM`. `external_provided` takes the signature your system sends to the process step. The plugin refuses `disabled` at startup while `JD_BASE_URL` is set. |
| `JD_EXTERNAL_SIGNER_URL` | — | In `external_provided` mode, the signing service that the plugin calls when a process request carries no signature. |
| `JD_EXTERNAL_SIGNER_AUTH_TOKEN` | — | Bearer token sent in the `Authorization` header for external-signer calls. |
| `JD_EXTERNAL_SIGNER_TIMEOUT_MS` | `5000` | Timeout (in milliseconds) for external-signer calls. |
| `JD_ALLOW_PRIVATE_NETWORK` | `false` | Allow the JD adapter to reach a private network address. Cloud metadata endpoints stay blocked. |
| `JD_SANDBOX_MODE` | `false` | Enable JD sandbox mode. Allowed only when `ENV_NAME` is `local`, `development`, or `test`. |

### JD polling

| Variable | Default / Required | Description |
| - | - | - |
| `JD_POLLING_ENABLED` | `false` | Enable TED IN polling worker. |
| `JD_POLL_INTERVAL_SECONDS` | `60` | How often (in seconds) the plugin polls for incoming TEDs. |
| `JD_POLL_CYCLE_TIMEOUT_SECONDS` | `0` | Deadline for one poll cycle, 30 to 3600 seconds. `0` derives it from the interval. |
| `RECONCILIATION_CYCLE_TIMEOUT_SECONDS` | `0` | Deadline for one reconciliation sweep, 30 to 3600 seconds. `0` derives it from the worker interval. |
| `DEVOLUTION_SCAN_CYCLE_TIMEOUT_SECONDS` | `0` | Deadline for one devolution scan, 30 to 3600 seconds. `0` derives it from the scan interval. |

> [!NOTE]
>
> `JD_POLLING_ENABLED` defaults to `false` for safer deployments. Set `ORGANIZATION_ID` before you enable it. Background workers inject that value into the context for downstream CRM and Midaz calls.

### External services (Midaz)

| Variable | Default / Required | Description |
| - | - | - |
| `MIDAZ_BASE_URL` | **Required** | Midaz base service URL. |
| `MIDAZ_TRANSACTION_URL` | **Required** | Midaz transaction service URL. |
| `MIDAZ_TIMEOUT_MS` | `3000` | Midaz request timeout in milliseconds. |
| `MIDAZ_MAX_RETRIES` | `3` | Retry attempts on Midaz failure. |
| `MIDAZ_AUTH_ENABLED` | `false` | Enable M2M authentication for Midaz. |
| `MIDAZ_AUTH_ADDRESS` | `PLUGIN_AUTH_ADDRESS` | Auth service URL for Midaz M2M tokens. |
| `MIDAZ_CLIENT_ID` | **Required if enabled** | OAuth client ID for Midaz M2M. |
| `MIDAZ_CLIENT_SECRET` | **Required if enabled** | OAuth client secret for Midaz M2M. |
| `MIDAZ_FEE_MODE` | `auto` | Who charges the fee of each transfer. `legacy`: plugin-fees, set up by the `FEES_*` variables below, with postings on the Midaz `/v1` API. `native`: the Midaz Fees Engine, from the fee packages of the ledger, with postings on `/v2`. `auto` reads the Midaz version, and uses `native` on Midaz 4.1.0 or later and `legacy` on an earlier version or when the first read fails. Bank Transfer does not start with any other value. |
| `MIDAZ_FEE_MODE_REFRESH` | `5m` | How often `auto` reads the Midaz version again, as a Go duration. The new read runs on the first transfer after this interval, and a failed read keeps the current mode. Bank Transfer does not start with a value of zero or less. |

Bank Transfer asks Midaz to create a transaction metadata index for its correlation reads. This call needs the Midaz `settings` `post` permission, in both fee modes.

> [!WARNING]
>
> Under the default `auto`, Bank Transfer moves to `native` by itself as soon as it reads Midaz 4.1.0 or later. If your fee packages still live in plugin-fees, Midaz finds no package, and new transfers carry no fee. Set `MIDAZ_FEE_MODE=legacy` before you upgrade Midaz, then follow [Migrate Bank Transfer fees to Midaz](/en/products/midaz/fees/fees-migration-guide).

### External services (CRM)

| Variable | Default / Required | Description |
| - | - | - |
| `CRM_BASE_URL` | **Required** | CRM service URL. Must use HTTPS in production. |
| `CRM_TIMEOUT_MS` | `2000` | CRM request timeout in milliseconds. |
| `CRM_MAX_RETRIES` | `2` | Retry attempts on CRM failure. |
| `CRM_AUTH_ENABLED` | `false` | Enable M2M authentication for CRM. |
| `CRM_CLIENT_ID` | **Required if enabled** | OAuth client ID for CRM M2M. |
| `CRM_CLIENT_SECRET` | **Required if enabled** | OAuth client secret for CRM M2M. |

### External services (Fees)

> [!NOTE]
>
> These variables configure plugin-fees, and they apply only when the fee mode is `legacy`. `BTF_FEE_ENABLED` turns plugin-fees on. When `false` (default), the plugin builds no plugin-fees adapter, and every `legacy` transfer proceeds with fee 0 and no HTTP call. The other `FEES_*` variables take effect only when `BTF_FEE_ENABLED=true`. In `native` mode, `BTF_FEE_ENABLED` does not turn fees on or off: the Midaz fee package of the ledger does.

| Variable | Default / Required | Description |
| - | - | - |
| `BTF_FEE_ENABLED` | `false` | Turns the plugin-fees integration on, in `legacy` mode only. When `false`, no plugin-fees adapter is built and every `legacy` transfer runs with fee 0 without HTTP calls. Set it to `true` to charge fees through plugin-fees. In `native` mode, enable or disable the Midaz fee package instead. |
| `FEES_BASE_URL` | **Required if enabled** | plugin-fees service URL. Must use HTTPS in production. |
| `FEES_TIMEOUT_MS` | `2000` | Fee request timeout in milliseconds. |
| `FEES_MAX_RETRIES` | `2` | Retry attempts on fee service failure. |
| `FEES_AUTH_ENABLED` | `false` | Enable M2M authentication for Fees. |
| `FEES_CLIENT_ID` | **Required if enabled** | OAuth client ID for Fees M2M. |
| `FEES_CLIENT_SECRET` | **Required if enabled** | OAuth client secret for Fees M2M. |

### RabbitMQ

When streaming is enabled, the plugin can fan out transfer lifecycle events to RabbitMQ for downstream consumers.

| Variable | Default / Required | Description |
| - | - | - |
| `RABBITMQ_ENABLED` | `false` | Add RabbitMQ as a transfer lifecycle fan-out target. Publishing requires `STREAMING_ENABLED=true`. |
| `RABBITMQ_URL` | **Required if enabled** | AMQP connection URL. `amqp://` is allowed only when `ENV_NAME` is `development`, `dev`, `test`, `testing`, or `local`, or for a loopback host. |
| `RABBITMQ_HEALTH_CHECK_URL` | — | HTTP(S) URL of the RabbitMQ management health endpoint. Hostname must match `RABBITMQ_URL`; must use `https://` in production. |
| `RABBITMQ_EXCHANGE` | `bank_transfer.lifecycle` | Exchange name for lifecycle events. |
| `RABBITMQ_EVENT_SIGNING_SECRET` | — | HMAC secret for signing published events. Falls back to `WEBHOOK_BROKER_EVENT_SIGNING_SECRET`, then to `WEBHOOK_SIGNING_SECRET`. The secret in effect must have at least 32 characters. |

### Streaming outbox

The streaming subsystem publishes transfer events to the single application topic `lerian.streaming.plugin-br-bank-transfer` on a Redpanda/Kafka broker through a transactional outbox. You must enable it for outbound webhook delivery (`WEBHOOK_ENABLED=true` requires `STREAMING_ENABLED=true`). While streaming is off, the plugin discards events: turning it on later publishes only new events.

| Variable | Default / Required | Description |
| - | - | - |
| `STREAMING_ENABLED` | `false` | Enable the streaming outbox subsystem. Required for webhook delivery. |
| `STREAMING_BROKERS` | **Required if enabled** | Comma-separated list of Kafka/Redpanda broker addresses. |
| `STREAMING_CLIENT_ID` | — | Client ID presented to the broker. |
| `STREAMING_CLOUDEVENTS_SOURCE` | `plugin-br-bank-transfer` | Optional override for the CloudEvents `source`. Leave it unset to use `plugin-br-bank-transfer`; if set, it must match that value exactly, even while streaming is disabled. |
| `STREAMING_OUTBOX_DISPATCH_INTERVAL_SECONDS` | `30` | Interval (in seconds) between outbox dispatch cycles. Must be > 0. |
| `STREAMING_CB_FAILURE_RATIO` | `0.5` | Circuit breaker failure ratio that trips the breaker (must be > 0 and ≤ 1). |
| `STREAMING_CB_MIN_REQUESTS` | `10` | Minimum requests in a window before the circuit breaker can trip. |
| `STREAMING_CB_TIMEOUT_S` | `30` | Circuit breaker recovery timeout in seconds. |
| `STREAMING_CLOSE_TIMEOUT_S` | `30` | Graceful shutdown timeout (in seconds) for the streaming producer. |
| `STREAMING_TLS_ENABLED` | `false` | Use TLS to the broker. Must be `true` when `DEPLOYMENT_MODE=saas`. |
| `STREAMING_TLS_CA_CERT` | — | CA certificate for the broker TLS connection. |
| `STREAMING_SASL_MECHANISM`, `STREAMING_SASL_USERNAME`, `STREAMING_SASL_PASSWORD` | — | SASL authentication to the broker. |
| `STREAMING_SASL_ALLOW_PLAINTEXT` | `false` | Allow SASL without TLS. |

### Webhook delivery

Outbound webhook delivery requires both RabbitMQ and the streaming outbox. The webhook worker consumes events from a RabbitMQ queue and delivers them to subscriber endpoints.

| Variable | Default / Required | Description |
| - | - | - |
| `WEBHOOK_ENABLED` | `false` | Enable outbound webhook delivery. Requires `RABBITMQ_ENABLED=true` and `STREAMING_ENABLED=true`. |
| `WEBHOOK_SIGNING_SECRET` | — | Last fallback for the broker-event secret. It does not sign deliveries: each webhook registration signs with its own `signingSecret`. |
| `WEBHOOK_BROKER_EVENT_SIGNING_SECRET` | **Required in production if enabled** | HMAC secret for verifying broker events. Falls back to `WEBHOOK_SIGNING_SECRET`. |
| `WEBHOOK_QUEUE_NAME` | `transfer.webhook.delivery` | RabbitMQ queue name for webhook events. |
| `WEBHOOK_DLQ_NAME` | `transfer.webhook.dlq` | Dead-letter queue for failed webhook deliveries. |
| `WEBHOOK_DLX_EXCHANGE_NAME` | — | Dead-letter exchange name. When empty, the worker derives `<WEBHOOK_DLQ_NAME>.exchange`. Override to centralize the DLX across plugins. |
| `WEBHOOK_DLQ_MESSAGE_TTL_MS` | `0` | `x-message-ttl` on the DLQ in milliseconds. `0` defers to the library default (7 days). Topology changes require deleting the existing DLQ before redeploy. |
| `WEBHOOK_DLQ_MAX_LENGTH` | `0` | Maximum DLQ message count. `0` defers to the library default (10000). |
| `WEBHOOK_PREFETCH_COUNT` | `20` | RabbitMQ prefetch count. |
| `WEBHOOK_DELIVERY_CONCURRENCY` | `8` | Maximum concurrent webhook deliveries per worker. |

### Telemetry (OpenTelemetry)

| Variable | Default / Required | Description |
| - | - | - |
| `ENABLE_TELEMETRY` | `false` | Enable OpenTelemetry tracing and metrics. |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | `localhost:4317` | OTel collector gRPC endpoint. |
| `OTEL_TRACES_SAMPLER_ARG` | — | Trace sampling ratio. A value in (0,1] applies as set. Unset, or a value of 0 or below, uses `0.1` in production and `1.0` elsewhere. A value above 1 counts as `1.0`. |
| `BTF_METRICS_PROMETHEUS_ENABLED` | `false` | Expose a dedicated Prometheus scrape endpoint for `btf.*` metrics. When `true`, the listener at `BTF_METRICS_PROMETHEUS_ADDRESS` is started. |
| `BTF_METRICS_PROMETHEUS_ADDRESS` | `127.0.0.1:9090` | Listen address for the Prometheus `/metrics` endpoint. Default binds to loopback so a misconfigured pod does not expose unauthenticated metrics to the cluster network. Override (e.g. `0.0.0.0:9090`) only behind a NetworkPolicy or sidecar. |

### License

| Variable | Default / Required | Description |
| - | - | - |
| `LICENSE_KEY` | **Required in production** | License key. Required in production environments. |
| `LICENSE_SERVICE_ADDRESS` | — | License validation service URL. In production, must use HTTPS and a public host. |
| `ORGANIZATION_IDS` | **Required in production** | Same variable as in [Organization scope](#organization-scope). Comma-separated list of Midaz organization UUIDs in the licensing scope; the license gateway validates `LICENSE_KEY` against these at startup. |

### Encryption

Field-level encryption for sensitive data at rest. Each key must be a hex-encoded 32-byte AES-256 key (64 hex characters). Both keys are required in production. Outside production, an empty key disables encryption for that field.

| Variable | Default / Required | Description |
| - | - | - |
| `JD_INCOMING_RAW_XML_ENCRYPTION_KEY` | — | AES-256 key for encrypting incoming JD XML payloads. Use a hex-encoded 32-byte key. Keep it stable across upgrades: a changed key makes the records that the previous key encrypted unreadable. |
| `RECIPIENT_DETAILS_ENCRYPTION_KEY` | — | AES-256 key for encrypting recipient details at rest. Use a hex-encoded 32-byte key. Keep it stable across upgrades: a changed key makes the records that the previous key encrypted unreadable. |


# Glossary
Source: https://docs.lerian.studio/en/interfaces/ted-jd/ted-glossary

Reference glossary for the Bank Transfer plugin: BACEN, SPB, STR, ISPB, PSTI, ISO 20022 account codes, and JD SPB message types like STR0008.

Quick reference for terms and acronyms used in the Bank Transfer plugin documentation.

## Regulatory and infrastructure terms

***

| Term | Definition |
| - | - |
| **BACEN** | Banco Central do Brasil (the Central Bank of Brazil). Regulates the financial system and operates SPB. |
| **SPB** | Sistema de Pagamentos Brasileiro (Brazil's Payment System), the infrastructure for all interbank settlements. |
| **STR** | Sistema de Transferência de Reservas (Reserve Transfer System), the real-time settlement component of SPB. |
| **RSFN** | Rede do Sistema Financeiro Nacional, the secure national financial network connecting BACEN and financial institutions. |
| **PSTI** | Provedor de Serviço de Tecnologia da Informação, an IT service provider authorized by BACEN to operate RSFN connectivity infrastructure. JD Consultores is a PSTI. |
| **ISPB** | Identificador de Sistema de Pagamentos Brasileiro, the 8-digit code that uniquely identifies each financial institution in SPB. |
| **STR0008** | The BACEN message format for initiating a TED transfer. Sent from the originating institution to SPB. |
| **STR0008R1** | The settlement result of an STR0008 that the plugin sent. |
| **STR0008R2** | An incoming TED. The plugin credits a TED IN from it. |
| **STR0010 / STR0010R2** | STR0010 returns a received TED to the origin bank. STR0010R2 is a return that the plugin receives: for a TED OUT it is a devolution, for a TED IN it is a chargeback. |
| **Devolução / `devolutionCode`** | Return of a TED. When a previously-sent TED OUT is returned (STR0010R2), the plugin records a new TED IN refund that carries the BACEN reason code (`devolutionCode`) and an `originalTransferId` linking back to the original TED OUT. |
| **JD / JD SPB** | JD Consultores, the PSTI that Lerian uses to route TED messages to SPB. |
| **JD parse failure** | Inbound JD message that the plugin could not parse (malformed XML or schema mismatch). The plugin keeps it for operator triage. Distinct from undeliverable transfers and from the webhook DLQ. |
| **NumCabSeq** | Sequential message identifier assigned by JD SPB to each STR0008 submission. Used to track and query transfer status. |
| **NumCtrlSTR** | BACEN clearing control number assigned by STR (the Reserve Transfer System) once a message is accepted into the SPB clearing flow. Distinct from `NumCabSeq`, which is the JD-assigned message sequence on submission. |

## Account type codes (ISO 20022)

***

| Code | Account Type |
| - | - |
| **CACC** | Current account (conta corrente), the most common type |
| **CPAY** | Payment account (conta de pagamento) |
| **SLRY** | Salary account (conta salário) |
| **SVGS** | Savings account (conta poupança) |

## Transfer types

***

| Term | Definition |
| - | - |
| **TED OUT** | Outbound transfer. Your client sends funds to an account at another bank. |
| **TED IN** | Inbound transfer. Your institution receives funds from another bank, automatically detected and credited. |
| **P2P** | Internal transfer between two accounts at the same institution (same ISPB), in the same Midaz organization and ledger. |
| **D+0** | Same-day settlement. The plugin accepts TED OUT only inside the operating window, 06:30 to 17:00 Brasília time by default. |

## Plugin-specific terms

***

| Term | Definition |
| - | - |
| **PaymentInitiation** | The entity created by `POST /v1/transfers/initiate`. Holds the fee calculation. It expires after 24 hours, or for TED OUT at the close of that day's operating window. |
| **initiationId** | UUID returned by the initiate endpoint. Required to confirm a transfer via `POST /v1/transfers/process`. |
| **X-Idempotency** | Required header on transfer writes. The plugin stores a successful response under the key and replays it for 7 days. The plugin rejects a repeat request that reuses the key with a different body (`422 BTF-0017`). |
| **Cashin fee** | Fee deducted from a received TED IN amount. Configured per organization via Fees Engine. |
| **Cashout fee** | Fee added to a TED OUT amount. The sender's account is debited for amount + fee. |
| **Reconciliation** | Process to match transfers in unknown state (PROCESSING with no confirmation) against JD SPB records. |
| **DLQ** | Webhook dead-letter queue. Outbound webhook notifications that cannot be delivered after all retries move here for manual review. |
| **Signing artifact** | Canonical TED OUT payload frozen during `POST /v1/transfers/signing/prepare`. Consumed by external HSM/signer integrations to produce a detached signature without the plugin holding the private key. |
| **Systemplane** | Runtime-config admin plane exposed via `/system/:namespace` and `/system/:namespace/:key`. Holds hot-reloadable settings that take effect without a redeploy. Distinct from bootstrap environment variables, which are read only at startup. |
| **Undeliverable transfer** | Inbound TED that the plugin parsed but could not credit. The plugin returns it to the origin bank. When the recipient is not found and automatic returns are off, the plugin retains it for an operator instead. Distinct from a JD parse failure and from the webhook DLQ. |


# Receive (TED IN)
Source: https://docs.lerian.studio/en/interfaces/ted-jd/ted-in

Receive TED transfers. The plugin polls SPB, validates recipient accounts, credits funds, and holds for an operator what it cannot credit or return.

TED IN lets your institution receive transfers from any Brazilian bank. The plugin detects, validates, and credits each transfer. When a customer at another bank sends a TED to your institution, the funds reach the recipient's account within minutes. A transfer that the plugin cannot credit or return on its own waits for an operator.

## How it works

***

1. A customer at another bank starts a TED transfer to one of your institution's accounts
2. When TED IN polling is on (`JD_POLLING_ENABLED`), the plugin polls the JD SPB network for new incoming transfers every 60 seconds (default `JD_POLL_INTERVAL_SECONDS`)
3. The plugin looks up the recipient account in your CRM by the document number in the transfer message
4. The plugin credits the recipient account, minus the cashin fee if you configured one. The plugin posts the credit on the recipient's Midaz ledger, under the [ledger routing](/en/interfaces/ted-jd/ted-configuration#ledger-routing) for that organization, ledger, and TED IN

![TED IN flow diagram](https://mintcdn.com/lerian-49cb71fc/0kJvev-xNu0CYwa1/images/en/d2/ted-how-it-works-ted-in.svg?fit=max\&auto=format\&n=0kJvev-xNu0CYwa1\&q=85\&s=0198d82bdb3efa1e5ae46d79bc7cc238)

## Detection and processing timeline

***

The stages below show what happens after the origin bank sends the transfer:

| Stage | What happens |
| - | - |
| Submission | The origin bank submits the transfer to the SPB network |
| Detection | The plugin fetches the transfer on its next poll cycle. Status becomes `RECEIVED` |
| Validation | The plugin confirms the recipient account. Status becomes `PROCESSING` |
| Credit | The plugin credits the recipient account. Status becomes `COMPLETED` |
| Notification | The plugin sends the webhook to your system |

**Typical time:** The credit completes within one poll cycle. With the default 60-second poll interval, the funds land in about a minute.

## Transfer states

***

| State | What it means for the recipient |
| - | - |
| `RECEIVED` | The plugin detected the transfer on the network and started processing |
| `PROCESSING` | The plugin confirmed the recipient account and applies the credit |
| `COMPLETED` | The funds reached the recipient's account |
| `FAILED` | The plugin could not apply the credit (for example, a Midaz rejection), or a chargeback reversed a completed credit |

## Receiving fee (cashin)

***

Your organization can charge a fee on incoming transfers. When you enable it, the plugin deducts the fee from the amount before it credits the recipient. The recipient receives the net amount. You set the fee amount and configuration per organization through the Fees Engine.

Formula: `credited amount = transfer amount − fee`

Example: a R$1,000.00 transfer with a R$2.50 fee credits R\$997.50 to the recipient's account. This is the opposite of TED OUT, where the plugin adds the fee on top and the sender pays more.

> [!WARNING]
>
> In legacy fee mode, an invalid fee response, including a fee at or above the gross amount, follows `fees.fail_closed_default`. With `false` (default), the plugin credits the gross amount at zero fee and records the fee failure. With `true`, it rejects the credit and returns the funds through STR0010. The native ledger fee path is separate. See [TED configuration](/en/interfaces/ted-jd/ted-configuration).

## What happens when a recipient isn't found

***

If the plugin cannot match the document number in the incoming transfer to an account in your CRM, the tenant policy `jd_polling.auto_return_authorized` decides what happens. The plugin credits nothing and creates no transfer record in either case.

* **`false` (default)**: the plugin returns nothing. It retains the message with reason `RECIPIENT_NOT_FOUND_RETURN_UNAUTHORIZED`. An operator settles the funds outside the plugin, then records the outcome with [Close Unsettled TED IN Credit](/en/reference/interfaces/ted-jd/close-unsettled-ted-in-credit). The close moves no money.
* **`true`**: the plugin returns the transfer to the origin bank (STR0010 devolução), and the sending customer gets the money back.

The plugin returns the transfer to the origin bank, whatever this policy says, in these cases:

* The recipient's account is not in the ledger or matches more than one account in your CRM.
* The ledger refuses the credit.
* The fee cannot be resolved and `fees.fail_closed_default` is `true`.

## Querying received transfers

***

Use the [List Transfers](/en/reference/interfaces/ted-jd/list-transfers) endpoint to retrieve all incoming transfers. Filter by `type=TED_IN` to view only received transfers, and by `ledgerId` to view the transfers of one ledger.

**Endpoint:** GET /v1/transfers

**Response (key fields):**

```json theme={null}
{
  "items": [
    {
      "transferId": "019c96a0-ab20-7def-a1b2-1f2a3b4c5d6e",
      "type": "TED_IN",
      "status": "COMPLETED",
      "amount": 5000.00,
      "feeAmount": 0.00,
      "totalAmount": 5000.00,
      "createdAt": "2026-01-21T13:15:00Z",
      "updatedAt": "2026-01-21T13:15:30Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "returned": 1,
    "totalCount": 150,
    "hasNextPage": true
  }
}
```

For full query parameter options, see the [List Transfers](/en/reference/interfaces/ted-jd/list-transfers) reference.

## Operational endpoints

***

These operator endpoints control the TED IN polling loop. They target scripts and runbooks, not end-user traffic.

| Endpoint | Purpose |
| - | - |
| `POST /v1/transfers/ted-in/poll` | Manually trigger the JD poller that normally runs on a 60s cron. Use it after an incident window or to validate JD connectivity. The route is tenant-scoped but does not require `X-Organization-Id`, because it resolves the tenant from the authenticated context. It requires `X-Idempotency` for safe retries. A same-key retry replays the cached response instead of reading JD's destructive queue again. |
| `POST /v1/transfers/ted-in/replay` | Replay persisted, unprocessed TED IN backlog rows that the plugin already fetched from JD. This route does not read JD again. It requires `X-Organization-Id` for Midaz organization scope and `X-Idempotency` for safe retries. It still resolves the tenant from the authenticated context. |
| `POST /v1/transfers/ted-in/resume` | Clear the fail-closed receive latch and re-arm a poller that auto-recovery cannot revive (a poller past the panic hard-cap). Higher-privilege than `/poll` because it re-opens JD destructive-read consumption. Resume never bypasses the money-path gate: if the current latch has no durable reconciliation gap yet, the request is refused with `409`. Verify pending gaps with [List TED IN Reconciliation Gaps](/en/reference/interfaces/ted-jd/list-ted-in-reconciliation-gaps) first, then optionally pass `{ "acknowledge": true, "note": "..." }` to mark the gap resolved in the same call. A healthy, not-latched poller returns `resumed: false`, and the route is a safe idempotent no-op. |
| `GET /v1/transfers/ted-in/poller` | Read the poller state: enabled, running, stale, and the stop reason. |

For request body, response, status codes, and error codes, see the [TED OpenAPI specification](/en/openapi/v3-current/ted.yaml).

## Messages that wait for an operator

***

Monitor each of these queues on its own. They are not interchangeable:

| Queue | What it holds | How to read it |
| - | - | - |
| Retained messages | Messages the plugin neither credited nor returned. The reason tells you why: for example `UNRECOGNIZED_TYPE`, `ACCOUNT_NOT_OWNED`, `RECIPIENT_NOT_FOUND_RETURN_UNAUTHORIZED`, or `LEDGER_ROUTE_UNRESOLVED`. A message retained for `LEDGER_ROUTE_UNRESOLVED` or `RECIPIENT_AMBIGUOUS_ORGANIZATIONS` is processed again on each poll cycle and clears when the cause is fixed. Close the others with [Close Unsettled TED IN Credit](/en/reference/interfaces/ted-jd/close-unsettled-ted-in-credit) | [List Retained TED IN Messages](/en/reference/interfaces/ted-jd/list-retained-ted-in-messages) |
| Undeliverable credits | Credits the plugin could not apply, with the state of their return to the origin bank | [List Undeliverable TED IN Credits](/en/reference/interfaces/ted-jd/list-undeliverable-ted-in-credits) |
| Transfers held by reconciliation | TED IN credits the ledger could not confirm, and chargeback refunds the plugin could not finish. The plugin retries a `REVERSING` chargeback on each cycle. Close a chargeback refund in `MANUAL_REVIEW` with [Resolve Transfer Reconciliation](/en/reference/interfaces/ted-jd/resolve-transfer-reconciliation), action `RE_POST` or `SETTLED_BY_HAND` | [List Pending Reconciliation](/en/reference/interfaces/ted-jd/list-pending-reconciliation) |
| Reconciliation gaps | Poll cycles whose receive outcome is unknown | [List TED IN Reconciliation Gaps](/en/reference/interfaces/ted-jd/list-ted-in-reconciliation-gaps) |
| JD parse failures | Messages the plugin could not parse (malformed XML or schema mismatch). No API reads them: the operator of the deployment triages them | None |

The webhook DLQ is a different path: it holds failed outbound webhook deliveries, not inbound transfers. See [Webhooks](/en/interfaces/ted-jd/ted-webhooks).

## Webhooks

***

Configure a webhook to get real-time notifications when transfers arrive. The `transfer_incoming.completed` event fires as soon as the plugin credits a transfer. See [Webhooks](/en/interfaces/ted-jd/ted-webhooks) for setup and event payload details.

## Reconciliation

***

For accounting and finance reconciliation, each transfer record includes these fields:

| Field | Usage |
| - | - |
| `controlNumber` | JD SPB control number (unique per transfer, used for interbank reconciliation) |
| `transferId` | Lerian internal identifier |
| `createdAt` | Timestamp when the plugin detected the transfer |
| `completedAt` | Timestamp when the plugin credited the funds |

The plugin persists transfer records for reconciliation and audit.

## Processing guarantees

***

* **No duplicate credits**: the plugin stores each JD message once, by its sequence number (`NumCabSeq`). It also deduplicates credits by control number, sender ISPB, and amount.
* **Message first**: the plugin stores each message before it processes it. A message that it cannot finish stays unprocessed, and the next poll cycle processes it again.
* **Operator queues**: a message that the plugin can neither credit nor return waits in the queues above.


# How the plugin works
Source: https://docs.lerian.studio/en/interfaces/ted-jd/ted-in-lerian

Understand how the Bank Transfer plugin handles SPB communication, fee calculation, settlement, and webhook notifications across the full transfer lifecycle.

The Bank Transfer plugin runs Brazil's TED rail through JD Consultores. JD provides the regulated SPB connectivity. The plugin drives each transfer from fee calculation to settlement confirmation, so your team does not call JD directly.

When another core engine of your institution uses the same JD channel and ISPB, [JD Courier](/en/interfaces/jd-courier/what-is-jd-courier) shares the channel between the engines.

## What the plugin handles for you

***

* Sends outgoing TEDs to any Brazilian bank (TED OUT)
* Receives and credits incoming TEDs (TED IN)
* Processes instant internal transfers between accounts (P2P)
* Detects and blocks duplicate transfers within a configurable window
* Validates BACEN business days against its built-in holiday calendar for 2026 to 2028
* Signs messages with your institution's digital certificate, as BACEN requires
* Reconciles transfers whose outcome is unknown with JD
* Notifies your system through webhooks when a transfer changes status

## How TED OUT works

***

TED OUT is a confirm-first flow. The customer reviews the fee before the plugin sends the transfer.

### Step 1: Initiate

> [!TIP]
>
> Endpoint: [POST /v1/transfers/initiate](/en/reference/interfaces/ted-jd/initiate-transfer)

**Step 1**

Your system calls the plugin with the transfer details: amount, recipient, and sender account.

**Step 2**

The plugin validates the sender account, checks operating hours, and runs duplicate detection.

**Step 3**

The plugin calculates the fee and returns an `initiationId` with the calculated amounts.

**Step 4**

Your system shows the fee to the customer for confirmation.

A TED OUT initiation is valid until the close of that day's operating window. If the customer does not confirm it in time, it expires.

### Step 2: Prepare signing (optional)

> [!TIP]
>
> Endpoint: [POST /v1/transfers/signing/prepare](/en/reference/interfaces/ted-jd/prepare-transfer-signing)

Use this step only when your tenant signs outside the plugin (external signing mode). The plugin freezes the canonical STR0008 payload and returns the exact bytes and hash to sign. Your system signs the payload and passes the signature to the process step. When the plugin signs with your local key (the default), skip this step.

### Step 3: Process

> [!TIP]
>
> Endpoint: [POST /v1/transfers/process](/en/reference/interfaces/ted-jd/process-transfer)

**Step 1**

Your system calls the plugin with the `initiationId` to confirm.

**Step 2**

The plugin checks the daily and monthly limits and the available balance.

**Step 3**

The plugin reserves funds in Midaz (a hold) and sends the signed message to JD Consultores.

**Step 4**

JD routes the transfer to the destination bank over the SPB network.

**Step 5**

The plugin receives the settlement confirmation from JD and finalizes the records.

**Step 6**

Your system reads the final status with [Get Transfer](/en/reference/interfaces/ted-jd/retrieve-transfer). See [Webhooks](/en/interfaces/ted-jd/ted-webhooks) for the TED OUT events.

## How TED IN works

***

1. An external bank sends a TED to your institution through JD Consultores.
2. The plugin polls JD every 60 seconds (default) to detect new incoming transfers.
3. The plugin validates the recipient against the CRM to find the correct account.
4. The plugin credits the account in Midaz and creates a completed transfer record.
5. Your system receives a webhook that confirms the credit.

> [!NOTE]
>
> TED IN polling is off by default. To turn it on, set `JD_POLLING_ENABLED` after you configure the JD credentials and the polling worker.

## How P2P works

***

P2P transfers move funds between two accounts in the same Midaz organization and ledger. They do not use the SPB network, and settlement is instant.

1. Your system calls the plugin with the sender account, the recipient account, and the amount.
2. The plugin calculates the fee, if configured, and presents it for confirmation.
3. After confirmation, the plugin runs the transfer in Midaz.
4. Both accounts update immediately, and your system receives a webhook.

## Deployment models

***

The TED plugin runs in two deployment models. The `DEPLOYMENT_MODE` environment variable (`byoc` by default, or `saas`) names the model. In `saas` mode, the plugin refuses to start unless PostgreSQL, Redis, MongoDB, RabbitMQ, and the streaming broker use TLS.

### SaaS (managed by Lerian)

In SaaS deployments, Lerian manages the integration with JD Consultores, including credential and certificate maintenance. Your team configures only business-level settings through the Admin API, such as transaction limits, fees, and webhooks. You do not manage infrastructure or connections.

### BYOC (bring your own cloud)

In BYOC deployments, the plugin runs in your own infrastructure. Your institution provides the JD Consultores credentials and the RSA private key that signs messages, and your DevOps team sets them through environment variables. You keep full control of the JD connection.

### Organization resolution

The plugin identifies the Midaz organization from the required `X-Organization-Id` header on organization-scoped API routes.

Some background processes do not receive request headers, such as the TED IN poller and the reconciliation workers. These processes use the `ORGANIZATION_ID` environment variable.

See [TED configuration](/en/interfaces/ted-jd/ted-configuration) for the complete list of supported environment variables.

## Integration with Midaz

***

All financial movements go through the Midaz ledger. The plugin creates a Midaz transaction for every transfer:

* **TED OUT**: the plugin holds the funds at the process step (via `pending: true`), then debits them when JD confirms settlement.
* **TED IN**: the plugin credits the funds when the incoming TED arrives from JD.
* **P2P**: a single Midaz transaction debits the sender and credits the recipient atomically.

Each transfer records its Midaz transaction in `midazTransactionId`. A TED IN chargeback adds a compensation transaction that carries the same transfer ID. See [TED data and reporting](/en/interfaces/ted-jd/ted-data-model) for the fields available for reconciliation.

## For developers

***

### Architecture

The plugin uses a Hexagonal (Ports and Adapters) architecture with CQRS. This design keeps business logic separate from infrastructure. You can add a new adapter, such as a different SPB provider, without a change to the core behavior.

![Ted Architectural Pattern](https://mintcdn.com/lerian-49cb71fc/0kJvev-xNu0CYwa1/images/en/d2/ted-architectural-pattern.svg?fit=max\&auto=format\&n=0kJvev-xNu0CYwa1\&q=85\&s=e90fb6d6e19c7e2a5fc2bcfc164d26e2)

### Duplicate detection

The plugin builds a duplicate-detection fingerprint for each transfer. The fingerprint covers `senderAccountId`, the recipient details (ISPB, branch, account, holder document), the amount, and the purpose. The plugin stores the fingerprint in Redis for 300 seconds by default (systemplane key `idempotency.duplicate_guard_ttl_seconds`).

The organization is not part of the fingerprint. Tenant isolation comes from the Redis key prefix. The plugin rejects a duplicate request within the window with `409 Conflict` and error code `BTF-0012`.

### Tenant data isolation

Lerian isolates each tenant's data. The plugin reads the `tenantId` from the JWT claim or the authenticated context, never from `X-Organization-Id`. The Redis cache uses per-tenant key prefixes. Business tables use the Midaz organization fields only for business-scope authorization inside the tenant.

### Observability

The plugin writes structured JSON logs, can export OpenTelemetry traces and metrics, and can serve Prometheus metrics. It also exposes unauthenticated liveness and readiness probes for Kubernetes orchestration. These probes matter mainly for BYOC deployments.

> [!WARNING]
>
> The liveness and readiness probes are unauthenticated by design, for K8s probe compatibility. In BYOC deployments, restrict access to these probes at the network level, for example with ingress rules or security groups. This keeps internal dependency status off the public internet.


# Send (TED OUT)
Source: https://docs.lerian.studio/en/interfaces/ted-jd/ted-out

Send TED transfers to any Brazilian bank with a two-step initiate-and-confirm flow: fee preview, same-day settlement, and BACEN compliance.

TED OUT lets your customers send money to any account at any Brazilian bank. The two-step flow, initiate then confirm, lets the customer review the fee before the system commits the transfer.

## How it works for your customer

***

**Step 1: Enter details and review fee**
The customer provides the recipient's bank details and the amount. The system calculates the fee and returns the total cost before it debits anything. The customer sees exactly what they will pay.

**Step 2: Confirm and send**
After the customer confirms, the system places a hold on the funds (amount + fee) in their account. It submits the transfer through JD's SPB gateway to the BACEN network and issues a confirmation number at once.

## Prerequisites

***

Before you initiate a transfer:

* The sender must have a registered account in CRM.
* The sender's balance must cover the transfer amount plus the applicable fee.
* You must request the transfer on a business day, inside the operating window (06:30 to 17:00 Brasília time by default).

## Step 1: Initiate the transfer

***

The customer submits the recipient's details and the amount. The system validates the request, calculates the fee, and creates a transfer intent that is valid until the close of that day's operating window. The system moves no funds at this stage.

See the full request specification in the [Initiate Transfer](/en/reference/interfaces/ted-jd/initiate-transfer) reference.

**Endpoint:** POST /v1/transfers/initiate

**Response (key fields):**

```json theme={null}
{
  "initiationId": "019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b",
  "feeAmount": 1.50,
  "totalAmount": 1001.50,
  "status": "PENDING_CONFIRMATION",
  "expiresAt": "2026-02-06T17:00:00-03:00"
}
```

> [!NOTE]
>
> **Fee direction (cash-out):** For TED OUT transfers, the plugin adds the fee on top of the transfer amount, so `totalAmount = amount + feeAmount`. The plugin holds, then debits, the full total from the sender's account. TED IN works the other way and deducts the fee from the received amount.

> [!WARNING]
>
> The transfer intent expires at `expiresAt`, the close of that day's operating window. If the customer does not confirm in time, create a new initiation.

## Step 2: Confirm the transfer

***

After the customer reviews the fee and confirms, submit the `initiationId` to process the transfer. The system provisions the funds and sends the payment to the BACEN network.

Most integrations process the transfer with only the `initiationId`. Some tenants sign TED OUT payloads outside the plugin. These tenants first call `POST /v1/transfers/signing/prepare`. They then send `signingArtifactId`, `payloadHash`, and `signature` with the same `initiationId`.

See the full request specification in the [Process Transfer](/en/reference/interfaces/ted-jd/process-transfer) reference.

**Endpoint:** POST /v1/transfers/process

**Response (key fields):**

```json theme={null}
{
  "transferId": "019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d",
  "confirmationNumber": "20260205001",
  "status": "PROCESSING",
  "feeAmount": 1.50,
  "totalAmount": 1001.50
}
```

## Settlement timeline

***

**1. Submitted**

The system provisions the funds and sends the transfer to the BACEN network. Status: `PROCESSING`.

**2. Settled**

The STR confirms settlement, and the plugin debits the held funds. Status: `COMPLETED`.

**3. Status available**

The plugin exposes the `COMPLETED` status through the transfer and reconciliation APIs. It does not emit `transfer.completed` for TED OUT.

TED settles same-day (D+0) for transfers submitted inside the operating window.

## Operating hours

***

> [!WARNING]
>
> Request TED transfers only on business days, 06:30–17:00 (Brasília, UTC-3, by default). The plugin rejects any transfer outside this window at once and moves no funds. It also rejects BACEN bank holidays. The error response gives the next available time.

## Error handling

***

> **Transfer rejected by JD or the STR**
>
> JD or the STR rejects the transfer. The plugin releases the hold, so the full amount, including the fee, returns to the sender's available balance. Status: `REJECTED`. When JD rejects the transfer at submission, the plugin sends a `transfer.rejected` webhook.

> **Temporary network issue**
>
> The plugin retries the JD call (`jdspb.max_retries`, default 3). If the outcome stays unknown after retries (a 5xx or a timeout from JD SPB), the plugin does not auto-revert the transfer. It keeps the hold and the `PROCESSING` status, and hands the transfer to the reconciliation worker, which asks JD for the outcome. If reconciliation runs out of attempts, the transfer becomes `FAILED` with the hold still in place, and waits for an operator (`MANUAL_REVIEW`). A clear 4xx rejection reverts the hold at once instead (see the rejected case above).

> **Return from the destination bank**
>
> The destination bank can return the funds after settlement, for example on account closure or a regulatory hold. The original transfer stays `COMPLETED`. The plugin creates a new `TED_IN` refund transfer that credits the returned amount to the original sender, with `originalTransferId` and `devolutionCode`. The plugin keeps the fee. It also sends a `transfer_outgoing.devolution_notified` webhook.

> [!NOTE]
>
> Every mutating transfer request must include an `X-Idempotency` header (max 255 characters). Reuse the same key to repeat a request whose response you did not receive. After a `5xx`, read the transfer before you send it again. See the [developer guide](/en/interfaces/ted-jd/ted-developer-guide#idempotency) for details.

For a full list of error codes, see the [TED error reference](/en/reference/interfaces/ted-jd/ted-error-list).

## Check transfer status

***

Track the progress of a transfer at any time.

**Endpoint:** [GET /v1/transfers/](/en/reference/interfaces/ted-jd/retrieve-transfer)

**Response (key fields):**

```json theme={null}
{
  "transferId": "019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d",
  "confirmationNumber": "20260205001",
  "senderAccountId": "019c96a0-a910-7abc-d1e2-8c9d0e1f2a3b",
  "type": "TED_OUT",
  "status": "COMPLETED",
  "amount": 1000.00,
  "feeAmount": 1.50,
  "totalAmount": 1001.50,
  "createdAt": "2026-02-05T18:30:00Z",
  "completedAt": "2026-02-05T18:35:12Z"
}
```

## Cancel a transfer

***

You can cancel a transfer while it is in `CREATED` or `PENDING` status, before the plugin submits it to the network.

**Endpoint:** [POST /v1/transfers//cancel](/en/reference/interfaces/ted-jd/cancel-transfer)

> [!WARNING]
>
> You cannot cancel a transfer in `PROCESSING` or a later state. After the plugin submits it to the BACEN network, the transfer must complete or fail before any reversal.

## Common ISPB codes

***

*Last verified: 2026-02-06. Values are subject to change.*

| Bank | ISPB |
| - | - |
| Banco do Brasil | 00000000 |
| Bradesco | 60746948 |
| Itaú | 60701190 |
| Santander | 90400888 |
| Caixa Econômica | 00360305 |
| Nubank | 18236120 |
| Inter | 00416968 |

For a complete list, consult the [ISPB directory](https://www.bcb.gov.br/pom/spb/estatistica/port/AODO.asp) on the Central Bank website.


# Internal transfers (P2P)
Source: https://docs.lerian.studio/en/interfaces/ted-jd/ted-p2p

Move funds between accounts within your institution instantly, 24/7, with no BACEN routing. The plugin detects internal transfers automatically.

P2P transfers move funds between accounts within your institution instantly, 24 hours a day. A P2P transfer can carry a fee. See [Fee configuration](#fee-configuration) below. The transfer never leaves your system, so it settles synchronously and needs no BACEN network.

## When to use P2P

***

P2P is the right transfer type whenever both the sender and recipient hold accounts at your institution. Common scenarios include:

* **Moving money between a customer's own accounts**: a customer transferring from their checking account to their savings account, or between two accounts they manage.
* **Paying another customer at the same institution**: a customer sending money to a friend, family member, or business that also banks with you.
* **Internal treasury movements**: splitting balances between corporate accounts held within the same organization.
* **Payment splitting**: distributing amounts across multiple accounts for payroll, expense sharing, or cashback.

The plugin detects P2P automatically. When the recipient's ISPB matches your institution's ISPB, the plugin routes the transfer internally. Your API integration is identical to TED OUT, so you need no separate endpoint or logic. Both accounts must be in the same Midaz organization and ledger.

## Key advantages

***

| Aspect | P2P | TED OUT |
| - | - | - |
| **Settlement time** | Real time (synchronous) | Via JD SPB |
| **Operating hours** | 24/7, including weekends and holidays | Mon–Fri, 06:30–17:00 (default) |
| **Fee** | Configurable | Configurable |
| **BACEN dependency** | None | Required (JD SPB) |

## How it works

***

P2P reuses the same API as TED OUT, so your integration stays consistent across transfer types. The process is two steps from the customer's perspective:

![P2P flow diagram](https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/ted-how-it-works-p2p.svg?fit=max\&auto=format\&n=SEOef3JqTInYAAau\&q=85\&s=5b2f5c4c8b5d0aee382a1ba5d6d73f28)

1. **Initiate**: The customer submits the transfer details. The plugin validates the recipient and calculates the fee. The customer sees the transfer summary before committing.
2. **Confirm**: The customer confirms. The plugin creates an atomic debit + credit in Midaz. The transfer completes immediately.

The two-step flow gives you a natural moment to show the customer a confirmation screen with the full transfer summary before any funds move.

## Transfer states

***

![P2P state machine diagram](https://mintcdn.com/lerian-49cb71fc/0kJvev-xNu0CYwa1/images/en/d2/ted-state-machine-ted-p2p.svg?fit=max\&auto=format\&n=0kJvev-xNu0CYwa1\&q=85\&s=070c9a653297ff59f1da407fcd0b2393)

| State | What it means |
| - | - |
| `CREATED` | The customer confirmed, and the plugin created the transfer |
| `PROCESSING` | Midaz atomic transaction underway |
| `COMPLETED` | Transfer settled, and funds have moved |
| `FAILED` | The ledger refused the posting; no funds were moved |

> [!NOTE]
>
> The `PENDING` state does not apply to P2P transfers. TED OUT uses `PENDING` while the plugin prepares the message for JD. The hold is already in place from `CREATED`. P2P settles entirely within Midaz, so the transfer moves from `CREATED` through `PROCESSING` to `COMPLETED`. A P2P transfer cannot be cancelled.

## Fee configuration

***

> [!NOTE]
>
> The fee mode, `MIDAZ_FEE_MODE`, decides who charges the fee of a P2P transfer. See [TED configuration](/en/interfaces/ted-jd/ted-configuration).

## Recipient validation

***

The recipient must have an account at the same institution. When you submit a transfer, the plugin looks up the recipient in CRM. It matches the bank details you provide: ISPB, branch, account, and holder document.

If the plugin does not find the recipient, it rejects the transfer and moves no funds. The customer must check the account details and try again. If the two accounts are in different Midaz organizations or ledgers, the plugin refuses the transfer with `422 BTF-0004`.

## Technical integration

***

P2P uses the same endpoints as TED OUT. You need no extra integration work beyond the outbound transfer flow you already built.

* [Initiate Transfer](/en/reference/interfaces/ted-jd/initiate-transfer): POST /v1/transfers/initiate
* [Process Transfer](/en/reference/interfaces/ted-jd/process-transfer): POST /v1/transfers/process
* [Get Transfer](/en/reference/interfaces/ted-jd/retrieve-transfer): GET /v1/transfers/

> [!NOTE]
>
> The `type` field in the transfer response is `P2P`. P2P transfers have no `controlNumber`, because they do not go through JD SPB.

## Error handling

***

P2P transfers are atomic. The plugin creates the debit and credit as a single Midaz transaction. If any part fails, Midaz applies neither leg. No intermediate state moves funds partially or leaves an account short.

If a transfer fails, the customer keeps the same balance and can retry. See the [full error list](/en/reference/interfaces/ted-jd/ted-error-list) for error codes and recovery guidance.


# Transfer types
Source: https://docs.lerian.studio/en/interfaces/ted-jd/ted-transfer-types

Overview of the three Bank Transfer types supported by the plugin: TED OUT, TED IN, and P2P, with links to each flow's guide and best practices.

## Content

***

Here, you'll find:

> **[Send (TED OUT)](/en/interfaces/ted-jd/ted-out)**
>
> Send funds to any Brazilian bank account. TED OUT uses a two-step flow: initiate, then process. Tenants that sign externally add an optional signing step. The guide covers settlement and error handling.

> **[Receive (TED IN)](/en/interfaces/ted-jd/ted-in)**
>
> Receive and credit incoming transfers from other banks.

> **[P2P Transfers](/en/interfaces/ted-jd/ted-p2p)**
>
> Move funds between accounts in the same Midaz organization and ledger. P2P settles internally and skips external bank routing.


# Webhooks
Source: https://docs.lerian.studio/en/interfaces/ted-jd/ted-webhooks

React to Bank Transfer events in real time with webhooks for completed, failed, chargeback, and reconciliation notifications without polling.

Webhooks let your system react to transfer events in real time, without polling. The plugin sends a notification to your endpoint when a transfer completes, fails, or needs attention.

## Available events

***

Each event lists the transfer types it applies to (in parentheses), when it fires, and the recommended action.

### Transfer lifecycle (TED OUT, P2P)

#### `transfer.initiated` (TED OUT)

* **Trigger**: the plugin created the TED OUT transfer record after it confirmed the initiation.
* **Action**: update the transfer status in your system. Show "transfer in progress" to the customer.

#### `transfer.processing_started` (TED OUT)

* **Trigger**: the TED OUT transfer entered processing (status path CREATED to PENDING to PROCESSING).
* **Action**: show the customer that the transfer is in progress.

#### `transfer.rejected` (TED OUT)

* **Trigger**: JD SPB rejected the transfer request before acceptance (invalid data or rule violation).
* **Action**: notify the customer of the rejection. The plugin already cancelled the fund hold.

#### `transfer.completed` (P2P)

* **Trigger**: the P2P transfer settled successfully.
* **Action**: notify the customer. Generate a receipt. Update the balance display.

### Reconciliation (TED OUT, TED IN)

#### `transfer.reconciliation_required`

* **Trigger**: a transfer with an unknown outcome moved to reconciliation.
* **Action**: track the transfer as pending. Do not assume success or failure.

#### `transfer.reconciliation_resolved`

* **Trigger**: reconciliation finished and the transfer reached a final outcome.
* **Action**: update the transfer to its final status.

#### `transfer.reconciliation_exhausted`

* **Trigger**: reconciliation stopped after the maximum number of attempts.
* **Action**: escalate the transfer for manual operator review.

#### `transfer.reconciliation_failed`

* **Trigger**: a reconciliation attempt hit a deterministic error, which failed the transfer.
* **Action**: treat the transfer as failed and investigate.

#### `transfer.reconciliation_manual_retry_requested`

* **Trigger**: an operator returned a transfer to the reconciliation queue for another attempt.
* **Action**: record the manual intervention and its reason. The state change and this fact are not atomically coupled. If the event does not arrive, confirm the transfer state through the API.

#### `transfer.scope_repaired`

* **Trigger**: an operator corrected the Midaz ledger that a transfer is filed under, with [Repair Transfer Ledger Scope](/en/reference/interfaces/ted-jd/repair-transfer-ledger-scope). No money moved.
* **Action**: update the ledger reference that you store for the transfer.

### Incoming transfers (TED IN)

#### `transfer_incoming.completed`

* **Trigger**: the plugin received an inbound TED, found the recipient, and applied the credit.
* **Action**: notify the recipient that the funds arrived. Update the balance display.

#### `transfer_incoming.chargeback`

* **Trigger**: the sending bank charged back a completed TED IN (STR0010R2), and the plugin took the credited amount back from the recipient's account. Status: `FAILED`.
* **Action**: notify the recipient. Start a review with your compliance team if your policy requires it.

#### `transfer_incoming.undeliverable`

* **Trigger**: the plugin could not credit an inbound TED (for example, it did not find the recipient account).
* **Action**: investigate the transfer. The plugin returns it to the origin bank, or retains it for an operator when the recipient is not found and automatic returns are off. See [Receive (TED IN)](/en/interfaces/ted-jd/ted-in#what-happens-when-a-recipient-isnt-found).

### Returns and initiation

#### `transfer_outgoing.devolution_notified` (TED OUT)

* **Trigger**: a return (devolução) arrived for an outgoing transfer.
* **Action**: reconcile the returned funds against the original transfer.

#### `payment_initiation.created` (TED OUT, P2P)

* **Trigger**: the plugin created a payment initiation (the pre-transfer step).
* **Action**: optional. Track initiations that await confirmation.

> [!NOTE]
>
> For TED OUT, the plugin does not emit `transfer.completed`. Check TED OUT status with the [Get Transfer](/en/reference/interfaces/ted-jd/retrieve-transfer) endpoint or the reconciliation endpoint.

## Configuring webhooks

***

Webhooks work per tenant. You register a destination in one of two ways.

**Self-service API (recommended).** Register one or more HTTPS endpoints through the webhook registration API. The server generates a `signingSecret` on creation and returns it **once**. Store it securely. Use it to verify the signature on every delivered event. You can also list, update, disable, and delete registrations, rotate the signing secret, and look up the accepted event types. The plugin derives the owning tenant from the bearer token, never from a request header.

* [Create a webhook registration](/en/reference/interfaces/ted-jd/create-webhook): `POST /v1/webhooks`
* [List webhook registrations](/en/reference/interfaces/ted-jd/list-webhooks): `GET /v1/webhooks`
* [Get](/en/reference/interfaces/ted-jd/get-webhook), [update](/en/reference/interfaces/ted-jd/update-webhook), and [delete](/en/reference/interfaces/ted-jd/delete-webhook) a registration
* [Rotate the signing secret](/en/reference/interfaces/ted-jd/rotate-webhook-signing-secret): `POST /v1/webhooks/{webhookId}/signing-secret/rotate`
* [List supported event types](/en/reference/interfaces/ted-jd/list-webhook-event-types): `GET /v1/webhooks/event-types`

**Enabling delivery (operator/env).** Set `WEBHOOK_ENABLED=true` to turn on outbound delivery. Delivery also requires RabbitMQ and the streaming outbox (`STREAMING_ENABLED=true`). Destinations come from the registrations above. There is no single static endpoint environment variable. You tune per-delivery behavior (timeout and max retries) at runtime through systemplane, not through env vars. See [Bank Transfer configuration](/en/interfaces/ted-jd/ted-configuration).

## Payload structure

***

The plugin delivers each event as an HTTPS POST. The request body is the event payload as JSON. The event type and the signature travel in HTTP headers, not in the body.

| Header | Value |
| - | - |
| `Content-Type` | `application/json`. |
| `X-Webhook-Event` | The event type, for example `transfer.completed`. |
| `X-Webhook-Timestamp` | Delivery time as a Unix timestamp (seconds). The signature covers this value. |
| `X-Webhook-Signature` | HMAC-SHA256 signature over the timestamp and body, keyed with the registration `signingSecret`. Format: `v1,sha256=<hex>`. |

The body fields depend on the event type. Every payload carries `tenantId`, and transfer-scoped events also carry `transferId`. Amounts are decimal strings in the account currency, not centavos (for example, `100.00`).

Here is an example body for `transfer.completed` on a P2P transfer:

```json theme={null}
{
  "transferId": "019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d",
  "initiationId": "019c96a0-9a01-7bcd-e0f1-2a3b4c5d6e7f",
  "tenantId": "019c96a0-0a98-7287-9a31-786e0809c769",
  "ledgerId": "019c96a0-1b20-7def-a1b2-c3d4e5f60718",
  "senderAccountId": "019c96a0-2c30-7ef0-b2c3-d4e5f6071829",
  "recipientAccountId": "019c96a0-3d40-7f01-c3d4-e5f60718293a",
  "midazTransactionId": "019c96a0-cd10-7eee-bbbb-3333bbbb4444",
  "confirmationNumber": "20260121001",
  "status": "COMPLETED",
  "transferType": "P2P",
  "amount": "100.00",
  "feeAmount": "0.00",
  "totalAmount": "100.00",
  "completedAt": "2026-01-21T17:35:00Z"
}
```

The `transfer.completed` payload carries the amounts, the accounts, and the `midazTransactionId`. For events with a smaller payload, or to read the full transfer record, fetch the transfer from [Get Transfer](/en/reference/interfaces/ted-jd/retrieve-transfer) with its `transferId`.

> [!NOTE]
>
> Payload fields differ per event type. To read every field of a transfer, use the [Get Transfer](/en/reference/interfaces/ted-jd/retrieve-transfer) endpoint.

## Handling delivery failures

***

Your endpoint must respond with a 2xx status within 5 seconds (the `webhook.timeout_ms` default). If it does not, the plugin retries the delivery with exponential backoff and full jitter. A `4xx` response other than `429` stops the retries at once, and the plugin does not follow redirects. After the first attempt, the plugin makes up to 3 more attempts (the `webhook.max_retries` default), which is 4 delivery attempts in total. The backoff base is 1 second and doubles per attempt. Full jitter applies to each delay:

| Attempt | Delay before this attempt |
| - | - |
| 1 (initial) | Immediate |
| 2 | Random in `[0, 1000 ms]` |
| 3 | Random in `[0, 2000 ms]` |
| 4 | Random in `[0, 4000 ms]` |

After all attempts fail (4 by default), the event moves to a dead-letter queue (DLQ). Set alerts on the DLQ to catch persistent delivery failures early. [List DLQ Messages](/en/reference/interfaces/ted-jd/list-webhook-dlq-messages) reads the queue, and [Retry DLQ Message](/en/reference/interfaces/ted-jd/retry-webhook-dlq-message) sends one message again. These two routes exist only when authentication is on. Tune `webhook.max_retries` through systemplane if your endpoint needs a longer or shorter retry budget. The `webhook.retry_backoff_ms` knob controls the broker reconnect backoff, not the per-delivery HTTP retry schedule above.

For reliable delivery, follow these rules:

* Respond within 5 seconds.
* Use HTTPS with a valid certificate.
* Return 200 even for events you ignore.
* Move heavy processing to a background queue. Keep the webhook handler fast.

## Idempotency

***

> [!NOTE]
>
> Your endpoint may receive the same event more than once. Use the `transferId` from the body and the `X-Webhook-Event` header to deduplicate. If you already processed that combination, return 200 and take no further action.

## For developers

***

For signature validation code (JavaScript, Python, Go), retry implementation, and the full integration checklist, see the [Bank Transfer developer guide](/en/interfaces/ted-jd/ted-developer-guide).


# Integrating with TED Lerian
Source: https://docs.lerian.studio/en/interfaces/ted-lerian/ted-lerian-integration

Integrating with Lerian SPB: STR operation event families, ledger integration, webhook delivery, and API conventions.

Lerian SPB is event-driven. Event emission is not guaranteed for every operation or lifecycle change: some emitters are optional or best effort, and `EMISSION_REQUIRED` defaults to `false`. Set `EMISSION_REQUIRED=true` in a deployment whose downstream systems depend on these events. Bootstrap then fails closed unless event emission is fully wired.

Registered webhooks receive durable control-plane events. The `settlement.*` and `spb.ldl.*` families go to the streaming backbone only. Downstream systems read settlement state from `settlement.*` streaming events and do not poll.

## Event families

***

| Family | Emitted on |
| - | - |
| `str.operation.*` | Operation lifecycle: `accepted`, `received`, `returnRequested`, `cancelRequested` |
| `str.readiness.changed` | The rail's readiness state changes |
| `str.certificate.*` | Certificate lifecycle: `rotated`, `expiring`, `counterpartyChanged`, `activationRequested` |
| `str.approval.*` | A queued approval emits `signed` or `denied`; when it reaches quorum and changes from `PENDING_APPROVAL` to `SUBMITTED`, it emits `quorumReached` once |
| `str.reconciliation.*` | A reconciliation case is `opened` or `resolved` |
| `str.schedule.changed` | The operating-window grades change |
| `str.message.*` | Message-level `received`, `submitted`, `rejected` |
| `str.emoney.transferAdvised` | A new third-party electronic-money advice (`SME0001R2`, `SME0002R2`, or `SME0004R2`) is recorded. Delivered through streaming and registered webhooks |
| `spb.ldl.*` | SILOC deposit-advisory and deposit-command facts, including `deposit-commanded`, `deposit-confirmed`, and `deposit-failed`. Delivered on the streaming backbone only, not on webhooks |
| `settlement.*` | The final settlement position: `settled` once the inbound R-leg confirms the transfer, `returned` when a confirmed return reverses a settled original, `failed` on a rejection or on the cancellation of a never-settled original. Delivered on the streaming backbone only, not on webhooks |

Inbound BACEN notices also publish dedicated events. See [Inbound messaging from BACEN](/en/rails/spb/spb-inbound-messaging).

## Ledger integration

***

Your ledger consumer must receive both the `str.operation.*` and `settlement.*` families on the streaming backbone. The `str.operation.accepted` event signals dispatch acceptance, not BACEN settlement, so use it to record a pending posting.

Record the final position from the `settlement.*` facts on the streaming backbone. The business transition behind `settlement.settled` occurs when the inbound R-leg moves the transfer's STR message to `CONFIRMED`. Broker delivery is at-least-once and can redeliver the fact. The `ce-id` is deterministic, so deduplicate on the `(ce-source, ce-id)` pair.

The `settlement.returned` event fires when a confirmed return reverses a settled original. A return follows the same pattern: `str.operation.returnRequested` signals the return's dispatch acceptance, and the parent posting reverses on `settlement.returned`. Lerian SPB holds no accounting position. The rail carries the message and its settlement state, and your ledger records the money.

## Webhooks

***

You register a webhook for canonical event types. Delivery is durable, and the rail retries a failed delivery. A delivery that uses all its attempts moves to `EXHAUSTED`, and you can retry it manually.

## API conventions

***

* **Auth** is a bearer token.
* **Writes are idempotent** through the `X-Idempotency` header. A retried submit does not double-dispatch.
* **Message-log reads do not expose the signed on-wire frame.** You read a single message by its NUOp for structured data. When the rail retained a frame, read its reconstructed XML through the dedicated, separately authorized frame route. It does not separately retain the literal sent bytes.
* **Unknown ids return a uniform not-found.** The response never reveals whether an operation exists that your institution does not own.


# Operating Lerian SPB
Source: https://docs.lerian.studio/en/interfaces/ted-lerian/ted-lerian-operations

Operating Lerian SPB: BACEN STR operating windows (GEN0021), ICP-Brasil signing certificate rotation, contingency, and per-case settlement reconciliation.

Lerian SPB works within two operational realities of the STR. The STR opens only inside BACEN's operating windows. Settlement is always asynchronous. The rail persists every message before it dispatches, so it never sends an unrecorded message.

## Operating windows

***

BACEN announces the STR operating-window grades through GEN0021. The rail persists them, and you query the current grades with STR0001. A live schedule view lists the opening and closing times per reference date. The last announcement for a reference date wins.

The rail does not impose a generic rejection of every submit outside an operating window. Its explicit schedule-related admission rule is RLPI0007: during the additional-aporte window, it rejects an aporte to a foreign Conta PI. Aportes to the institution's own Conta PI and resgates remain allowed.

## Certificate rotation

***

The rail hot-reloads the ICP-Brasil signing certificate pair with no restart. A rotation swaps the in-memory signing pointer and writes audit evidence. An activation announces the new certificate to BACEN through GEN0006. Responses never expose the private key path or any key material. Certificate warnings surface in the readiness and summary views before the certificate expires.

## Contingency and durability

***

* **Persist-before-send** guarantees the rail dispatches no unrecorded message.
* A **dispatch sweep** retries stuck outbound work.
* The rail retries a **failed event delivery**. A delivery that uses all its attempts moves to `EXHAUSTED`, and an operator can retry it manually.

## Reconciliation

***

The rail opens a reconciliation case for an operation that needs review, such as one that is stuck or has an uncertain outcome. An operator resolves a case by recording an action against it. A terminal case accepts no more actions.

## Settlement invariants

***

Two invariants hold throughout:

* **A submit is dispatch, not confirmation.** `SUBMITTED` (a TED) or `PENDING` (a Conta PI or SME movement) means the rail accepted the dispatch. The inbound R-leg moves the TED's STR message to `CONFIRMED` or `REJECTED`. That R-leg carries BACEN's settlement fields, for example `numCtrlSTR` and `sitLancSTR`, projected verbatim.
* **The rail is money-neutral.** It forwards declared amounts exactly and computes no position or balance. Your ledger consumer records any accounting position.


# What is TED Lerian?
Source: https://docs.lerian.studio/en/interfaces/ted-lerian/what-is-ted-lerian

TED Lerian is the interface Lerian offers over Lerian SPB: the API, the ledger events, and the operator workflows for TED-family transfers.

**TED Lerian** is the interface that Lerian offers over **Lerian SPB**. Lerian SPB is Lerian's own messaging connector to the **STR** (Sistema de Transferência de Reservas). It is a direct connection with no connectivity partner in the path.

Through TED Lerian, an institution sends and settles interbank and large-value wire transfers, the TED family. TED Lerian gives you the API, the ledger events, and the operator workflows. The rail carries the message and its settlement state. Your ledger consumer records the money movement.

* [What is Lerian SPB?](/en/rails/spb/what-is-lerian-spb) (the rail below this interface).
* [Integrating with TED Lerian](/en/interfaces/ted-lerian/ted-lerian-integration) (the event families, the ledger integration, and the API conventions).
* [Operating Lerian SPB](/en/interfaces/ted-lerian/ted-lerian-operations) (the operating windows, the certificate rotation, and the reconciliation).


# What is Bank Transfer?
Source: https://docs.lerian.studio/en/interfaces/ted/ted-overview

Move money between Brazilian banks the same business day with Lerian's Bank Transfer plugin: outbound, inbound, and P2P transfers with BACEN compliance built in.

TED (Transferência Eletrônica Disponível) is Brazil's interbank transfer system. Money moves between any two banks on the same business day.

Lerian reaches TED in two ways. **Lerian SPB** is Lerian's own messaging with the Brazilian Payment System. It is a direct connection with no connectivity partner in the path, and it carries other SPB message flows as well as TED. The **Bank Transfer plugin** connects your institution through the connectivity partner JD. It gives your institution outbound and inbound transfers, internal P2P, and fee handling.

> [!TIP]
>
> **Regulatory reference**
>
> This page presents a practical overview of how TED works. For complete technical, legal, and regulatory details, consult the [official documentation](https://www.bcb.gov.br/estabilidadefinanceira/spb) published by the Central Bank of Brazil (BACEN).

## What you can build

***

* **Payroll disbursements**: send salaries or contractor payments directly to employees' accounts at any Brazilian bank
* **Supplier and vendor payments**: pay invoices and settle B2B obligations without manual bank portal access
* **Customer withdrawals**: let customers move funds out of your platform to their external bank accounts on demand
* **Internal fund movement**: move money between accounts in your own institution, with no external routing (P2P)

## Transfer types

***

| Type | What it means for your business |
| - | - |
| **TED OUT** | Your customer sends money to an account at another bank |
| **TED IN** | Your institution receives money from another bank automatically |
| **P2P** | Money moves the same day between two accounts within your institution, with no external routing |

## How it works

***

1. **Initiate**: you enter the recipient's bank details and the amount. The plugin shows the fee first
2. **Confirm**: you authorize the transfer, and the plugin reserves the funds in Midaz
3. **Send**: the plugin signs the payment and dispatches it over the BACEN STR network to the destination bank
4. **Settle**: the recipient's bank credits the funds, and you receive the JD SPB control number as confirmation

## Operating hours and limits

***

What your customers can expect:

| Rule | Details |
| - | - |
| Operating window | Monday to Friday, 06:30–17:00 Brasília time (default, configurable) |
| Settlement SLA | Same day (D+0) for transfers confirmed within the window |
| Weekends / holidays | TED is unavailable; schedule transfers for the next business day |

> [!NOTE]
>
> Outside the operating window, the plugin rejects the transfer and moves no funds. The error names the next available time.

## What the plugin handles for you

***

Your team does not need to build or maintain:

* **Fee calculation**: the plugin computes fees through Fees Engine at initiation, before you confirm
* **Idempotency**: a retried request carries an idempotency key, so it returns the original result and never creates a second transfer
* **BACEN compliance**: the plugin enforces the operating window and records a full audit trail
* **Holiday calendar**: BACEN business-day validation, backed by the `bacen_holidays` table (seeded for 2026–2099)
* **Webhook notifications**: webhooks notify your system when a transfer completes, arrives, or fails
* **Reconciliation**: every transfer records the JD SPB control number, timestamps, and status history for audit
* **Automatic returns (devolução)**: an incoming transfer the plugin cannot credit goes back to the origin bank, except when the plugin does not find the recipient account. That case returns only if your configuration authorizes automatic returns. Otherwise, the plugin parks the return for operator review. This differs from a chargeback, which reverses a completed credit

> [!TIP]
>
> To configure fee pricing for TED transfers in your organization, see [Fees Engine](/en/products/midaz/fees/fees-engine-overview).

> [!TIP]
>
> [Explore the TED API](/en/reference/interfaces/ted-jd/initiate-transfer). Browse the endpoints for initiating and managing transfers.


# Buy and sell federal bonds
Source: https://docs.lerian.studio/en/diagrams/market-infrastructures/buy-and-sell-federal-bonds

How an outright trade in federal government bonds settles in Selic, cash through STR first and custody after.

Exchange cash for federal bonds with no repurchase agreed.

> [!NOTE]
>
> This journey is in construction. The page shows where it sits in the tab; the diagram and steps come in a later update.


# Buy and sell private securities
Source: https://docs.lerian.studio/en/diagrams/market-infrastructures/buy-and-sell-private-securities

How an outright trade in a private security registers and settles in B3.

The buyer acquires the asset and the seller receives the price, with no repurchase.

> [!NOTE]
>
> This journey is in construction. The page shows where it sits in the tab; the diagram and steps come in a later update.


# Cancel, refund and recover
Source: https://docs.lerian.studio/en/diagrams/market-infrastructures/cancel-return-and-recover

How to recover a lost response, cancel an operation and receive a refund in B3.

Handle a missing answer or a cancellation without duplicating or losing the original operation.

> [!NOTE]
>
> This journey is in construction. The page shows where it sits in the tab; the diagram and steps come in a later update.


# Transfer custody and pledge collateral
Source: https://docs.lerian.studio/en/diagrams/market-infrastructures/custody-transfer-and-collateral

How securities move between accounts without payment, and how they are linked or blocked as collateral, in Selic and in B3.

Move or restrict securities without a cash leg.

> [!NOTE]
>
> This journey is in construction. The page shows where it sits in the tab; the diagram and steps come in a later update.


# Financial settlement paths
Source: https://docs.lerian.studio/en/diagrams/market-infrastructures/financial-settlement-paths

The gross and multilateral paths that move the cash of a B3 operation through STR, and how Selic settles cash.

Move the cash of an operation on the path its modality requires.

> [!NOTE]
>
> This journey is in construction. The page shows where it sits in the tab; the diagram and steps come in a later update.


# Subscribe and redeem fund quotas
Source: https://docs.lerian.studio/en/diagrams/market-infrastructures/fund-quotas

How a subscription or redemption in an open-ended fund registers, gets confirmed and settles in B3.

Subscribe or redeem quotas under the fund's rules and conversion dates.

> [!NOTE]
>
> This journey is in construction. The page shows where it sits in the tab; the diagram and steps come in a later update.


# Issue and place fixed income
Source: https://docs.lerian.studio/en/diagrams/market-infrastructures/issue-and-place-fixed-income

How an instrument is registered, issued and placed with investors in B3.

An authorized institution issues an instrument and an investor acquires it.

> [!NOTE]
>
> This journey is in construction. The page shows where it sits in the tab; the diagram and steps come in a later update.


# Liquidity and rediscount
Source: https://docs.lerian.studio/en/diagrams/market-infrastructures/liquidity-and-rediscount

How an eligible institution gets and repays liquidity in its PI account, and how a rediscount reaches Selic.

Meet a specific liquidity need under the rules and eligibility of each facility.

> [!NOTE]
>
> This journey is in construction. The page shows where it sits in the tab; the diagram and steps come in a later update.


# Market infrastructure journeys
Source: https://docs.lerian.studio/en/diagrams/market-infrastructures/overview

Treasury and securities journeys in Selic and B3, which are not Lerian products, and the rule that their manuals prevail.

These journeys run in Selic and in B3. Lerian does not offer messaging for these infrastructures. The pages are here because credit and treasury journeys depend on them: collateral in federal bonds, repos, and cash settled through STR. These journeys are in construction.

## The manual prevails

***

* **Source.** The official manuals of BACEN and of the market infrastructures (Núclea, B3, Selic) define each message, its fields and its cut-off times. A manual does not define the order between messages, so the order shown here is a suggested reading.
* **Conflicts.** If this site and a manual disagree, the manual prevails.
* **Responsibility.** Your institution is the participant. It validates each flow against the manuals in force and decides how to apply it to its operation.
* **Support.** Lerian supports its own products and APIs. Advice on applying the manuals to your operation is a separate service: Lerian offers workshops and consulting by proposal. Contact your Lerian account team.

## Journeys

***

**Treasury and liquidity**

* [Buy and sell federal bonds](/en/diagrams/market-infrastructures/buy-and-sell-federal-bonds): How an outright trade in federal government bonds settles in Selic, cash through STR first and custody after.
* [Repurchase agreements](/en/diagrams/market-infrastructures/repurchase-agreements): How a repo runs its start and return legs in Selic and in B3.
* [Buy bonds in a public offering](/en/diagrams/market-infrastructures/public-offerings): How a winning bid in a federal bond auction settles in Selic.
* [Liquidity and rediscount](/en/diagrams/market-infrastructures/liquidity-and-rediscount): How an eligible institution gets and repays liquidity in its PI account, and how a rediscount reaches Selic.

**Private securities and funds**

* [Issue and place fixed income](/en/diagrams/market-infrastructures/issue-and-place-fixed-income): How an instrument is registered, issued and placed with investors in B3.
* [Buy and sell private securities](/en/diagrams/market-infrastructures/buy-and-sell-private-securities): How an outright trade in a private security registers and settles in B3.
* [Interest, amortization and redemption](/en/diagrams/market-infrastructures/payment-events): How interest, amortization, maturity and redemption reach the holder in Selic and in B3.
* [Subscribe and redeem fund quotas](/en/diagrams/market-infrastructures/fund-quotas): How a subscription or redemption in an open-ended fund registers, gets confirmed and settles in B3.
* [Transfer custody and pledge collateral](/en/diagrams/market-infrastructures/custody-transfer-and-collateral): How securities move between accounts without payment, and how they are linked or blocked as collateral, in Selic and in B3.

**Settlement and operation**

* [Financial settlement paths](/en/diagrams/market-infrastructures/financial-settlement-paths): The gross and multilateral paths that move the cash of a B3 operation through STR, and how Selic settles cash.
* [Cancel, refund and recover](/en/diagrams/market-infrastructures/cancel-return-and-recover): How to recover a lost response, cancel an operation and receive a refund in B3.
* [Position and reconciliation](/en/diagrams/market-infrastructures/position-and-reconciliation): The B3 queries and notices that let your institution reconcile operations, positions and cash.


# Interest, amortization and redemption
Source: https://docs.lerian.studio/en/diagrams/market-infrastructures/payment-events

How interest, amortization, maturity and redemption reach the holder in Selic and in B3.

Receive the events of a security you already hold, with no new trade.

> [!NOTE]
>
> This journey is in construction. The page shows where it sits in the tab; the diagram and steps come in a later update.


# Position and reconciliation
Source: https://docs.lerian.studio/en/diagrams/market-infrastructures/position-and-reconciliation

The B3 queries and notices that let your institution reconcile operations, positions and cash.

Prove that the operation, the asset and the cash agree, or open an exception.

> [!NOTE]
>
> This journey is in construction. The page shows where it sits in the tab; the diagram and steps come in a later update.


# Buy bonds in a public offering
Source: https://docs.lerian.studio/en/diagrams/market-infrastructures/public-offerings

How a winning bid in a federal bond auction settles in Selic.

Receive the bonds from a winning bid and pay for them.

> [!NOTE]
>
> This journey is in construction. The page shows where it sits in the tab; the diagram and steps come in a later update.


# Repurchase agreements
Source: https://docs.lerian.studio/en/diagrams/market-infrastructures/repurchase-agreements

How a repo runs its start and return legs in Selic and in B3.

The buyer invests cash and the seller gets funding, with a repurchase agreed from the start.

> [!NOTE]
>
> This journey is in construction. The page shows where it sits in the tab; the diagram and steps come in a later update.


# Collect trade bills and boletos
Source: https://docs.lerian.studio/en/diagrams/native-rails/collect-trade-bills-and-boletos

How the payment of a boleto linked to a trade bill reaches your institution through the SILOC collection cycle and Lerian.

Receive the payment of trade bills and boletos given as collateral when the payer pays at another bank.

> [!NOTE]
>
> This flow is a suggested reading of the Núclea and BACEN manuals. The manuals prevail over this page. Your institution, as the participant, validates the flow and implements it on the Lerian APIs. See [how to read the diagrams](/en/diagrams/introduction).

## Participants

***

* **Your institution.** The participant that runs the journey and books its effects.
* **Lerian.** Lerian SLC, Lerian SILOC and Lerian SPB. They exchange the messages with Núclea and STR, and expose the API and the events your institution uses.
* **Núclea.** Runs the SLC and SILOC clearinghouses and their settlement windows.
* **STR (BACEN).** The BACEN reserve transfer system. It moves the money between reserve accounts.
* **Payer's bank.** The bank where the payer pays the boleto.

## Diagram

***

![Collect trade bills and boletos](https://mintcdn.com/lerian-49cb71fc/uPpoYRQEvEJ6QK6W/images/en/d2/id-collect-trade-bills-and-boletos.svg?fit=max\&auto=format\&n=uPpoYRQEvEJ6QK6W\&q=85\&s=20c2fe79ec2ace42355a9603538743f3)

## Steps

***

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Your institution | Lerian | Lerian API | Pending | Before maturity, ask Lerian to register the boleto linked to the trade bill. |
| 2 | Lerian | Núclea | `DDA0101` | Pending | Lerian registers the boleto in the centralized base. |
| 3 | Payer's bank | Núclea | Between other parties | | The payer pays the boleto at another bank, which writes it off in the centralized base. |
| 4 | Núclea | Lerian | `ROC` | Pending | In the same-processing-date collection cycle, Núclea sends the last partial ROC at 15:00 and the final ROC by 15:05. |
| 5 | Núclea | Lerian | `LDL0021` | | From 15:21 to 15:23, Núclea informs creditors of the collection result for reconciliation. |
| 6 | Your institution | Lerian | Lerian API | [`GET /api/v1/siloc/settlement-instructions/{instructionId}`](/en/reference/rails/siloc/get-settlement-instruction) | Read the expected credit in the settlement instruction. |
| 7 | Núclea | STR (BACEN) | `LDL0020` | | At 16:10 on the same processing date, Núclea orders the transfer to creditor reserve or settlement accounts. |
| 8 | STR (BACEN) | Lerian | `LDL0020R2` | | STR reports the credit in your institution's reserve account. Lerian SILOC moves the instruction to `SETTLED`. |
| 9 | Your institution | Lerian | Lerian API | [`GET /api/v1/siloc/cycles/{cycleId}/reconciliation`](/en/reference/rails/siloc/get-cycle-reconciliation) | Read the reconciliation of the settled instruction against the clearing result. |
| 10 | Your institution | Your institution | Internal step | | Write off the trade bill and amortize the loan only after confirmed settlement. |

If your institution's net position is a debit, the instruction is in `FUNDING_REQUIRED`. Fund it with `LDL0022` through [`POST /v1/str/operations/ldl-deposits`](/en/reference/rails/spb/create-ldl-deposit): 07:00 to 08:00 in the first cycle, or 15:20 to 15:50 in the second cycle shown here. Do not apply the first-cycle window to this same-processing-date afternoon flow.

## How you know it finished

***

The settlement instruction in `SETTLED` with the `LDL0020R2` control number, and the cycle reconciliation matched against the clearing result.

## Related

***

* [Pay the net debit position](/en/diagrams/native-rails/pay-the-net-debit-position)
* [Register receivables as collateral](/en/diagrams/native-rails/register-receivables-collateral)
* [Lerian SILOC](/en/rails/siloc/what-is-lerian-siloc)
* [Lerian SPB](/en/rails/spb/what-is-lerian-spb)


# Native rail journeys
Source: https://docs.lerian.studio/en/diagrams/native-rails/overview

Business journeys that run on Lerian's native messaging with BACEN and Núclea, and the rule that the regulator's manuals prevail.

These journeys run on Lerian's native messaging, which connects your institution directly to BACEN and to Núclea over RSFN. One journey often crosses several rails: a card receivable, for example, moves through SLC, SILOC and STR. Each diagram has a Lerian column. A row between your institution and that column shows the endpoint or the event your institution uses, unless the step is pending, and the step table links each endpoint to the API reference.

## The manual prevails

***

* **Source.** The official manuals of BACEN and of the market infrastructures (Núclea, B3, Selic) define each message, its fields and its cut-off times.
* **Conflicts.** If this site and a manual disagree, the manual prevails.
* **Responsibility.** Your institution is the participant. It validates each flow against the manuals in force and decides how to apply it to its operation.
* **Support.** Lerian supports its own products and APIs. Advice on applying the manuals to your operation is a separate service: Lerian offers workshops and consulting by proposal. Contact your Lerian account team.

## Journeys

***

**Secured credit**

* [Register receivables as collateral](/en/diagrams/native-rails/register-receivables-collateral): How a contract effect on card receivables is registered, and how the settlement reaches your institution through Lerian.
* [Receive card receivables at the domicile](/en/diagrams/native-rails/receive-receivables-at-domicile): How a card receivable is paid into the borrower's account at your institution through the SLC cycle and Lerian.
* [Settle anticipated receivables in real time](/en/diagrams/native-rails/settle-anticipated-receivables): How a receivable that the acquirer anticipated is settled one operation at a time, outside the net cycle, through Lerian.
* [Collect trade bills and boletos](/en/diagrams/native-rails/collect-trade-bills-and-boletos): How the payment of a boleto linked to a trade bill reaches your institution through the SILOC collection cycle and Lerian.

**Payments**

* [Send and receive Pix](/en/diagrams/native-rails/send-and-receive-pix): A Pix payment from your institution through SPI, with Lerian SPI and Pix Lerian.
* [Send and receive TED](/en/diagrams/native-rails/send-and-receive-ted): A TED transfer from your institution through STR, with Lerian SPB and TED Lerian.

**Settlement and daily operation**

* [Pay the net debit position](/en/diagrams/native-rails/pay-the-net-debit-position): How a settlement bank pays its net debit in the multilateral SLC cycle through Lerian.
* [Recalculate after a default](/en/diagrams/native-rails/recalculate-after-a-default): What happens in the SLC cycle, and through Lerian, when a participant with a net debit does not pay in full.
* [Settle within the same bank](/en/diagrams/native-rails/settle-within-the-same-bank): How Núclea settles an operation when the debtor and the creditor use the same settlement bank, without the STR, and how you answer through Lerian.


# Pay the net debit position
Source: https://docs.lerian.studio/en/diagrams/native-rails/pay-the-net-debit-position

How a settlement bank pays its net debit in the multilateral SLC cycle through Lerian.

Pay, within the deposit window, the day's net debit into Núclea's settlement account.

> [!NOTE]
>
> This flow is a suggested reading of the Núclea and BACEN manuals. The manuals prevail over this page. Your institution, as the participant, validates the flow and implements it on the Lerian APIs. See [how to read the diagrams](/en/diagrams/introduction).

## Participants

***

* **Your institution.** The participant that runs the journey and books its effects.
* **Lerian.** Lerian SLC, Lerian SILOC and Lerian SPB. They exchange the messages with Núclea and STR, and expose the API and the events your institution uses.
* **Núclea.** Runs the SLC and SILOC clearinghouses and their settlement windows.
* **STR (BACEN).** The BACEN reserve transfer system. It moves the money between reserve accounts.

## Diagram

***

![Pay the net debit position](https://mintcdn.com/lerian-49cb71fc/uMjNOPyy5mI7z1yU/images/en/d2/id-pay-the-net-debit-position.svg?fit=max\&auto=format\&n=uMjNOPyy5mI7z1yU\&q=85\&s=15a7bb10a1fc5bf250f2b7a7f87f11c6)

## Steps

***

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Núclea | Lerian | `SLC0001` | | Núclea sends the preview at 05:40 in the first cycle and 11:10 in the second. |
| 2 | Lerian | Your institution | Lerian API | Event `clearing.preview_available` | Lerian publishes the preview. `GET /v1/clearing/positions` returns it. |
| 3 | Your institution | Lerian | Lerian API | Pending | Optional: dispute a line by 06:20 or 11:50. |
| 4 | Lerian | Núclea | `SLC0002` | Pending | Lerian sends the divergence to Núclea. |
| 5 | Núclea | Lerian | `SLC0001` | | Núclea sends the final position at 06:20 or 11:50. |
| 6 | Lerian | Your institution | Lerian API | Event `clearing.final_available` | Lerian publishes the final position. `GET /v1/clearing/positions` returns it. |
| 7 | Núclea | Lerian | `LDL0021` | | At 06:35 or 12:00, Núclea informs the amount and the deadline. |
| 8 | Lerian | Your institution | Lerian API | Event `clearing.deposit_required` | Lerian publishes the amount and the deadline. |
| 9 | Your institution | Lerian | Lerian API | Pending | Command the card cycle deposit (`CodProdt=SLC`) through Lerian, from 06:35 to 07:30 or from 12:00 to 12:50. SILOC does not accept partial deposits. |
| 10 | Lerian | STR (BACEN) | `LDL0022` | Pending | Lerian sends the deposit to STR. |
| 11 | STR (BACEN) | Lerian | `LDL0022R1` | Pending | STR returns the result of the entry. |
| 12 | Your institution | Lerian | Lerian API | [`POST /v1/funding/settlement-instructions/{instructionId}/ack`](/en/reference/rails/slc/record-funding-ack) | Record the deposit result, `SENT` or `FAILED`. `FAILED` keeps the instruction open and raises `funding.deposit_failed`. |
| 13 | Núclea | Lerian | `PAG0103` | | Núclea closes the deposit window. |
| 14 | Lerian | Your institution | Lerian API | Event `clearing.cycle_closed` | Lerian publishes the closed cycle. |

Until the deposit through Lerian is available, your institution sends `LDL0022` on its own STR connection and records the result with [`POST /v1/funding/settlement-instructions/{instructionId}/ack`](/en/reference/rails/slc/record-funding-ack).

A participant that does not deposit the full amount is excluded from the cycle, and Núclea recalculates everyone's balances. See [Recalculate after a default](/en/diagrams/native-rails/recalculate-after-a-default).

## How you know it finished

***

`LDL0022R1` with the entry made, your deposit confirmation recorded, and `clearing.cycle_closed` with your institution still in the cycle.

## Related

***

* [Recalculate after a default](/en/diagrams/native-rails/recalculate-after-a-default)
* [Receive card receivables at the domicile](/en/diagrams/native-rails/receive-receivables-at-domicile)
* [Lerian SLC](/en/rails/slc/what-is-lerian-slc)
* [Lerian SILOC](/en/rails/siloc/what-is-lerian-siloc)
* [Lerian SPB](/en/rails/spb/what-is-lerian-spb)


# Recalculate after a default
Source: https://docs.lerian.studio/en/diagrams/native-rails/recalculate-after-a-default

What happens in the SLC cycle, and through Lerian, when a participant with a net debit does not pay in full.

Adjust the cycle when a participant with a net debit does not deposit the full amount, whether it is another participant or your own institution.

> [!NOTE]
>
> This flow is a suggested reading of the Núclea and BACEN manuals. The manuals prevail over this page. Your institution, as the participant, validates the flow and implements it on the Lerian APIs. See [how to read the diagrams](/en/diagrams/introduction).

## Participants

***

* **Your institution.** The participant that runs the journey and books its effects.
* **Lerian.** Lerian SLC, Lerian SILOC and Lerian SPB. They exchange the messages with Núclea and STR, and expose the API and the events your institution uses.
* **Núclea.** Runs the SLC and SILOC clearinghouses and their settlement windows.
* **STR (BACEN).** The BACEN reserve transfer system. It moves the money between reserve accounts.

## Diagram

***

### Recalculated cycle

![Recalculate after a default: Recalculated cycle](https://mintcdn.com/lerian-49cb71fc/_MF2X4Vb4ztnn0Rl/images/en/d2/id-recalculate-after-a-default-1.svg?fit=max\&auto=format\&n=_MF2X4Vb4ztnn0Rl\&q=85\&s=482843ee99930b59d62b29c6e55bdf1c)

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Núclea | Núclea | Internal step | | At the end of the deposit window, Núclea excludes the defaulter and recalculates the balances. |
| 2 | Núclea | Lerian | `LDL0021` | | Núclea sends a new request with the recalculated balance and a new deadline. |
| 3 | Lerian | Your institution | Lerian API | Event `clearing.cycle_recalculated` | Lerian publishes the recalculated cycle with the new amount and deadline. |
| 4 | Your institution | Lerian | Lerian API | Pending | If your institution is a debtor, command the new amount or the difference within the new deadline. |
| 5 | Lerian | STR (BACEN) | `LDL0022` | Pending | Lerian sends the deposit to STR. |
| 6 | STR (BACEN) | Lerian | `LDL0022R1` | Pending | STR returns the result of the entry. |
| 7 | Núclea | STR (BACEN) | `LDL0020` | | At settlement time, Núclea orders the transfer to the creditors. |
| 8 | STR (BACEN) | Lerian | `LDL0020R2` | | If your institution is a creditor, STR reports the credit in its reserve account. |
| 9 | Lerian | Your institution | Lerian API | Pending | Lerian reports the card cycle credit. |
| 10 | Núclea | STR (BACEN) | `LDL0006` | | If your institution deposited more than the new amount, Núclea refunds the excess. |
| 11 | STR (BACEN) | Lerian | `LDL0006R2` | | STR reports the refund. |
| 12 | Lerian | Your institution | Lerian API | Pending | Lerian reports the refund. |

Until the deposit through Lerian is available, your institution sends `LDL0022` on its own STR connection and records the result with [`POST /v1/funding/settlement-instructions/{instructionId}/ack`](/en/reference/rails/slc/record-funding-ack).

### CRC adjustment

![Recalculate after a default: CRC adjustment](https://mintcdn.com/lerian-49cb71fc/uMjNOPyy5mI7z1yU/images/en/d2/id-recalculate-after-a-default-2.svg?fit=max\&auto=format\&n=uMjNOPyy5mI7z1yU\&q=85\&s=f06dd3aa22a9b4e535e2d5b71f9aed06)

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Núclea | Lerian | `LTR0001` | | Núclea creates a mandatory bilateral adjustment (`SubTpAtv=CRC`) for the amounts the defaulter left open. |
| 2 | Lerian | Your institution | Lerian API | [`GET /v1/lbtr/results`](/en/reference/rails/slc/list-lbtr-results) | Read the announced adjustment and its amount. |
| 3 | Your institution | Lerian | Lerian API | [`POST /v1/lbtr/results/{resultId}/decision`](/en/reference/rails/slc/decide-lbtr-result) | Agree or dispute by 10:00 or 17:30. |
| 4 | Lerian | Núclea | `LTR0002` | | Lerian sends your answer to Núclea. |
| 5 | Your institution | Lerian | Lerian API | [`POST /v1/str/operations/ltr-transfers`](/en/reference/rails/spb/create-ltr-transfer) | If your institution is the debtor of the adjustment, command the payment. |
| 6 | Lerian | STR (BACEN) | `LTR0004` | | Lerian pays into Núclea's settlement account. |
| 7 | STR (BACEN) | Lerian | `LTR0004R1` | | STR returns the result of the payment. |
| 8 | Núclea | STR (BACEN) | `LTR0005` | | If your institution is the creditor of the adjustment, Núclea orders the credit after the debtor pays. |
| 9 | STR (BACEN) | Lerian | `LTR0005R2` | Pending | STR reports the credit in your institution's reserve account. |

## How you know it finished

***

The new `LDL0021` acknowledged, plus the evidence for your side of each step. As a debtor: `LDL0022R1` for the deposit and `LTR0004R1` for each `CRC` adjustment paid. As a creditor: `LDL0020R2` for the recalculated balance and `LTR0005R2` for each `CRC` adjustment received.

## Related

***

* [Pay the net debit position](/en/diagrams/native-rails/pay-the-net-debit-position)
* [Settle anticipated receivables in real time](/en/diagrams/native-rails/settle-anticipated-receivables)
* [Lerian SLC](/en/rails/slc/what-is-lerian-slc)
* [Lerian SILOC](/en/rails/siloc/what-is-lerian-siloc)
* [Lerian SPB](/en/rails/spb/what-is-lerian-spb)


# Receive card receivables at the domicile
Source: https://docs.lerian.studio/en/diagrams/native-rails/receive-receivables-at-domicile

How a card receivable is paid into the borrower's account at your institution through the SLC cycle and Lerian.

Receive the payment of the receivable in the borrower's account at your institution and use the credit to amortize the loan.

> [!NOTE]
>
> This flow is a suggested reading of the Núclea and BACEN manuals. The manuals prevail over this page. Your institution, as the participant, validates the flow and implements it on the Lerian APIs. See [how to read the diagrams](/en/diagrams/introduction).

## Participants

***

* **Your institution.** The participant that runs the journey and books its effects.
* **Lerian.** Lerian SLC, Lerian SILOC and Lerian SPB. They exchange the messages with Núclea and STR, and expose the API and the events your institution uses.
* **Núclea.** Runs the SLC and SILOC clearinghouses and their settlement windows.
* **STR (BACEN).** The BACEN reserve transfer system. It moves the money between reserve accounts.

## Diagram

***

![Receive card receivables at the domicile](https://mintcdn.com/lerian-49cb71fc/H3YVOh41FKGzJJC8/images/en/d2/id-receive-receivables-at-domicile.svg?fit=max\&auto=format\&n=H3YVOh41FKGzJJC8\&q=85\&s=d4c99439271b887260ebefe1bd4f4f9b)

## Steps

***

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Núclea | Lerian | `ASLC022/024` | Pending | Núclea sends the card credit or debit settlement file to the domicile. |
| 2 | Núclea | Lerian | `GEN0015` | | Núclea announces the file availability. |
| 3 | Your institution | Lerian | Lerian API | [`GET /api/v1/siloc/file-notices`](/en/reference/rails/siloc/list-file-notices) | Read the available file notices. |
| 4 | Lerian | Your institution | Lerian API | Pending | Lerian delivers the settlement details so your institution can check the borrower account. |
| 5 | Your institution | Lerian | Lerian API | Pending | For credit-card records only, confirm the borrower account for pre-scheduling or report its inconsistencies. This is not confirmation of payment. |
| 6 | Lerian | Núclea | `ASLC023` | Pending | For credit-card records only, send the mandatory ASLC023 scheduling response by D-1 of the payment date. Confirm or reject pre-scheduling with an occurrence code other than 00. Rejected records do not proceed to settlement. |
| 7 | Núclea | Lerian | `SLC0001` | | Núclea sends the final position at 06:20 or 11:50. |
| 8 | Lerian | Your institution | Lerian API | Event `clearing.final_available` | Lerian publishes the final position. |
| 9 | Núclea | Lerian | `LDL0021` | | Núclea informs the net amount to receive at 06:35 or 12:00. |
| 10 | Lerian | Your institution | Lerian API | Event `clearing.deposit_required` | Lerian publishes the amount to receive. |
| 11 | Núclea | STR (BACEN) | `LDL0020` | | When the settlement window opens, Núclea orders the transfer to creditors. |
| 12 | STR (BACEN) | Lerian | `LDL0020R2` | | STR reports the credit in your institution's reserve account. |
| 13 | Lerian | Your institution | Lerian API | Pending | Lerian reports the card cycle credit. |
| 14 | Your institution | Your institution | Internal step | | After financial settlement, credit the borrower and amortize only if the account can receive the credit. A rejection books no credit or amortization. |
| 15 | Your institution | Lerian | Lerian API | Pending | Report the actual end-recipient payment or rejection. |
| 16 | Lerian | Núclea | `ASLC023/025` or `ASLC041/042` | Pending | Return the processing status after SILOC settlement on D0 through ASLC023 (credit) or ASLC025 (debit). Only if systemic problems prevented that D0 return, use ASLC041 (credit) or ASLC042 (debit) by D1. Never resend a record already returned in the D0 window; it is rejected with ESLC0135. |

The credit-card scheduling response is distinct from the payment-status return after settlement. A scheduling response on D0 is outside its deadline (ESLC0130). ASLC041 cannot replace it. The financial-settlement steps apply to accepted records.

## How you know it finished

***

`LDL0020R2` with the STR control number matched to `LDL0021` proves financial settlement. The end-recipient processing status is returned through ASLC023 or ASLC025 on D0, or through ASLC041 or ASLC042 by D1 only when the D0 return was missed due to systemic problems.

## Related

***

* [Register receivables as collateral](/en/diagrams/native-rails/register-receivables-collateral)
* [Pay the net debit position](/en/diagrams/native-rails/pay-the-net-debit-position)
* [Recalculate after a default](/en/diagrams/native-rails/recalculate-after-a-default)
* [Lerian SLC](/en/rails/slc/what-is-lerian-slc)
* [Lerian SILOC](/en/rails/siloc/what-is-lerian-siloc)
* [Lerian SPB](/en/rails/spb/what-is-lerian-spb)


# Register receivables as collateral
Source: https://docs.lerian.studio/en/diagrams/native-rails/register-receivables-collateral

How a contract effect on card receivables is registered, and how the settlement reaches your institution through Lerian.

Make sure the receivable given as collateral is paid to the account your institution indicates, and check later that each expected amount arrived.

> [!NOTE]
>
> This flow is a suggested reading of the Núclea and BACEN manuals. The manuals prevail over this page. Your institution, as the participant, validates the flow and implements it on the Lerian APIs. See [how to read the diagrams](/en/diagrams/introduction).

## Participants

***

* **Your institution.** The participant that runs the journey and books its effects.
* **Lerian.** Lerian SLC, Lerian SILOC and Lerian SPB. They exchange the messages with Núclea and STR, and expose the API and the events your institution uses.
* **Receivables registrar.** Records the contract effect (lien, fiduciary assignment or change of holder) on the receivable.
* **Acquirer.** Pays the merchant's card receivables and reports each settlement to Núclea.
* **Núclea.** Runs the SLC and SILOC clearinghouses and their settlement windows.

## Diagram

***

![Register receivables as collateral](https://mintcdn.com/lerian-49cb71fc/uMjNOPyy5mI7z1yU/images/en/d2/id-register-receivables-collateral.svg?fit=max\&auto=format\&n=uMjNOPyy5mI7z1yU\&q=85\&s=574aba98acbc50268c09ff41fd562d16)

## Steps

***

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Your institution | Your institution | Internal step | | Grant the credit to the borrower and select the receivables that secure it. |
| 2 | Your institution | Lerian | Lerian API | Pending | Ask Lerian to register the contract effect: a lien, a fiduciary assignment or a change of holder. |
| 3 | Lerian | Receivables registrar | Registrar API | Pending | Lerian registers the contract effect at the receivables registrar. |
| 4 | Receivables registrar | Lerian | Registrar API | Pending | The registrar confirms the registration. |
| 5 | Receivables registrar | Acquirer | Between other parties | | The registrar informs the acquirer of the new holder and of the payment account. |
| 6 | Acquirer | Núclea | `ASLC027/029/031` | | The acquirer reports each settlement to Núclea with the holder and the account that the contract effect set. |
| 7 | Receivables registrar | Lerian | Registrar API | Pending | The registrar sends the receivables schedule and the settlements, and Lerian reconciles them with the credits received. |

## How you know it finished

***

Every receivable in the schedule matches a credit received at the domicile, or opens an exception.

## Related

***

* [Receive card receivables at the domicile](/en/diagrams/native-rails/receive-receivables-at-domicile)
* [Settle anticipated receivables in real time](/en/diagrams/native-rails/settle-anticipated-receivables)
* [Lerian SLC](/en/rails/slc/what-is-lerian-slc)


# Send and receive Pix
Source: https://docs.lerian.studio/en/diagrams/native-rails/send-and-receive-pix

A Pix payment from your institution through SPI, with Lerian SPI and Pix Lerian.

Send a Pix payment and receive one, from the request to the settlement in SPI.

> [!NOTE]
>
> This journey is in construction. The page shows where it sits in the tab; the diagram and steps come in a later update.


# Send and receive TED
Source: https://docs.lerian.studio/en/diagrams/native-rails/send-and-receive-ted

A TED transfer from your institution through STR, with Lerian SPB and TED Lerian.

Send a TED and receive one, from the request to the settlement in STR.

> [!NOTE]
>
> This journey is in construction. The page shows where it sits in the tab; the diagram and steps come in a later update.


# Settle anticipated receivables in real time
Source: https://docs.lerian.studio/en/diagrams/native-rails/settle-anticipated-receivables

How a receivable that the acquirer anticipated is settled one operation at a time, outside the net cycle, through Lerian.

Settle, one operation at a time, a receivable that the acquirer anticipated to the merchant and whose value belongs to your institution as holder or secured creditor.

> [!NOTE]
>
> This flow is a suggested reading of the Núclea and BACEN manuals. The manuals prevail over this page. Your institution, as the participant, validates the flow and implements it on the Lerian APIs. See [how to read the diagrams](/en/diagrams/introduction).

## Participants

***

* **Your institution.** The participant that runs the journey and books its effects.
* **Lerian.** Lerian SLC, Lerian SILOC and Lerian SPB. They exchange the messages with Núclea and STR, and expose the API and the events your institution uses.
* **Núclea.** Runs the SLC and SILOC clearinghouses and their settlement windows.
* **STR (BACEN).** The BACEN reserve transfer system. It moves the money between reserve accounts.

## Diagram

***

![Settle anticipated receivables in real time](https://mintcdn.com/lerian-49cb71fc/H3YVOh41FKGzJJC8/images/en/d2/id-settle-anticipated-receivables.svg?fit=max\&auto=format\&n=H3YVOh41FKGzJJC8\&q=85\&s=b5545fee451be9667947b26ef92c868b)

## Steps

***

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Núclea | STR (BACEN) | `LTR0005` | | After the debtor bank pays, Núclea orders the credit to the creditor. See the debtor-side note below. |
| 2 | STR (BACEN) | Lerian | `LTR0005R2` | Pending | STR reports the financial credit in your institution's reserve account. |
| 3 | Núclea | Lerian | `ASLC032` | Pending | After the acquirer reports ASLC031 and financial settlement is effected or confirmed, Núclea sends ASLC032 to the domicile. |
| 4 | Lerian | Your institution | Lerian API | Pending | Lerian delivers the anticipation details. This notice alone does not authorize ASLC033. |
| 5 | Núclea | Lerian | `SLC0005` | Pending | Núclea sends the data linking the credit to the operation. |
| 6 | Lerian | Your institution | Lerian API | Pending | Lerian delivers the settlement linked to the STR credit. Match ASLC032 and LTR0005R2 before reporting payment or rejection. |
| 7 | Your institution | Your institution | Internal step | | Credit the end recipient if possible. If the account cannot receive the credit, reject without booking the credit or amortization. |
| 8 | Your institution | Lerian | Lerian API | Pending | Report the actual payment or rejection only after receiving both ASLC032 and the LTR0005R2 financial value. |
| 9 | Lerian | Núclea | `ASLC033` | Pending | Send ASLC033 within the anticipation window. A failed end-recipient credit is returned to the acquirer through SILOC LBTR; ASLC034 reports the status to the acquirer. |

When your institution is the debtor bank, it gets the gross result (`LTR0001`) from [`GET /v1/lbtr/results`](/en/reference/rails/slc/list-lbtr-results), may agree or dispute (`LTR0002`) with [`POST /v1/lbtr/results/{resultId}/decision`](/en/reference/rails/slc/decide-lbtr-result), and pays with `LTR0004` through [`POST /v1/str/operations/ltr-transfers`](/en/reference/rails/spb/create-ltr-transfer). If it pays less than due, Núclea returns the payment with `LTR0006`.

## How you know it finished

***

`LTR0005R2` matched with ASLC032 and `SLC0005` proves the financial credit. ASLC033 then reports payment or rejection for the end recipient to Núclea; a rejected end-recipient credit follows the SILOC LBTR return path.

## Related

***

* [Receive card receivables at the domicile](/en/diagrams/native-rails/receive-receivables-at-domicile)
* [Recalculate after a default](/en/diagrams/native-rails/recalculate-after-a-default)
* [Lerian SLC](/en/rails/slc/what-is-lerian-slc)
* [Lerian SPB](/en/rails/spb/what-is-lerian-spb)


# Settle within the same bank
Source: https://docs.lerian.studio/en/diagrams/native-rails/settle-within-the-same-bank

How Núclea settles an operation when the debtor and the creditor use the same settlement bank, without the STR, and how you answer through Lerian.

Settle when the debtor and the creditor are served by the same settlement bank. This happens, for example, when your institution settles for an acquirer and is also the merchant's domicile.

> [!NOTE]
>
> This flow is a suggested reading of the Núclea and BACEN manuals. The manuals prevail over this page. Your institution, as the participant, validates the flow and implements it on the Lerian APIs. See [how to read the diagrams](/en/diagrams/introduction).

## Participants

***

* **Your institution.** The participant that runs the journey and books its effects.
* **Lerian.** Lerian SLC, Lerian SILOC and Lerian SPB. They exchange the messages with Núclea and STR, and expose the API and the events your institution uses.
* **Núclea.** Runs the SLC and SILOC clearinghouses and their settlement windows.

## Diagram

***

![Settle within the same bank](https://mintcdn.com/lerian-49cb71fc/uMjNOPyy5mI7z1yU/images/en/d2/id-settle-within-the-same-bank.svg?fit=max\&auto=format\&n=uMjNOPyy5mI7z1yU\&q=85\&s=f4952f63e2584b72b705603b13ee4fcc)

## Steps

***

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Núclea | Lerian | `LTR0007` | | Núclea informs an operation between two participants that your institution settles for. |
| 2 | Lerian | Your institution | Lerian API | [`GET /v1/lbtr/nonliquidante-operations`](/en/reference/rails/slc/list-lbtr-non-settlor-operations) | Read the announced operation and whether Núclea asked for a confirmation. |
| 3 | Your institution | Your institution | Internal step | | Check the debtor's account. If you will confirm, debit and credit the two internal accounts. If you will reject, book nothing. |
| 4 | Your institution | Lerian | Lerian API | [`POST /v1/lbtr/nonliquidante-operations/{operationId}/decision`](/en/reference/rails/slc/decide-lbtr-non-settlor-operation) | Answer `CONFIRM` after the two entries, or `REJECT`. The answer is mandatory. |
| 5 | Lerian | Núclea | `LTR0008` | | Lerian sends your answer to Núclea. |
| 6 | Núclea | Lerian | `LTR0008R1` | | Núclea answers the confirmation. |
| 7 | Lerian | Your institution | Lerian API | [`GET /v1/lbtr/commands/{commandId}`](/en/reference/rails/slc/get-lbtr-command) | Read the command and Núclea's answer, as it arrived. |

## How you know it finished

***

The command in `ANSWERED` with `LTR0008R1`. After a confirmation, both internal entries carry the same reference. After a rejection, there are no entries. If the command ends in `REFUSED`, reverse the two entries.

## Related

***

* [Pay the net debit position](/en/diagrams/native-rails/pay-the-net-debit-position)
* [Lerian SLC](/en/rails/slc/what-is-lerian-slc)
* [Lerian SILOC](/en/rails/siloc/what-is-lerian-siloc)


# Bills and payments through a partner
Source: https://docs.lerian.studio/en/diagrams/partner-interfaces/bills-and-payments

Paying boletos and utility bills through a partner interface.

Pay boletos and bills when a partner connects your institution to the payment networks.

> [!NOTE]
>
> This journey is in construction. The page shows where it sits in the tab; the diagram and steps come in a later update.


# Partner interface journeys
Source: https://docs.lerian.studio/en/diagrams/partner-interfaces/overview

Payment journeys that run through a partner that connects your institution to the payment networks.

These journeys run through a partner interface, such as JD or BTG, instead of Lerian's native messaging. Each page covers one type of payment and has one section per partner, because the journey is the same and the partner changes some of the steps.

## The partner's documentation prevails

***

The partner's documentation and the BACEN manuals define the messages and the rules. If this site and those documents disagree, they prevail. Lerian supports its interface to each partner. Advice on applying the partner's rules to your operation is offered by proposal.

## Journeys

***

**Pix**

* [Pix through a partner](/en/diagrams/partner-interfaces/pix): A Pix payment through a partner interface, with one section per partner.

**TED**

* [TED through a partner](/en/diagrams/partner-interfaces/ted): A TED transfer through a partner interface.

**Bills and payments**

* [Bills and payments through a partner](/en/diagrams/partner-interfaces/bills-and-payments): Paying boletos and utility bills through a partner interface.


# Pix through a partner
Source: https://docs.lerian.studio/en/diagrams/partner-interfaces/pix

A Pix payment through a partner interface, with one section per partner.

Send and receive Pix when a partner connects your institution to SPI.

> [!NOTE]
>
> This journey is in construction. The page shows where it sits in the tab; the diagram and steps come in a later update.


# TED through a partner
Source: https://docs.lerian.studio/en/diagrams/partner-interfaces/ted

A TED transfer through a partner interface.

Send and receive TED when a partner connects your institution to STR.

> [!NOTE]
>
> This journey is in construction. The page shows where it sits in the tab; the diagram and steps come in a later update.


# BYOC configuration essentials
Source: https://docs.lerian.studio/en/reference/byoc-configuration

Environment variables that recur across Lerian Go services when you run BYOC in your own cloud or on-prem.

In a BYOC (bring your own cloud) deployment, you run Lerian products inside your own AWS, GCP, or on-prem infrastructure. You own the data and the runtime. You configure each service through environment variables, and most of them are service-specific. This page covers variables that recur across Lerian Go services. Use each product's own page for the rest.

> [!NOTE]
>
> These variables are not the full list. Variable names and defaults differ between services, and services add their own keys. See [Per-product variables](#per-product-variables).

## Deployment mode and TLS

| Variable | Description | Default | Allowed values |
| - | - | - | - |
| `DEPLOYMENT_MODE` | Deployment posture. Its effect, default and accepted values vary per service. | Varies per service | Varies per service |
| `ALLOW_INSECURE_TLS` | Bypass per-connection TLS enforcement on infrastructure DSNs. Intended for local development only. [Pix JD](/en/interfaces/pix-jd/pix-jd-environment-variables#connections-without-tls) also uses it to accept `http://` addresses for its outbound connections, in every environment. | `false` | `true`, `false` |

> [!WARNING]
>
> For a production BYOC deployment, set `DEPLOYMENT_MODE=byoc`, connect every datastore over TLS, and leave `ALLOW_INSECURE_TLS` unset (`false`).

## Server

| Variable | Description | Default | Allowed values |
| - | - | - | - |
| `SERVER_ADDRESS` | Main HTTP listen address (`host:port`, usually `:port`). The probes bind this same port. | Varies per service | `host:port` |
| `LOG_LEVEL` | Log verbosity. Use `info` or higher in production. | Varies per service | `debug`, `info`, `warn`, `error` |
| `ENV_NAME` | Environment label. In SLC, it is normalized to an allowlist. | Varies per service | SLC: `production`, `staging`, `uat`, `development`, `local` |

> [!NOTE]
>
> Some services expose a numeric `SERVER_PORT` instead of, or alongside, `SERVER_ADDRESS`. Some worker components expose a dedicated health port (for example `HEALTH_PORT` or `WORKER_SERVER_PORT`). See [Default network ports](/en/reference/default-network-ports) and [Health and readiness](/en/reference/health-and-readiness).

## Datastores

Every service that persists state connects to one or more datastores. The variable prefix depends on the store, and in some services on the logical database. The table below shows the common shape. Consult each product's page for the exact names.

| Variable | Description | Default | Allowed values |
| - | - | - | - |
| `POSTGRES_HOST` / `POSTGRES_PORT` | PostgreSQL host and port. | Varies per service | Host / port |
| `POSTGRES_USER` / `POSTGRES_PASSWORD` | Connection credentials. The password is a secret. Inject it at deploy time, and never commit it. | Varies per service | String / secret |
| `POSTGRES_NAME` / `POSTGRES_DB` / `DB_NAME` | Database name. The exact key varies by service: `POSTGRES_NAME` (for example STA, SLC, SISBAJUD, Consignado), `POSTGRES_DB` (SPB, SPI, Boleto), or `DB_NAME` (Pix Indirect). Midaz namespaces it per logical database as `DB_{MODULE}_NAME`. Consult each product's page. | Varies per service | String |
| `POSTGRES_SSLMODE` | libpq TLS mode. Use `require` or stronger in production. | Varies per service | `disable`, `require`, `verify-ca`, `verify-full` |
| `POSTGRES_REPLICA_*` | Optional read-replica connection (same shape as the primary). | — | Host / port / credentials |
| `MONGO_URI` / `MONGO_HOST` / `MONGO_PORT` | MongoDB connection, as a full URI or discrete host and port. | — | Connection string / host / port |
| `MONGO_TLS_CA_CERT` | Base64-encoded PEM CA certificate for TLS (for example, a managed MongoDB service). | — | Base64 PEM |
| `REDIS_HOST` / `REDIS_PASSWORD` | Redis/Valkey endpoint and auth password (secret). | Varies per service | `host:port` / secret |
| `REDIS_TLS` / `REDIS_CA_CERT` | Enable TLS to Redis and supply a base64-encoded PEM CA certificate. In SLC, `REDIS_TLS=true` requires a nonblank `REDIS_CA_CERT`. | `false` / — | `true`, `false` / base64 PEM |
| `RABBITMQ_HOST` / `RABBITMQ_URI` | Broker host and connection scheme. Use `amqps` in production. | Varies per service | Host / `amqp`, `amqps` |
| `RABBITMQ_DEFAULT_USER` / `RABBITMQ_DEFAULT_PASS` | Broker credentials (password is a secret). In SLC, when RabbitMQ is enabled and its URL has no credentials, explicitly declare both `RABBITMQ_DEFAULT_USER` and `RABBITMQ_DEFAULT_PASS`. | — | String / secret |

> [!NOTE]
>
> Not every service uses every store, and prefixes vary. Midaz namespaces connections per logical database (for example `DB_ONBOARDING_*`, `DB_TRANSACTION_*`, `MONGO_CRM_*`).

## Runtime configuration

| Variable | Description | Default | Allowed values |
| - | - | - | - |
| `SYSTEMPLANE_ENABLED` | Enable the systemplane runtime-configuration admin API, in services that expose the switch. Check each service's page. | Varies per service | `true`, `false` |

When enabled, the service exposes a plane for reading and writing runtime configuration. See [Systemplane](/en/reference/platform/systemplane/overview) for the API and namespaces.

## Streaming and outbox

Whether event publication is on by default, and which switch controls it, differs by service. Check each product's page for its contract, for example [SPI](/en/rails/spi/spi-environment-variables#outbox-and-streaming) and [SILOC](/en/rails/siloc/siloc-environment-variables#observability).

| Variable | Description | Default | Allowed values |
| - | - | - | - |
| `STREAMING_ENABLED` | Enable the event producer, in services that expose the switch. | Varies per service | `true`, `false` |
| `STREAMING_BROKERS` | Kafka/RedPanda bootstrap brokers, as a `host:port` comma-separated list. Required at startup by services whose streaming has no disabled mode. | — | `host:port` CSV |
| `STREAMING_CLOUDEVENTS_SOURCE` | The CloudEvents `source` stamped on every event the service emits. Several products accept exactly one literal and refuse to boot on any other, so take the value from the product's own page. | Varies per service | The literal the product requires |
| `STREAMING_EVENT_POLICIES` | Per-event delivery-policy overrides, as `event.key.attribute=value` entries separated by commas, semicolons, or newlines (for example `transaction.created.enabled=true,transaction.created.outbox=always`). The attributes are `enabled`, `direct`, `outbox`, and `dlq`. Empty keeps each event's default policy. | — | `event.key.attribute=value` list |
| `STREAMING_COMPRESSION` | Producer compression codec. | `lz4` | `none`, `gzip`, `snappy`, `lz4`, `zstd` |
| `STREAMING_REQUIRED_ACKS` | Producer acknowledgement level. | `all` | `all`, `leader`, `none` |
| `OUTBOX_ENABLED` | Enable the transactional outbox dispatcher (where the service exposes it separately). | Varies per service | `true`, `false` |

> [!NOTE]
>
> The variables that secure the broker connection differ by service. Some services read `STREAMING_SASL_*` and `STREAMING_TLS_*`, and [Consignado](/en/rails/consignado/consignado-environment-variables) reads `STREAMING_KAFKA_SASL_*` and `STREAMING_KAFKA_TLS_*`. Set them when your broker requires authentication or TLS, and take the names from the product's own page.

## Service discovery

In services that support Consul service discovery, it is off by default. When enabled, the service registers itself and resolves peers through Consul instead of static addresses.

| Variable | Description | Default | Allowed values |
| - | - | - | - |
| `SD_ENABLED` | Enable Consul service discovery. | `false` | `true`, `false` |
| `SD_EXTERNAL_ADDRESS` / `SD_INTERNAL_ADDRESS` | Advertised addresses. Required when enabled. | — | `host:port` |
| `SD_TLS` / `SD_TLS_SKIP_VERIFY` | Enable TLS to Consul, and (separately) bypass certificate verification. | `false` | `true`, `false` |
| `SD_TOKEN` | Consul ACL token (secret). | — | Secret |

> [!NOTE]
>
> Some services use legacy aliases (`SD_ADVERTISE_*`, `CONSUL_ADDR`) for the same behavior.

## Observability

Telemetry is push-based (OTLP). Some services additionally expose a `/metrics` endpoint for Prometheus scraping. See [Health and readiness](/en/reference/health-and-readiness).

| Variable | Description | Default | Allowed values |
| - | - | - | - |
| `ENABLE_TELEMETRY` | Enable OpenTelemetry instrumentation. | `false` | `true`, `false` |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector endpoint. Use an `https://` endpoint in production. | Varies per service | URL |
| `ALLOW_INSECURE_OTEL` | Lets a service send telemetry to a plaintext OTLP endpoint (`http://` or no scheme) in production. Without it, many services refuse to start with a plaintext endpoint in production. Any non-empty value turns it on, so use a short reason. To keep TLS required, leave it unset. | Unset | String |
| `OTEL_RESOURCE_SERVICE_NAME` | Service name attached to exported telemetry. | Service default | String |
| `OTEL_RESOURCE_DEPLOYMENT_ENVIRONMENT` | Environment label attached to exported telemetry. | Varies per service | String |

## Plugin authentication

Lerian services can authenticate protected routes through Access Manager (Caradhras-backed). The authentication toggle, its variable name, and its default differ by service. Always enable authentication in production. Check each product or rail's own environment-variables page for the authoritative toggle name, its default, and the routes it protects.

| Variable | Description | Default | Allowed values |
| - | - | - | - |
| `PLUGIN_AUTH_ENABLED` / `AUTH_ENABLED` | Require Access Manager authentication on protected routes. The name and default vary by service. | Varies per service | `true`, `false` |
| `PLUGIN_AUTH_ADDRESS` / `PLUGIN_AUTH_HOST` / `AUTH_ADDRESS` | Access Manager service address. Required when enabled. | — | Address |

## Per-product variables

Each product adds its own variables: datastore prefixes, integration URLs, worker tuning, and feature toggles. Its own page holds the full, current list, for example:

> **[Midaz](/en/products/midaz/midaz-environment-variables)**

> **[Tracer](/en/products/tracer/tracer-environment-variables)**

> **[Reporter](/en/products/reporter/reporter-environment-variables)**

> **[Lender](/en/products/lender/configuration-and-deploy)**


# Choosing the right product
Source: https://docs.lerian.studio/en/reference/choosing-the-right-api

Learn which Lerian product, plugin, or API to use for each job across ledger, reporting, and orchestration flows, and how the pieces fit together.

Each Lerian product and plugin owns one job, and most real flows touch more than one. The rule that prevents most mistakes:

> **Plugins perform actions. Midaz is the source of truth for state.**

Tell a plugin to *do* something: move money. Ask **Midaz** what the money *is*: balances, history, who owns what.

## Which product for which job

***

| You want to… | Call | Why |
| - | - | - |
| Authenticate before any call | [**Access Manager**](/en/reference/platform/access-manager/am-api-introduction) | Issues the tokens every product API trusts |
| Move money in or out | [**Bank Transfer**](/en/reference/interfaces/ted-jd/initiate-transfer) or **Pix** | Executes the transfer and records it in Midaz for you |
| Read a balance, statement, or transaction | [**Midaz**](/en/reference/products/midaz/quick-start-guide) | The Ledger is the source of truth for state. Don't infer a balance from a payment plugin |
| Identify who owns an account | [**Midaz (CRM)**](/en/reference/products/midaz/v2/create-holder) | Account owners are Holders in Midaz. There's no separate identity service to register first |
| Apply a fee | [**Fees**](/en/reference/products/midaz/v2/create-package) | You configure fee packages; Midaz applies the matching package when you create a v2 transaction |
| Validate a transaction before it happens | [**Tracer**](/en/reference/products/tracer/tracer-api-quick-start) | Returns `ALLOW` / `DENY` / `REVIEW` before you submit anything |
| Generate a report (including regulatory) | [**Reporter**](/en/reference/products/reporter/reporter-developer-quick-start) | Reads Midaz data read-only, on its own period and format |
| Reconcile transactions across sources | [**Matcher**](/en/reference/products/matcher/matcher-developer-quick-start) | Automates multi-source matching with configurable rules and immutable audit trails |
| Orchestrate a multi-step financial workflow | [**Flowker**](/en/reference/products/flowker/create-workflow) | Manages validation pipelines and sequences of financial operations |

> [!NOTE]
>
> **Access Manager** handles authentication and authorization. It controls who can use the products. Account owners are **Holders** stored in Midaz. There's no separate identity service to register before opening an account.

## Flows that span products

***

Most real financial operations chain more than one product together. These are the common sequences.

### Payment with validation

> Use **Tracer** → **Bank Transfer** or **Pix** → Midaz

**Step 1**

Call **Tracer** first. It returns `ALLOW`, `DENY`, or `REVIEW`. Stop here if the decision is `DENY`. You do not need a payment call.

**Step 2**

Call one of the plugins used for payment:

* **Bank Transfer** for wire transfers
* **Pix** for instant payments

**Step 3**

Read the result from **Midaz**. **Bank Transfer** or **Pix** confirms the transfer event. Midaz confirms the new balance. These are two different facts.

### Apply fees

> Use **Fees** → **Midaz**

**Step 1**

Configure a fee package in **Fees**. The package defines the fee rules and the transactions they apply to.

**Step 2**

Create the transaction through the **Midaz** v2 API. Midaz applies the matching package to that transaction. Do not submit a separate fee transaction.

### Regulatory or period report

> Use **Midaz** → **Reporter**

**Step 1**

The source data lives in **Midaz**: transactions, balances, holders.

**Step 2**

Call **Reporter** with the period and output format. It reads Midaz read-only and produces the BACEN or fiscal file.

### Transaction reconciliation

> Use **Midaz** + external sources → **Matcher**

**Step 1**

**Matcher** reads from Midaz and one or more external sources.

**Step 2**

It applies configurable matching rules and produces match results, exceptions, and an immutable audit trail. It does not write to Midaz.

## See also

***

* The conceptual map of how the pieces connect: [Building a complete core banking](/en/products/building-a-complete-core-banking)
* Midaz-specific scenarios: [Midaz use cases](/en/products/midaz/use-cases)


# Default network ports
Source: https://docs.lerian.studio/en/reference/default-network-ports

Reference the default TCP ports used by Midaz and Lerian plugins so you can open the right firewall rules when deploying in self-hosted environments.

> [!CAUTION]
>
> These are the default internal ports. If you're using Docker Compose, Kubernetes, or a cloud provider, port mappings may differ. Always verify your configuration before exposing services publicly.

## Core services

***

| Service | Port |
| :- | :- |
| Midaz Ledger | 3002 |
| Midaz Tracer | 4020 |
| Midaz Console | 8081 |

## Plugin services

***

Each plugin runs as an independent service and may expose its own API or background processes.

| Plugin | Port |
| :- | :- |
| Access Manager - Auth | 4000 |
| Access Manager - Identity | 4001 |
| Reporter Manager | 4005 |

> [!TIP]
>
> For better security, expose only necessary ports (like Console) and restrict others using firewall rules or internal networking policies.

## Customization

***

You can change the default ports using environment variables, Docker Compose files, or Helm values, depending on your setup. If you override a port, make sure to update any references across your infrastructure, load balancers, and API consumers.


# Error handling
Source: https://docs.lerian.studio/en/reference/error-handling

Learn how to interpret and resolve error responses returned by Lerian APIs, including the error envelopes, HTTP status codes, and field-level detail.

This guide explains the shape of a Lerian error response and how to respond to each kind.

## What you will receive

***

An `application/problem+json` response is an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details object. Your API reference carries an **Error handling** page that names the shape that API answers.

```json application/problem+json theme={null}
{
  "type": "https://errors.lerian.studio/v1/RPT-0012",
  "title": "Bad Request",
  "status": 400,
  "detail": "The specified templateID is not a valid UUID. Please check the value passed.",
  "code": "RPT-0012"
}
```

```json application/json theme={null}
{
  "code": "PIX-0030",
  "title": "Idempotency Key Required",
  "message": "The X-Idempotency header is required for this operation and must be within the accepted length."
}
```

**Field definitions**

In the problem details object:

* **`type`** – A URI reference that identifies the error type.
* **`title`** – A short summary of the problem type.
* **`status`** – The HTTP status code.
* **`detail`** – Guidance specific to this occurrence.
* **`errors`** – Optional list of per-field detail, each entry with a `location` and a `message`.
* **`instance`** – Optional URI reference for this specific occurrence.

Plain envelopes differ between APIs. They differ in the field names, in whether the error sits at
the top level, and in which field carries the machine-readable token. Read your API reference's
**Error handling** page before you write a parser.

> [!TIP]
>
> Where an API publishes a stable code, branch on it. Not every API publishes a code, and its
> **Error handling** page says whether it does.

## Error codes

***

Code shape varies by API. You will meet a prefixed `<PREFIX>-<NNNN>`, a bare number, a lowercase
token, and a code that a rail's counterparty assigned. Midaz core uses bare numbers such as `0002`
and `0009`.

Your API reference carries an **Error handling** page that names the shape that API uses and lists
the codes it emits.

## HTTP status codes

***

These are the status codes you will meet most often. An API can answer others, and its own **Error handling** page lists them.

| Code | Meaning |
| - | - |
| `400` | Bad Request |
| `401` | Unauthorized |
| `403` | Forbidden |
| `404` | Not Found |
| `409` | Conflict |
| `422` | Unprocessable Entity |
| `412` | Precondition Failed |
| `413` | Payload Too Large |
| `429` | Too Many Requests |
| `500` | Internal Server Error |
| `502` | Bad Gateway |
| `501` | Not Implemented |
| `503` | Service Unavailable |
| `504` | Gateway Timeout |

## Retry guidance

***

You should not retry every error. The following table helps you decide:

| Error type | Retryable | Recommended action |
| - | - | - |
| `400` | No | Fix the request payload |
| `401` | After a token refresh | Check credentials |
| `403` | No | Check permissions |
| `404` not found | No | Verify the resource ID |
| `409` conflicts | Sometimes | Check current state, then retry if the conflict is resolved |
| `422` | No | Fix the cause the error names |
| `429` rate limit | Sometimes | Wait, then retry reads. Reconcile commands before retrying. |
| `500` internal errors | Sometimes | Retry reads with exponential backoff. Reconcile commands before retrying. |
| `502` / `503` / `504` | Sometimes | Retry reads with exponential backoff. Reconcile commands before retrying. |

> [!WARNING]
>
> A failed command can have an unknown outcome. For commands, follow that API's reference for the idempotency key to use. Some APIs require the original key, while others reject or discard it after an uncertain provider outcome.

### Exponential backoff strategy

For retryable errors, use exponential backoff to avoid overwhelming the service:

1. **First retry**: Wait 1 second
2. **Second retry**: Wait 2 seconds
3. **Third retry**: Wait 4 seconds
4. **Maximum retries**: Stop after 3–5 attempts
5. **Jitter**: Add a small random delay (0–500ms) to each wait to prevent thundering herd

> [!WARNING]
>
> Do not repeat a `400`, a `403` or a `422` unchanged. A `401` is worth one retry after you refresh the token, and no more.

## Troubleshooting by category

***

### Missing or invalid fields (400)

A `400` response can carry field-level detail that names the fields at fault.

**Common causes:**

* Required field omitted from the request body
* Field value does not match the expected type (e.g., string instead of UUID)
* Field value exceeds maximum length
* Unexpected extra fields in the request body

**Resolution steps:**

1. Read the field-level detail in the error response
2. Compare your request against the API reference for that endpoint

### Authentication and authorization (401/403)

**Common causes:**

* Missing credential
* Expired or revoked token
* Token does not grant access to the requested endpoint

**Resolution steps:**

1. Verify that the request carries the credential your API expects
2. Request a new token if the current one has expired
3. Check that the caller has the required permissions

### Resource not found (404)

**Common causes:**

* Incorrect resource ID in the URL path
* Resource was soft-deleted
* Resource belongs to a different organization or ledger

**Resolution steps:**

1. Verify the resource ID in the URL path
2. List resources to confirm the ID exists

### Conflict errors (409)

**Common causes:**

* Creating a resource with a name that already exists (e.g., duplicate ledger name, duplicate rule name)
* Attempting an operation that is already complete (e.g., duplicate transaction)

**Resolution steps:**

1. Read the error message to identify which field caused the conflict
2. Use a different value (e.g., rename) or retrieve the existing resource instead
3. For idempotent operations, verify the existing resource matches your intent

### Rate limiting (429)

**Common causes:**

* Too many requests in a short period

**Resolution steps:**

1. Implement exponential backoff with jitter
2. Reduce the frequency of API calls
3. Batch operations where possible

### Server and timeout errors (500/502/503/504)

**Common causes:**

* Temporary service disruption
* High load on the platform
* Upstream dependency unavailable

**Resolution steps:**

1. Retry reads with exponential backoff (1s, 2s, 4s). Reconcile commands before retrying them, because the original outcome can be unknown.
2. If the error persists after 3–5 retries, contact support
3. Log a redacted error response for support escalation

## Service-specific error lists

***

Every API reference carries an **Error handling** page. Use it to look up a code you received.

**Products**

| API | Error list |
| - | - |
| Midaz | [Midaz error list](/en/reference/products/midaz/error-list) |
| Tracer | [Tracer error list](/en/reference/products/tracer/tracer-error-list) |
| Matcher | [Matcher error list](/en/reference/products/matcher/matcher-error-list) |
| Flowker | [Flowker error list](/en/reference/products/flowker/flowker-error-list) |
| Lender | [Lender error list](/en/reference/products/lender/lender-error-list) |
| Reporter | [Reporter error list](/en/reference/products/reporter/reporter-error-list) |

**Brazil Rails**

| API | Error list |
| - | - |
| SPB (TED) | [SPB error list](/en/reference/rails/spb/spb-error-list) |
| SPI (Pix) | [SPI error list](/en/reference/rails/spi/spi-error-list) |
| SLC | [SLC error list](/en/reference/rails/slc/slc-error-list) |
| SILOC | [SILOC error list](/en/reference/rails/siloc/siloc-error-list) |
| STA | [STA error list](/en/reference/rails/sta/sta-error-list) |
| SISBAJUD | [SISBAJUD error list](/en/reference/rails/sisbajud/sisbajud-error-list) |
| BC Correios | [BC Correios error list](/en/reference/rails/bc-correios/bc-correios-error-list) |
| SRC | [SRC error list](/en/reference/rails/src/src-error-list) |
| Consignado CLT (Dataprev) | [Consignado error list](/en/reference/rails/consignado/consignado-error-list) |

**Interfaces**

| API | Error list |
| - | - |
| Pix Lerian | [Pix Lerian error list](/en/reference/interfaces/pix-lerian/pix-lerian-error-list) |
| Pix JD | [Pix JD error list](/en/reference/interfaces/pix-jd/pix-jd-error-list) |
| Pix BTG | [Pix BTG error list](/en/reference/interfaces/pix-btg/indirect-pix-error-list) |
| TED JD | [TED JD error list](/en/reference/interfaces/ted-jd/ted-error-list) |
| Payments BTG | [Payments error list](/en/reference/interfaces/payments-btg/payments-error-list) |

**Platform**

| API | Error list |
| - | - |
| Access Manager | [Access Manager error list](/en/reference/platform/access-manager/access-manager-error-list) |
| Streaming Hub | [Streaming Hub error list](/en/reference/platform/streaming-hub/streaming-hub-error-list) |
| Systemplane | [Systemplane error list](/en/reference/platform/systemplane/systemplane-error-list) |
| Narya | [Narya host API error list](/en/reference/platform/narya/host-api-error-list) |

## Best practices

***

### 1. Use error codes for programmatic handling

Error codes are stable identifiers for automation. Map specific codes to resolution paths in your integration. Take the codes from your API's error list page.

### 2. Log errors with context

Log the operation, timestamp, status, stable error code, and a redacted response. Do not log credentials, bearer tokens, personal data, or sensitive request fields. This keeps support context useful without copying secrets or PII into logs.

### 3. Handle field-level errors

When the response carries field-level detail, surface those messages to your users rather than a generic error. The member that carries it differs by API. Each error list page names the member its API sends.

### 4. Implement circuit breakers for integrations

If you receive repeated `500`, `502`, or `503` errors, use a circuit breaker pattern to temporarily stop calling the failing service and prevent cascading failures.

### 5. Stay updated

Review the error list pages periodically. New error codes can appear as services evolve.


# Event streaming overview
Source: https://docs.lerian.studio/en/reference/events/overview

Shared event streaming contract for Lerian products: the CloudEvents envelope, topic and type conventions, schema versioning, and delivery guarantees.

Lerian products emit domain events onto a shared streaming backbone. A domain event is a past-tense business fact, for example an account creation or a credential issuance. Any service or downstream subscriber consumes them without coupling to the producer's internal APIs. This page describes the common transport envelope and platform conventions. The per-product pages are authoritative for each producer's concrete event types, identifiers, and delivery policy. [Streaming Hub](/en/platform/streaming-hub/what-is-streaming-hub) delivers these same events to your own infrastructure (webhooks, SQS, RabbitMQ, EventBridge, or pull) with managed retries.

## Transport

Events travel as **CloudEvents 1.0** messages in **binary content mode**. Binary mode puts the CloudEvents context attributes in transport headers, each prefixed with `ce-`, and the event body in the message value as JSON. A consumer reads routing and identity from the headers without deserializing the payload.

Most producers publish over **Kafka**: Midaz, Tracer (in Midaz), Lender, Matcher, and Consignado. [Reporter](/en/reference/events/reporter) publishes the same envelope over **RabbitMQ** when `STREAMING_ENABLED=true`. It routes each event to a configured exchange with the event key as the routing key. When `STREAMING_KAFKA_BROKERS` is also set, Reporter publishes `report.finished` and `report.partial` to Kafka as well.

Both transports share the CloudEvents type and versioning conventions. Each producer's page remains authoritative for exact ids, schemas, destinations, and delivery policy. Tracer's Kafka producer is the component in Midaz.

## The envelope

Every record carries these CloudEvents headers.

| Header | Present | Carries |
| - | - | - |
| `ce-specversion` | Always | CloudEvents spec version: `1.0`. |
| `ce-id` | Always | Opaque, producer-defined stable event id. Deduplicate on the `(ce-source, ce-id)` pair; do not assume a UUID format. |
| `ce-source` | Always | The producing service. |
| `ce-type` | Always | v3 producers use `studio.lerian.<source>.<resource>.<event>`. |
| `ce-time` | Always | Emission timestamp (RFC 3339). |
| `ce-resourcetype` | Always | The resource, for example `account`. |
| `ce-eventtype` | Always | The event, for example `created`. |
| `ce-schemaversion` | Always | Payload schema version. |
| `ce-subject` | When set | The aggregate id the event concerns. |
| `ce-tenantid` | Producer-defined | The owning tenant. Midaz always sends it: your tenant, or the literal `default` when the event has no tenant. Other producers define their own behavior. |
| `ce-datacontenttype` | When set | Body media type: `application/json`. |

## Event type

The v3 contract uses the source-qualified form `studio.lerian.<source>.<resource>.<event>`. The same `<source>` value appears in `ce-source`. `ce-resourcetype` and `ce-eventtype` carry the dispatch key as separate headers. Check the producer-specific page or manifest before routing.

## Topic naming

Kafka producers on the v3 application-stream contract (including Midaz, Midaz `components/tracer`, Matcher, Lender, and Consignado) send their public JSON business facts to:

```
lerian.streaming.<ce-source>
```

Commands use `lerian.streaming.<ce-source>.commands`. The producer's dead letters use `lerian.streaming.<ce-source>.dlq`. There is no separate `.commands.dlq` topic. Resource type, event type, and schema version stay in CloudEvents headers, so schema-major changes do not rename the topic.

Examples:

* Midaz ledger, CRM, and Fees public JSON facts: `lerian.streaming.ledger`
* Midaz `components/tracer` facts: `lerian.streaming.tracer`
* Matcher facts: `lerian.streaming.matcher`
* Lender facts and commands: `lerian.streaming.lender` and `lerian.streaming.lender.commands`
* Consignado gateway facts: `lerian.streaming.consignado-gw`

Product-internal metering signals are outside this public integration contract and may use separate destinations and encodings. Reporter keeps an explicit RabbitMQ destination: its configured exchange, with the event key as routing key. Its `ce-type` values are still source-qualified.

## Source

`ce-source` identifies the producing service and is part of the wire contract. Current v3 product examples use `ledger`, `tracer` (Midaz `components/tracer`), `matcher`, `lender`, `consignado-gw`, or `reporter`. All except Matcher pin or validate that exact roster value. Matcher derives its wire identity from the configured value. v3 Kafka producers embed the source in the application topic, and all v3 producers embed it in `ce-type`. Changing it therefore changes consumer routing and identity. Treat it as a breaking change.

## Subject and tenant

`ce-subject` carries the id of the aggregate the event is about (the account, transaction, or credential the fact concerns). `ce-tenantid` carries the owning tenant. When an event has no tenant, the behavior is producer-specific: Midaz sends the literal `default`, while other producers document their own behavior. Follow the producer-specific contract.

## Schema versioning

Each event declares its own payload schema version in `ce-schemaversion`, independent of other events from the same source. The default is `1.0.0`. A minor bump is additive and backward compatible. A major bump introduces a breaking change.

On v3 Kafka application streams, the schema version never changes the topic name. A schema bump also leaves explicit RabbitMQ exchanges and routing keys unchanged. An additive change does not affect a consumer that reads payloads as a [tolerant reader](/en/reference/tolerant-reader) and ignores unknown fields.

## Delivery guarantees

Delivery is **at-least-once**. A consumer commits its position only after it finishes handling a record. A crash mid-handling replays the record rather than dropping it, so the same event can arrive more than once. Deduplicate on the `(ce-source, ce-id)` pair (CloudEvents defines event identity by that combination, and `ce-id` alone can collide across sources) and keep handlers idempotent.

On the producer side, the delivery policy belongs to each event definition, not to the platform. An **outbox-backed** policy guarantees durable relay and retry. By itself it does not prove that the business-state write and outbox insert share one database transaction.

Lender and Consignado make that atomic write for their catalog events. Reporter emits after the state commit, and its critical policies then use a durable Mongo outbox in a separate operation. A crash or a failed outbox insert in that post-commit window loses the Reporter event. No reconciliation recovers it, and only an error log and a metric record the loss.

Matcher and Reporter also publish operational signals directly with outbox fallback. Check the product's own event page for both its policy and transaction boundary. Where the product exposes a streaming manifest, read the manifest at startup.

## Per-product catalogs

| Producer | Page | Transport | Streaming manifest |
| - | - | - | - |
| Midaz (ledger, CRM, Fees) | [Midaz events](/en/reference/events/midaz) | Kafka | `GET /v1/streaming/manifest` |
| Midaz `components/tracer` | [Tracer events](/en/reference/events/tracer) | Kafka | `GET /v1/streaming/manifest` |
| Lender | [Lender events](/en/reference/events/lender) | Kafka | `GET /api/v1/streaming/manifest` |
| Matcher | [Matcher events](/en/reference/events/matcher) | Kafka | `GET /system/matcher/streaming/manifest` |
| Consignado | [Consignado events](/en/reference/events/consignado) | Kafka | `GET /v1/streaming/manifest` |
| Pix Direct via JD | [Pix Direct via JD events](/en/reference/events/pix-direct-jd) | Kafka | — |
| Lerian SISBAJUD Mensageria | [Lerian SISBAJUD events](/en/rails/sisbajud/sisbajud-integration#events) | Kafka | — |
| Reporter | [Reporter events](/en/reference/events/reporter) | RabbitMQ; Kafka for `report.finished` and `report.partial` when `STREAMING_KAFKA_BROKERS` is set | [`GET /v1/streaming/events`](/en/reference/products/reporter/get-streaming-events) |

Other Brazil rails also publish events on this contract. Use a rail's event page or runtime manifest only when the rail explicitly exposes its catalog.


# Authentication & security
Source: https://docs.lerian.studio/en/reference/field-dictionary/fd-auth-security

Reference the auth and security fields used across Lerian APIs: OAuth2 tokens, webhook signatures, scopes, and component health checks.

## 1. OAuth2 and authorization fields

***

| Field | Description | Used in |
| - | - | - |
| accessToken | JWT access token | Auth, Pix |
| refreshToken | Refresh token | Auth |
| idToken | OpenID Connect ID token | Auth |
| tokenType | Token type (Bearer) | Auth, Pix |
| expiresIn | Expiration time (seconds) | Auth, Pix |
| grantType | OAuth2 grant type | Auth |
| clientId | OAuth2 client ID | Auth, Pix |
| clientSecret | OAuth2 client secret | Auth, Pix |
| username | Username | Auth, Identity |
| password | Password | Auth, Identity |
| scope | Requested scope | Auth, Pix |
| sub | Subject identifier | Auth |
| aud | Audience | Auth |
| iss | Issuer | Auth |
| iat | Issued at | Auth |
| exp | Expiration | Auth |
| nbf | Not before | Auth |
| jti | JWT ID | Auth |
| active | Token active flag | Auth |
| authorized | Authorization result | Auth |
| resource | Target resource | Auth |
| action | Action on the resource | Auth |

## 2. Webhooks and notifications

***

| Field | Description | Used in |
| - | - | - |
| idReqJdPi | JD request identifier | Pix |
| pagador | Pix payer | Pix |
| recebedor | Pix receiver | Pix |
| valor | Pix value | Pix |
| dtHrOp | Pix operation timestamp | Pix |
| descricao | Operation description | Pix |
| endToEndIdOriginal | Original E2E ID | Pix |
| endToEndIdDevolucao | Return E2E ID | Pix |
| codigoDevolucao | Return reason code | Pix |
| motivoDevolucao | Return reason | Pix |
| refundUrlNotification | Refund notification URL | Pix |

## 3. Health and monitoring

***

| Field | Description | Used in |
| - | - | - |
| status | General status | Pix, JD Mock |
| services | Dependent services status | Pix |
| database | Database status | Pix |
| redis | Redis status | Pix |
| jd | JD integration status | Pix |


# Core fields
Source: https://docs.lerian.studio/en/reference/field-dictionary/fd-core-fields

Reference the foundational fields shared across Lerian APIs: identifiers, lifecycle timestamps, pagination, and traceability metadata.

This page consolidates the foundational fields that appear across multiple Lerian APIs. These fields identify data, track lifecycle events, paginate results, and guarantee traceability.

## 1. Unique identifiers

***

| Field | Description | Used in |
| - | - | - |
| accountId | Unique account identifier in the ledger | Midaz, CRM, Pix |
| organizationId | Identifier of the owning organization | Midaz, Fee |
| ledgerId | Unique ledger identifier | Midaz, CRM, Fee |
| holderId | Identifier of the account holder | CRM |
| transactionId | Unique financial transaction identifier | Midaz, Pix |
| externalId | Correlation ID for external systems | CRM, Pix |
| endToEndId | Pix end-to-end identifier | Pix |
| protocolId | DICT Pix protocol identifier | Pix |
| segmentId | Organizational segment identifier | Midaz, Fee |
| portfolioId | Portfolio identifier | Midaz |
| assetId | Financial asset identifier | Midaz |
| routeId | Operation route identifier | Midaz |
| templateId | Template identifier | Reporter |
| jobId | Processing job identifier | Reporter |
| clientId | OAuth2 client identifier | Auth |
| userId | User identifier | Auth, Identity |
| groupId | Group identifier | Identity |
| roleId | Role identifier | Identity |
| bankId | ISPB bank code (8 digits) | Pix |

## 2. Temporal fields (timestamps)

***

| Field | Description | Used in |
| - | - | - |
| createdAt | Creation timestamp (ISO 8601) | Midaz, CRM, Fee, Pix, Identity |
| updatedAt | Last update timestamp | Midaz, CRM, Fee, Pix, Identity |
| deletedAt | Logical deletion timestamp | Midaz, CRM, Fee, Identity |
| executedAt | Effective execution timestamp | Pix |
| scheduledAt | Scheduled execution time | Pix |
| expiresAt | Expiration timestamp | Pix, Auth |
| settledAt | Financial settlement timestamp | Pix |
| transactionAt | Transaction timestamp | Pix |
| dueDate | Due date | Pix |
| birthDate | Date of birth (YYYY-MM-DD) | CRM |
| foundingDate | Company founding date | CRM |
| accountOpeningDate | Account opening date | Pix |
| timestamp | Generic event timestamp | Auth, JD Mock |
| uptime | System uptime | Pix, JD Mock |
| lastLoginAt | Last login timestamp | Identity |
| lastActivityAt | Last activity timestamp | Identity |

## 3. Pagination and navigation

***

| Field | Description | Used in |
| - | - | - |
| page | Current page | Midaz, CRM, Fee |
| total | Total number of items | Midaz, CRM, Fee |
| items | Items in the current page | Midaz, CRM, Fee |
| sortOrder | Sort direction: `ASC` or `DESC` (default `DESC`) | Flowker |
| includeDeleted | Include logically deleted items | CRM |
| hardDelete | Requests removal subject to retention and compliance policy | CRM |

## 4. Control and audit metadata

***

| Field | Description | Used in |
| - | - | - |
| version | Resource or API version | Pix, JD Mock |
| environment | Environment (prod/dev/stage) | Pix, JD Mock |
| traceId | Log trace identifier | Pix |
| createdBy | Creator user | Identity |
| updatedBy | Last updater user | Identity |
| deletedBy | User who deleted the resource | Identity |


# Financial data
Source: https://docs.lerian.studio/en/reference/field-dictionary/fd-financial-data

Reference the financial data fields used across Midaz, CRM, Pix, and Fees Engine: banking details, Pix keys, amounts, and currency codes.

This page brings together all financial information fields used across Midaz, CRM, Pix, and Fees Engine.

## 1. Banking data

***

| Field | Description | Used in |
| - | - | - |
| branch | Bank branch code | CRM, Pix |
| account | Account number | CRM |
| accountNumber | Generic account number | Pix |
| accountDigit | Check digit | Pix |
| agency | Bank agency | Pix |
| accountType | Account type | CRM, Pix |
| iban | International Bank Account Number | CRM |
| bankId | Bank identifier | CRM, Pix |
| openingDate | Account opening date | CRM |

## 2. Pix keys

***

| Field | Description | Used in |
| - | - | - |
| key | Pix key value | Pix |
| keyType | Key type (email, phone, tax ID, random) | Pix |
| requiresConfirmation | Requires token confirmation | Pix |
| confirmationToken | Token for key confirmation | Pix |
| claimId | Claim identifier | Pix |
| claimReason | Claim reason | Pix |
| claimType | Claim type | Pix |
| authorizationCode | Authorization code | Pix |
| checked | Key verification flag | Pix |

## 3. Financial transactions

***

| Field | Description | Used in |
| - | - | - |
| amount | Monetary amount | Midaz, Pix, Fee |
| value | Numeric value | Fee, Pix |
| totalAmount | Total amount of the operation | Pix |
| minimumAmount | Minimum allowed amount | Fee |
| maximumAmount | Maximum allowed amount | Fee |
| originalAmount | Amount before fees | Fee |
| afterFeesAmount | Amount after fee application | Fee |
| description | Transaction description | Midaz, Pix |
| asset | Asset code (BRL, USD) | Midaz, Fee |
| code | Transaction or authorization code | Midaz |
| route | Operation route | Midaz |
| pending | Pending status | Midaz |
| isPixSaque | Pix withdrawal flag | Pix |
| isPixTroco | Pix cashback flag | Pix |
| isReversal | Reversal flag | Pix |
| isInternal | Internal transaction flag | Pix |
| reversalType | Type of reversal | Pix |
| refundId | Refund identifier | Pix |
| returnId | Return identifier | Pix |
| returnReason | Reason for return | Pix |
| returnedAt | Return timestamp | Pix |
| failureReason | Failure reason | Pix |

## 4. Pix QR codes

***

| Field | Description | Used in |
| - | - | - |
| qrCode | Pix QR Code string | Pix |
| qrCodeType | QR type (static/dynamic) | Pix |
| recipientName | Recipient name | Pix |
| expirationTime | Expiration time in seconds | Pix |
| isValid | Whether QR is valid | Pix |
| validationMessage | Validation message | Pix |
| additionalData | Additional QR data | Pix |

## 5. Limits and controls

***

| Field | Description | Used in |
| - | - | - |
| limitType | Limit type | Pix |
| periodType | Period type | Pix |
| used | Amount used in the period | Pix |
| remaining | Remaining amount | Pix |
| resetDate | Period reset date | Pix |
| waivedAccounts | Accounts exempt from fees | Fee |


# Ledger operations
Source: https://docs.lerian.studio/en/reference/field-dictionary/fd-ledger-operations

Reference the Midaz Ledger operation fields: balances, transaction routes, operation routes, and metadata indexes used in postings.

This page covers fields specific to Midaz ledger operations, including balances, transaction routes, operation routes, and metadata indexes.

## 1. Balances

***

| Field | Description | Used in |
| - | - | - |
| key | Unique identifier for the balance within the account context | Midaz |
| available | Amount available for transactions | Midaz |
| onHold | Amount currently reserved or on hold | Midaz |
| version | Balance version, updated with each transaction (for optimistic concurrency) | Midaz |
| accountType | Type of account that holds this balance | Midaz |
| allowSending | Whether the balance can be used to send transactions | Midaz |
| allowReceiving | Whether the balance can be used to receive transactions | Midaz |
| assetCode | Asset or currency code (e.g., BRL, USD) | Midaz |
| alias | Account alias for quick identification | Midaz |

## 2. Transaction routes

***

| Field | Description | Used in |
| - | - | - |
| title | Short text summarizing the route's purpose (max 255 characters) | Midaz |
| description | Detailed description of the transaction route (max 250 characters) | Midaz |
| operationRoutes | In requests, array of operation-route IDs that define source and destination logic; in responses, array of `OperationRoute` objects | Midaz |

## 3. Operation routes

***

| Field | Description | Used in |
| - | - | - |
| operationType | Route direction: source, destination, or bidirectional | Midaz |
| code | External reference code for the operation route | Midaz |
| account | Account selection rule for the operation | Midaz |
| ruleType | Account selection method: alias or account\_type | Midaz |
| validIf | Condition that must be satisfied for the rule to match | Midaz |

## 4. Metadata indexes

***

| Field | Description | Used in |
| - | - | - |
| metadataKey | Metadata key to index (max 100 characters, must match the field name in entities) | Midaz |
| unique | Whether the index enforces uniqueness (duplicate values rejected when true) | Midaz |
| sparse | Whether the index is sparse (only indexes entities containing the field) | Midaz |
| indexName | Name of the created index | Midaz |
| entityName | Name of the entity collection the index applies to | Midaz |


# Lerian field dictionary
Source: https://docs.lerian.studio/en/reference/field-dictionary/fd-main

The centralized dictionary of fields used across Lerian products: Midaz, its embedded CRM and Fees, Flowker, Pix, Auth, Reporter, and related plugins.

This guide organizes fields used across the Lerian ecosystem into a single reference. It supports the engineering teams that work with Midaz, its embedded CRM and Fees Engine components, Flowker, Identity, Pix, Auth, Reporter, and related plugins.

This dictionary helps you validate payloads, improve interoperability, simplify QA, and accelerate integration development.

## What the dictionary covers

***

New features, plugins, and versions bring new fields and behavior. This dictionary centralizes all definitions, so you can see how our products communicate with each other.

Use it to:

* Build integrations with confidence
* Reduce ambiguity across workflows
* Validate payload structures
* Support QA, observability, and debugging
* Accelerate onboarding for new developers

## How to use this page

***

Each section groups fields by semantic categories. Every field includes:

* Field name
* Description
* Where it is used across Lerian products

If you work with a specific product, open the dictionary page for that area, listed under Structure of the dictionary below.

> [!CAUTION]
>
> For strict schema validation, always check the official OpenAPI specifications. Those files reflect the exact structure required by each endpoint.

## Before you explore

***

This dictionary follows consistent conventions across all products.

* Dates use ISO 8601 or RFC3339 formats
* Pix fields follow BACEN standards
* Workflow fields follow Flowker’s runtime and authoring semantics
* Fees Engine fields reflect the latest v2 model
* Metadata is always a flexible key-value

> [!WARNING]
>
> If your integration uses sensitive operations like Pix, Identity, or Fees Engine, verify behavior and accepted formats directly in the product APIs. Some fields behave differently depending on the execution context.

## Structure of the dictionary

***

The dictionary has the following categories:

> **[Core fields](/en/reference/field-dictionary/fd-core-fields)**
>
> Essential fields shared across all Lerian APIs, including identifiers, timestamps, pagination, and audit metadata.

> **[People & Organizations](/en/reference/field-dictionary/fd-people-organizations)**
>
> Fields that describe individuals, companies, users, groups, and organizational structures.

> **[Financial data](/en/reference/field-dictionary/fd-financial-data)**
>
> Fields related to banking details, Pix operations, financial transactions, QR Codes, and operational limits.

> **[Authentication & Security](/en/reference/field-dictionary/fd-auth-security)**
>
> Fields used for authentication, authorization, OAuth2 flows, webhook validation, and system health monitoring.

> **[Workflows & Reporting](/en/reference/field-dictionary/fd-workflows-reporting)**
>
> Fields related to workflow orchestration (Flowker), reporting (Reporter), fee calculations, and error handling.

> **[Tracer](/en/reference/field-dictionary/fd-tracer)**
>
> Fields for transaction validation, rules, spending limits, and decision responses.

> **[Pix operations](/en/reference/field-dictionary/fd-pix-operations)**
>
> Fields for Pix dispute resolution: claims, infraction reports, refund requests, and fraud markers.

> **[Ledger operations](/en/reference/field-dictionary/fd-ledger-operations)**
>
> Fields for balances, transaction routes, operation routes, and metadata indexes.


# People & Organizations
Source: https://docs.lerian.studio/en/reference/field-dictionary/fd-people-organizations

Reference the people and organization fields used across Lerian APIs: personal data, corporate data, contacts, addresses, and identity.

## 1. Personal and business information

***

| Field | Description | Used in |
| - | - | - |
| name | Full name or legal entity name | Midaz, CRM, Pix, Identity |
| document | Tax ID (CPF/CNPJ) | CRM, Pix |
| type | Person type or resource type | CRM, Pix |
| favoriteName | Preferred or nickname | CRM |
| socialName | Social name | CRM |
| tradeName | Trade name | CRM, Pix |
| motherName | Mother's name | CRM, Pix |
| fatherName | Father's name | CRM |
| gender | Gender | CRM, Identity |
| civilStatus | Civil status | CRM |
| nationality | Nationality | CRM |
| activity | Business activity | CRM |
| size | Company size | CRM |
| status | Status (active, inactive, etc) | Midaz, CRM, Pix, Fee, Identity |

## 2. Contact information

***

| Field | Description | Used in |
| - | - | - |
| email | Primary email | Auth, CRM, Identity |
| primaryEmail | Primary email | CRM, Identity |
| secondaryEmail | Secondary email | CRM, Identity |
| emailVerified | Email verification flag | Auth, Identity |
| mobilePhone | Mobile phone | CRM, Identity |
| otherPhone | Additional phone | CRM |
| phone | Main phone | Midaz, Identity |

## 3. Addresses

***

| Field | Description | Used in |
| - | - | - |
| address | Full address or nested object | Midaz, Identity |
| line1 | Address line 1 | CRM |
| line2 | Address line 2 | CRM |
| zipCode | ZIP code | CRM |
| city | City | CRM |
| state | State | CRM |
| country | ISO 3166-1 alpha-2 country code | CRM |
| countryCode | Country bank code | CRM |
| description | Address description | CRM |

## 4. Organizational structures (Midaz)

***

| Field | Description | Used in |
| - | - | - |
| legalName | Legal company name | Midaz |
| doingBusinessAs | Trade name | Midaz |
| legalDocument | Official legal document | Midaz |
| address | Organization address | Midaz |
| phone | Main phone | Midaz |
| website | Website | Midaz |
| parentOrganizationId | Parent organization identifier | Midaz |
| metadata | Flexible key-value metadata | Midaz |
| scale | Scale factor for calculations | Midaz |
| precision | Decimal precision | Midaz |
| symbol | Currency or asset symbol | Midaz |
| balance | Account balance | Midaz |
| available | Available balance | Midaz |
| onHold | Held balance | Midaz |

## 5. User profile

***

| Field | Description | Used in |
| - | - | - |
| profile | User profile URL | Auth, Identity |
| preferredUsername | Preferred username | Auth, Identity |
| picture | Profile picture URL | Auth, Identity |
| avatar | Avatar image URL | Identity |
| bio | User biography | Identity |
| locale | Preferred locale | Identity |
| timezone | User timezone | Identity |
| representative | Legal representative | CRM |
| role | User role | CRM, Identity |

## 6. Identity: users and groups

***

| Field | Description | Used in |
| - | - | - |
| userId | Unique user identifier | Identity |
| user\_id | User ID (admin context) | Identity |
| username | Unique username | Identity |
| email | Primary email | Identity |
| emailVerified | Email verified flag | Identity |
| phone | User phone | Identity |
| phoneVerified | Phone verified flag | Identity |
| passwordHash | bcrypt hash | Identity |
| passwordChangedAt | Last password change | Identity |
| passwordResetToken | Reset token | Identity |
| passwordResetExpires | Reset expiration | Identity |
| firstName | First name | Identity |
| lastName | Last name | Identity |
| fullName | Full name | Identity |
| displayName | Display name | Identity |
| avatar | Avatar | Identity |
| bio | User biography | Identity |
| locale | User locale | Identity |
| timezone | Timezone | Identity |
| isActive | User active flag | Identity |
| isEmailVerified | Email verified flag | Identity |
| isMfaEnabled | MFA enabled | Identity |
| mfaSecret | MFA secret | Identity |
| lastLoginAt | Last login | Identity |
| lastActivityAt | Last activity | Identity |
| loginCount | Login counter | Identity |
| failedLoginAttempts | Failed login attempts | Identity |
| lockedUntil | Lock expiration | Identity |
| groupId | Group ID | Identity |
| groupName | Group name | Identity |
| groupDescription | Group description | Identity |
| permissions | Array of permissions | Identity |
| roles | Array of roles | Identity |
| metadata | Custom metadata | Identity |
| createdBy | Created by user | Identity |
| updatedBy | Updated by user | Identity |
| deletedBy | Deleted by user | Identity |
| createdAt | Creation timestamp | Identity |
| updatedAt | Update timestamp | Identity |
| deletedAt | Deletion timestamp | Identity |


# Pix operations
Source: https://docs.lerian.studio/en/reference/field-dictionary/fd-pix-operations

Reference the Pix dispute and anti-fraud fields aligned with BACEN: key claims, infraction reports, refund requests, and fraud markers.

This page covers fields specific to Pix dispute resolution and anti-fraud operations, including key claims, infraction reports, refund requests, and fraud markers. These fields follow BACEN's regulatory standards.

## 1. Claims

***

| Field | Description | Used in |
| - | - | - |
| claimId | Unique identifier for the key claim | Pix |
| claimType | Type of claim: OWNERSHIP or PORTABILITY | Pix |
| status | Current claim status: OPEN, WAITING\_RESOLUTION, CONFIRMED, CANCELLED, or COMPLETED | Pix |
| claimer | The claiming party as an object. `participant` is required. `document`, `name`, `personType`, `tradeName` and `account` are optional. When present, `account` carries `branch`, `number`, `type` and `openingDate`. | Pix |
| donorParticipant | ISPB of the donor participant (8 digits) | Pix |
| confirmReason | Reason for confirming the claim | Pix |
| cancelReason | Reason for cancelling the claim | Pix |
| cancelledBy | Party that cancelled the claim: DONOR or CLAIMER | Pix |
| resolutionPeriodEnd | Deadline for the counterparty to respond (D+7) | Pix |
| completionPeriodEnd | Deadline for claim completion (D+14) | Pix |

## 2. Infraction reports

***

| Field | Description | Used in |
| - | - | - |
| infractionReportId | Unique identifier for the infraction report | Pix |
| transactionId | SPI transaction identifier (End-to-End ID) | Pix |
| reason | Infraction reason: REFUND\_REQUEST or REFUND\_CANCELLED | Pix |
| situationType | Type of fraud situation (e.g., SCAM, ACCOUNT\_TAKEOVER, COERCION) | Pix |
| reportDetails | Detailed description of the infraction (max 2000 characters) | Pix |
| reporterParticipant | ISPB of the reporting participant (8 digits) | Pix |
| counterpartyParticipant | ISPB of the counterparty (8 digits) | Pix |
| analysisResult | Analysis result: AGREED or DISAGREED | Pix |
| analysisDetails | Detailed analysis comments | Pix |
| status | Current status: OPEN, ACKNOWLEDGED, CLOSED, or CANCELLED | Pix |

## 3. Refund requests

***

| Field | Description | Used in |
| - | - | - |
| refundId | Unique identifier for the refund request | Pix |
| transactionId | Original Pix transaction identifier (End-to-End ID) | Pix |
| amount | Refund amount in BRL | Pix |
| infractionId | Optional. The related infraction report identifier | Pix |
| status | Current refund status: OPEN, CLOSED, or CANCELLED | Pix |
| refundAnalysisResult | Analysis result: TOTALLY\_ACCEPTED, PARTIALLY\_ACCEPTED, or REJECTED | Pix |
| refundAnalysisDetails | Detailed analysis comments | Pix |
| refundRejectionReason | Rejection reason: NO\_BALANCE, ACCOUNT\_CLOSURE, INVALID\_REQUEST, OTHER, or PARTICIPANT\_EXCLUSION on a read | Pix |
| refundTransactionId | End-to-End ID of the refund transaction | Pix |

## 4. Fraud markers

***

| Field | Description | Used in |
| - | - | - |
| fraudMarkerId | Unique identifier for the fraud marker | Pix |
| fraudType | Classification: APPLICATION\_FRAUD, MULE\_ACCOUNT, SCAMMER\_ACCOUNT, OTHER, or UNKNOWN on a read | Pix |
| key | Optional Pix key associated with the fraud | Pix |
| document | CPF or CNPJ of the flagged party | Pix |
| status | Current fraud marker status: REGISTERED or CANCELLED | Pix |


# Tracer
Source: https://docs.lerian.studio/en/reference/field-dictionary/fd-tracer

Reference the Tracer fields used in real-time transaction validation: request payloads, rules, spending limits, and decision responses returned to callers.

This page covers fields specific to Tracer, Lerian's real-time transaction validation engine. These fields appear across validation requests, rules, spending limits, and decision responses.

## 1. Validation requests

***

| Field | Description | Used in |
| - | - | - |
| requestId | Client-generated unique ID for idempotency and audit correlation | Tracer |
| transactionType | Type of transaction: CARD, WIRE, PIX, or CRYPTO | Tracer |
| subType | Transaction subtype for additional context (e.g., debit, credit) | Tracer |
| amount | Transaction amount as a decimal string, for example `"100.00"` (must be positive) | Tracer |
| asset | Asset code of 1 to 100 uppercase letters used by the transaction, for example `BRL` or `USD` | Tracer |
| transactionTimestamp | When the transaction occurred (RFC 3339 format with timezone) | Tracer |

## 2. Validation responses

***

| Field | Description | Used in |
| - | - | - |
| validationId | Server-generated unique identifier for the validation record | Tracer |
| decision | Validation decision: ALLOW, DENY, or REVIEW | Tracer |
| reason | Human-readable reason for the decision | Tracer |
| matchedRuleIds | IDs of the rules that matched. On a `REVIEW` with the reason `rule_evaluation_error`, the matched REVIEW rules and then the rules that failed | Tracer |
| evaluatedRuleIds | IDs of the rules evaluated without an error | Tracer |
| processingTimeMs | Processing time in milliseconds | Tracer |
| totalRulesLoaded | Total number of rules loaded for evaluation | Tracer |
| truncated | Whether Tracer skipped the active rules past the `MAX_RULES_PER_REQUEST` ceiling | Tracer |

## 3. Rules

***

| Field | Description | Used in |
| - | - | - |
| ruleId | Unique identifier for the rule | Tracer |
| name | Human-readable rule name (unique within its context, max 255 characters) | Tracer |
| description | Rule purpose and logic explanation (max 1000 characters) | Tracer |
| expression | CEL expression that must evaluate to boolean (max 5000 characters) | Tracer |
| action | Action taken when the expression evaluates to true: ALLOW, DENY, or REVIEW | Tracer |
| scopes | Array of scopes that determine which transactions this rule applies to | Tracer |
| status | Rule lifecycle status: DRAFT, ACTIVE, INACTIVE, or DELETED | Tracer |

## 4. Spending limits

***

| Field | Description | Used in |
| - | - | - |
| limitId | Unique identifier for the limit | Tracer |
| name | Human-readable limit name (globally unique, max 255 characters) | Tracer |
| description | Limit purpose and usage explanation (max 1000 characters) | Tracer |
| limitType | Type of limit: DAILY, WEEKLY, MONTHLY, CUSTOM, or PER\_TRANSACTION (immutable after creation) | Tracer |
| maxAmount | Maximum decimal amount as a string, for example `"1000.00"` | Tracer |
| asset | Asset code of 1 to 100 uppercase letters for the limit (immutable after creation) | Tracer |
| scopes | Array of scopes that determine which transactions this limit applies to | Tracer |
| status | Limit lifecycle status: DRAFT, ACTIVE, INACTIVE, or DELETED | Tracer |
| activeTimeStart | Start of the daily active window in `HH:mm` format | Tracer |
| activeTimeEnd | End of the daily active window in `HH:mm` format | Tracer |
| customStartDate | Start date-time for CUSTOM limits | Tracer |
| customEndDate | End date-time for CUSTOM limits | Tracer |
| resetTime | Start of each DAILY, WEEKLY, or MONTHLY period in `HH:mm` format, UTC (immutable after creation) | Tracer |

## 5. Limit usage

***

| Field | Description | Used in |
| - | - | - |
| limitAmount | Total limit amount as a decimal string | Tracer |
| exceeded | Whether the limit was exceeded during validation | Tracer |
| period | Limit period type: DAILY, WEEKLY, MONTHLY, CUSTOM, or PER\_TRANSACTION | Tracer |
| scope | Human-readable scope description (e.g., "account:uuid", "segment:uuid") | Tracer |
| attemptedAmount | Transaction amount being validated, as a decimal string | Tracer |

## 6. Scopes and targeting

***

| Field | Description | Used in |
| - | - | - |
| accountId | Account identifier for scope targeting | Tracer |
| segmentId | Segment identifier for scope targeting | Tracer |
| portfolioId | Portfolio identifier for scope targeting | Tracer |
| merchantId | Merchant identifier for scope targeting | Tracer |
| transactionType | Transaction type filter: CARD, WIRE, PIX, or CRYPTO | Tracer |
| category | Merchant Category Code (4-digit MCC per ISO 18245) | Tracer |
| country | Merchant country (ISO 3166-1 alpha-2, 2 uppercase letters) | Tracer |


# Workflows & Reporting
Source: https://docs.lerian.studio/en/reference/field-dictionary/fd-workflows-reporting

Reference selected reporting, workflow, fee, and error fields used across Lerian products.

This page lists selected fields whose contract the owning product documents. Use the product API reference for a complete request or response schema.

## 1. Reporting (Reporter)

***

| Field | Description | Used in |
| - | - | - |
| templateName | Name of the associated template | Reporter |
| templateId | Identifier of the template used to generate the report | Reporter |
| outputFormat | Output format generated from the template (HTML, PDF, CSV, XML, TXT) | Reporter |
| dataSourceId | Data source identifier (e.g., midaz\_onboarding) | Reporter |
| filters | Filter conditions grouped by data source, table, and field | Reporter |
| reportId | Generated report ID | Reporter |

## 2. Workflow identifiers (Flowker)

***

| Field | Description | Used in |
| - | - | - |
| workflowId | Workflow identifier (UUID) | Flowker |
| executionId | Execution identifier (UUID) | Flowker |

## 3. Fees Engine

***

| Field | Description | Used in |
| - | - | - |
| feeGroupLabel | Fee group label | Fee |
| feeLabel | Specific fee label | Fee |
| calculationModel | Fee calculation model | Fee |
| applicationRule | Application rule | Fee |
| calculations | Fee calculation array | Fee |
| referenceAmount | Reference amount | Fee |
| priority | Fee priority | Fee |
| isDeductibleFrom | Whether fee is deductible | Fee |
| creditAccount | Fee credit account | Fee |
| routeFrom | Origin route | Fee |
| routeTo | Destination route | Fee |
| transactionRoute | Transaction route | Fee |
| enable | Fee enabled flag | Fee |

## 4. Error handling

***

| Field | Description | Used in |
| - | - | - |
| error | Error code | Pix, Fee, CRM |
| message | Error message | Pix, Fee, CRM |
| details | Specific error details | Pix, Fee |
| field | Field that caused the error | Pix, Fee |
| path | Endpoint path | Pix |
| code | Standardized error code | Fee, CRM |
| entityType | Entity type | Fee |
| title | Error title | Fee |
| timestamp | Error timestamp | Pix, Fee |


# Health and readiness
Source: https://docs.lerian.studio/en/reference/health-and-readiness

Reference the /health, /readyz, and /version probes, with response shapes and per-service coverage.

This page covers the operational HTTP probes `/health`, `/readyz`, and `/version`. Orchestrators such as Kubernetes use them to decide when a service is alive, when it can receive traffic, and which build it runs. Paths, ports, and response bodies differ per service. See the [per-service coverage table](#per-service-coverage) below.

## The probe endpoints

| Endpoint | Method | Purpose |
| - | - | - |
| `/health` | GET | **Liveness.** Confirms the process is up. |
| `/readyz` | GET | **Readiness.** Confirms the service can receive traffic. |
| `/version` | GET | **Version.** Returns the service version. |

## The `/readyz` response body

`/readyz` returns a JSON document describing overall readiness and each dependency check.

```json theme={null}
{
  "status": "healthy",
  "checks": {
    "postgres": { "status": "up", "latency_ms": 2, "tls": true },
    "redis":    { "status": "skipped", "reason": "not configured" },
    "rabbitmq": { "status": "up", "breaker_state": "closed", "latency_ms": 12 }
  },
  "version": "1.2.3",
  "deployment_mode": "byoc"
}
```

| Field | Meaning |
| - | - |
| `status` | Overall readiness. |
| `checks` | One entry per dependency (Postgres, MongoDB, Redis, RabbitMQ, systemplane, and others). |
| `checks.<dep>.status` | Per-dependency result: `up`, `down`, `degraded`, `skipped`, or `n/a`. |
| `checks.<dep>.latency_ms` | Round-trip probe latency in milliseconds, when measured. |
| `checks.<dep>.tls` | Whether the connection to that dependency uses TLS. |
| `checks.<dep>.breaker_state` | Circuit-breaker state, when a breaker fronts the dependency. |
| `checks.<dep>.error` / `.reason` | Failure detail or the reason a check was skipped. |
| `version` | Running service version. |
| `deployment_mode` | The active [`DEPLOYMENT_MODE`](/en/reference/byoc-configuration#deployment-mode-and-tls). |

Which checks turn the response into HTTP `503`, and whether a `degraded` check does, differs per service.

## Per-service coverage

The table lists default ports and the path deviations.

| Product / service | Main port | Liveness | Readiness | Notes |
| - | - | - | - | - |
| Midaz ledger | 3002 | `/health` | `/readyz` | Also `/version`. No `/metrics` (OTLP push). |
| Reporter (API) | 4005 | `/health` | `/readyz` | `/version`. |
| Reporter (worker) | 4006 | `/health` | `/readyz` | `/version`. Dedicated worker health server. |
| Lender | 8080 | `/health` | `/readyz` | `/version`. Webhook listeners expose `/readyz` only. Systemplane admin API. |
| Access Manager | 4000 (auth), 4001 (identity) | `/health` | `/readyz` | Two servers, each with its own probes and `/version`. `/readyz` also returns `revision` and `buildTime`. |
| Console | 8081 | `/api/admin/health/alive` | `/api/admin/health/readyz` | **Deviation:** probes live under `/api/admin/health/`. |
| Streaming Hub | 8080 | `/healthz` | `/readyz` | **Deviation:** liveness is `/healthz`. Also `/version`, `/metrics`, `/runtime`. The `/readyz` body has `state`, `version`, `ingestAllowed`, and `probes`. |
| Pix (Direct, via JD) | 8080 | `/health` | `/readyz` | `/metrics`, `/version`. Systemplane admin API. |
| Pix (Indirect, via BTG) | 4014 | `/health` | `/readyz` | Multi-component (API plus workers). |
| Pix Lerian | Varies (dedicated component) | Varies | Varies | Systemplane runs as a separate deployable component. See [Pix Lerian environment variables](/en/interfaces/pix-lerian/pix-lerian-environment-variables). |
| TED (via JD) | 4027 | `/health`, `/health/live` | `/readyz`, `/health/ready` | **Deviation:** additionally exposes `/health/live` and `/health/ready`. Systemplane admin API. |
| Boleto and bill payments (via BTG) | 8080 | `/health` | `/readyz` | Multi-component. |
| CCS | 4030 | `/health` | `/readyz` | `/metrics`, `/version`. Systemplane admin API. |
| STA | 4028 | `/health` | `/readyz` | `/metrics`, `/version`. Systemplane admin API. |
| SISBAJUD Mensageria | 4031 | `/health` | `/readyz` | `/version`. Systemplane admin API. The execution API listens on its own TLS port, 4032. |
| SISBAJUD executor | Set `SERVER_ADDRESS` to `:4029` | `/health` | `/readyz` | `/version`. Port 4029 is the port the image exposes. Systemplane admin API. The webhook listener uses its own port, 9082. |
| SLC | 4111 | `/health` | `/readyz` | `/metrics`, `/version`. Systemplane admin API. |
| SPI | 8080 | `/health` | `/readyz` | Systemplane admin API. |
| SPB | 3000 | `/health` | `/readyz` | Systemplane admin API. |
| SILOC | 9820 | `/health` | `/readyz` | — |
| Consignado | 8080 | `/health` | `/readyz` | `/metrics`, `/version`. Systemplane admin API. |
| BC Correios | 9090 | `/health` | `/readyz` | `/version`. |
| SRC | 3006 | `/health` | `/readyz` | `/version`. Systemplane admin API. |

> [!NOTE]
>
> **Ports** are compose/`.env.example` defaults and can be overridden per deployment. See [Default network ports](/en/reference/default-network-ports). `Varies` marks a service whose default port depends on deployment configuration.


# API patterns and tools
Source: https://docs.lerian.studio/en/reference/integration-essentials

API patterns, conventions, and tooling that keep Lerian integrations stable, scalable, and maintainable.

This section covers the API patterns and tools that keep your integrations stable, scalable, and easy to maintain.

## Available pages

***

> **[Retries and idempotency](/en/reference/retries-idempotency)**
>
> Ensure safe retries and prevent duplicate transactions using idempotency keys.

> **[Metadata](/en/reference/metadata)**
>
> Structure and optimize data use with custom metadata fields.

> **[Pagination](/en/reference/pagination)**
>
> Manage large datasets efficiently while keeping performance high.

> **[Tolerant reader](/en/reference/tolerant-reader)**
>
> Build integrations that adapt to changes without breaking.

> **[Default network ports](/en/reference/default-network-ports)**
>
> Check the default ports used by Midaz and the plugins.

> **[Postman integration](/en/reference/postman-integration)**
>
> Import our OpenAPI specifications into Postman to call our APIs.


# Welcome to our API Reference
Source: https://docs.lerian.studio/en/reference/introduction

Explore the Lerian APIs, organized by product and plugin, with the conventions they share.

> [!TIP]
>
> **This section is for developers and technical integrators**. For a business-level overview of what Lerian products do, start with [Who we are](/en/start-here/about-lerian/who-we-are). You can also explore individual product pages like [About Midaz](/en/products/midaz/about-midaz) and [What is Matcher?](/en/products/matcher/what-is-matcher).

This section documents the Lerian APIs, grouped into Products, Brazil Rails, Interfaces, and Platform.

## Product-structured, plugin-aware

***

Each product, like Midaz or Reporter, has its own API section. Plugins, such as the Pix and TED interfaces, have their own sections under Interfaces.

For example, the Midaz reference has APIs for core entities like Ledgers and Transactions. It also covers Fees and CRM, which are part of Midaz.

## Key highlights

***

* **Plugin-first architecture**: Features are modular. Each plugin has its own API set.

## What you'll find here

***

* **Integration Essentials**: Concepts like retries, pagination, metadata, and stability tools.
* **Stability & Quality**: Error handling, testing best practices, QA process, and support coverage.
* **Error Lists**: Each API reference includes a dedicated error code reference.

## How to navigate

***

To access a product's reference:

**Step 1**

You’re already in the **API Reference** section of our documentation.

**Step 2**

Open the dropdown menu in the left sidebar and select the product you’re working with, such as Midaz or Reporter.

**Step 3**

You’ll land in a dedicated space with product-specific API details, full schema references, and real-world payload examples.


# Metadata
Source: https://docs.lerian.studio/en/reference/metadata

Attach custom key-value metadata to Midaz entities so you can extend the standard ledger schema with data specific to your integration and business needs.

**Metadata** lets you enrich entities with user-defined information. You attach custom data as key-value pairs within a metadata object.

## What is metadata?

***

Metadata lets you store supplementary information alongside an entity’s standard data model by adding custom attributes or annotations without altering the entity's predefined schema.

In Midaz, metadata is an object that supports key-value pairs in these data types: strings, integers, floats, and booleans. Keys take **up to 100 bytes** and values **up to 2,000 bytes**.

> [!WARNING]
>
> Metadata does **not** support nested values.

### Example of metadata

Consider an Organization entity as shown below:

```json JSON expandable theme={null}
{
  "id": "cc15194a-6bc9-4ebb-b15d-43411a54ba4b",
  "parentOrganizationId": null,
  "legalName": "Empresa Teste Ltda",
  "doingBusinessAs": "Empresa Teste",
  "legalDocument": "86820799000188",
  "address": {
    "line1": "Rua Botucatu, 10",
    "line2": "Casa B",
    "zipCode": "04023060",
    "city": "São Paulo",
    "state": "SP",
    "country": "BR"
  },
  "metadata": null,
  "status": {
    "code": "ACTIVE",
    "description": null
  },
  "createdAt": "2024-02-08T16:59:31+0300",
  "updatedAt": "2024-02-08T16:59:31+0300",
  "deletedAt": null
}
```

To enrich this organization with additional information, such as industry sector and number of employees, you can include a metadata object in your `POST` or `PATCH` requests:

```json JSON theme={null}
{
  "metadata": {
    "sector": "Fintech",
    "employees": "50-100"
  }
}
```

## Creating entities with metadata

***

When creating an entity, you can submit metadata through our `POST` endpoints and add custom data from the start.

## Updating and removing metadata

***

Our API follows the JSON Merge Patch RFC for metadata updates:

* **Adding or Updating Values**: Submitting a key with a new value in a `PATCH` request updates the existing metadata.
* **Removing Keys**: Sending a key as `null` in a `PATCH` request removes that key-value pair. A key you omit keeps its value.
* **Removing all keys**: Sending `metadata` as `null` in a `PATCH` request removes every key that you set. On a transaction or an operation, the keys that the ledger writes stay.
* **Keeping metadata unchanged**: Sending `metadata` as `{}`, or leaving `metadata` out of the `PATCH` request, keeps the stored metadata.

### Practical example: modifying metadata

Suppose an Organization entity initially included metadata for sector and employee count. To update the employee count while removing the sector, send a `PATCH` request with the following metadata:

```json JSON theme={null}
{
  "metadata": {
    "employees": "100-150",
    "sector": null
  }
}
```

After the request is processed, the sector key will be removed, and the employee count will be updated.


# OpenAPI specifications
Source: https://docs.lerian.studio/en/reference/openapi-specifications

Download the OpenAPI YAML specification for each Lerian API.

Download the current OpenAPI YAML file for each API. Use these files to inspect the contract or configure API development tools.

> [!NOTE]
>
> On any endpoint page, open the page action menu and select **Download API spec** to download all specifications as a ZIP archive.

## Products

***

[**Midaz Ledger API**
`ledger.yaml`
Download YAML ↓](/en/openapi/v3-current/ledger.yaml)
[**Tracer API**
`tracer.yaml`
Download YAML ↓](/en/openapi/v3-current/tracer.yaml)
[**Reporter API**
`reporter.yaml`
Download YAML ↓](/en/openapi/v3-current/reporter.yaml)
[**Matcher API**
`matcher.yaml`
Download YAML ↓](/en/openapi/v3-current/matcher.yaml)
[**Flowker API**
`flowker.yaml`
Download YAML ↓](/en/openapi/v3-current/flowker.yaml)
[**Lender API**
`lender.yaml`
Download YAML ↓](/en/openapi/v3-current/lender.yaml)
[**Streaming Hub API**
`streaming-hub.yaml`
Download YAML ↓](/en/openapi/v3-current/streaming-hub.yaml)

## Brazil Rails and interfaces

***

[**Payments API**
`payments.yaml`
Download YAML ↓](/en/openapi/v3-current/payments.yaml)
[**Pix Lerian DICT API**
`pix-lerian-dict.yaml`
Download YAML ↓](/en/openapi/v3-current/pix-lerian-dict.yaml)
[**Pix Lerian Collections API**
`pix-lerian-cob.yaml`
Download YAML ↓](/en/openapi/v3-current/pix-lerian-cob.yaml)
[**Pix Lerian Payments API**
`pix-lerian-spi.yaml`
Download YAML ↓](/en/openapi/v3-current/pix-lerian-spi.yaml)
[**Pix Lerian Pix Automático API**
`pix-lerian-pixauto.yaml`
Download YAML ↓](/en/openapi/v3-current/pix-lerian-pixauto.yaml)
[**Pix Direct API**
`pix.yaml`
Download YAML ↓](/en/openapi/v3-current/pix.yaml)
[**Pix Indirect API**
`indirect-pix.yaml`
Download YAML ↓](/en/openapi/v3-current/indirect-pix.yaml)
[**SPI API**
`spi.yaml`
Download YAML ↓](/en/openapi/v3-current/spi.yaml)
[**SPI Core API**
`spi-core.yaml`
Download YAML ↓](/en/openapi/v3-current/spi-core.yaml)
[**SPI DICT API**
`spi-dict.yaml`
Download YAML ↓](/en/openapi/v3-current/spi-dict.yaml)
[**SPI BR Code API**
`spi-brcode.yaml`
Download YAML ↓](/en/openapi/v3-current/spi-brcode.yaml)
[**SPB API**
`spb.yaml`
Download YAML ↓](/en/openapi/v3-current/spb.yaml)
[**TED API**
`ted.yaml`
Download YAML ↓](/en/openapi/v3-current/ted.yaml)
[**JD Courier API**
`jd-courier.yaml`
Download YAML ↓](/en/openapi/v3-current/jd-courier.yaml)
[**Consignado API**
`consignado.yaml`
Download YAML ↓](/en/openapi/v3-current/consignado.yaml)
[**BC Correios API**
`bc-correios.yaml`
Download YAML ↓](/en/openapi/v3-current/bc-correios.yaml)
[**SRC API**
`src.yaml`
Download YAML ↓](/en/openapi/v3-current/src.yaml)
[**SISBAJUD Mensageria API**
`sisbajud-mensageria.yaml`
Download YAML ↓](/en/openapi/v3-current/sisbajud-mensageria.yaml)
[**SISBAJUD executor API**
`sisbajud-executor.yaml`
Download YAML ↓](/en/openapi/v3-current/sisbajud-executor.yaml)
[**SILOC API**
`siloc.yaml`
Download YAML ↓](/en/openapi/v3-current/siloc.yaml)
[**SLC API**
`slc.yaml`
Download YAML ↓](/en/openapi/v3-current/slc.yaml)
[**STA API**
`sta.yaml`
Download YAML ↓](/en/openapi/v3-current/sta.yaml)

## Platform

***

[**Access Manager Auth API**
`AM-auth.yaml`
Download YAML ↓](/en/openapi/v3-current/AM-auth.yaml)
[**Access Manager Identity API**
`AM-identity.yaml`
Download YAML ↓](/en/openapi/v3-current/AM-identity.yaml)
[**Narya Host API**
`narya.yaml`
Download YAML ↓](/en/openapi/v3-current/narya.yaml)
[**System Facts API**
`system-facts.yaml`
Download YAML ↓](/en/openapi/v3-current/system-facts.yaml)
[**Systemplane Admin API**
`systemplane.yaml`
Download YAML ↓](/en/openapi/v3-current/systemplane.yaml)


# Pagination
Source: https://docs.lerian.studio/en/reference/pagination

Page-based and cursor-based pagination on Midaz list endpoints: query parameters, response payloads, and the page-size limit.

Midaz list endpoints deliver data in smaller, manageable portions. This improves response times and client-side processing, particularly for applications that load results incrementally. Other Lerian APIs set their own pagination parameters, defaults, and limits. Check each API's reference.

## Page-based pagination

***

Instead of returning the entire dataset in a single response, which can strain resources, clients can request specific subsets of data.

Page-based endpoints accept two query parameters:

* `page` (integer): Specifies the page number to retrieve. The default value is `1`.
  * Values below `1` return an error.
* `limit` (integer): Defines the maximum number of items per page. The default value is `10`.

For example, to retrieve the first page of organizations with a maximum of 10 items per page:

```http HTTP theme={null}
GET /v1/organizations?page=1&limit=10
```

### Pagination response

The pagination response includes the following structure:

* `items`: An array of entities retrieved for the current page. Each object contains detailed information about the resource requested, as shown in the example below.
* `page`: The current page number, starting from `1` (default).
* `limit`: The maximum number of items included in the response, as defined in the request or default configuration.

Below is an example response for a paginated request:

```json JSON expandable theme={null}
{
    "items": [
        {
            "id": "0193696f-8eff-7926-a77a-0b424cf7156b",
            "parentOrganizationId": null,
            "legalName": "Collins Inc",
            "doingBusinessAs": "The ledger.io",
            "legalDocument": "78425230000190",
            "address": {
                "line1": "Avenida Paulista, 1234",
                "line2": "CJ 203",
                "zipCode": "01310916",
                "city": "New Lyla",
                "state": "CH",
                "country": "FO"
            },
            "status": {
                "code": "ACTIVE",
                "description": "Ledger Test"
            },
            "createdAt": "2024-11-26T17:05:39.071587Z",
            "updatedAt": "2024-11-26T17:05:39.071587Z",
            "deletedAt": null,
            "metadata": {
                "bitcoinn": "3QH2XV7JxMRKXDqh87JG7LWuf7AeGfy",
                "boolean": true,
                "chave": "metadata_chave",
                "double": 10.5,
                "int": 1
            }
        }
    ],
    "page": 1,
    "limit": 1
}
```

### Maximum page size

By default, Midaz accepts a maximum of **100 items per page** (`limit=100`). This restriction avoids excessive payload sizes.

If your use case requires retrieving a larger number of items per request, you can override this limit by setting the `MAX_PAGINATION_LIMIT` environment variable in your deployment configuration ( `.env` file). Billing package lists keep the 100 maximum.

> [!WARNING]
>
> Increasing the pagination limit may result in slower response times depending on the volume of data and infrastructure conditions. Be sure to test thoroughly in staging environments before applying the change in production.

After you change it, restart the Ledger. To set it on a Midaz deployment, see the [Midaz chart README](https://github.com/LerianStudio/helm/tree/main/charts/midaz).

## Cursor-based pagination

***

Some endpoints use cursor-based pagination instead of page numbers. This approach is more efficient for large or frequently changing datasets.

Cursor-based endpoints accept the following query parameters:

* `cursor` (string): An encoded token from a previous response (`next_cursor` or `prev_cursor`) to navigate forward or backward. Omit this parameter to start from the beginning.
* `limit` (integer): The maximum number of items per page.
* `sort_order` (string): The direction used to sort results. Accepted values: `asc` (ascending) or `desc` (descending).

> [!NOTE]
>
> Set `sort_order` on the initial request and keep it unchanged while you follow the cursors.

For example, to retrieve balances using cursor pagination:

```http HTTP theme={null}
GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/balances?limit=10
```

### Cursor pagination response

The response includes the following structure:

* `items`: An array of entities for the current page.
* `next_cursor`: An encoded token to retrieve the next page. If absent or empty, there are no more results.
* `prev_cursor`: An encoded token to retrieve the previous page. If absent or empty, you are on the first page.
* `limit`: The maximum number of items included in the response.

To navigate to the next page, pass the `next_cursor` value as the `cursor` query parameter:

```http HTTP theme={null}
GET /v1/organizations/{organization_id}/ledgers/{ledger_id}/balances?cursor=eyJpZCI6IjAxOTNiN...&limit=10
```

Below is an example response for a cursor-paginated request:

```json JSON theme={null}
{
    "items": [
        {
            "id": "019c96a0-0c0d-7915-84b9-e497bfee9916",
            "organizationId": "019c96a0-0a98-7287-9a31-786e0809c769",
            "ledgerId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
            "accountId": "019c96a0-0c0c-7221-8cf3-13313fb60081",
            "alias": "customer-brl-1",
            "key": "default",
            "assetCode": "BRL",
            "available": "1000",
            "onHold": "0"
        }
    ],
    "next_cursor": "eyJpZCI6IjAxOTNiNTZmLWJhY2YtNzQ0MS05NDU4LTEyZTE5MjVlOGI4NCIsInBvaW50c19uZXh0Ijp0cnVlfQ==",
    "prev_cursor": "eyJpZCI6IjAxOTNiNTZmLWJhY2YtNzQ0MS05NDU4LTEyZTE5MjVlOGI4NCIsInBvaW50c19uZXh0IjpmYWxzZX0=",
    "limit": 10
}
```

### Which endpoints use cursor pagination?

Each endpoint's API reference shows whether it takes `page` or `cursor`.


# Postman integration
Source: https://docs.lerian.studio/en/reference/postman-integration

Import a Lerian OpenAPI specification into Postman and run authenticated requests against your API instance to test endpoints and speed up integration work.

Postman is a quick way to get hands-on with our APIs. You can test requests, receive real responses, and explore how the APIs fit together.

Postman builds a collection from a Lerian OpenAPI YAML file. Download the file for your API from [OpenAPI specifications](/en/reference/openapi-specifications).

> [!TIP]
>
> To learn more about importing collections, check the [Postman’s documentation](https://learning.postman.com/docs/getting-started/importing-and-exporting/importing-data/) .

## Importing the Postman collection

***

To import the Postman collection, follow these steps:

**Step 1**

Open Postman.

**Step 2**

Click **"Import"** in the top-left corner.

**Step 3**

In the **Import** modal, select the **"File"** tab.

**Step 4**

Click **"Choose Files"**, then select the OpenAPI YAML file you downloaded.

**Step 5**

Postman will process the file and add the collection to **"Collections"** in your workspace.

**Step 6**

Open the collection and check that Postman imported all API requests and folders.

## Tokens and authentication

***

For the [**Enterprise model**](/en/products/midaz/what-is-midaz), you can enable authentication and token management using [Access Manager](/en/platform/access-manager).

> [!TIP]
>
> Access Manager is available as a part of the Enterprise model. If you'd like to learn more or evaluate it for your use case, [get in touch with our team](https://lerian.studio/contact).


# Quick start guide
Source: https://docs.lerian.studio/en/reference/products/midaz/quick-start-guide

Set up Midaz for the first time, from environment installation and configuration to creating your first ledger structure.

> [!TIP]
>
> **This guide is intended for developers** setting up Midaz for the first time. If you're looking for a business-level overview of how Midaz works, see [What is Midaz?](/en/products/midaz/what-is-midaz). For deployment options, see [SaaS and BYOC](/en/start-here/evaluate-and-deploy/deployment-models).

Follow these steps to set up Midaz.

## Step 1 - Set up your environment

***

To set up your Midaz environment, follow the steps in the [Installing Midaz monorepo](/en/products/midaz/midaz-setup) page.

* This will install Midaz Ledger.

### Authentication and authorization

Midaz does not include a built-in authentication or authorization system. You can integrate Midaz with your existing identity provider or security stack.

If you need a ready-to-use solution, you can enable **Access Manager**, an optional feature developed by Lerian. It handles authentication and authorization for Midaz and other Lerian products.

> [!TIP]
>
> Access Manager supports common identity standards like OAuth2 and OIDC. For more details, refer to the [Access Manager](/en/platform/access-manager) guide.

## Step 2 - Create your Midaz structure

***

Start by creating the data structure that your workflows use.

### Step 2.1 - Create an Organization

The first step is to create your Organization within Midaz.

* [**To create an Organization, use the Create an Organization endpoint.**](/en/reference/products/midaz/v2/create-organization)

> [!TIP]
>
> If your organization has multiple branches, you can create various Organizations and designate a **Parent Organization**.
>
> For example, if Company XYZ has branches in New York and Brazil, you can create an Organization for Company XYZ and set it as the parent of XYZ New York and XYZ Brazil.

For a complete list of endpoints to manage your Organization, expand the section below:

> **Managing Organizations**
>
> * Retrieve all Organizations using the [List Organizations](/en/reference/products/midaz/v2/list-organizations) endpoint.
> * Retrieve a specific Organization with the [Retrieve an Organization](/en/reference/products/midaz/v2/get-organization-by-id)
> * Update Organization details using the [Update an Organization](/en/reference/products/midaz/v2/update-organization) endpoint.
> * Delete an Organization in Homologation using the [Delete an Organization](/en/reference/products/midaz/v2/delete-organization) endpoint.
>   * For Organizations in Production, deletion requires contacting Lerian support for security purposes.

### Step 2.2 - Create a Ledger

Create at least one Ledger in each Organization. You can create multiple Ledgers if needed.

* [**To create a Ledger, use the Create a Ledger endpoint.**](/en/reference/products/midaz/v2/create-ledger)

For a complete list of endpoints to manage your Ledger, expand the section below:

> **Managing Ledgers**
>
> * Retrieve all Ledgers using the [List Ledgers](/en/reference/products/midaz/v2/list-ledgers) endpoint.
> * Retrieve a specific Ledger with the [Retrieve a Ledger](/en/reference/products/midaz/v2/get-ledger-by-id) endpoint.
> * Update Ledger details using the [Update a Ledger](/en/reference/products/midaz/v2/update-ledger) endpoint.
> * Delete a Ledger in Homologation using the [Delete a Ledger](/en/reference/products/midaz/v2/delete-ledger) endpoint.
>   * For Ledgers in Production, deletion requires contacting Lerian support for security purposes.

### Step 2.3 - Create the Assets

Each Ledger can have multiple Assets. Create each Asset individually.

* [**To create an Asset, use the Create an Asset endpoint.**](/en/reference/products/midaz/v2/create-asset)

> [!TIP]
>
> When you create an Asset, Midaz automatically sets up an External Account if one doesn’t already exist. The External Account backs all transactions that flow in and out of the Ledger.

For a complete list of endpoints to manage your Assets, expand the section below:

> **Managing Assets**
>
> * Retrieve all Assets using the [List Assets](/en/reference/products/midaz/v2/list-assets) endpoint.
> * Retrieve a specific Asset with the [Retrieve an Asset](/en/reference/products/midaz/v2/get-asset-by-id) endpoint.
> * Update Asset details using the [Update an Asset](/en/reference/products/midaz/v2/update-asset) endpoint.
> * Delete an Asset with the [Delete an Asset](/en/reference/products/midaz/v2/delete-asset) endpoint.

### Step 2.4 - Create a Segment (optional)

If you want, you can use the **Segment ID** as a custom grouping label that clusters accounts according to user-defined policies.

* [**To create a Segment, use the Create a Segment endpoint.**](/en/reference/products/midaz/v2/create-segment)

For a complete list of endpoints to manage your Segment, expand the section below:

> **Managing Segment**
>
> * Retrieve all Segments using the [List Segments](/en/reference/products/midaz/v2/list-segments) endpoint.
> * Retrieve a specific Segment with the [Retrieve a Segment](/en/reference/products/midaz/v2/get-segment-by-id) endpoint.
> * Update Segment details using the [Update a Segment](/en/reference/products/midaz/v2/update-segment) endpoint.
> * Delete a Segment using the [Delete a Segment](/en/reference/products/midaz/v2/delete-segment) endpoint.

### Step 2.5 - Create a Portfolio (optional)

Create a Portfolio to group your accounts of different Assets.

* [**To create a Portfolio, use the Create a Portfolio endpoint.**](/en/reference/products/midaz/v2/create-portfolio)

For a complete list of endpoints to manage your Portfolios, expand the section below:

> **Managing Portfolios**
>
> * Retrieve all Portfolios using the [List Portfolios](/en/reference/products/midaz/v2/list-portfolios) endpoint.
> * Retrieve a specific Portfolio with the [Retrieve a Portfolio](/en/reference/products/midaz/v2/get-portfolio-by-id) endpoint.
> * Update Portfolio details using the [Update a Portfolio](/en/reference/products/midaz/v2/update-portfolio) endpoint.
> * Delete a Portfolio with the [Delete a Portfolio](/en/reference/products/midaz/v2/delete-portfolio) endpoint.

### Step 2.6 - Create the Accounts

You can now add the accounts related to the Assets you want to use with the Ledger. Each Account holds one Asset.

* [**To create an account, use the Create an Account endpoint.**](/en/reference/products/midaz/v2/create-account)

For a complete list of endpoints to manage your Accounts, expand the section below:

> **Managing Accounts**
>
> * Retrieve all Accounts using the [List Accounts](/en/reference/products/midaz/v2/list-accounts) endpoint.
> * Retrieve a specific Account with the [Retrieve an Account](/en/reference/products/midaz/v2/get-account-by-id) endpoint.
> * Update Account details using the [Update an Account](/en/reference/products/midaz/v2/update-account) endpoint.
> * Delete an Account with the [Delete an Account](/en/reference/products/midaz/v2/delete-account) endpoint.

## Step 3 - Explore our APIs

***

See the [API reference](/en/reference/introduction) to learn more about Midaz, from metadata handling to idempotency.

## Need help?

***

* Explore our [Documentation hub](/en/start-here/welcome-to-our-guides) for in-depth guides and resources.

* Join the [Discord community](https://discord.gg/DnhqKwkGv3).

* [Contact our support team](https://lerian.studio/support) for personalized assistance.


# Close an account
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/close-account

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/close
Closes an account whose balances are all exactly zero and whose funds no pending transaction still holds, preserving its history and refusing every later movement. The command takes no body and the closing instant is read back as the account's closedAt, which every account read then exposes. An external account is never eligible (0074), balances that are not exactly zero (0523), a pending transaction still holding the account's funds (0524), a balance that still owes pending fees (0527) and a balance that other balances still owe pending fees to (0528) are refused with 422. An account already closed (0521), an account whose closing is already in progress (0522), an account held by another operation such as transactions loading its balances or a balance creation or deletion (0526) and an account whose accounting persistence is still settling (0518) are refused with 409, the last two of which may be retried later. An indeterminate protection or an unavailable dependency answers 503 (0520). Once the account is closed, any movement that would touch it is refused with 0519, including the commit of a pending transaction that names it as destination.



# Create a new account
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-account

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts
The closing instant is output only: a body naming closedAt or closed_at at its root is refused with 400 whatever the value it carries, and the stored instant is only ever written by the close command.



# Create single-use account block exceptions
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-account-block-exceptions

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/block-exceptions
Creates a batch of single-use exceptions that authorize a debit of an exact amount out of a blocked account. Each exception is returned with its identifier and its expiry, lives only in the cache, and dies on first use or when its TTL elapses.



# Create a new account type
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-account-type

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/ledgers/{ledger_id}/account-types



# Create Additional Balance
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-additional-balance

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/balances



# Create a new asset
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-asset

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/ledgers/{ledger_id}/assets



# Create a new ledger
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-ledger

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/ledgers



# Create Operation Route
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-operation-route

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/ledgers/{ledger_id}/operation-routes



# Create a new organization
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-organization

/en/openapi/v3-current/ledger.yaml post /v2/organizations



# Delete an account
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/delete-account

/en/openapi/v3-current/ledger.yaml delete /v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{id}
Deletes an account together with its balances. A balance that still owes pending fees (0527) or that other balances still owe pending fees to (0528) is refused with 422. A state that cannot be established answers 503 (0520) and may be retried.



# Delete an account type
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/delete-account-type

/en/openapi/v3-current/ledger.yaml delete /v2/organizations/{organization_id}/ledgers/{ledger_id}/account-types/{id}



# Delete an asset
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/delete-asset

/en/openapi/v3-current/ledger.yaml delete /v2/organizations/{organization_id}/ledgers/{ledger_id}/assets/{id}



# Delete Balance by account
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/delete-balance

/en/openapi/v3-current/ledger.yaml delete /v2/organizations/{organization_id}/ledgers/{ledger_id}/balances/{balance_id}
Deletes a balance. A balance that still owes pending fees (0527) or that other balances still owe pending fees to (0528) is refused with 422. A state that cannot be established answers 503 (0520) and may be retried.



# Delete a ledger
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/delete-ledger

/en/openapi/v3-current/ledger.yaml delete /v2/organizations/{organization_id}/ledgers/{ledger_id}



# Delete an organization
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/delete-organization

/en/openapi/v3-current/ledger.yaml delete /v2/organizations/{id}



# Get Account Balances history at date
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-account-balances-at-timestamp

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/balances/history



# Retrieve an account by alias
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-account-by-alias

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/alias/{alias}



# Retrieve a specific account
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-account-by-id

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{id}



# Retrieve an account by external code
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-account-external-by-code

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/external/{code}



# Retrieve a specific account type
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-account-type-by-id

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/account-types/{id}



# Get all balances
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-all-balances

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/balances



# Get all balances by account id
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-all-balances-by-account-id

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/balances



# Get all Operations by account
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-all-operations-by-account

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/operations



# Retrieve a specific asset
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-asset-by-id

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/assets/{id}



# Get Balance history at date
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-balance-at-timestamp

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/balances/{balance_id}/history



# Get Balance by id
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-balance-by-id

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/balances/{balance_id}



# Get Balances using Alias
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-balances-by-alias

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/alias/{alias}/balances



# Get External balances using code
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-balances-external-by-code

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/external/{code}/balances



# Get ledger current position per asset
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-dashboard-assets

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/dashboard/assets
Returns the ledger's CURRENT position in each asset — how many distinct accounts hold it, and the summed available and on-hold figures — read from the balance table. It takes NO window and ignores any window parameter a caller sends: a balance is a running total, not an aggregate over history. Amounts are exact decimal strings, per asset, never summed across assets.



# Get ledger dashboard metrics
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-dashboard-metrics

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/dashboard/metrics
Returns, for the window, the total number of transactions, the count of each status the ledger knows, and the settled volume per asset. Volume sums transaction.amount over SETTLED transactions only — status APPROVED, the only status whose transactions moved money — and is reported PER ASSET with no cross-asset total, because adding two assets together does not produce money. Amounts are exact decimal strings whose scale is not normative; format them with the asset's own exponent and never parse them as a binary float. volumeByAsset is the GROSS settled amount: every settled leg inside the window, reversal legs included. reversalsByAsset is the part of it made of reversal legs, same window and same settled filter. A true net is NOT derivable from the two alone, because it depends on whether each reversed original also falls inside the window; a consumer that needs net reads the transactions.



# Get ledger dashboard volume series
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-dashboard-volume

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/dashboard/volume
Returns one point per UTC calendar day the window TOUCHES, including days with no transactions, which are present with transactions 0 and an empty byAsset. A window is half-open and snaps to the minute rather than to midnight, so a 7d window opened mid-afternoon returns EIGHT points. Each point's transactions counts every status; its byAsset applies the same settled rule as /metrics. Summing the points reproduces /metrics exactly, and is likewise GROSS of reversals.



# Retrieve a specific ledger
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-ledger-by-id

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}



# Get Operation
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-operation-by-account

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{account_id}/operations/{operation_id}



# Retrieve a specific organization
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-organization-by-id

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{id}



# List all account types
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/list-account-types

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/account-types



# List all accounts
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/list-accounts

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts



# List all assets
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/list-assets

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/assets



# List all ledgers
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/list-ledgers

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers



# Retrieve all operation routes
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/list-operation-routes

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/operation-routes



# List all organizations
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/list-organizations

/en/openapi/v3-current/ledger.yaml get /v2/organizations



# Update an account
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/update-account

/en/openapi/v3-current/ledger.yaml patch /v2/organizations/{organization_id}/ledgers/{ledger_id}/accounts/{id}
The closing instant is output only: a body naming closedAt or closed_at at its root is refused with 400 whatever the value it carries, and the stored instant is only ever written by the close command.



# Update an account type
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/update-account-type

/en/openapi/v3-current/ledger.yaml patch /v2/organizations/{organization_id}/ledgers/{ledger_id}/account-types/{id}



# Update an asset
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/update-asset

/en/openapi/v3-current/ledger.yaml patch /v2/organizations/{organization_id}/ledgers/{ledger_id}/assets/{id}



# Update Balance
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/update-balance

/en/openapi/v3-current/ledger.yaml patch /v2/organizations/{organization_id}/ledgers/{ledger_id}/balances/{balance_id}



# Update an existing ledger
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/update-ledger

/en/openapi/v3-current/ledger.yaml patch /v2/organizations/{organization_id}/ledgers/{ledger_id}



# Update an existing organization
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/update-organization

/en/openapi/v3-current/ledger.yaml patch /v2/organizations/{id}



# Retries and idempotency
Source: https://docs.lerian.studio/en/reference/retries-idempotency

Use idempotency keys to prevent duplicate operations on Midaz transaction endpoints when retrying transient failures, network timeouts, and 5xx responses.

This page explains how Midaz protects against duplication with **idempotency keys**, and how to use them when you retry a request.

### Making retries safe

Failed API requests are common. A network timeout occurs, or your service goes down right after it sends a request. Retrying is natural, and you need to be sure Midaz will not process the same operation twice.

By attaching a unique key to each request, you’re telling Midaz: "This is the same operation. If you’ve already processed it, don’t do it again."

Midaz stores this key temporarily and uses it to determine whether the request is new, complete, or still in progress. This protects your system from duplicates.

## Idempotency in Midaz

***

The `X-Idempotency` header is available on every transaction create endpoint: in `/v1`, `json`, `inflow`, `outflow`, `annotation`, `block`, and `unblock`; in `/v2`, `direct`, `hold`, `block`, `unblock`, and `batch`. Revert takes no key of its own: Midaz derives one.

> [!NOTE]
>
> Other Lerian APIs use their own idempotency headers, or none. This page focuses on idempotency for the Midaz Ledger API.

> [!NOTE]
>
> The `commit` and `cancel` transaction endpoints use a Redis-based lock to prevent concurrent processing of the same transaction, but they do not support full idempotency (no cached responses or `X-Idempotency-Replayed` header).

To use it, your request can include two headers:

* `X-Idempotency`: the unique key that identifies the request.
* `X-TTL`: the time-to-live (in seconds) that Midaz should store this key in cache.

> [!NOTE]
>
> If you don’t send the `X-Idempotency` header, Midaz automatically generates one by computing a SHA-256 hash of the request body. Midaz therefore deduplicates identical request bodies sent to the same organization and ledger.

Here’s what happens:

1. When a new key arrives, Midaz marks it as `pending`, processes the request, and stores the full response in cache.
2. If you send the same key again within the TTL window:
   1. While the operation runs, Midaz returns a `409 Conflict` (error code `0084`).
   2. If it’s done and the request matches, Midaz returns the exact same response with a `201 Created` status code and `X-Idempotency-Replayed: true`.
3. If the transaction fails due to validation or insufficient balance errors, Midaz deletes the idempotency key. You can then fix the issue and retry with the same key.

Midaz scopes idempotency keys by organization and ledger. You can therefore use the same key value independently across different organizations or ledgers without conflict.

### Workflow summary

*Figure 1* shows the full lifecycle of an idempotent request:

![Full lifecycle of an idempotent request in Midaz, from receiving the idempotency key to returning the cached or newly processed response](https://mintcdn.com/lerian-49cb71fc/a5129LsdHp16c4y9/images/en/d2/idempotency.svg?fit=max\&auto=format\&n=a5129LsdHp16c4y9\&q=85\&s=1dd0d057ed68d00bbaae45b2def41d4d)

Figure 1. Idempotent request lifecycle in Midaz.

**How it works:**

* If the request doesn’t include an existing idempotency key, Midaz creates a new one, or auto-generates one from the request body hash. Midaz then processes the request, stores the response, and returns it with `X-Idempotency-Replayed: false`.
* If the key already exists:
  * While the operation runs, Midaz returns a `409 Conflict`.
  * If the operation is complete and the request matches, Midaz skips execution and returns the cached response with a `201 Created` status code and `X-Idempotency-Replayed: true`.
* If the original request failed due to validation or balance errors, Midaz deletes the key automatically. You can safely retry with the same key.

### Example request

Here’s how to send an idempotent request to create a transaction:

```http HTTP theme={null}
POST /v1/organizations/{organization_id}/ledgers/{ledger_id}/transactions/json HTTP/1.1
X-Idempotency: 7fb8e1d098cd4730bb932d038b3b8651
X-TTL: 60
Content-Type: application/json

{
  "description": "Monthly subscription payment",
  "code": "SUB-2025-001",
  "send": {
    "asset": "USD",
    "value": "1500",
    "source": {
      "from": [
        {
          "accountAlias": "customer-usd-1",
          "amount": {
            "asset": "USD",
            "value": "1500"
          }
        }
      ]
    },
    "distribute": {
      "to": [
        {
          "accountAlias": "merchant-usd-1",
          "amount": {
            "asset": "USD",
            "value": "1500"
          }
        }
      ]
    }
  }
}
```

If the request succeeds and you send it again within 60 seconds, Midaz will return the cached result with:

```http HTTP theme={null}
HTTP/1.1 201 Created
X-Idempotency-Replayed: true
```

If you send it again while Midaz still processes the original, you’ll receive:

```http HTTP theme={null}
HTTP/1.1 409 Conflict
```

## Key generation

***

You can provide your own `X-Idempotency` key or let Midaz generate one automatically.

### Automatic key generation

If you omit the `X-Idempotency` header, Midaz computes a SHA-256 hash of the request body and uses it as the idempotency key. Midaz therefore deduplicates the exact same JSON body sent to the same organization and ledger.

This is sufficient for most retry scenarios where the request body doesn’t change between attempts.

### Custom key generation

Use a custom key when you need to:

* Correlate the idempotency key with an ID in your own system (e.g., an order ID).
* Retry with a modified request body while still deduplicating (e.g., after correcting a field).
* Control the key format for logging or auditing purposes.

The key should be deterministic: if you retry the same logical operation, the key remains the same. A common approach is to use a UUID or a hash based on your internal reference:

```python Python theme={null}
import uuid

# Option 1: Use an existing business ID as the key
idempotency_key = f"order-{order_id}"

# Option 2: Generate a UUID and store it for retries
idempotency_key = str(uuid.uuid4())
```

## Best practices

***

### Always validate the `X-Idempotency-Replayed` header

When your system receives a response from a transaction endpoint, always check the `X-Idempotency-Replayed` response header before processing the result. This header tells you whether the response is from a new operation or a cached replay:

* `X-Idempotency-Replayed: false`: This is a fresh response. Midaz just processed the transaction.
* `X-Idempotency-Replayed: true`: This response comes from cache. Midaz already processed the transaction.

> [!WARNING]
>
> Failing to check this header is a common integration mistake. Without it, your system may interpret a replayed response as a new transaction. That creates duplicate processing on your side, even though Midaz only executed it once.

For example, if your system settles boletos (bank slips) based on transaction responses, you must verify `X-Idempotency-Replayed` to avoid settling the same boleto twice.

### Use explicit idempotency keys for critical flows

While Midaz auto-generates keys from the request body, for critical financial flows (settlements, payouts, transfers), always provide an explicit `X-Idempotency` key tied to your business process ID. This gives you:

* After the first request succeeds, a retry with a changed body within the TTL window gets `409` (`0084`) instead of a second transaction.
* A clear audit trail linking Midaz transactions to your internal operations.
* Protection against edge cases where request serialization might differ.

### Set appropriate TTL values

Choose TTL values that match your retry window:

* For synchronous operations with fast retries: **60–120 seconds**.
* For asynchronous workflows with potential delays: **300–600 seconds**.
* For batch processing with long retry windows: consider longer TTLs and explicit keys.

## Retry strategy

***

Use these patterns for different failure scenarios:

### Retryable failures

These failures are safe to retry with the same idempotency key:

| Scenario | What to do |
| - | - |
| Network timeout or connection error | Retry with the same key and body. If the original request was processed, you'll get the cached response. |
| `5xx` server error | Retry with exponential backoff. The server may be temporarily overloaded. |
| `409 Conflict` (`0084`), same body | No response is stored under the key yet. Retry after a short delay. |
| Validation or balance error | Fix the issue in your request, then retry with the same idempotency key (Midaz deletes the key on these failures). |

### Non-retryable failures

These failures require a different approach:

| Scenario | What to do |
| - | - |
| `400 Bad Request` (schema error) | Fix the request format. Do not retry the same payload. |
| `401 Unauthorized` / `403 Forbidden` | Check your authentication credentials. Retrying won't help. |
| `404 Not Found` | Verify the organization, ledger, or account IDs in your request path. |

### Exponential backoff

For transient errors, use exponential backoff with jitter to avoid overwhelming the server.

## Preventing entity duplication

***

For some endpoints, you don’t need idempotency keys to avoid duplication. Midaz enforces **uniqueness constraints** on critical resources. If you attempt to create an entity that conflicts with an existing one, the system blocks the request and returns a `409 Conflict` with a descriptive error:

| Resource | Unique field | Error code |
| - | - | - |
| Ledger | Name (within organization) | `0002` |
| Asset | Name or code (within ledger) | `0003` |
| Segment | Name (within ledger) | `0015` |
| Account | Alias (within organization and ledger) | `0020` |
| Account Type | Key value (within organization and ledger) | `0108` |

Unlike idempotency keys, these constraints are permanent and don’t expire.

## Idempotency across Lerian products

***

Other Lerian APIs set their own idempotency headers, scopes, and replay signals, and some accept no idempotency header. Check the API reference of the product you call before you retry a command.

## FAQ

***

> **What happens if I don’t send an idempotency key?**
>
> Midaz automatically generates one by computing a SHA-256 hash of the request body. Midaz therefore deduplicates identical request bodies sent to the same organization and ledger. You only need to provide a custom key if you want to control deduplication independently from the request body.

> **Can I reuse a key across different organizations or ledgers?**
>
> Yes. Midaz scopes idempotency keys per organization and ledger. The same key value used in different organizations or ledgers won’t conflict. However, within the same organization and ledger, each key must be unique per operation.

> **Can I reuse a key across different endpoints?**
>
> No. Use a unique key for each distinct operation.

> **What happens if I change the TTL on a retry?**
>
> Midaz uses only the TTL from the first request. Changing it later has no effect.

> **Will the replayed response always be identical?**
>
> Yes. Midaz replays the full response, including status code (`201 Created`) and body, for completed requests.

> **What’s the default TTL if I don’t send X-TTL?**
>
> The default window is 300 seconds (5 minutes).

> **What happens if the original request fails?**
>
> If the transaction fails due to validation errors or insufficient balance, Midaz deletes the idempotency key from cache. You can then fix the issue and retry with the same key.


# Reliability and support
Source: https://docs.lerian.studio/en/reference/stability-quality

Error handling, testing practices, and support channels that keep Lerian integrations stable across releases.

This section covers how to handle errors, validate quality, and get support when a problem happens.

## Available pages

***

> **[Error handling](/en/reference/error-handling)**
>
> Learn how Lerian services communicate errors and how to design resilient integrations.

> **[Testing and quality assurance](/en/reference/testing-quality-assurance)**
>
> Explore recommended testing strategies, tools, and validation flows.

> **[Troubleshooting and support](/en/reference/troubleshooting-support)**
>
> Diagnose issues, review logs, and reach out to our support team.


# Testing and quality assurance
Source: https://docs.lerian.studio/en/reference/testing-quality-assurance

Unit and integration test policies, plus the CI checks and quality gates that guard every code change in the Midaz codebase before it reaches production.

We use both unit and integration tests throughout the Midaz codebase. They check that each component functions correctly and integrates with the others.

This page covers the testing process and the policy that requires unit tests for every new feature.

## Running tests

***

To execute the tests, use the following command in your terminal:

```bash command theme={null}
make test
```

This command runs the predefined test suite.

## Continuous integration

***

* **GitHub actions**: GitHub Actions runs our tests automatically as part of our continuous integration pipeline. The pipeline checks that all code commits meet our quality standards before they merge.

## Unit testing policy

***

* **New features**: Any new feature introduced in Midaz must include corresponding unit tests. These tests help confirm that new code does not harm existing functionality.
* **Test coverage**: We aim for broad test coverage as a benchmark for software quality.

## Test outputs

***

* **Terminal outputs**: Test results appear directly in the terminal and give developers immediate feedback.
* **Automated test pipeline**: Tests also run automatically as part of our continuous delivery pipeline.


# Tolerant reader
Source: https://docs.lerian.studio/en/reference/tolerant-reader

The tolerant reader integration pattern lets your client code absorb Lerian API changes (new fields, reordering, or additions) without breaking.

As our public API evolves, integrators and clients need to adapt. The **Tolerant Reader** pattern makes a client resilient to those changes.

By adopting the Tolerant Reader pattern, integrations can better handle new information without frequent updates. This approach reduces maintenance needs.

## What is a tolerant reader?

***

The Tolerant Reader pattern is an integration design approach. In this pattern, a client that consumes data handles changes gracefully, such as added fields or minor structure modifications. This pattern promotes forward compatibility and reduces the need for immediate updates whenever the data or service evolves.

## Real-world scenario

***

Consider a request to `GET /v1/organizations/{organization_id}`. Initially, the response might be:

```json JSON theme={null}
{
    "id": "cc15194a-6bc9-4ebb-b15d-43411a54ba4b",
    "parentOrganizationId": null,
    "legalName": "Empresa Teste Ltda",
    "legalDocument": "86820799000188",
    "metadata": null,
    "status": {
        "code": "ACTIVE",
        "description": null
    },
    "createdAt": "2024-02-08T16:59:31+0300",
    "updatedAt": "2024-02-08T16:59:31+0300",
    "deletedAt": null
}
```

Later, fields like `doingBusinessAs` and `address` may be added:

```json JSON expandable theme={null}
{
    "id": "cc15194a-6bc9-4ebb-b15d-43411a54ba4b",
    "parentOrganizationId": null,
    "legalName": "Empresa Teste Ltda",
    "doingBusinessAs": "Empresa Teste",
    "legalDocument": "86820799000188",
    "address": {
        "line1": "Rua Botucatu, 10",
        "line2": "Casa B",
        "zipCode": "04023060",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR"
    },
    "metadata": null,
    "status": {
        "code": "ACTIVE",
        "description": null
    },
    "createdAt": "2024-02-08T16:59:31+0300",
    "updatedAt": "2024-02-08T16:59:31+0300",
    "deletedAt": null
}
```

A client that follows the Tolerant Reader pattern would handle the additional fields without issue.

## Implementing a tolerant reader

***

Below is an example Python code snippet that processes additional fields gracefully.

```python Python expandable theme={null}
def fetch_organization_info(organization_id):
    response = requests.get(f"{host}/v1/organizations/{organization_id}")
    org_info = response.json()

    # Fetch required fields
    legal_name = org_info.get("legalName", "Unknown")
    legal_document = org_info.get("legalDocument", "No document provided")

    # Handle optional fields
    doing_business_as = org_info.get("doingBusinessAs")

    # Nested address structure
    address_info = org_info.get("address", {})
    line1 = address_info.get("line1", "Address not provided")
    city = address_info.get("city", "City not provided")
    state = address_info.get("state", "State not provided")
    country = address_info.get("country", "Country not provided")

    # Display information
    print(f"Legal Name: {legal_name}, Legal Document: {legal_document}")
    print(f"Doing Business As: {doing_business_as}")
    print(f"Address: {line1}, {city}, {state}, {country}")

# Example usage
fetch_organization_info("cc15194a-6bc9-4ebb-b15d-43411a54ba4b")
```

In this example, `get` methods safely access values. This allows for flexibility when new fields appear, such as `phoneNumber`. The code remains functional even if a field is absent.


# Troubleshooting and support
Source: https://docs.lerian.studio/en/reference/troubleshooting-support

Troubleshoot common Midaz issues and reach the right community or Enterprise support channels.

If you have suggestions, questions, or ideas that could improve Midaz, reach out using the channels listed below.

## Troubleshooting

***

Before reaching out for support, try these quick checks for common issues:

### Midaz isn’t starting

* Check that all dependencies (Docker, Kubernetes, Helm) are present and that each one runs.
* Check that you set the required environment variables.
* Use `docker compose logs` or `kubectl logs` to inspect container output for errors.

### API not responding

* Verify you’re hitting the correct endpoint and using the right credentials.
* Use tools like Postman or `curl` to test requests manually.
* Refer to the [API Reference](/en/reference/introduction) to confirm the expected payload.

> [!TIP]
>
> If something breaks, start with the logs.

## Community support

***

If you use the **Community** version, we offer open channels where you can ask questions, report bugs, and share ideas.

* **GitHub Discussions**: Use the [Discussions tab](https://github.com/LerianStudio/midaz/discussions) to talk with other users, propose improvements, or raise issues.
* **Discord**: Join our [community on Discord](https://discord.gg/DnhqKwkGv3) for real-time support and updates. Look for the **#midaz** channel.

> [!CAUTION]
>
> If you're an **Enterprise** institution, use the [**Lerian Support Portal**](/en/products/midaz/lerian-support-portal) to get guaranteed response times and access to our dedicated support team.


# Midaz events
Source: https://docs.lerian.studio/en/reference/events/midaz

Reference all public JSON event facts emitted by Midaz, including CloudEvents headers, application topics, delivery behavior, and complete data contracts.

Midaz emits its public JSON business facts as CloudEvents 1.0 in binary content mode over Kafka.

## Public JSON ledger catalog

The public ledger manifest contains the following verified definitions. Every cataloged definition has a non-test production emission path.

| Cataloged | Emitted | Catalog-only |
| -: | -: | -: |
| 54 | 54 | 0 |

## CloudEvents envelope

Every public JSON fact uses the shared envelope below. The headers carry routing and schema information. The Kafka value carries the JSON `data` object.

| Header | Presence and value |
| - | - |
| `ce-specversion` | Always `1.0`. |
| `ce-id` | Always; opaque producer-defined event identifier. |
| `ce-source` | Always `ledger`. |
| `ce-type` | Always `studio.lerian.ledger.<resource>.<event>`. |
| `ce-time` | Always; RFC 3339 emission timestamp. |
| `ce-resourcetype` | Always; the resource token from the definition key. |
| `ce-eventtype` | Always; the event token from the definition key. |
| `ce-subject` | Set by the payload-specific expression listed with each contract. |
| `ce-tenantid` | **Always present.** Your tenant ID, or the literal `default` when the event has no tenant. |
| `ce-schemaversion` | `1.1.0` for the six operation-route and transaction-route facts; `1.0.0` for the other 48. |
| `ce-datacontenttype` | `application/json`. |

## Topics, manifest, and routing

The application topic identifies the producing application, not an individual event. Route a record by `ce-resourcetype` and `ce-eventtype`, and validate `ce-schemaversion` before decoding its `data` value.

* **Facts:** `lerian.streaming.ledger`
* **Route DLQ:** `lerian.streaming.ledger.dlq`
* **Manifest:** `GET /v1/streaming/manifest` exposes the public JSON catalog and topic mapping, including while publication is disabled.

## Delivery and failure semantics

Publication is disabled until `STREAMING_ENABLED=true` and broker configuration succeeds. When enabled, Midaz emits after the business-state change. It does not use a transactional outbox.

* **Policy:** every public JSON definition is a `fact` with direct delivery, `on_routable_failure` DLQ handling, and `fallback_on_circuit_open`.
* **Actual Midaz boundary:** because Midaz has no outbox, the circuit-open fallback cannot persist an event. Emit paths log and swallow publication errors instead of returning them to the business command.
* **Consumer requirement:** broker delivery is at least once for published records. Make handlers idempotent and deduplicate with `(ce-source, ce-id)`.

## Separate legacy RabbitMQ plane

Midaz also has compatibility exchanges for selected overdraft and audit notifications. They are a separate legacy RabbitMQ plane and do not carry the full 54-event public JSON catalog. New integrations should use the Kafka contract on this page.

## Complete `data` contracts

These TypeScript-style declarations mirror the producer wire shape. Every field name is its JSON name. `?` means the field has `omitempty`. `| null` means the field is nullable and the producer always includes it. A source-type comment preserves the inventory type exactly. Decimal values are JSON strings, never binary floating-point numbers.

### Shared source-type mappings

```typescript theme={null}
type DecimalString = string // JSON encoding of decimal.Decimal
type JsonRawMessage = unknown // Go: json.RawMessage

type MmodelStatus = { // Go: mmodel.Status
  code: string // string; wire null: false; omitempty: false
  description: string | null // *string; wire null: true; omitempty: false
}

type BalanceSettings = { // Go: mmodel.BalanceSettings
  balanceScope?: string // string; wire null: false; omitempty: true
  allowOverdraft: boolean // bool; wire null: false; omitempty: false
  overdraftLimitEnabled: boolean // bool; wire null: false; omitempty: false
  overdraftLimit?: string // *string; wire null: false; omitempty: true
}

type AccountingRubric = { // Go: mmodel.AccountingRubric
  code: string // string; wire null: false; omitempty: false
  description: string // string; wire null: false; omitempty: false
}

type AccountingEntry = { // Go: mmodel.AccountingEntry
  debit: AccountingRubric | null // *AccountingRubric; wire null: true; omitempty: false
  credit: AccountingRubric | null // *AccountingRubric; wire null: true; omitempty: false
}

type AccountingEntries = { // Go: mmodel.AccountingEntries
  direct?: AccountingEntry // *AccountingEntry; wire null: false; omitempty: true
  hold?: AccountingEntry // *AccountingEntry; wire null: false; omitempty: true
  commit?: AccountingEntry // *AccountingEntry; wire null: false; omitempty: true
  cancel?: AccountingEntry // *AccountingEntry; wire null: false; omitempty: true
  revert?: AccountingEntry // *AccountingEntry; wire null: false; omitempty: true
  overdraft?: AccountingEntry // *AccountingEntry; wire null: false; omitempty: true
  block?: AccountingEntry // *AccountingEntry; wire null: false; omitempty: true
  unblock?: AccountingEntry // *AccountingEntry; wire null: false; omitempty: true
}

type AccountRule = { // Go: mmodel.AccountRule
  ruleType?: string // string; wire null: false; omitempty: true
  validIf?: unknown // any; wire null: false; omitempty: true
}

type TransactionGroupPart = { // Go: events.TransactionGroupPart
  transactionId: string // string; wire null: false; omitempty: false
  organizationId: string // string; wire null: false; omitempty: false
  ledgerId: string // string; wire null: false; omitempty: false
  role: string // string; wire null: false; omitempty: false
  status: string // string; wire null: false; omitempty: false
}
```

> **account.closed**
>
> **Event:** `studio.lerian.ledger.account.closed`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the closing of an account. `closedAt` is the closing instant.
>
> **Subject:** account ID (`p.ID`)
>
> ```typescript theme={null}
> // account.closed
> type AccountClosedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   closedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **account.created**
>
> **Event:** `studio.lerian.ledger.account.created`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the opening of an account in a ledger.
>
> **Subject:** account ID (`p.ID`)
>
> ```typescript theme={null}
> type AccountStatusPayload = {
>   code: string // string; wire null: false; omitempty: false
>   description?: string // *string; wire null: false; omitempty: true
> }
>
> // account.created
> type AccountCreatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   name: string // string; wire null: false; omitempty: false
>   assetCode: string // string; wire null: false; omitempty: false
>   type: string // string; wire null: false; omitempty: false
>   portfolioId: string | null // *string; wire null: true; omitempty: false
>   segmentId: string | null // *string; wire null: true; omitempty: false
>   parentAccountId: string | null // *string; wire null: true; omitempty: false
>   entityId: string | null // *string; wire null: true; omitempty: false
>   holderId: string | null // *string; wire null: true; omitempty: false
>   alias: string | null // *string; wire null: true; omitempty: false
>   status: AccountStatusPayload // AccountStatusPayload; wire null: false; omitempty: false
>   blocked: boolean | null // *bool; wire null: true; omitempty: false
>   holderCheckSkipped: boolean // bool; wire null: false; omitempty: false
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **account.deleted**
>
> **Event:** `studio.lerian.ledger.account.deleted`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the deletion of an account.
>
> **Subject:** account ID (`p.ID`)
>
> ```typescript theme={null}
> // account.deleted
> type AccountDeletedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   portfolioId: string | null // *string; wire null: true; omitempty: false
>   deletedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **account.updated**
>
> **Event:** `studio.lerian.ledger.account.updated`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** An account's mutable fields change.
>
> **Subject:** account ID (`p.ID`)
>
> ```typescript theme={null}
> type AccountStatusPayload = {
>   code: string // string; wire null: false; omitempty: false
>   description?: string // *string; wire null: false; omitempty: true
> }
>
> // account.updated
> type AccountUpdatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   name: string // string; wire null: false; omitempty: false
>   portfolioId: string | null // *string; wire null: true; omitempty: false
>   segmentId: string | null // *string; wire null: true; omitempty: false
>   entityId: string | null // *string; wire null: true; omitempty: false
>   status: AccountStatusPayload // AccountStatusPayload; wire null: false; omitempty: false
>   blocked: boolean | null // *bool; wire null: true; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **asset.created**
>
> **Event:** `studio.lerian.ledger.asset.created`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the registration of an asset in a ledger.
>
> **Subject:** asset ID (`p.ID`)
>
> ```typescript theme={null}
> type AssetStatusPayload = {
>   code: string // string; wire null: false; omitempty: false
>   description?: string // *string; wire null: false; omitempty: true
> }
>
> // asset.created
> type AssetCreatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   name: string // string; wire null: false; omitempty: false
>   type: string // string; wire null: false; omitempty: false
>   code: string // string; wire null: false; omitempty: false
>   status: AssetStatusPayload // AssetStatusPayload; wire null: false; omitempty: false
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **asset.deleted**
>
> **Event:** `studio.lerian.ledger.asset.deleted`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the deletion of an asset.
>
> **Subject:** asset ID (`p.ID`)
>
> ```typescript theme={null}
> // asset.deleted
> type AssetDeletedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   deletedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **asset.updated**
>
> **Event:** `studio.lerian.ledger.asset.updated`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** An asset's mutable fields change.
>
> **Subject:** asset ID (`p.ID`)
>
> ```typescript theme={null}
> type AssetStatusPayload = {
>   code: string // string; wire null: false; omitempty: false
>   description?: string // *string; wire null: false; omitempty: true
> }
>
> // asset.updated
> type AssetUpdatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   name: string // string; wire null: false; omitempty: false
>   type: string // string; wire null: false; omitempty: false
>   code: string // string; wire null: false; omitempty: false
>   status: AssetStatusPayload // AssetStatusPayload; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **balance.changed**
>
> **Event:** `studio.lerian.ledger.balance.changed`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** A committed transaction moves a balance (one event per balance-affecting operation). Values reflect the state after the operation.
>
> **Subject:** transaction ID and operation ID (`p.TransactionID + ":" + p.OperationID`)
>
> ```typescript theme={null}
> // balance.changed
> type BalanceChangedDataV1 = {
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   accountId: string // string; wire null: false; omitempty: false
>   balanceId: string // string; wire null: false; omitempty: false
>   alias?: string // string; wire null: false; omitempty: true
>   assetCode: string // string; wire null: false; omitempty: false
>   balanceKey: string // string; wire null: false; omitempty: false
>   available: DecimalString // decimal.Decimal; wire null: false; omitempty: false
>   onHold: DecimalString // decimal.Decimal; wire null: false; omitempty: false
>   version: number // int64; wire null: false; omitempty: false
>   reason: string // string; wire null: false; omitempty: false
>   operationType: string // string; wire null: false; omitempty: false
>   direction?: string // string; wire null: false; omitempty: true
>   amount: DecimalString // decimal.Decimal; wire null: false; omitempty: false
>   transactionId: string // string; wire null: false; omitempty: false
>   operationId: string // string; wire null: false; omitempty: false
>   occurredAt: string // string; wire null: false; omitempty: false
> }
> ```

> **balance.config\_changed**
>
> **Event:** `studio.lerian.ledger.balance.config_changed`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** A balance's settings change, or overdraft is enabled (companion balance materialized). `changeType` discriminates `settings_updated` from `overdraft_enabled`.
>
> **Subject:** balance ID (`p.ID`)
>
> ```typescript theme={null}
> // balance.config_changed
> type BalanceConfigChangedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   accountId: string // string; wire null: false; omitempty: false
>   alias?: string // string; wire null: false; omitempty: true
>   key: string // string; wire null: false; omitempty: false
>   allowSending: boolean // bool; wire null: false; omitempty: false
>   allowReceiving: boolean // bool; wire null: false; omitempty: false
>   direction?: string // string; wire null: false; omitempty: true
>   settings?: BalanceSettings // *mmodel.BalanceSettings; wire null: false; omitempty: true
>   changeType: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **balance.created**
>
> **Event:** `studio.lerian.ledger.balance.created`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Subject:** balance ID (`p.ID`)
>
> ```typescript theme={null}
> // balance.created
> type BalanceCreatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   accountId: string // string; wire null: false; omitempty: false
>   alias?: string // string; wire null: false; omitempty: true
>   key: string // string; wire null: false; omitempty: false
>   assetCode: string // string; wire null: false; omitempty: false
>   accountType?: string // string; wire null: false; omitempty: true
>   available: DecimalString // decimal.Decimal; wire null: false; omitempty: false
>   onHold: DecimalString // decimal.Decimal; wire null: false; omitempty: false
>   allowSending: boolean // bool; wire null: false; omitempty: false
>   allowReceiving: boolean // bool; wire null: false; omitempty: false
>   direction?: string // string; wire null: false; omitempty: true
>   settings?: BalanceSettings // *mmodel.BalanceSettings; wire null: false; omitempty: true
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **balance.deleted**
>
> **Event:** `studio.lerian.ledger.balance.deleted`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the deletion of a balance.
>
> **Subject:** balance ID (`p.ID`)
>
> ```typescript theme={null}
> // balance.deleted
> type BalanceDeletedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   accountId: string // string; wire null: false; omitempty: false
>   deletedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **balance.overdraft\_cleared**
>
> **Event:** `studio.lerian.ledger.balance.overdraft_cleared`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** Overdraft is fully repaid, a terminal signal (`action` = `cleared`).
>
> **Subject:** transaction ID and operation ID (`p.TransactionID + ":" + p.OperationID`)
>
> ```typescript theme={null}
> // balance.overdraft_cleared
> type BalanceOverdraftClearedDataV1 = {
>   balanceId: string // string; wire null: false; omitempty: false
>   accountId: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   assetCode: string // string; wire null: false; omitempty: false
>   transactionId: string // string; wire null: false; omitempty: false
>   operationId: string // string; wire null: false; omitempty: false
>   action: string // string; wire null: false; omitempty: false
>   amount: DecimalString // decimal.Decimal; wire null: false; omitempty: false
>   overdraftBalance: DecimalString // decimal.Decimal; wire null: false; omitempty: false
>   overdraftLimit?: DecimalString // *decimal.Decimal; wire null: false; omitempty: true
>   occurredAt: string // string; wire null: false; omitempty: false
> }
> ```

> **balance.overdraft\_drawn**
>
> **Event:** `studio.lerian.ledger.balance.overdraft_drawn`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** A debit consumes overdraft beyond available funds (`action` = `drawn`).
>
> **Subject:** transaction ID and operation ID (`p.TransactionID + ":" + p.OperationID`)
>
> ```typescript theme={null}
> // balance.overdraft_drawn
> type BalanceOverdraftDrawnDataV1 = {
>   balanceId: string // string; wire null: false; omitempty: false
>   accountId: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   assetCode: string // string; wire null: false; omitempty: false
>   transactionId: string // string; wire null: false; omitempty: false
>   operationId: string // string; wire null: false; omitempty: false
>   action: string // string; wire null: false; omitempty: false
>   amount: DecimalString // decimal.Decimal; wire null: false; omitempty: false
>   overdraftBalance: DecimalString // decimal.Decimal; wire null: false; omitempty: false
>   overdraftLimit?: DecimalString // *decimal.Decimal; wire null: false; omitempty: true
>   occurredAt: string // string; wire null: false; omitempty: false
> }
> ```

> **balance.overdraft\_repaid**
>
> **Event:** `studio.lerian.ledger.balance.overdraft_repaid`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** Overdraft usage decreases but is not fully cleared (`action` = `repaid`).
>
> **Subject:** transaction ID and operation ID (`p.TransactionID + ":" + p.OperationID`)
>
> ```typescript theme={null}
> // balance.overdraft_repaid
> type BalanceOverdraftRepaidDataV1 = {
>   balanceId: string // string; wire null: false; omitempty: false
>   accountId: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   assetCode: string // string; wire null: false; omitempty: false
>   transactionId: string // string; wire null: false; omitempty: false
>   operationId: string // string; wire null: false; omitempty: false
>   action: string // string; wire null: false; omitempty: false
>   amount: DecimalString // decimal.Decimal; wire null: false; omitempty: false
>   overdraftBalance: DecimalString // decimal.Decimal; wire null: false; omitempty: false
>   overdraftLimit?: DecimalString // *decimal.Decimal; wire null: false; omitempty: true
>   occurredAt: string // string; wire null: false; omitempty: false
> }
> ```

> **fee\_billing\_packages.created**
>
> **Event:** `studio.lerian.ledger.fee_billing_packages.created`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the creation of a billing package.
>
> **Subject:** billing package ID (`p.ID`)
>
> ```typescript theme={null}
> // fee_billing_packages.created
> type FeeBillingPackagesCreatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   type: string // string; wire null: false; omitempty: false
>   pricingModel: string | null // *string; wire null: true; omitempty: false
>   countMode: string | null // *string; wire null: true; omitempty: false
>   enable: boolean // bool; wire null: false; omitempty: false
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **fee\_billing\_packages.deleted**
>
> **Event:** `studio.lerian.ledger.fee_billing_packages.deleted`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the deletion of a billing package.
>
> **Subject:** billing package ID (`p.ID`)
>
> ```typescript theme={null}
> // fee_billing_packages.deleted
> type FeeBillingPackagesDeletedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   deletedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **fee\_billing\_packages.updated**
>
> **Event:** `studio.lerian.ledger.fee_billing_packages.updated`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** A billing package's mutable fields change.
>
> **Subject:** billing package ID (`p.ID`)
>
> ```typescript theme={null}
> // fee_billing_packages.updated
> type FeeBillingPackagesUpdatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   type: string // string; wire null: false; omitempty: false
>   pricingModel: string | null // *string; wire null: true; omitempty: false
>   countMode: string | null // *string; wire null: true; omitempty: false
>   enable: boolean // bool; wire null: false; omitempty: false
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **fee\_charge.applied**
>
> **Event:** `studio.lerian.ledger.fee_charge.applied`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the application of a fee package to a committed transaction.
>
> **Subject:** transaction ID (`p.TransactionID`)
>
> ```typescript theme={null}
> // fee_charge.applied
> type FeeChargeAppliedDataV1 = {
>   transactionId: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   feePackageId: string // string; wire null: false; omitempty: false
>   appliedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **fee\_packages.created**
>
> **Event:** `studio.lerian.ledger.fee_packages.created`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the creation of a fee package.
>
> **Subject:** fee package ID (`p.ID`)
>
> ```typescript theme={null}
> // fee_packages.created
> type FeePackagesCreatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   segmentId: string | null // *string; wire null: true; omitempty: false
>   transactionRoute: string | null // *string; wire null: true; omitempty: false
>   enable: boolean // bool; wire null: false; omitempty: false
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **fee\_packages.deleted**
>
> **Event:** `studio.lerian.ledger.fee_packages.deleted`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the deletion of a fee package.
>
> **Subject:** fee package ID (`p.ID`)
>
> ```typescript theme={null}
> // fee_packages.deleted
> type FeePackagesDeletedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   deletedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **fee\_packages.updated**
>
> **Event:** `studio.lerian.ledger.fee_packages.updated`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** A fee package's mutable fields change.
>
> **Subject:** fee package ID (`p.ID`)
>
> ```typescript theme={null}
> // fee_packages.updated
> type FeePackagesUpdatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   segmentId: string | null // *string; wire null: true; omitempty: false
>   transactionRoute: string | null // *string; wire null: true; omitempty: false
>   enable: boolean // bool; wire null: false; omitempty: false
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **holder.created**
>
> **Event:** `studio.lerian.ledger.holder.created`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the creation of a holder.
>
> **Subject:** holder ID (`p.ID`)
>
> ```typescript theme={null}
> // holder.created
> type HolderCreatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   type: string // string; wire null: false; omitempty: false
>   externalId: string | null // *string; wire null: true; omitempty: false
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **holder.deleted**
>
> **Event:** `studio.lerian.ledger.holder.deleted`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the deletion of a holder.
>
> **Subject:** holder ID (`p.ID`)
>
> ```typescript theme={null}
> // holder.deleted
> type HolderDeletedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   deletionType: string // string; wire null: false; omitempty: false
>   deletedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **holder.updated**
>
> **Event:** `studio.lerian.ledger.holder.updated`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** A holder's mutable fields change.
>
> **Subject:** holder ID (`p.ID`)
>
> ```typescript theme={null}
> // holder.updated
> type HolderUpdatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   type: string // string; wire null: false; omitempty: false
>   externalId: string | null // *string; wire null: true; omitempty: false
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **instrument.created**
>
> **Event:** `studio.lerian.ledger.instrument.created`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the creation of an instrument for a holder and account.
>
> **Subject:** instrument ID (`p.ID`)
>
> ```typescript theme={null}
> type InstrumentRelatedPartyPayload = {
>   relatedPartyId: string // string; wire null: false; omitempty: false
>   role: string // string; wire null: false; omitempty: false
> }
>
> // instrument.created
> type InstrumentCreatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   holderId: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   accountId: string // string; wire null: false; omitempty: false
>   type: string // string; wire null: false; omitempty: false
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
>   relatedParties: InstrumentRelatedPartyPayload[] // []InstrumentRelatedPartyPayload; wire null: false; omitempty: false
> }
> ```

> **instrument.deleted**
>
> **Event:** `studio.lerian.ledger.instrument.deleted`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the deletion of an instrument.
>
> **Subject:** instrument ID (`p.ID`)
>
> ```typescript theme={null}
> // instrument.deleted
> type InstrumentDeletedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   holderId: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   deletionType: string // string; wire null: false; omitempty: false
>   deletedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **instrument.related\_party\_deleted**
>
> **Event:** `studio.lerian.ledger.instrument.related_party_deleted`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the removal of a single related party from an instrument (`ce-subject` is the instrument id).
>
> **Subject:** instrument ID (`p.InstrumentID`)
>
> ```typescript theme={null}
> // instrument.related_party_deleted
> type InstrumentRelatedPartyDeletedDataV1 = {
>   instrumentId: string // string; wire null: false; omitempty: false
>   holderId: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   relatedPartyId: string // string; wire null: false; omitempty: false
>   deletedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **instrument.updated**
>
> **Event:** `studio.lerian.ledger.instrument.updated`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** An instrument's mutable fields change.
>
> **Subject:** instrument ID (`p.ID`)
>
> ```typescript theme={null}
> type InstrumentRelatedPartyPayload = {
>   relatedPartyId: string // string; wire null: false; omitempty: false
>   role: string // string; wire null: false; omitempty: false
> }
>
> // instrument.updated
> type InstrumentUpdatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   holderId: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   accountId: string // string; wire null: false; omitempty: false
>   type: string // string; wire null: false; omitempty: false
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
>   relatedParties: InstrumentRelatedPartyPayload[] // []InstrumentRelatedPartyPayload; wire null: false; omitempty: false
> }
> ```

> **ledger.created**
>
> **Event:** `studio.lerian.ledger.ledger.created`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the creation of a ledger within an organization.
>
> **Subject:** ledger ID (`p.ID`)
>
> ```typescript theme={null}
> type LedgerStatusPayload = {
>   code: string // string; wire null: false; omitempty: false
>   description?: string // *string; wire null: false; omitempty: true
> }
>
> // ledger.created
> type LedgerCreatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   name: string // string; wire null: false; omitempty: false
>   status: LedgerStatusPayload // LedgerStatusPayload; wire null: false; omitempty: false
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **ledger.deleted**
>
> **Event:** `studio.lerian.ledger.ledger.deleted`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the deletion of a ledger.
>
> **Subject:** ledger ID (`p.ID`)
>
> ```typescript theme={null}
> // ledger.deleted
> type LedgerDeletedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   deletedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **ledger.updated**
>
> **Event:** `studio.lerian.ledger.ledger.updated`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** A ledger's name or status changes.
>
> **Subject:** ledger ID (`p.ID`)
>
> ```typescript theme={null}
> type LedgerStatusPayload = {
>   code: string // string; wire null: false; omitempty: false
>   description?: string // *string; wire null: false; omitempty: true
> }
>
> // ledger.updated
> type LedgerUpdatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   name: string // string; wire null: false; omitempty: false
>   status: LedgerStatusPayload // LedgerStatusPayload; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **operation\_route.created**
>
> **Event:** `studio.lerian.ledger.operation_route.created`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.1.0`
>
> **Trigger:** the creation of an operation route.
>
> **Subject:** operation-route ID (`p.ID`)
>
> ```typescript theme={null}
> // operation_route.created
> type OperationRouteCreatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId?: string // string; wire null: false; omitempty: true
>   title: string // string; wire null: false; omitempty: false
>   description?: string // string; wire null: false; omitempty: true
>   code?: string // string; wire null: false; omitempty: true
>   operationType: string // string; wire null: false; omitempty: false
>   account?: AccountRule // *mmodel.AccountRule; wire null: false; omitempty: true
>   accountingEntries?: AccountingEntries // *mmodel.AccountingEntries; wire null: false; omitempty: true
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **operation\_route.deleted**
>
> **Event:** `studio.lerian.ledger.operation_route.deleted`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.1.0`
>
> **Trigger:** the deletion of an operation route.
>
> **Subject:** operation-route ID (`p.ID`)
>
> ```typescript theme={null}
> // operation_route.deleted
> type OperationRouteDeletedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId?: string // string; wire null: false; omitempty: true
>   deletedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **operation\_route.updated**
>
> **Event:** `studio.lerian.ledger.operation_route.updated`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.1.0`
>
> **Trigger:** An operation route's mutable fields change.
>
> **Subject:** operation-route ID (`p.ID`)
>
> ```typescript theme={null}
> // operation_route.updated
> type OperationRouteUpdatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId?: string // string; wire null: false; omitempty: true
>   title: string // string; wire null: false; omitempty: false
>   description?: string // string; wire null: false; omitempty: true
>   code?: string // string; wire null: false; omitempty: true
>   operationType: string // string; wire null: false; omitempty: false
>   account?: AccountRule // *mmodel.AccountRule; wire null: false; omitempty: true
>   accountingEntries?: AccountingEntries // *mmodel.AccountingEntries; wire null: false; omitempty: true
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **organization.created**
>
> **Event:** `studio.lerian.ledger.organization.created`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the creation of an organization.
>
> **Subject:** organization ID (`p.ID`)
>
> ```typescript theme={null}
> type OrganizationAddressPayload = {
>   line1: string // string; wire null: false; omitempty: false
>   line2: string | null // *string; wire null: true; omitempty: false
>   zipCode: string // string; wire null: false; omitempty: false
>   city: string // string; wire null: false; omitempty: false
>   state: string // string; wire null: false; omitempty: false
>   country: string // string; wire null: false; omitempty: false
>   description?: string // *string; wire null: false; omitempty: true
> }
>
> type OrganizationStatusPayload = {
>   code: string // string; wire null: false; omitempty: false
>   description?: string // *string; wire null: false; omitempty: true
> }
>
> // organization.created
> type OrganizationCreatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   parentOrganizationId: string | null // *string; wire null: true; omitempty: false
>   legalName: string // string; wire null: false; omitempty: false
>   doingBusinessAs: string | null // *string; wire null: true; omitempty: false
>   legalDocument: string // string; wire null: false; omitempty: false
>   address: OrganizationAddressPayload // OrganizationAddressPayload; wire null: false; omitempty: false
>   status: OrganizationStatusPayload // OrganizationStatusPayload; wire null: false; omitempty: false
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **organization.deleted**
>
> **Event:** `studio.lerian.ledger.organization.deleted`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the deletion of an organization.
>
> **Subject:** organization ID (`p.ID`)
>
> ```typescript theme={null}
> // organization.deleted
> type OrganizationDeletedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   deletedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **organization.updated**
>
> **Event:** `studio.lerian.ledger.organization.updated`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** An organization's mutable fields change.
>
> **Subject:** organization ID (`p.ID`)
>
> ```typescript theme={null}
> type OrganizationAddressPayload = {
>   line1: string // string; wire null: false; omitempty: false
>   line2: string | null // *string; wire null: true; omitempty: false
>   zipCode: string // string; wire null: false; omitempty: false
>   city: string // string; wire null: false; omitempty: false
>   state: string // string; wire null: false; omitempty: false
>   country: string // string; wire null: false; omitempty: false
>   description?: string // *string; wire null: false; omitempty: true
> }
>
> type OrganizationStatusPayload = {
>   code: string // string; wire null: false; omitempty: false
>   description?: string // *string; wire null: false; omitempty: true
> }
>
> // organization.updated
> type OrganizationUpdatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   parentOrganizationId: string | null // *string; wire null: true; omitempty: false
>   legalName: string // string; wire null: false; omitempty: false
>   doingBusinessAs: string | null // *string; wire null: true; omitempty: false
>   address: OrganizationAddressPayload // OrganizationAddressPayload; wire null: false; omitempty: false
>   status: OrganizationStatusPayload // OrganizationStatusPayload; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **portfolio.created**
>
> **Event:** `studio.lerian.ledger.portfolio.created`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the creation of a portfolio.
>
> **Subject:** portfolio ID (`p.ID`)
>
> ```typescript theme={null}
> type PortfolioStatusPayload = {
>   code: string // string; wire null: false; omitempty: false
>   description?: string // *string; wire null: false; omitempty: true
> }
>
> // portfolio.created
> type PortfolioCreatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   name: string // string; wire null: false; omitempty: false
>   entityId?: string // string; wire null: false; omitempty: true
>   status: PortfolioStatusPayload // PortfolioStatusPayload; wire null: false; omitempty: false
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **portfolio.deleted**
>
> **Event:** `studio.lerian.ledger.portfolio.deleted`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the deletion of a portfolio.
>
> **Subject:** portfolio ID (`p.ID`)
>
> ```typescript theme={null}
> // portfolio.deleted
> type PortfolioDeletedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   deletedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **portfolio.updated**
>
> **Event:** `studio.lerian.ledger.portfolio.updated`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** A portfolio's mutable fields change.
>
> **Subject:** portfolio ID (`p.ID`)
>
> ```typescript theme={null}
> type PortfolioStatusPayload = {
>   code: string // string; wire null: false; omitempty: false
>   description?: string // *string; wire null: false; omitempty: true
> }
>
> // portfolio.updated
> type PortfolioUpdatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   name: string // string; wire null: false; omitempty: false
>   entityId?: string // string; wire null: false; omitempty: true
>   status: PortfolioStatusPayload // PortfolioStatusPayload; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **segment.created**
>
> **Event:** `studio.lerian.ledger.segment.created`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the creation of a segment.
>
> **Subject:** segment ID (`p.ID`)
>
> ```typescript theme={null}
> type SegmentStatusPayload = {
>   code: string // string; wire null: false; omitempty: false
>   description?: string // *string; wire null: false; omitempty: true
> }
>
> // segment.created
> type SegmentCreatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   name: string // string; wire null: false; omitempty: false
>   status: SegmentStatusPayload // SegmentStatusPayload; wire null: false; omitempty: false
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **segment.deleted**
>
> **Event:** `studio.lerian.ledger.segment.deleted`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the deletion of a segment.
>
> **Subject:** segment ID (`p.ID`)
>
> ```typescript theme={null}
> // segment.deleted
> type SegmentDeletedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   deletedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **segment.updated**
>
> **Event:** `studio.lerian.ledger.segment.updated`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** A segment's mutable fields change.
>
> **Subject:** segment ID (`p.ID`)
>
> ```typescript theme={null}
> type SegmentStatusPayload = {
>   code: string // string; wire null: false; omitempty: false
>   description?: string // *string; wire null: false; omitempty: true
> }
>
> // segment.updated
> type SegmentUpdatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   name: string // string; wire null: false; omitempty: false
>   status: SegmentStatusPayload // SegmentStatusPayload; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **transaction.canceled**
>
> **Event:** `studio.lerian.ledger.transaction.canceled`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** A pending transaction transitions from `PENDING` to `CANCELED`.
>
> **Subject:** transaction ID (`p.ID`)
>
> ```typescript theme={null}
> // transaction.canceled
> type TransactionCanceledDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   parentTransactionId?: string // *string; wire null: false; omitempty: true
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   status: MmodelStatus // mmodel.Status; wire null: false; omitempty: false
>   amount?: DecimalString // *decimal.Decimal; wire null: false; omitempty: true
>   assetCode: string // string; wire null: false; omitempty: false
>   chartOfAccountsGroupName?: string // string; wire null: false; omitempty: true
>   description?: string // string; wire null: false; omitempty: true
>   source?: string[] // []string; wire null: false; omitempty: true
>   destination?: string[] // []string; wire null: false; omitempty: true
>   route?: string // string; wire null: false; omitempty: true
>   routeId?: string // *string; wire null: false; omitempty: true
>   operations: JsonRawMessage[] // []json.RawMessage; wire null: false; omitempty: false
>   metadata?: Record<string, unknown> // map[string]any; wire null: false; omitempty: true
>   feesSkipped: boolean // bool; wire null: false; omitempty: false
>   tracerSkipped: boolean // bool; wire null: false; omitempty: false
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **transaction.committed**
>
> **Event:** `studio.lerian.ledger.transaction.committed`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** A pending transaction transitions from `PENDING` to `APPROVED`.
>
> **Subject:** transaction ID (`p.ID`)
>
> ```typescript theme={null}
> // transaction.committed
> type TransactionCommittedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   parentTransactionId?: string // *string; wire null: false; omitempty: true
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   status: MmodelStatus // mmodel.Status; wire null: false; omitempty: false
>   amount?: DecimalString // *decimal.Decimal; wire null: false; omitempty: true
>   assetCode: string // string; wire null: false; omitempty: false
>   chartOfAccountsGroupName?: string // string; wire null: false; omitempty: true
>   description?: string // string; wire null: false; omitempty: true
>   source?: string[] // []string; wire null: false; omitempty: true
>   destination?: string[] // []string; wire null: false; omitempty: true
>   route?: string // string; wire null: false; omitempty: true
>   routeId?: string // *string; wire null: false; omitempty: true
>   operations: JsonRawMessage[] // []json.RawMessage; wire null: false; omitempty: false
>   metadata?: Record<string, unknown> // map[string]any; wire null: false; omitempty: true
>   feesSkipped: boolean // bool; wire null: false; omitempty: false
>   tracerSkipped: boolean // bool; wire null: false; omitempty: false
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **transaction.posted**
>
> **Event:** `studio.lerian.ledger.transaction.posted`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** the commit of a newly created transaction to storage with all its operations persisted (no parent).
>
> **Subject:** transaction ID (`p.ID`)
>
> ```typescript theme={null}
> // transaction.posted
> type TransactionPostedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   parentTransactionId?: string // *string; wire null: false; omitempty: true
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   status: MmodelStatus // mmodel.Status; wire null: false; omitempty: false
>   amount?: DecimalString // *decimal.Decimal; wire null: false; omitempty: true
>   assetCode: string // string; wire null: false; omitempty: false
>   chartOfAccountsGroupName?: string // string; wire null: false; omitempty: true
>   description?: string // string; wire null: false; omitempty: true
>   source?: string[] // []string; wire null: false; omitempty: true
>   destination?: string[] // []string; wire null: false; omitempty: true
>   route?: string // string; wire null: false; omitempty: true
>   routeId?: string // *string; wire null: false; omitempty: true
>   operations: JsonRawMessage[] // []json.RawMessage; wire null: false; omitempty: false
>   metadata?: Record<string, unknown> // map[string]any; wire null: false; omitempty: true
>   feesSkipped: boolean // bool; wire null: false; omitempty: false
>   tracerSkipped: boolean // bool; wire null: false; omitempty: false
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **transaction.reverted**
>
> **Event:** `studio.lerian.ledger.transaction.reverted`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** A revert flow creates a child transaction. `parentTransactionId` correlates it to the original.
>
> **Subject:** transaction ID (`p.ID`)
>
> ```typescript theme={null}
> // transaction.reverted
> type TransactionRevertedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   parentTransactionId?: string // *string; wire null: false; omitempty: true
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId: string // string; wire null: false; omitempty: false
>   status: MmodelStatus // mmodel.Status; wire null: false; omitempty: false
>   amount?: DecimalString // *decimal.Decimal; wire null: false; omitempty: true
>   assetCode: string // string; wire null: false; omitempty: false
>   chartOfAccountsGroupName?: string // string; wire null: false; omitempty: true
>   description?: string // string; wire null: false; omitempty: true
>   source?: string[] // []string; wire null: false; omitempty: true
>   destination?: string[] // []string; wire null: false; omitempty: true
>   route?: string // string; wire null: false; omitempty: true
>   routeId?: string // *string; wire null: false; omitempty: true
>   operations: JsonRawMessage[] // []json.RawMessage; wire null: false; omitempty: false
>   metadata?: Record<string, unknown> // map[string]any; wire null: false; omitempty: true
>   feesSkipped: boolean // bool; wire null: false; omitempty: false
>   tracerSkipped: boolean // bool; wire null: false; omitempty: false
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **transaction\_group.canceled**
>
> **Event:** `studio.lerian.ledger.transaction_group.canceled`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** A pending cross-ledger group is canceled.
>
> **Subject:** group ID (`p.GroupID`)
>
> ```typescript theme={null}
> // transaction_group.canceled
> type TransactionGroupCanceledDataV1 = {
>   groupId: string // string; wire null: false; omitempty: false
>   revertedGroupId?: string // *string; wire null: false; omitempty: true
>   status: string // string; wire null: false; omitempty: false
>   assetCode: string // string; wire null: false; omitempty: false
>   ledgerCount: number // int; wire null: false; omitempty: false
>   parts: TransactionGroupPart[] // []events.TransactionGroupPart; wire null: false; omitempty: false
>   occurredAt: string // string; wire null: false; omitempty: false
> }
> ```

> **transaction\_group.committed**
>
> **Event:** `studio.lerian.ledger.transaction_group.committed`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** A pending cross-ledger group is committed.
>
> **Subject:** group ID (`p.GroupID`)
>
> ```typescript theme={null}
> // transaction_group.committed
> type TransactionGroupCommittedDataV1 = {
>   groupId: string // string; wire null: false; omitempty: false
>   revertedGroupId?: string // *string; wire null: false; omitempty: true
>   status: string // string; wire null: false; omitempty: false
>   assetCode: string // string; wire null: false; omitempty: false
>   ledgerCount: number // int; wire null: false; omitempty: false
>   parts: TransactionGroupPart[] // []events.TransactionGroupPart; wire null: false; omitempty: false
>   occurredAt: string // string; wire null: false; omitempty: false
> }
> ```

> **transaction\_group.posted**
>
> **Event:** `studio.lerian.ledger.transaction_group.posted`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** A direct cross-ledger transaction completes. `parts` lists the transactions in the group.
>
> **Subject:** group ID (`p.GroupID`)
>
> ```typescript theme={null}
> // transaction_group.posted
> type TransactionGroupPostedDataV1 = {
>   groupId: string // string; wire null: false; omitempty: false
>   revertedGroupId?: string // *string; wire null: false; omitempty: true
>   status: string // string; wire null: false; omitempty: false
>   assetCode: string // string; wire null: false; omitempty: false
>   ledgerCount: number // int; wire null: false; omitempty: false
>   parts: TransactionGroupPart[] // []events.TransactionGroupPart; wire null: false; omitempty: false
>   occurredAt: string // string; wire null: false; omitempty: false
> }
> ```

> **transaction\_group.reverted**
>
> **Event:** `studio.lerian.ledger.transaction_group.reverted`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.0.0`
>
> **Trigger:** A cross-ledger group is reverted. `groupId` names the new group and `revertedGroupId` names the original.
>
> **Subject:** group ID (`p.GroupID`)
>
> ```typescript theme={null}
> // transaction_group.reverted
> type TransactionGroupRevertedDataV1 = {
>   groupId: string // string; wire null: false; omitempty: false
>   revertedGroupId?: string // *string; wire null: false; omitempty: true
>   status: string // string; wire null: false; omitempty: false
>   assetCode: string // string; wire null: false; omitempty: false
>   ledgerCount: number // int; wire null: false; omitempty: false
>   parts: TransactionGroupPart[] // []events.TransactionGroupPart; wire null: false; omitempty: false
>   occurredAt: string // string; wire null: false; omitempty: false
> }
> ```

> **transaction\_route.created**
>
> **Event:** `studio.lerian.ledger.transaction_route.created`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.1.0`
>
> **Trigger:** the creation of a transaction route.
>
> **Subject:** transaction-route ID (`p.ID`)
>
> ```typescript theme={null}
> // transaction_route.created
> type TransactionRouteCreatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId?: string // string; wire null: false; omitempty: true
>   title: string // string; wire null: false; omitempty: false
>   description?: string // string; wire null: false; omitempty: true
>   operationRouteIds?: string[] // []string; wire null: false; omitempty: true
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **transaction\_route.deleted**
>
> **Event:** `studio.lerian.ledger.transaction_route.deleted`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.1.0`
>
> **Trigger:** the deletion of a transaction route.
>
> **Subject:** transaction-route ID (`p.ID`)
>
> ```typescript theme={null}
> // transaction_route.deleted
> type TransactionRouteDeletedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId?: string // string; wire null: false; omitempty: true
>   deletedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **transaction\_route.updated**
>
> **Event:** `studio.lerian.ledger.transaction_route.updated`
>
> **Topic:** `lerian.streaming.ledger`
>
> **Route DLQ:** `lerian.streaming.ledger.dlq`
>
> **Schema:** `1.1.0`
>
> **Trigger:** A transaction route's mutable fields change.
>
> **Subject:** transaction-route ID (`p.ID`)
>
> ```typescript theme={null}
> // transaction_route.updated
> type TransactionRouteUpdatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   organizationId: string // string; wire null: false; omitempty: false
>   ledgerId?: string // string; wire null: false; omitempty: true
>   title: string // string; wire null: false; omitempty: false
>   description?: string // string; wire null: false; omitempty: true
>   operationRouteIds?: string[] // []string; wire null: false; omitempty: true
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```


# Midaz error list
Source: https://docs.lerian.studio/en/reference/products/midaz/error-list

Midaz APIs return a structured error object with a stable code, HTTP status, and message so you can quickly diagnose ledger issues and remediate them.

The Midaz API returns errors on `/v2` routes as an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details object, served with the `application/problem+json` content type:

```json theme={null}
{
   "type": "https://errors.lerian.studio/v1/<error_code>",
   "title": "<error_title>",
   "status": <http_status>,
   "detail": "<error_message>",
   "code": "<error_code>"
}
```

> [!NOTE]
>
> Routes under `/v1` return errors as `application/json` with `code`, `title`, and `message`. Validation errors on `/v1` can also carry `entityType` and `fields`.

**Field definitions**

* `type`: A URI that identifies the error type, built as `https://errors.lerian.studio/v1/` followed by the error code.
* `title`: A brief summary of the issue.
* `status`: The HTTP status code of the response.
* `detail`: Detailed guidance for resolving the error. The `message` column in the table below shows the text that the API returns. `%v` stands for a value that the response fills in.
* `code`: A unique, stable identifier for the error.
* `entityType`: The entity the error relates to (for example, `Organization`). Only present when applicable.

> [!NOTE]
>
> For server-side errors (HTTP 5xx), `title` and `detail` carry the catalog text. An unexpected error returns a generic body. Use `code` and `type` to identify the error.

**Field-level error details**

For issues specific to individual fields, an `errors` array lists each field with its problem.

Examples:

```json Missing Required Fields theme={null}
{
   "type": "https://errors.lerian.studio/v1/0009",
   "title": "Missing Fields in Request",
   "status": 400,
   "detail": "Your request is missing one or more required fields: [legalName]. Please refer to the documentation to ensure all necessary fields are included in your request.",
   "code": "0009",
   "entityType": "Organization",
   "errors": [
      { "location": "legalName", "message": "legalName is a required field" }
   ]
}
```

```json Invalid Field Values theme={null}
{
   "type": "https://errors.lerian.studio/v1/0047",
   "title": "Bad Request",
   "status": 400,
   "detail": "The server could not understand the request due to malformed syntax. Please check the listed fields and try again.",
   "code": "0047",
   "errors": [
      { "location": "legalName", "message": "legalName is a required field." },
      { "location": "parentOrganizationId", "message": "parentOrganizationId must be a valid UUID" }
   ]
}
```

```json Unexpected Fields theme={null}
{
   "type": "https://errors.lerian.studio/v1/0053",
   "title": "Unexpected Fields in the Request",
   "status": 400,
   "detail": "The request body contains more fields than expected. Please send only the allowed fields as per the documentation. The unexpected fields are listed in the fields object.",
   "code": "0053",
   "errors": [
      { "location": "unknownField", "message": "unexpected field", "value": "..." }
   ]
}
```

## Midaz errors

***

Refer to the following table for error codes and their descriptions:

| `code` | `title` | `message` |
| - | - | - |
| 0002 | `Ledger Name Conflict` | `A ledger named %v already exists in your organization. Please rename the ledger, or if you want to use the same name, consider creating a new ledger for a different division.` |
| 0003 | `Asset Name or Code Duplicate` | `An asset with the same name or code already exists in your ledger. Please modify the name or code of your new asset.` |
| 0004 | `Code Uppercase Requirement` | `The code must be in uppercase. Please ensure that the code is in uppercase format and try again.` |
| 0005 | `Currency Code Standard Compliance` | `Currency-type assets must comply with the ISO-4217 standard. Please use a currency code that conforms to ISO-4217 guidelines.` |
| 0007 | `Entity Not Found` | `No entity was found for the given ID. Please make sure to use the correct ID for the entity you are trying to manage.` |
| 0008 | `Action Not Permitted` | `The action you are attempting is not allowed in the current environment. Please refer to the documentation for guidance.` |
| 0009 | `Missing Fields in Request` | `Your request is missing one or more required fields: %v. Please refer to the documentation to ensure all necessary fields are included in your request.` |
| 0012 | `Account Balance Deletion Error` | `An account or sub-account cannot be deleted if it has a remaining balance. Please ensure all remaining balances are transferred to another account before attempting to delete.` |
| 0015 | `Duplicate Segment Name Error` | `A segment with the name %v already exists for this ledger ID %v. Please try again with a different ledger or name.` |
| 0018 | `Insufficient Funds Error` | `The transaction could not be completed due to insufficient funds in the account. Please add sufficient funds to your account and try again.` |
| 0019 | `Account Ineligibility Error` | `One or more accounts listed in the transaction are not eligible to participate. Please review the account statuses and try again.` |
| 0020 | `Alias Unavailability Error` | `The alias %v is already in use. Please choose a different alias and try again.` |
| 0024 | `Account Status Transaction Restriction` | `The current statuses of the source and/or destination accounts do not permit transactions. Change the account status(es) and try again.` |
| 0029 | `Invalid Parent Account ID` | `The specified parent account ID does not exist. Please verify the ID is correct and attempt your request again.` |
| 0030 | `Mismatched Asset Code` | `The parent account ID you provided is associated with a different asset code than the one specified in your request. Please make sure the asset code matches that of the parent account, or use a different parent account ID and try again.` |
| 0032 | `Invalid Country Code` | `The provided country code in the 'address.country' field does not conform to the ISO-3166 alpha-2 standard. Please provide a valid alpha-2 country code.` |
| 0033 | `Invalid Code Format` | `The 'code' field must be alphanumeric, in upper case, and must contain at least one letter. Please provide a valid code.` |
| 0034 | `Asset Code Not Found` | `The provided asset code does not exist in our records. Please verify the asset code and try again.` |
| 0035 | `Portfolio ID Not Found` | `The provided portfolio ID does not exist in our records. Please verify the portfolio ID and try again.` |
| 0036 | `Segment ID Not Found` | `The provided segment ID does not exist in our records. Please verify the segment ID and try again.` |
| 0037 | `Ledger ID Not Found` | `The provided ledger ID does not exist in our records. Please verify the ledger ID and try again.` |
| 0038 | `Organization ID Not Found` | `The provided organization ID does not exist in our records. Please verify the organization ID and try again.` |
| 0039 | `Parent Organization ID Not Found` | `The provided parent organization ID does not exist in our records. Please verify the parent organization ID and try again.` |
| 0040 | `Invalid Type` | `The provided 'type' is not valid. Accepted types are currency, fiat, crypto, commodity, or others. Please provide a valid type.` |
| 0042 | `Invalid Token` | `The provided token is expired, invalid or malformed. Please provide a valid token and try again.` |
| 0043 | `Insufficient Privileges` | `You do not have the necessary permissions to perform this action. Please contact your administrator if you believe this is an error.` |
| 0046 | `Internal Server Error` | `The server encountered an unexpected error. Please try again later or contact support.` |
| 0047 | `Bad Request` | `The server could not understand the request due to malformed syntax. Please check the listed fields and try again.` |
| 0050 | `Metadata Key Length Exceeded` | `The metadata key %v exceeds the maximum allowed length of %v characters. Please use a shorter key.` |
| 0051 | `Metadata Value Length Exceeded` | `The metadata value %v exceeds the maximum allowed length of %v characters. Please use a shorter value.` |
| 0052 | `Account ID Not Found` | `The provided account ID does not exist in our records. Please verify the account ID and try again.` |
| 0053 | `Unexpected Fields in the Request` | `The request body contains more fields than expected. Please send only the allowed fields as per the documentation. The unexpected fields are listed in the fields object.` |
| 0055 | `Asset ID Not Found` | `The provided asset ID does not exist in our records. Please verify the asset ID and try again.` |
| 0056 | `No Assets Found` | `No assets were found in the search. Please review the search criteria and try again.` |
| 0057 | `No Segments Found` | `No segments were found in the search. Please review the search criteria and try again.` |
| 0058 | `No Portfolios Found` | `No portfolios were found in the search. Please review the search criteria and try again.` |
| 0059 | `No Organizations Found` | `No organizations were found in the search. Please review the search criteria and try again.` |
| 0060 | `No Ledgers Found` | `No ledgers were found in the search. Please review the search criteria and try again.` |
| 0064 | `No Accounts Found` | `No accounts were found in the search. Please review the search criteria and try again.` |
| 0065 | `Invalid Path Parameter` | `One or more path parameters are in an incorrect format. Please check the following parameters %v and ensure they meet the required format before trying again.` |
| 0066 | `Invalid Account Type` | `The provided 'type' is not valid.` |
| 0067 | `Invalid Metadata Nesting` | `The metadata object cannot contain nested values. Please ensure that the value %v is not nested and try again.` |
| 0068 | `Operation ID Not Found` | `The provided operation ID does not exist in our records. Please verify the operation ID and try again.` |
| 0069 | `No Operations Found` | `No operations were found in the search. Please review the search criteria and try again.` |
| 0070 | `Transaction ID Not Found` | `The provided transaction ID does not exist in our records. Please verify the transaction ID and try again.` |
| 0071 | `No Transactions Found` | `No transactions were found in the search. Please review the search criteria and try again.` |
| 0072 | `Invalid Transaction Type` | `Only one transaction type (%v) must be specified in the '%v' field for each entry. Please review your input and try again.` |
| 0073 | `Transaction Value Mismatch` | `The values for the source, the destination, or both do not match the specified transaction amount. Please verify the values and try again.` |
| 0074 | `External Account Modification Prohibited` | `Accounts of type 'external' cannot be deleted or modified as they are used for traceability with external systems. Please review your request and ensure operations are only performed on internal accounts.` |
| 0077 | `Invalid Date Format Error` | `The 'initialDate', 'finalDate', or both are in the incorrect format. Please use the 'yyyy-mm-dd' format and try again.` |
| 0078 | `Invalid Final Date Error` | `The 'finalDate' cannot be earlier than the 'initialDate'. Please verify the dates and try again.` |
| 0079 | `Date Range Exceeds Limit Error` | `The range between 'initialDate' and 'finalDate' exceeds the permitted limit of %v months. Please adjust the dates and try again.` |
| 0080 | `Pagination Limit Exceeded` | `The pagination limit exceeds the maximum allowed of %v items per page. Please verify the limit and try again.` |
| 0081 | `Invalid Sort Order` | `The 'sort_order' field must be 'asc' or 'desc'. Please provide a valid sort order and try again.` |
| 0082 | `Invalid Query Parameter` | `One or more query parameters are in an incorrect format. Please check the following parameters '%v' and ensure they meet the required format before trying again.` |
| 0083 | `Invalid Date Range Error` | `Both 'initialDate' and 'finalDate' fields are required and must be in the 'yyyy-mm-dd' format. Please provide valid dates and try again.` |
| 0084 | `Duplicate Idempotency Key` | `The idempotency key %v is already in use. Please provide a unique key and try again.` |
| 0085 | `Account Alias Not Found` | `The provided account Alias does not exist in our records. Please verify the account Alias and try again.` |
| 0087 | `Transaction Revert already exist` | `Transaction revert already exists. Please try again.` |
| 0088 | `Transaction is already a reversal` | `Transaction is already a reversal. Please try again` |
| 0089 | `Transaction can't be reverted` | `Transaction can't be reverted. Please try again` |
| 0090 | `Transaction ambiguous account` | `Transaction can't use the same account in sources and destinations` |
| 0091 | `ID cannot be used as the parent ID` | `The provided ID cannot be used as the parent ID. Please choose a different one.` |
| 0093 | `Balance cannot be deleted` | `Balance cannot be deleted because it still has funds in it.` |
| 0094 | `Unmarshalling error` | `invalid value for field '%v': expected type '%v', but got '%v'` |
| 0095 | `Message Broker Unavailable` | `The server encountered an unexpected error while connecting to Message Broker. Please try again later or contact support.` |
| 0096 | `Invalid Account Alias` | `The alias contains invalid characters. Please verify the alias value and try again.` |
| 0098 | `Invalid Pending Transaction` | `External accounts cannot be used for pending transactions in source operations. Please check the accounts and try again.` |
| 0099 | `Invalid Transaction Status` | `The transaction status does not allow the requested action. Please check the transaction status.` |
| 0101 | `Operation Route Not Found` | `The provided operation route does not exist in our records. Please verify the operation route and try again.` |
| 0102 | `No Operation Routes Found` | `No operation routes were found in the search. Please review the search criteria and try again.` |
| 0103 | `Invalid Operation Route Type` | `The provided 'operationType' is not valid. Accepted types are 'source', 'destination', or 'bidirectional'. Please provide a valid type.` |
| 0104 | `Missing Operation Routes in Request` | `Your request must include at least one operation route of each type (debit and credit). Please refer to the documentation to ensure these fields are properly populated.` |
| 0105 | `Transaction Route Not Found` | `The provided transaction route does not exist in our records. Please verify the transaction route and try again.` |
| 0106 | `No Transaction Routes Found` | `No transaction routes were found in the search. Please review the search criteria and try again.` |
| 0107 | `Operation Route Linked to Transaction Routes` | `The operation route cannot be deleted because it is linked to one or more transaction routes. Please remove the operation route from all transaction routes before attempting to delete it.` |
| 0108 | `Duplicate Account Type Key Value Error` | `An account type with the specified key value already exists for this organization and ledger. Please use a different key value or update the existing account type.` |
| 0109 | `Account Type Not Found Error` | `The account type you are trying to access does not exist or has been removed.` |
| 0110 | `No Account Types Found` | `No account types were found in the search. Please review the search criteria and try again.` |
| 0111 | `Invalid Account Rule Type` | `The provided 'account.ruleType' is not valid. Accepted types are 'alias' or 'account_type'. Please provide a valid rule type.` |
| 0112 | `Invalid Account Rule Value` | `The provided 'account.validIf' is not valid. Please provide a string for 'alias' or an array of strings for 'account_type'.` |
| 0113 | `Corrupted Account Rule` | `The account rule data in the operation route is internally inconsistent (unknown rule type or malformed validIf value). This indicates a data integrity issue — please verify the operation route configuration.` |
| 0114 | `Transaction Route Not Informed` | `The transaction route is not informed. Please inform the transaction route for this transaction.` |
| 0115 | `Invalid Transaction Route ID` | `The provided transaction route ID is not a valid UUID format. Please provide a valid UUID for the transaction route.` |
| 0116 | `Accounting Route Count Mismatch` | `The operation routes count does not match the transaction route cache. Expected %v source and %v destination operations, but the route has %v source, %v destination, and %v bidirectional operation routes.` |
| 0117 | `Accounting Route Not Found` | `The operation route ID '%v' was not found in the transaction route cache for operation '%v'. Please verify the route configuration.` |
| 0118 | `Accounting Alias Validation Failed` | `The operation alias '%v' does not match the expected alias '%v' defined in the accounting route rule.` |
| 0119 | `Accounting Account Type Validation Failed` | `The account type '%v' does not match any of the expected account types %v defined in the accounting route rule.` |
| 0120 | `Invalid Characters` | `The field 'keyValue' contains invalid characters. Use only letters, numbers, underscores and hyphens.` |
| 0121 | `Invalid Future Date Error` | `The 'transactionDate' cannot be a future date. Please provide a valid date.` |
| 0122 | `Invalid Field for Pending Transaction Error` | `Pending transactions do not support the 'transactionDate' field. To proceed, please remove it from your request.` |
| 0123 | `Duplicated Alias Key Value Error` | `An account alias with the specified key value already exists for this organization and ledger. Please use a different key value.` |
| 0124 | `Additional Balance Creation Not Allowed` | `Additional balances are not allowed for external account type.` |
| 0125 | `Invalid Transaction Value` | `Negative or zero transaction values are not allowed. The 'send.value' must be greater than zero.` |
| 0127 | `Account Creation Failed` | `The account could not be created because the default balance could not be created. Please try again.` |
| 0128 | `Transaction Backup Cache Failed` | `The server encountered an unexpected error while adding the transaction to the backup cache. Please try again later or contact support.` |
| 0129 | `Transaction Backup Cache Marshal Failed` | `The server encountered an unexpected error while serializing the transaction for the backup cache. This uses the same backup mechanism. Please try again later or contact support.` |
| 0131 | `Invalid Datetime Format Error` | `The '%v' parameter is in the incorrect format. Please use the '%v' format and try again.` |
| 0132 | `Metadata Index Already Exists` | `A metadata index with the same key already exists for this entity. Please use a different key from the existing index.` |
| 0133 | `Metadata Index Not Found` | `The specified metadata index does not exist. Please verify the index name and try again.` |
| 0137 | `Metadata Index Deletion Forbidden` | `System indexes cannot be deleted. Please ensure you are deleting a custom metadata index.` |
| 0138 | `Invalid Entity Name` | `The provided entity name is not valid.` |
| 0139 | `Transaction Backup Cache Retrieval Failed` | `The transaction could not be retrieved from the backup cache internal function. Please ensure the transaction exists in the cache before processing balances.` |
| 0140 | `Invalid Timestamp` | `The provided timestamp '%v' is invalid. Timestamps cannot be in the future.` |
| 0141 | `No Balance Data at Date` | `No balance data is available at the specified date.` |
| 0142 | `Missing Required Query Parameter` | `The required query parameter '%v' is missing from the request.` |
| 0143 | `Payload Too Large` | `The request payload exceeds the maximum allowed size of 64KB.` |
| 0144 | `JSON Nesting Depth Exceeded` | `The JSON payload exceeds the maximum allowed nesting depth of 10 levels. Please flatten your data structure.` |
| 0145 | `JSON Key Count Exceeded` | `The JSON payload exceeds the maximum allowed number of keys (100). Please reduce the number of keys in your payload.` |
| 0146 | `Tenant Not Provisioned` | `Database schema not initialized for this tenant. Contact your administrator.` |
| 0147 | `Unknown Settings Field` | `The settings contain an unknown field: '%v'. Only known settings fields are allowed.` |
| 0148 | `Invalid Settings Field Type` | `The settings field '%v' has an invalid type. Expected %v.` |
| 0149 | `Settings Field at Root Level` | `The settings field '%v' must be nested under '%v'. Expected structure: {"%v": {"%v": value}}.` |
| 0150 | `Route Not Bidirectional` | `The operation route does not allow bidirectional transactions. Only routes with operation type 'bidirectional' can be reverted.` |
| 0151 | `Missing Counterpart` | `Route '%v' requires at least one debit and one credit operation (counterpart validation).` |
| 0152 | `Direction Route Mismatch` | `Operation direction '%v' is not compatible with route operation type '%v' for operation '%v'.` |
| 0153 | `No Source for Action` | `The action '%v' requires at least one source operation route. Please add a source route for this action.` |
| 0154 | `No Destination for Action` | `The action '%v' requires at least one destination operation route. Please add a destination route for this action.` |
| 0157 | `No Routes for Action` | `No routes found for action '%v'. Please configure operation routes for this action in the transaction route.` |
| 0158 | `Too Many Operation Routes` | `The number of operation routes exceeds the maximum allowed. Please reduce the number of operation routes and try again.` |
| 0159 | `Service Suspended` | `service is %v for tenant %v` |
| 0160 | `Tenant Not Found` | `tenant not found: %v` |
| 0161 | `Tenant Service Unavailable` | `failed to resolve tenant %v` |
| 0162 | `Scenario Not Allowed For Direction` | `The accounting scenario is not allowed for the specified operation direction. %v` |
| 0163 | `Reserve Group Incomplete` | `The reserve group (hold, commit, cancel) must be complete. %v` |
| 0164 | `Direct Scenario Required` | `The direct scenario is required when other scenarios are present. %v` |
| 0165 | `Revert Only Bidirectional` | `The revert scenario is only allowed for bidirectional operation routes. %v` |
| 0166 | `Accounting Entry Field Required` | `A required field is missing in the accounting entry. %v` |
| 0167 | `Overdraft Limit Exceeded Error` | `The transaction could not be completed because it would exceed the configured overdraft limit for the balance. Please reduce the amount or increase the overdraft limit and try again.` |
| 0168 | `Direct Operation On Internal Balance Error` | `Direct operations on internal-scope balances are not permitted. Internal balances are managed exclusively by the system. Please target a transactional balance and try again.` |
| 0169 | `Deletion Of Internal Balance Error` | `Internal-scope balances cannot be deleted. They are managed by the system and must remain for accounting consistency.` |
| 0170 | `Reserved Balance Key Error` | `The balance key %v is reserved for system use and cannot be created through the public API. Please choose a different key and try again.` |
| 0171 | `Invalid Balance Direction Error` | `The balance direction %v is not supported. Allowed values are "credit" and "debit".` |
| 0172 | `Invalid Balance Settings Error` | `The balance settings payload is invalid. Please review overdraft, limit, and scope fields and try again.` |
| 0173 | `Overdraft Limit Below Usage Error` | `The new overdraft limit is below the amount currently used. Raise the limit above the current usage or repay the outstanding amount before reducing the limit.` |
| 0174 | `Stale Balance Version Error` | `The balance was modified by another transaction between read and write. Please retry the operation after reading the latest balance state.` |
| 0175 | `Update Of Internal Balance Error` | `Internal balances are system-managed and cannot be updated through the public API. They are maintained by the system for accounting consistency.` |
| 0176 | `Invalid Settings Field Value` | `The settings field '%v' has an invalid value. Allowed values are: %v.` |
| 0177 | `Transaction Reservation Denied Error` | `The transaction could not be completed because it would exceed a configured usage limit. Please reduce the amount or wait for the limit window to reset and try again.` |
| 0178 | `Transaction Reservation Unavailable Error` | `The transaction could not be completed because the usage-limit service is temporarily unavailable and this ledger is configured to reject transactions when it cannot be reached. Please retry shortly.` |
| 0180 | `Invalid fee priority` | `The priority field in fees is invalid. Field can not be repeated.` |
| 0182 | `minimumAmount greater than maximumAmount` | `minimumAmount value is greater than maximumAmount.` |
| 0183 | `Nothing to Update` | `No updatable fields were provided. Please include at least one field to update.` |
| 0184 | `Package already exists` | `A package already exists in the same scope with the same minimumAmount and maximumAmount.` |
| 0185 | `Invalid header parameter` | `One or more header parameters are in an incorrect format. Please check the following parameters %v and ensure they meet the required format before trying again.` |
| 0186 | `Failed to calculate fee` | `Failed to calculate the fee for the transaction. Please check the fee configuration and try again.` |
| 0187 | `Missing calculation model` | `The calculation model is required for fee %v.` |
| 0188 | `originalAmount is required when priority is one` | `For Priority equals to one, referenceAmount must be 'originalAmount' for fee %v.` |
| 0189 | `Failed to apply rule: flatFee or percentual` | `applicationRule flatFee or percentual must have exactly 1 calculation for Fee %v.` |
| 0190 | `Invalid calculation type: percentual` | `The calculation type percentual must be 'percentage' for Fee %v.` |
| 0191 | `Invalid calculation type: flatFee` | `The calculation type flatFee must be 'flat' for Fee %v.` |
| 0192 | `Missing required fee fields` | `All fields of a new Fee must be filled. Please check again the payload passed.` |
| 0193 | `Calculation field is required for fee` | `Please fill the Calculation object correctly. All calculation fields must be filled.` |
| 0194 | `referenceAmount is not valid` | `Field reference amount must be originalAmount or afterFeesAmount.` |
| 0195 | `Invalid applicationRule` | `Field application rule must be maxBetweenTypes, flatFee or percentual.` |
| 0196 | `Invalid calculation type` | `Field calculation type must be percentage or flat.` |
| 0197 | `maximumAmount less than minimumAmount` | `maximumAmount value is less than minimumAmount.` |
| 0198 | `Package filtering error` | `More than one fee package matches this transaction at the same specificity, so none of them can be applied. Re-scope one of these packages: %v.` |
| 0199 | `Package amount range overlap` | `The maximumAmount and minimumAmount of the new package overlap with the amount range of an existing package.` |
| 0200 | `Failed to distribute values` | `Failed to distribute the transaction values. Please check the data passed.` |
| 0201 | `Failed to apply rule: maxBetweenTypes` | `applicationRule maxBetweenTypes must have more than 1 calculation for Fee %v.` |
| 0202 | `Invalid segmentID` | `The specified segmentID is not a valid UUID. Please check the value passed.` |
| 0204 | `Error to convert values` | `The value of the field %v is invalid. Remember to use dot (.) as decimal separator instead of comma (,). Example: use 1000.50 instead of 1000,50.` |
| 0205 | `originalAmount is required when isDeductibleFrom is true` | ``For isDeductibleFrom `true`, referenceAmount must be 'originalAmount' for fee %v.`` |
| 0206 | `applicationRule invalid value` | `applicationRule is invalid, Err: %v.` |
| 0207 | `calculation value percentage invalid` | `Calculation value is invalid, it cannot exceed 100%. Please check the calculation value for Fee %v.` |
| 0208 | `calculation value flat invalid` | `Calculation value is invalid, it cannot exceed the minimum amount %v. Please check the calculation value for Fee %v.` |
| 0210 | `deductible value forbidden` | `Can not update deductible value to true. The calculation value is bigger than 100% for Fee %v.` |
| 0211 | `deductible value forbidden` | `Can not update deductible value to true. Calculation value is bigger than the minimum amount %v for Fee %v.` |
| 0212 | `Invalid Page` | `Query parameter page is invalid. The page must be greater than 0.` |
| 0213 | `Billing package not found` | `No billing package was found for the given ID '%v'.` |
| 0214 | `Invalid billing package type` | `The billing package type is invalid. Valid types are 'volume' and 'maintenance'.` |
| 0215 | `Missing volume fields` | `Volume billing packages require: eventFilter (transactionRoute, status), pricingModel, tiers, assetCode, debitAccountAlias, and creditAccountAlias.` |
| 0216 | `Missing maintenance fields` | `Maintenance billing packages require: feeAmount, assetCode, maintenanceCreditAccount, and accountTarget.` |
| 0217 | `Invalid pricing model` | `The pricing model is invalid. Valid models are 'tiered' and 'fixed'.` |
| 0218 | `Invalid pricing tier` | `Pricing tier configuration is invalid: %v.` |
| 0219 | `Billing route overlap` | `A billing package already exists for this organization, ledger, and transaction route combination.` |
| 0221 | `Billing calculation failed` | `Failed to calculate billing: %v` |
| 0224 | `Invalid billing period` | `The billing period format is invalid. Use 'YYYY-MM' (monthly), 'YYYY-Www' (weekly, e.g. '2026-W13'), or 'YYYY-MM-DD' (daily) format (e.g., '2026-01' or '2026-01-15').` |
| 0225 | `Invalid free quota` | `The free quota value is invalid. Must be a non-negative integer.` |
| 0226 | `Invalid discount tier` | `Discount tier configuration is invalid. Each tier must have minQuantity and discountPercentage between 0 and 100.` |
| 0227 | `Invalid count mode` | `The count mode is invalid. Valid modes are 'perRoute' and 'perAccount'.` |
| 0229 | `Invalid account target` | `The account target is invalid. Exactly one of segmentId, portfolioId, or aliases must be provided.` |
| 0230 | `Invalid fee amount` | `The fee amount is invalid. It must be a positive value greater than zero.` |
| 0231 | `Segment context unavailable` | `Segment-based waivers are configured but the resolution service is not available. This is an internal configuration issue.` |
| 0233 | `Deductible fee exceeds the amount it deducts from` | `A deductible fee cannot be applied because it meets or exceeds the amount it is deducted from, which would leave the recipient with nothing or a negative balance. Reduce the fee, increase the transfer amount, or exempt the account.` |
| 0235 | `Query Parameter Not Accepted` | `The query parameter '%v' is not accepted on this endpoint because the request path already names the ledger. Please remove it and try again.` |
| 0236 | `Duplicate fee key` | `More than one fee in this request resolves to the key '%v', so the fee it applies to is ambiguous. Please send each fee once.` |
| 0249 | `Cross-Ledger Not Enabled Error` | `Ledger %v is not enabled for cross-ledger transactions. Enable crossLedger.enabled on every ledger involved.` |
| 0250 | `Cross-Ledger Asset Mismatch Error` | `Cross-ledger transactions must use the same asset on every leg.` |
| 0251 | `Cross-Organization Route Validation Unsupported Error` | `Cross-ledger transactions that span more than one organization are not supported when accounting route validation is enabled on a participating ledger, because accounting routes belong to a single organization.` |
| 0252 | `Cross-Ledger Lifecycle Requires V2 Error` | `A transaction that belongs to a cross-ledger group must be committed, canceled, or reverted through the v2 API so the complete group is transitioned atomically.` |
| 0253 | `Cross-Ledger Group Incomplete Error` | `The cross-ledger transaction group is incomplete and cannot be transitioned safely.` |
| 0254 | `Cross-Ledger Group Not Pending Error` | `The cross-ledger transaction group is %v and can no longer be committed or canceled.` |
| 0255 | `Cross-Ledger Route Not Configured Error` | `The transaction could not be completed because route validation is enabled on a participating ledger but the transaction route has no operation route with a crossLedger accounting entry for the cross-ledger bridge. Link a bidirectional operation route with a crossLedger entry to the transaction route and try again.` |
| 0256 | `Invalid Cross-Ledger Route Error` | `The cross-ledger bridge route must resolve to exactly one operation route. %v` |
| 0336 | `Metadata Key Invalid Chars` | `Metadata key contains invalid characters.` |
| 0484 | `Route Not Found` | `The requested route does not exist. Please verify the HTTP method and path and try again.` |
| 0485 | `Method Not Allowed` | `The HTTP method is not allowed for the requested route. Please verify the method and try again.` |
| 0486 | `Transaction Locked` | `This transaction is currently being processed by another request. Please retry shortly.` |
| 0488 | `Instrument Ledger Reference Not Found` | `The ledger referenced by this instrument does not exist in this organization. Please provide a ledgerId that belongs to the organization and try again.` |
| 0489 | `Instrument Account Reference Not Found` | `The account referenced by this instrument does not exist in the referenced ledger. Please provide an accountId that belongs to the ledger and try again.` |
| 0490 | `Skip Not Permitted` | `The %v skip requested for this operation is not permitted on this ledger. Enable the matching ledger override to allow it, or remove the skip from your request.` |
| 0491 | `Holder Required` | `This ledger requires every account to name an existing holder. Please provide a valid holderId and try again.` |
| 0492 | `Overdraft Route Not Configured Error` | `The transaction could not be completed because route validation is enabled but the accounting route applied to the overdraft operation does not define an overdraft entry for the required direction. Configure an overdraft accounting entry on the operation route and try again.` |
| 0497 | `Request Header Fields Too Large` | `The request header fields are too large. Please reduce the size of the request headers and try again.` |
| 0498 | `Invalid Dashboard Window` | `Invalid dashboard window: use period (7d, 30d, 90d) or start_date/end_date (RFC3339, at most 90 days apart), never both.` |
| 0499 | `Transaction Scope Mismatch` | `Every leg of the transaction must name the same organization and ledger. Please review your input so that all legs share one scope and try again.` |
| 0500 | `Invalid Account Type Direction` | `The field 'defaultDirection' has an invalid value. Use one of the allowed values: credit or debit.` |
| 0501 | `Schema Migration Pending` | `The request could not be completed because a pending database migration has not been applied to this database yet. Please retry shortly.` |
| 0502 | `Account Blocked` | `A source and/or destination account involved in this transaction is blocked and cannot transact. Unblock the account and try again.` |
| 0503 | `Missing Account Block Exceptions` | `The 'exceptions' field must carry at least one exception. Please provide the exceptions to create and try again.` |
| 0504 | `Account Block Exception Batch Too Large` | `The 'exceptions' field accepts at most 100 items per request. Please split the batch and try again.` |
| 0505 | `Invalid Account Block Exception Amount` | `The 'amount' of the exception at index %v must be a positive decimal value. Please verify the amount and try again.` |
| 0506 | `Invalid Account Block Exception TTL` | `The 'ttl' of the exception at index %v must be between 1 and 86400 seconds. Please verify the ttl and try again.` |
| 0507 | `Account Block Exception Alias Not Found` | `The 'accountAlias' of the exception at index %v does not exist in this ledger: %v. No exception was created. Please verify the alias and try again.` |
| 0508 | `Invalid Account Block Exception` | `The 'accountBlockExceptionId' presented does not exist, has expired or has already been used, or does not authorize this transaction's source account and debited amount. Please create a new exception and try again.` |
| 0509 | `Account Block Exception Not Supported` | `The 'accountBlockExceptionId' field is not accepted on the %v operation. Please present it on the direct, commit or revert operation instead.` |
| 0511 | `Transaction Already Transitioned` | `The transaction has already been committed or canceled, so the requested transition cannot run again. Please check the transaction status.` |
| 0512 | `Reserved Metadata Key` | `The metadata key %v is reserved by the ledger, which writes it itself. Please remove it from your request and try again.` |
| 0513 | `Balance Seed Rebuild Inconsistent Error` | `The request could not be completed because the current state of this balance could not be established from its operation history. Please retry shortly.` |
| 0514 | `Invalid Transaction Batch Cardinality` | `The transaction batch contains %v items, but it must contain between 1 and %v items. Please adjust the 'transactions' array and try again.` |
| 0515 | `Transaction Batch Input Leg Limit Exceeded` | `The transaction batch contains %v input debit and credit legs, exceeding the maximum of %v. Please reduce the number of legs and try again.` |
| 0516 | `Transaction Batch Budget Exceeded` | `The transaction batch exceeds the %v budget at transaction index %v: observed %v, maximum %v. Please reduce the batch work and try again.` |
| 0517 | `Invalid Transaction Batch` | `One or more transactions in the batch failed structural validation. Check errors for details.` |
| 0518 | `Account Closing Persistence Pending Error` | `The account cannot be closed yet because earlier work on it has not finished being persisted. No transaction is reapplied; please try again shortly.` |
| 0519 | `Account Closed Error` | `The operation could not be completed because the account is closed. A closed account accepts no further movements, and unblocking it does not reopen it.` |
| 0520 | `Account Closing Protection Indeterminate Error` | `The request could not be completed because the state of this account could not be established. Please retry shortly.` |
| 0521 | `Account Already Closed Error` | `The account is already closed and cannot be closed again. The recorded closing instant is preserved; please review the account state and try again if this was unexpected.` |
| 0522 | `Account Closing In Progress Error` | `A closing of this account is in progress. Please wait for it to conclude and try again.` |
| 0523 | `Account Balance Not Zero Error` | `The account cannot be closed because at least one of its balances still holds available funds, funds on hold or used overdraft. Please settle every balance to exactly zero and try again.` |
| 0524 | `Account Has Pending Transactions Error` | `The account cannot be closed because a pending transaction still holds its funds. Please commit or cancel those transactions and try again.` |
| 0525 | `Authorization Service Unavailable` | `The request could not be completed because the authorization service did not respond. Please retry shortly.` |
| 0526 | `Account Administrative Operation In Progress Error` | `Another operation on this account is in progress. Please try again shortly.` |
| 0527 | `Balance Has Open Fee Debt Error` | `A balance that still owes pending fees cannot be deleted, and its account cannot be deleted or closed. Please credit the balance so the pending fees are collected and try again.` |
| 0528 | `Balance Owed Fee Debt Error` | `A balance that other balances still owe pending fees to cannot be deleted, and its account cannot be deleted or closed. Please credit the balances that owe those fees so they are collected and try again.` |
| 0529 | `Fee Debt Record Pending Error` | `The pending fees this transaction touches have not finished being recorded. No transaction is reapplied; please try again shortly.` |
| 0530 | `Deductible fee cannot be deferrable` | `Fee %v is deducted from the payment (isDeductibleFrom true), so it cannot be deferrable. Set deferrable to false or isDeductibleFrom to false.` |
| 0531 | `Transaction Reservation Review Error` | `The transaction was flagged for review by a transaction validation rule, or a rule could not be evaluated for it, and this ledger enforces tracer decisions. Review the tracer rules or the ledger tracer settings.` |
| 0532 | `Transaction Reservation Rejected Error` | `The usage-limit service rejected the reservation request for this transaction. Verify that the asset, account type and transaction date are accepted by the tracer configuration.` |
| 0535 | `Transaction Reservation Rule Denied Error` | `The transaction was denied by a transaction validation rule and this ledger enforces tracer decisions. Review the tracer rules or the ledger tracer settings.` |
| 0536 | `Transaction Reservation Unauthorized Error` | `The tracer reservation seam rejected this ledger's credential and the ledger enforces tracer decisions with a closed fail posture. Check the ledger's Access Manager client and the tracer's allowed clients.` |
| CRM-0006 | `Holder ID Not Found` | `The provided holder ID does not exist in our records. Please verify the holder ID and try again.` |
| CRM-0008 | `Instrument ID Not Found` | `The provided instrument ID does not exist in our records. Please verify the instrument ID and try again.` |
| CRM-0010 | `Document Association Error` | `A document can only be associated with one holder.` |
| CRM-0013 | `Account Already Associated` | `An accountId from ledger can only be associated with a single related account on CRM.` |
| CRM-0017 | `Unable to Delete Holder` | `The holder cannot be deleted because it has one or more associated aliases.` |
| CRM-0023 | `Alias Closing Date Before Creation Date` | `The alias closing date cannot be before the creation date. Please provide a valid closing date.` |
| CRM-0024 | `Related Party Not Found` | `The specified related party does not exist. Please verify the related party ID and try again.` |
| CRM-0025 | `Invalid Related Party Role` | `The provided related party role is not valid. Accepted roles are: PRIMARY_HOLDER, LEGAL_REPRESENTATIVE, or RESPONSIBLE_PARTY.` |
| CRM-0026 | `Related Party Document Required` | `The related party document is required. Please provide a valid document.` |
| CRM-0027 | `Related Party Name Required` | `The related party name is required. Please provide a valid name.` |
| CRM-0028 | `Related Party Start Date Required` | `The related party start date is required. Please provide a valid start date.` |
| CRM-0029 | `Related Party End Date Invalid` | `The related party end date must be after the start date. Please provide a valid end date.` |
| CRM-0030 | `Unable to Delete Holder` | `The holder cannot be deleted because it owns one or more active accounts.` |
| CRM-0038 | `Provisioning Failed` | `The provisioning operation failed. Please try again later.` |
| CRM-0041 | `Reserved Tenant ID` | `The tenant id "default" is reserved for internal single-tenant use and cannot be used as a tenant identifier. Please use a different tenant id and try again.` |
| CRM-0042 | `Invalid Instrument Account Type` | `The provided instrument account type is not valid. Accepted values are: DEPOSIT, SAVINGS, INVESTMENT, OTHER_FINANCIAL_INVESTMENTS, NON_RESIDENT, or PAYMENT.` |
| CRM-0043 | `Bank Account Already Registered` | `This bank account is already registered to another instrument in this organization: the same bankId and account, on the same branch or where one of them has no branch. Use that instrument, or delete it before registering the account again.` |


# Quick start guide
Source: https://docs.lerian.studio/en/reference/products/midaz/quick-start-guide

Set up Midaz for the first time, from environment installation and configuration to creating your first ledger structure.

> [!TIP]
>
> **This guide is intended for developers** setting up Midaz for the first time. If you're looking for a business-level overview of how Midaz works, see [What is Midaz?](/en/products/midaz/what-is-midaz). For deployment options, see [SaaS and BYOC](/en/start-here/evaluate-and-deploy/deployment-models).

Follow these steps to set up Midaz.

## Step 1 - Set up your environment

***

To set up your Midaz environment, follow the steps in the [Installing Midaz monorepo](/en/products/midaz/midaz-setup) page.

* This will install Midaz Ledger.

### Authentication and authorization

Midaz does not include a built-in authentication or authorization system. You can integrate Midaz with your existing identity provider or security stack.

If you need a ready-to-use solution, you can enable **Access Manager**, an optional feature developed by Lerian. It handles authentication and authorization for Midaz and other Lerian products.

> [!TIP]
>
> Access Manager supports common identity standards like OAuth2 and OIDC. For more details, refer to the [Access Manager](/en/platform/access-manager) guide.

## Step 2 - Create your Midaz structure

***

Start by creating the data structure that your workflows use.

### Step 2.1 - Create an Organization

The first step is to create your Organization within Midaz.

* [**To create an Organization, use the Create an Organization endpoint.**](/en/reference/products/midaz/v2/create-organization)

> [!TIP]
>
> If your organization has multiple branches, you can create various Organizations and designate a **Parent Organization**.
>
> For example, if Company XYZ has branches in New York and Brazil, you can create an Organization for Company XYZ and set it as the parent of XYZ New York and XYZ Brazil.

For a complete list of endpoints to manage your Organization, expand the section below:

> **Managing Organizations**
>
> * Retrieve all Organizations using the [List Organizations](/en/reference/products/midaz/v2/list-organizations) endpoint.
> * Retrieve a specific Organization with the [Retrieve an Organization](/en/reference/products/midaz/v2/get-organization-by-id)
> * Update Organization details using the [Update an Organization](/en/reference/products/midaz/v2/update-organization) endpoint.
> * Delete an Organization in Homologation using the [Delete an Organization](/en/reference/products/midaz/v2/delete-organization) endpoint.
>   * For Organizations in Production, deletion requires contacting Lerian support for security purposes.

### Step 2.2 - Create a Ledger

Create at least one Ledger in each Organization. You can create multiple Ledgers if needed.

* [**To create a Ledger, use the Create a Ledger endpoint.**](/en/reference/products/midaz/v2/create-ledger)

For a complete list of endpoints to manage your Ledger, expand the section below:

> **Managing Ledgers**
>
> * Retrieve all Ledgers using the [List Ledgers](/en/reference/products/midaz/v2/list-ledgers) endpoint.
> * Retrieve a specific Ledger with the [Retrieve a Ledger](/en/reference/products/midaz/v2/get-ledger-by-id) endpoint.
> * Update Ledger details using the [Update a Ledger](/en/reference/products/midaz/v2/update-ledger) endpoint.
> * Delete a Ledger in Homologation using the [Delete a Ledger](/en/reference/products/midaz/v2/delete-ledger) endpoint.
>   * For Ledgers in Production, deletion requires contacting Lerian support for security purposes.

### Step 2.3 - Create the Assets

Each Ledger can have multiple Assets. Create each Asset individually.

* [**To create an Asset, use the Create an Asset endpoint.**](/en/reference/products/midaz/v2/create-asset)

> [!TIP]
>
> When you create an Asset, Midaz automatically sets up an External Account if one doesn’t already exist. The External Account backs all transactions that flow in and out of the Ledger.

For a complete list of endpoints to manage your Assets, expand the section below:

> **Managing Assets**
>
> * Retrieve all Assets using the [List Assets](/en/reference/products/midaz/v2/list-assets) endpoint.
> * Retrieve a specific Asset with the [Retrieve an Asset](/en/reference/products/midaz/v2/get-asset-by-id) endpoint.
> * Update Asset details using the [Update an Asset](/en/reference/products/midaz/v2/update-asset) endpoint.
> * Delete an Asset with the [Delete an Asset](/en/reference/products/midaz/v2/delete-asset) endpoint.

### Step 2.4 - Create a Segment (optional)

If you want, you can use the **Segment ID** as a custom grouping label that clusters accounts according to user-defined policies.

* [**To create a Segment, use the Create a Segment endpoint.**](/en/reference/products/midaz/v2/create-segment)

For a complete list of endpoints to manage your Segment, expand the section below:

> **Managing Segment**
>
> * Retrieve all Segments using the [List Segments](/en/reference/products/midaz/v2/list-segments) endpoint.
> * Retrieve a specific Segment with the [Retrieve a Segment](/en/reference/products/midaz/v2/get-segment-by-id) endpoint.
> * Update Segment details using the [Update a Segment](/en/reference/products/midaz/v2/update-segment) endpoint.
> * Delete a Segment using the [Delete a Segment](/en/reference/products/midaz/v2/delete-segment) endpoint.

### Step 2.5 - Create a Portfolio (optional)

Create a Portfolio to group your accounts of different Assets.

* [**To create a Portfolio, use the Create a Portfolio endpoint.**](/en/reference/products/midaz/v2/create-portfolio)

For a complete list of endpoints to manage your Portfolios, expand the section below:

> **Managing Portfolios**
>
> * Retrieve all Portfolios using the [List Portfolios](/en/reference/products/midaz/v2/list-portfolios) endpoint.
> * Retrieve a specific Portfolio with the [Retrieve a Portfolio](/en/reference/products/midaz/v2/get-portfolio-by-id) endpoint.
> * Update Portfolio details using the [Update a Portfolio](/en/reference/products/midaz/v2/update-portfolio) endpoint.
> * Delete a Portfolio with the [Delete a Portfolio](/en/reference/products/midaz/v2/delete-portfolio) endpoint.

### Step 2.6 - Create the Accounts

You can now add the accounts related to the Assets you want to use with the Ledger. Each Account holds one Asset.

* [**To create an account, use the Create an Account endpoint.**](/en/reference/products/midaz/v2/create-account)

For a complete list of endpoints to manage your Accounts, expand the section below:

> **Managing Accounts**
>
> * Retrieve all Accounts using the [List Accounts](/en/reference/products/midaz/v2/list-accounts) endpoint.
> * Retrieve a specific Account with the [Retrieve an Account](/en/reference/products/midaz/v2/get-account-by-id) endpoint.
> * Update Account details using the [Update an Account](/en/reference/products/midaz/v2/update-account) endpoint.
> * Delete an Account with the [Delete an Account](/en/reference/products/midaz/v2/delete-account) endpoint.

## Step 3 - Explore our APIs

***

See the [API reference](/en/reference/introduction) to learn more about Midaz, from metadata handling to idempotency.

## Need help?

***

* Explore our [Documentation hub](/en/start-here/welcome-to-our-guides) for in-depth guides and resources.

* Join the [Discord community](https://discord.gg/DnhqKwkGv3).

* [Contact our support team](https://lerian.studio/support) for personalized assistance.


# Calculate billing
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/calculate-billing

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing/calculate



# Cancel a pending Transaction (v2)
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/cancel-transaction

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}/cancel



# Collect a balance's open fee debts
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/collect-a-balance-s-open-fee-debts

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/ledgers/{ledger_id}/fee-debts/collect
Settles the balance's open fee debts oldest first from its available funds, up to maxAmount and never more than it owes, in one transaction. It charges no new fee. Without an error, it collects nothing when the balance has no available funds or is blocked, cannot send, is closing or closed, deleted, debit-direction or external, and it stops at the first debt whose fee account is blocked, cannot receive, is closing or closed, deleted, debit-direction, external, in overdraft or of another asset. When nothing is settled the response is collected 0 and no transaction is created. With X-Idempotency a retry returns the first collection; an answer that settled nothing is not kept. Without it every call is a new collection. A collection transaction cannot be reverted.



# Commit a Transaction (v2)
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/commit-transaction

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}/commit



# Create a BillingPackage
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-billing-package

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages



# Create a Holder
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-holder

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/holders



# Open a holder-owned account (with optional instrument)
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-holder-account

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/ledgers/{ledger_id}/holders/{id}/accounts



# Create an Instrument Account
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-instrument

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/holders/{holder_id}/instruments
Creates an instrument linking a ledger account to its holder and banking details. A ledger account already linked to another instrument (CRM-0013) is refused with 409, and so is a bank account already registered to another live instrument of the organization (CRM-0043): the same bankId and account, on the same branch (leading zeros ignored when both branches are numeric) or where one of them has no branch, whatever the type.



# Create Metadata Index
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-metadata-index

/en/openapi/v3-current/ledger.yaml post /v2/settings/metadata-indexes/entities/{entity_name}



# Create an organization Operation Route
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-organization-operation-route

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/operation-routes
Creates an operation route that belongs to the organization and validates in every ledger of it. The route has no ledgerId.



# Create an organization Transaction Route
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-organization-transaction-route

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/transaction-routes
Creates a transaction route that belongs to the organization and validates in every ledger of it. The route has no ledgerId.



# Create a Package
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-package

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/ledgers/{ledger_id}/packages



# Create a new portfolio
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-portfolio

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/ledgers/{ledger_id}/portfolios



# Create a new segment
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-segment

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/ledgers/{ledger_id}/segments



# Create an atomic batch of Transactions (v2)
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-transaction-batch

/en/openapi/v3-current/ledger.yaml post /v2/transactions/batch
Executes direct and hold transactions once, in explicit increasing order, as one all-or-none accounting decision. The response preserves that order. The decoded body must be smaller than 1 MiB; the configured cardinality is 1-50, aggregate input legs are limited to 1,000, and post-fee work is limited to 100 postings and 150 balance snapshots. The internal idempotency/recovery batch identifier is not exposed; there is no batch query endpoint.



# Create a Transaction using the v2 block model
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-transaction-block

/en/openapi/v3-current/ledger.yaml post /v2/transactions/block



# Create a Transaction using the v2 direct model
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-transaction-direct

/en/openapi/v3-current/ledger.yaml post /v2/transactions/direct



# Create a Transaction using the v2 hold model
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-transaction-hold

/en/openapi/v3-current/ledger.yaml post /v2/transactions/hold



# Create Transaction Route
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-transaction-route

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/ledgers/{ledger_id}/transaction-routes



# Create a Transaction using the v2 unblock model
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/create-transaction-unblock

/en/openapi/v3-current/ledger.yaml post /v2/transactions/unblock



# SoftDelete a BillingPackage by ID
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/delete-billing-package

/en/openapi/v3-current/ledger.yaml delete /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}



# Delete a Holder
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/delete-holder

/en/openapi/v3-current/ledger.yaml delete /v2/organizations/{organization_id}/holders/{id}



# Delete an Instrument
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/delete-instrument

/en/openapi/v3-current/ledger.yaml delete /v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}



# Delete Metadata Index
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/delete-metadata-index

/en/openapi/v3-current/ledger.yaml delete /v2/settings/metadata-indexes/entities/{entity_name}/key/{index_key}



# Delete an operation route
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/delete-operation-route

/en/openapi/v3-current/ledger.yaml delete /v2/organizations/{organization_id}/ledgers/{ledger_id}/operation-routes/{operation_route_id}



# Delete an organization Operation Route by ID
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/delete-organization-operation-route

/en/openapi/v3-current/ledger.yaml delete /v2/organizations/{organization_id}/operation-routes/{operation_route_id}



# Delete an organization Transaction Route by ID
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/delete-organization-transaction-route

/en/openapi/v3-current/ledger.yaml delete /v2/organizations/{organization_id}/transaction-routes/{transaction_route_id}



# SoftDelete a Package by ID
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/delete-package

/en/openapi/v3-current/ledger.yaml delete /v2/organizations/{organization_id}/ledgers/{ledger_id}/packages/{id}



# Delete a portfolio
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/delete-portfolio

/en/openapi/v3-current/ledger.yaml delete /v2/organizations/{organization_id}/ledgers/{ledger_id}/portfolios/{id}



# Delete a Related Party
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/delete-related-party

/en/openapi/v3-current/ledger.yaml delete /v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}/related-parties/{related_party_id}



# Delete a segment
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/delete-segment

/en/openapi/v3-current/ledger.yaml delete /v2/organizations/{organization_id}/ledgers/{ledger_id}/segments/{id}



# Delete Transaction Route by ID
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/delete-transaction-route

/en/openapi/v3-current/ledger.yaml delete /v2/organizations/{organization_id}/ledgers/{ledger_id}/transaction-routes/{transaction_route_id}



# Create a fee estimate calculation
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/estimate-fee-calculation

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/ledgers/{ledger_id}/estimates



# Get a fee debt
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-a-fee-debt

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/fee-debts/{debt_id}



# Get all billing packages of a ledger
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-all-billing-packages

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages



# Get all Metadata Indexes
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-all-metadata-indexes

/en/openapi/v3-current/ledger.yaml get /v2/settings/metadata-indexes



# Get all packages of a ledger
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-all-packages

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/packages



# Get all Transactions
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-all-transactions

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions



# List Protection Audit Events
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-audit-events

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/protection/audit



# Get billing package
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-billing-package-by-id

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}



# Retrieve Holder details
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-holder-by-id

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/holders/{id}



# Retrieve Instrument details
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-instrument-by-id

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}



# Get ledger settings
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-ledger-settings

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/settings



# Retrieve a specific operation route
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-operation-route-by-id

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/operation-routes/{operation_route_id}



# Get an organization Operation Route by ID
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-organization-operation-route-by-id

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/operation-routes/{operation_route_id}



# Get an organization Transaction Route by ID
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-organization-transaction-route-by-id

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/transaction-routes/{transaction_route_id}



# Get package
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-package-by-id

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/packages/{id}



# Retrieve a specific portfolio
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-portfolio-by-id

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/portfolios/{id}



# Get Provisioning Status
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-provisioning-status

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/encryption/status



# Retrieve a specific segment
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-segment-by-id

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/segments/{id}



# Get a Transaction by ID
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-transaction

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}



# Get Transaction Route by ID
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/get-transaction-route-by-id

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/transaction-routes/{transaction_route_id}



# List Accounts by Holder
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/list-accounts-by-holder

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/holders/{id}/accounts



# List Holders
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/list-holders

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/holders



# List Instruments
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/list-instruments

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/instruments



# List the organization Operation Routes
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/list-organization-operation-routes

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/operation-routes
Lists every operation route of the organization, whichever ledger it was created under, including routes created at organization level.



# List the organization Transaction Routes
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/list-organization-transaction-routes

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/transaction-routes
Lists every transaction route of the organization, whichever ledger it was created under, including routes created at organization level.



# List all portfolios
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/list-portfolios

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/portfolios



# List all segments
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/list-segments

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/segments



# List the fee debts of a ledger, oldest first
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/list-the-fee-debts-of-a-ledger-oldest-first

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/fee-debts



# Get all Transaction Routes
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/list-transaction-routes

/en/openapi/v3-current/ledger.yaml get /v2/organizations/{organization_id}/ledgers/{ledger_id}/transaction-routes



# Provision an Organization for Envelope Encryption
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/provision-encryption

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/encryption/provision



# Revert a Transaction (v2)
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/revert-transaction

/en/openapi/v3-current/ledger.yaml post /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}/revert
A revert whose pending fees have not finished being recorded is refused with 409 (0529); nothing moves, and a later retry may succeed.



# Update a billing package
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/update-billing-package

/en/openapi/v3-current/ledger.yaml patch /v2/organizations/{organization_id}/ledgers/{ledger_id}/billing-packages/{id}



# Update a Holder
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/update-holder

/en/openapi/v3-current/ledger.yaml patch /v2/organizations/{organization_id}/holders/{id}



# Update an Instrument
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/update-instrument

/en/openapi/v3-current/ledger.yaml patch /v2/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}
Updates an instrument as an RFC 7396 merge patch. A change to bankId, branch or account that leaves the instrument holding a bank account already registered to another live instrument of the organization is refused with 409 (CRM-0043).



# Update ledger settings
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/update-ledger-settings

/en/openapi/v3-current/ledger.yaml patch /v2/organizations/{organization_id}/ledgers/{ledger_id}/settings



# Update an Operation
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/update-operation

/en/openapi/v3-current/ledger.yaml patch /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}/operations/{operation_id}



# Update an operation route
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/update-operation-route

/en/openapi/v3-current/ledger.yaml patch /v2/organizations/{organization_id}/ledgers/{ledger_id}/operation-routes/{operation_route_id}



# Update an organization Operation Route
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/update-organization-operation-route

/en/openapi/v3-current/ledger.yaml patch /v2/organizations/{organization_id}/operation-routes/{operation_route_id}



# Update an organization Transaction Route
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/update-organization-transaction-route

/en/openapi/v3-current/ledger.yaml patch /v2/organizations/{organization_id}/transaction-routes/{transaction_route_id}



# Update a package
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/update-package

/en/openapi/v3-current/ledger.yaml patch /v2/organizations/{organization_id}/ledgers/{ledger_id}/packages/{id}



# Update a portfolio
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/update-portfolio

/en/openapi/v3-current/ledger.yaml patch /v2/organizations/{organization_id}/ledgers/{ledger_id}/portfolios/{id}



# Update a segment
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/update-segment

/en/openapi/v3-current/ledger.yaml patch /v2/organizations/{organization_id}/ledgers/{ledger_id}/segments/{id}



# Update a Transaction
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/update-transaction

/en/openapi/v3-current/ledger.yaml patch /v2/organizations/{organization_id}/ledgers/{ledger_id}/transactions/{transaction_id}



# Update Transaction Route
Source: https://docs.lerian.studio/en/reference/products/midaz/v2/update-transaction-route

/en/openapi/v3-current/ledger.yaml patch /v2/organizations/{organization_id}/ledgers/{ledger_id}/transaction-routes/{transaction_route_id}



# Tracer events
Source: https://docs.lerian.studio/en/reference/events/tracer

Reference all public JSON event facts emitted by the Tracer component in Midaz, including CloudEvents headers, application topics, delivery behavior, and complete data contracts.

Tracer emits its public JSON business facts as **CloudEvents 1.0** in binary content mode over Kafka. Tracer is the separately deployed Midaz component and the sole producer of the `studio.lerian.tracer.*` contract on this page.

## CloudEvents envelope

Every public JSON fact uses the shared envelope below. The headers carry routing and schema information. The Kafka value carries the JSON `data` object.

| Header | Presence and value |
| - | - |
| `ce-specversion` | Always `1.0`. |
| `ce-id` | Always; opaque producer-defined event identifier. |
| `ce-source` | Always `tracer`. |
| `ce-type` | Always `studio.lerian.tracer.<resource>.<event>`. |
| `ce-time` | Always; RFC 3339 emission timestamp. |
| `ce-resourcetype` | Always; the resource token from the definition key. |
| `ce-eventtype` | Always; the event token from the definition key. |
| `ce-subject` | Always `p.ID` for these 12 contracts. |
| `ce-tenantid` | **Always present.** Your tenant ID, or the literal `default` when the event has no tenant. |
| `ce-schemaversion` | `1.1.0` for `limit.created` and `limit.updated`. `1.0.0` for the other 10 public JSON facts. |
| `ce-datacontenttype` | `application/json`. |

## Topics, manifest, and routing

The application topic identifies Midaz Tracer, not an individual event. Route a record by `ce-resourcetype` and `ce-eventtype`, and validate `ce-schemaversion` before decoding its `data` value.

* **Facts:** `lerian.streaming.tracer`
* **Route DLQ:** `lerian.streaming.tracer.dlq`
* **Manifest:** `GET /v1/streaming/manifest` exposes the public JSON catalog and topic mapping, including while publication is off.

## Delivery and failure semantics

Publication is disabled until `STREAMING_ENABLED=true` and broker configuration succeeds. When enabled, Tracer emits after the business-state change. It does not use a transactional outbox.

* **Policy:** every public JSON definition is a `fact` with direct delivery, `on_routable_failure` DLQ handling, and `fallback_on_circuit_open`.
* **Actual Tracer boundary:** because Tracer has no outbox, the circuit-open fallback cannot persist an event. Emit paths log and swallow publication errors instead of returning them to the business command.
* **Consumer requirement:** broker delivery is at least once for published records. Make handlers idempotent and deduplicate with `(ce-source, ce-id)`.

## Complete `data` contracts

These TypeScript-style declarations mirror the CloudEvent `data` JSON tags in Midaz. Every field name is its JSON name. `?` means the field has `omitempty`. `| null` means the field is nullable and never absent. A source-type comment preserves the inventory type exactly. All fields in these 12 Tracer payloads are present (`omitempty: false`). Nullable fields still carry `null` when absent.

> **limit.activated**
>
> **Definition key:** `limit.activated` (`LimitActivatedDefinition`)
>
> **Event:** `studio.lerian.tracer.limit.activated`
>
> **Topic:** `lerian.streaming.tracer`
>
> **Route DLQ:** `lerian.streaming.tracer.dlq`
>
> **Schema:** `1.0.0` (`application/json`)
>
> **Fires when:** `ActivateLimitCommand` successfully activates a limit.
>
> **Subject:** `p.ID`
>
> ```typescript theme={null}
> // limit.activated
> type LimitActivatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   status: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **limit.created**
>
> **Definition key:** `limit.created` (`LimitCreatedDefinition`)
>
> **Event:** `studio.lerian.tracer.limit.created`
>
> **Topic:** `lerian.streaming.tracer`
>
> **Route DLQ:** `lerian.streaming.tracer.dlq`
>
> **Schema:** `1.1.0` (`application/json`)
>
> **Fires when:** `CreateLimitCommand` successfully creates a limit.
>
> **Subject:** `p.ID`
>
> ```typescript theme={null}
> type RuleScopePayload = { // Go: RuleScopePayload
>   segmentId: string | null // *string; wire null: true; omitempty: false
>   portfolioId: string | null // *string; wire null: true; omitempty: false
>   accountId: string | null // *string; wire null: true; omitempty: false
>   merchantId: string | null // *string; wire null: true; omitempty: false
>   transactionType: string | null // *string; wire null: true; omitempty: false
>   subType: string | null // *string; wire null: true; omitempty: false
> }
>
> // limit.created
> type LimitCreatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   status: string // string; wire null: false; omitempty: false
>   limitType: string // string; wire null: false; omitempty: false
>   asset: string // string; wire null: false; omitempty: false
>   scopes: RuleScopePayload[] // []RuleScopePayload; wire null: false; omitempty: false
>   activeTimeStart: string | null // *string; wire null: true; omitempty: false
>   activeTimeEnd: string | null // *string; wire null: true; omitempty: false
>   customStartDate: string | null // *string; wire null: true; omitempty: false
>   customEndDate: string | null // *string; wire null: true; omitempty: false
>   resetTime: string | null // *string; wire null: true; omitempty: false
>   resetAt: string | null // *string; wire null: true; omitempty: false
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **limit.deactivated**
>
> **Definition key:** `limit.deactivated` (`LimitDeactivatedDefinition`)
>
> **Event:** `studio.lerian.tracer.limit.deactivated`
>
> **Topic:** `lerian.streaming.tracer`
>
> **Route DLQ:** `lerian.streaming.tracer.dlq`
>
> **Schema:** `1.0.0` (`application/json`)
>
> **Fires when:** `DeactivateLimitCommand` successfully deactivates a limit.
>
> **Subject:** `p.ID`
>
> ```typescript theme={null}
> // limit.deactivated
> type LimitDeactivatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   status: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **limit.deleted**
>
> **Definition key:** `limit.deleted` (`LimitDeletedDefinition`)
>
> **Event:** `studio.lerian.tracer.limit.deleted`
>
> **Topic:** `lerian.streaming.tracer`
>
> **Route DLQ:** `lerian.streaming.tracer.dlq`
>
> **Schema:** `1.0.0` (`application/json`)
>
> **Fires when:** `DeleteLimitCommand` successfully deletes a limit.
>
> **Subject:** `p.ID`
>
> ```typescript theme={null}
> // limit.deleted
> type LimitDeletedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   deletedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **limit.drafted**
>
> **Definition key:** `limit.drafted` (`LimitDraftedDefinition`)
>
> **Event:** `studio.lerian.tracer.limit.drafted`
>
> **Topic:** `lerian.streaming.tracer`
>
> **Route DLQ:** `lerian.streaming.tracer.dlq`
>
> **Schema:** `1.0.0` (`application/json`)
>
> **Fires when:** `DraftLimitCommand` successfully moves a limit to DRAFT.
>
> **Subject:** `p.ID`
>
> ```typescript theme={null}
> // limit.drafted
> type LimitDraftedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   status: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **limit.updated**
>
> **Definition key:** `limit.updated` (`LimitUpdatedDefinition`)
>
> **Event:** `studio.lerian.tracer.limit.updated`
>
> **Topic:** `lerian.streaming.tracer`
>
> **Route DLQ:** `lerian.streaming.tracer.dlq`
>
> **Schema:** `1.1.0` (`application/json`)
>
> **Fires when:** `UpdateLimitCommand` successfully updates a limit.
>
> **Subject:** `p.ID`
>
> ```typescript theme={null}
> type RuleScopePayload = { // Go: RuleScopePayload
>   segmentId: string | null // *string; wire null: true; omitempty: false
>   portfolioId: string | null // *string; wire null: true; omitempty: false
>   accountId: string | null // *string; wire null: true; omitempty: false
>   merchantId: string | null // *string; wire null: true; omitempty: false
>   transactionType: string | null // *string; wire null: true; omitempty: false
>   subType: string | null // *string; wire null: true; omitempty: false
> }
>
> // limit.updated
> type LimitUpdatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   status: string // string; wire null: false; omitempty: false
>   limitType: string // string; wire null: false; omitempty: false
>   asset: string // string; wire null: false; omitempty: false
>   scopes: RuleScopePayload[] // []RuleScopePayload; wire null: false; omitempty: false
>   activeTimeStart: string | null // *string; wire null: true; omitempty: false
>   activeTimeEnd: string | null // *string; wire null: true; omitempty: false
>   customStartDate: string | null // *string; wire null: true; omitempty: false
>   customEndDate: string | null // *string; wire null: true; omitempty: false
>   resetTime: string | null // *string; wire null: true; omitempty: false
>   resetAt: string | null // *string; wire null: true; omitempty: false
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **rule.activated**
>
> **Definition key:** `rule.activated` (`RuleActivatedDefinition`)
>
> **Event:** `studio.lerian.tracer.rule.activated`
>
> **Topic:** `lerian.streaming.tracer`
>
> **Route DLQ:** `lerian.streaming.tracer.dlq`
>
> **Schema:** `1.0.0` (`application/json`)
>
> **Fires when:** `ActivateRuleService` successfully activates a rule.
>
> **Subject:** `p.ID`
>
> ```typescript theme={null}
> // rule.activated
> type RuleActivatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   status: string // string; wire null: false; omitempty: false
>   activatedAt: string | null // *string; wire null: true; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **rule.created**
>
> **Definition key:** `rule.created` (`RuleCreatedDefinition`)
>
> **Event:** `studio.lerian.tracer.rule.created`
>
> **Topic:** `lerian.streaming.tracer`
>
> **Route DLQ:** `lerian.streaming.tracer.dlq`
>
> **Schema:** `1.0.0` (`application/json`)
>
> **Fires when:** `CreateRuleCommand` successfully creates a rule.
>
> **Subject:** `p.ID`
>
> ```typescript theme={null}
> type RuleScopePayload = { // Go: RuleScopePayload
>   segmentId: string | null // *string; wire null: true; omitempty: false
>   portfolioId: string | null // *string; wire null: true; omitempty: false
>   accountId: string | null // *string; wire null: true; omitempty: false
>   merchantId: string | null // *string; wire null: true; omitempty: false
>   transactionType: string | null // *string; wire null: true; omitempty: false
>   subType: string | null // *string; wire null: true; omitempty: false
> }
>
> // rule.created
> type RuleCreatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   status: string // string; wire null: false; omitempty: false
>   action: string // string; wire null: false; omitempty: false
>   scopes: RuleScopePayload[] // []RuleScopePayload; wire null: false; omitempty: false
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **rule.deactivated**
>
> **Definition key:** `rule.deactivated` (`RuleDeactivatedDefinition`)
>
> **Event:** `studio.lerian.tracer.rule.deactivated`
>
> **Topic:** `lerian.streaming.tracer`
>
> **Route DLQ:** `lerian.streaming.tracer.dlq`
>
> **Schema:** `1.0.0` (`application/json`)
>
> **Fires when:** `DeactivateRuleService` successfully deactivates a rule.
>
> **Subject:** `p.ID`
>
> ```typescript theme={null}
> // rule.deactivated
> type RuleDeactivatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   status: string // string; wire null: false; omitempty: false
>   deactivatedAt: string | null // *string; wire null: true; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **rule.deleted**
>
> **Definition key:** `rule.deleted` (`RuleDeletedDefinition`)
>
> **Event:** `studio.lerian.tracer.rule.deleted`
>
> **Topic:** `lerian.streaming.tracer`
>
> **Route DLQ:** `lerian.streaming.tracer.dlq`
>
> **Schema:** `1.0.0` (`application/json`)
>
> **Fires when:** `DeleteRuleService` successfully deletes a rule.
>
> **Subject:** `p.ID`
>
> ```typescript theme={null}
> // rule.deleted
> type RuleDeletedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   deletedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **rule.drafted**
>
> **Definition key:** `rule.drafted` (`RuleDraftedDefinition`)
>
> **Event:** `studio.lerian.tracer.rule.drafted`
>
> **Topic:** `lerian.streaming.tracer`
>
> **Route DLQ:** `lerian.streaming.tracer.dlq`
>
> **Schema:** `1.0.0` (`application/json`)
>
> **Fires when:** `DraftRuleService` successfully moves a rule to DRAFT.
>
> **Subject:** `p.ID`
>
> ```typescript theme={null}
> // rule.drafted
> type RuleDraftedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   status: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

> **rule.updated**
>
> **Definition key:** `rule.updated` (`RuleUpdatedDefinition`)
>
> **Event:** `studio.lerian.tracer.rule.updated`
>
> **Topic:** `lerian.streaming.tracer`
>
> **Route DLQ:** `lerian.streaming.tracer.dlq`
>
> **Schema:** `1.0.0` (`application/json`)
>
> **Fires when:** `UpdateRuleCommand` successfully updates a rule.
>
> **Subject:** `p.ID`
>
> ```typescript theme={null}
> type RuleScopePayload = { // Go: RuleScopePayload
>   segmentId: string | null // *string; wire null: true; omitempty: false
>   portfolioId: string | null // *string; wire null: true; omitempty: false
>   accountId: string | null // *string; wire null: true; omitempty: false
>   merchantId: string | null // *string; wire null: true; omitempty: false
>   transactionType: string | null // *string; wire null: true; omitempty: false
>   subType: string | null // *string; wire null: true; omitempty: false
> }
>
> // rule.updated
> type RuleUpdatedDataV1 = {
>   id: string // string; wire null: false; omitempty: false
>   status: string // string; wire null: false; omitempty: false
>   action: string // string; wire null: false; omitempty: false
>   scopes: RuleScopePayload[] // []RuleScopePayload; wire null: false; omitempty: false
>   createdAt: string // string; wire null: false; omitempty: false
>   updatedAt: string // string; wire null: false; omitempty: false
> }
> ```

## Emitted event index

| Definition key | `ce-type` | Schema | Subject | Fires when |
| - | - | - | - | - |
| `limit.activated` | `studio.lerian.tracer.limit.activated` | `1.0.0` | `p.ID` | `ActivateLimitCommand` successfully activates a limit. |
| `limit.created` | `studio.lerian.tracer.limit.created` | `1.1.0` | `p.ID` | `CreateLimitCommand` successfully creates a limit. |
| `limit.deactivated` | `studio.lerian.tracer.limit.deactivated` | `1.0.0` | `p.ID` | `DeactivateLimitCommand` successfully deactivates a limit. |
| `limit.deleted` | `studio.lerian.tracer.limit.deleted` | `1.0.0` | `p.ID` | `DeleteLimitCommand` successfully deletes a limit. |
| `limit.drafted` | `studio.lerian.tracer.limit.drafted` | `1.0.0` | `p.ID` | `DraftLimitCommand` successfully moves a limit to DRAFT. |
| `limit.updated` | `studio.lerian.tracer.limit.updated` | `1.1.0` | `p.ID` | `UpdateLimitCommand` successfully updates a limit. |
| `rule.activated` | `studio.lerian.tracer.rule.activated` | `1.0.0` | `p.ID` | `ActivateRuleService` successfully activates a rule. |
| `rule.created` | `studio.lerian.tracer.rule.created` | `1.0.0` | `p.ID` | `CreateRuleCommand` successfully creates a rule. |
| `rule.deactivated` | `studio.lerian.tracer.rule.deactivated` | `1.0.0` | `p.ID` | `DeactivateRuleService` successfully deactivates a rule. |
| `rule.deleted` | `studio.lerian.tracer.rule.deleted` | `1.0.0` | `p.ID` | `DeleteRuleService` successfully deletes a rule. |
| `rule.drafted` | `studio.lerian.tracer.rule.drafted` | `1.0.0` | `p.ID` | `DraftRuleService` successfully moves a rule to DRAFT. |
| `rule.updated` | `studio.lerian.tracer.rule.updated` | `1.0.0` | `p.ID` | `UpdateRuleCommand` successfully updates a rule. |


# Clone a reconciliation context
Source: https://docs.lerian.studio/en/reference/products/matcher/clone-context

/en/openapi/v3-current/matcher.yaml post /v1/contexts/{contextId}/clone
Use this endpoint to clone an existing reconciliation context with its associated sources, rules, and fee schedules. You can selectively include or exclude specific components.



# Create a reconciliation context
Source: https://docs.lerian.studio/en/reference/products/matcher/create-context

/en/openapi/v3-current/matcher.yaml post /v1/contexts
Use this endpoint to create a new reconciliation context. Contexts are used to scope matching rules and organize your reconciliation configuration.



# Get context setup progress
Source: https://docs.lerian.studio/en/reference/products/matcher/get-setup-progress

/en/openapi/v3-current/matcher.yaml get /v1/contexts/{contextId}/setup-progress
Returns configured-resource counts, last-run state, and activation readiness for a context in a single aggregate, so clients derive wizard/checklist state from one request.



# List reconciliation contexts
Source: https://docs.lerian.studio/en/reference/products/matcher/list-contexts

/en/openapi/v3-current/matcher.yaml get /v1/contexts
Use this endpoint to retrieve all reconciliation contexts.  

Supports filtering by type and status and uses cursor-based pagination.




# Matcher API quick start
Source: https://docs.lerian.studio/en/reference/products/matcher/matcher-developer-quick-start

Get Matcher running: create your first reconciliation context, upload files, and review matched transactions with cURL and the Matcher API.

> [!TIP]
>
> **This guide is for developers.** If you're looking for a business-level overview of what Matcher does, see [What is Matcher?](/en/products/matcher/what-is-matcher).

This guide takes you from creating your first reconciliation context to reviewing matched transactions.

## Before you begin

***

You need:

* The Matcher API address that Lerian gives you
* A valid JWT token for authentication
* Two transaction files to reconcile (CSV, JSON, or XML)

All examples use `cURL`. Replace `$TOKEN` with your JWT token and `https://api.matcher.example.com` with the Matcher API address.

## Step 1: Create a reconciliation context

***

A context defines the scope of your reconciliation: what you compare and how.

> [!TIP]
>
> API reference: [Create context](/en/reference/products/matcher/create-context)

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Daily Bank Reconciliation",
   "type": "1:1",
   "interval": "daily"
 }'
```

The `type` field defines how Matcher pairs transactions:

| Type | Description |
| - | - |
| `1:1` | Each transaction matches exactly one counterpart |
| `1:N` | One transaction can match multiple counterparts |
| `N:M` | Multiple transactions can match across both sides |

Save the `id` from the response. You will use it in every subsequent step.

```json theme={null}
{
  "id": "019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f",
  "name": "Daily Bank Reconciliation",
  "type": "1:1",
  "interval": "daily",
  "status": "DRAFT",
  "createdAt": "2026-03-04T12:00:00Z",
  "updatedAt": "2026-03-04T12:00:00Z"
}
```

> [!NOTE]
>
> The context starts in DRAFT status. It moves to ACTIVE when you are ready to run reconciliation.

## Step 2: Add data sources

***

To run a match, configure at least two sources: the systems whose transactions you want to compare.

> [!TIP]
>
> API reference: [Create source](/en/reference/products/matcher/create-source)

### Create a bank source

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Chase Bank - Account 1234",
   "type": "BANK",
   "side": "RIGHT"
 }'
```

### Create a ledger source

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "General Ledger - GL 1000",
   "type": "LEDGER",
   "side": "LEFT"
 }'
```

Save both source `id` values. Every source needs a `side` (`LEFT` or `RIGHT`): the context reconciles its `LEFT` sources against its `RIGHT` sources.

### Source types

| Type | Use case |
| - | - |
| `BANK` | Bank statements |
| `LEDGER` | General ledger / ERP exports |
| `GATEWAY` | Payment processor data |
| `CUSTOM` | Any other data source |
| `FETCHER` | Data extracted through the embedded extraction engine |

## Step 3: Map source fields

***

Your source files probably use different column names than Matcher expects. Field maps translate them into Matcher's standard schema.

> [!TIP]
>
> API reference: [Create field map](/en/reference/products/matcher/create-field-map)

### Map the bank source

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{bankSourceId}/field-maps" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mapping": {
     "external_id": "Transaction ID",
     "amount": "Amount",
     "currency": "Currency",
     "date": "Post Date",
     "description": "Description"
   }
 }'
```

### Map the ledger source

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{ledgerSourceId}/field-maps" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mapping": {
     "external_id": "entry_id",
     "amount": "debit_credit_amount",
     "currency": "currency_code",
     "date": "posting_date",
     "description": "memo"
   }
 }'
```

### Required fields

Every transaction must have these fields after mapping:

| Field | Type | Description |
| - | - | - |
| `external_id` | String | Unique identifier within the source |
| `amount` | Decimal | Transaction amount |
| `currency` | String | ISO 4217 currency code (e.g. USD) |
| `date` | Date | Transaction date (YYYY-MM-DD) |

**Optional:** `description`, `fee_amount`, `fee_currency`, and `direction`. Each mapping key is a Matcher field. Each value is the column name in your file, except for `direction`. Its value is an object `{column, debit, credit}` for a file that marks each row as debit or credit in a separate column. A debit row imports with a negative amount, and a credit row with a positive one.

## Step 4: Create match rules

***

Rules define how Matcher compares transactions. Start with an exact rule, which is the most precise.

> [!TIP]
>
> API reference: [Create match rule](/en/reference/products/matcher/create-match-rule)

### Create an exact rule

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "EXACT",
   "priority": 1,
   "config": {
     "matchAmount": true,
     "matchCurrency": true,
     "matchDate": true,
     "matchReference": true,
     "caseInsensitive": true,
     "datePrecision": "DAY"
   }
 }'
```

### Add a tolerance rule as fallback

Catch small differences like bank fees or rounding:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "TOLERANCE",
   "priority": 20,
   "config": {
     "percentTolerance": 0.01,
     "absTolerance": 5.0,
     "dateWindowDays": 2,
     "matchCurrency": true,
     "matchReference": true,
     "caseInsensitive": true
   }
 }'
```

> [!TIP]
>
> Matcher evaluates rules by priority (lowest number first). The exact rule runs first. Only unmatched transactions fall through to the tolerance rule.

### Rule types

| Type | When to use | Priority range |
| - | - | - |
| `EXACT` | Values should match exactly | 1-1000; unique within the context |
| `TOLERANCE` | Small, expected differences | 1-1000; unique within the context |
| `DATE_LAG` | Date delays between systems; always proposed for review | 1-1000; unique within the context |
| `FUZZY` | Similarity-scored references; always proposed for review | 1-1000; unique within the context |

## Step 5: Activate the context

***

Move the context from DRAFT to ACTIVE:

> [!TIP]
>
> API reference: [Update context](/en/reference/products/matcher/update-context)

```bash cURL theme={null}
curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "status": "ACTIVE"
 }'
```

If the context is not ready, Matcher refuses the update with `409 Conflict` and code `MTCH-0103`. The `errors` array of the response lists each missing requirement. [Setup progress](/en/products/matcher/getting-started/matcher-setup-progress) lists the missing requirements and the next call to make.

## Step 6: Upload transaction files

***

Upload one file per source. Matcher accepts CSV, JSON, and XML formats via multipart form upload.

> [!TIP]
>
> * API reference: [Upload transaction file](/en/reference/products/matcher/upload-transaction-file)
> * [List ingestion jobs](/en/reference/products/matcher/list-ingestion-jobs)

### Upload bank transactions

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{bankSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "format=csv" \
 -F "file=@bank_transactions.csv"
```

### Upload ledger transactions

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{ledgerSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "format=csv" \
 -F "file=@ledger_entries.csv"
```

Each upload creates an ingestion job. Check the job status:

```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/imports/contexts/{contextId}/jobs" \
 -H "Authorization: Bearer $TOKEN"
```

Wait for both jobs to reach `COMPLETED` status before running the match.

## Step 7: Run matching

***

Start with a dry run to preview results without persisting:

> [!TIP]
>
> API reference: [Run match](/en/reference/products/matcher/run-match)

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mode": "DRY_RUN"
 }'
```

The response includes a `runId`. A dry run saves no match groups. To review its results, read the aggregate statistics of the run with [Get match run](/en/reference/products/matcher/retrieve-match-run).

When satisfied, run with COMMIT to persist matches:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mode": "COMMIT"
 }'
```

Save the `runId` from the COMMIT response. You use it in Step 8.

## Step 8: Review results

***

> [!TIP]
>
> * API reference: [List match run groups](/en/reference/products/matcher/list-match-run-groups)
> * [Unmatch group](/en/reference/products/matcher/unmatch-group)

### View match groups

```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/matching/runs/{runId}/groups?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN"
```

Each match group contains paired transactions and a confidence score (0-100):

| Score | What happens |
| - | - |
| 90-100 | Auto-confirmed for EXACT and TOLERANCE matches. FUZZY and DATE\_LAG matches need manual review |
| 60-89 | Needs manual review |

### Undo an incorrect match

Use the unmatch endpoint to reject a `PROPOSED` match group or revoke a `CONFIRMED` one. Matcher returns the group's transactions to the unmatched pool for the next run:

```bash cURL theme={null}
curl -X DELETE "https://api.matcher.example.com/v1/matching/groups/{matchGroupId}?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "reason": "Transactions belong to different records"
 }'
```

## Step 9: Handle exceptions

***

Exceptions are transactions that Matcher could not match automatically. Matcher classifies each exception by severity:

> [!TIP]
>
> API reference: [List exceptions](/en/reference/products/matcher/list-exceptions)

| Severity | Criteria |
| - | - |
| `CRITICAL` | Amount >= 100,000 or age >= 120h |
| `HIGH` | Amount >= 10,000 or age >= 72h |
| `MEDIUM` | Amount >= 1,000 or age >= 24h |
| `LOW` | All others |

### List exceptions

```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/exceptions" \
 -H "Authorization: Bearer $TOKEN"
```

Resolve exceptions directly, by force matching, or by creating adjustment entries.

## Next steps

***

> **[Contexts and sources](/en/products/matcher/configuration/matcher-contexts-and-sources)**
>
> Full guide to context and source configuration.

> **[Match rules](/en/products/matcher/configuration/matcher-match-rules)**
>
> All rule types and config options in detail.

> **[Confidence scoring](/en/products/matcher/reference/matcher-confidence-scoring)**
>
> How Matcher calculates scores and what they mean.

> **[Resolving exceptions](/en/products/matcher/daily-reconciliation/matcher-resolving-exceptions)**
>
> Handle unmatched transactions.


# Get a reconciliation context
Source: https://docs.lerian.studio/en/reference/products/matcher/retrieve-context

/en/openapi/v3-current/matcher.yaml get /v1/contexts/{contextId}
Use this endpoint to retrieve the details of a specific reconciliation context by its identifier.



# Update a reconciliation context
Source: https://docs.lerian.studio/en/reference/products/matcher/update-context

/en/openapi/v3-current/matcher.yaml patch /v1/contexts/{contextId}
Use this endpoint to update the fields of a specific reconciliation context by its identifier. Setting `status` to `ACTIVE` is refused with `409` while the context is not ready for activation. A `signConvention` change is refused with `409` once the context has carried a partial balance, or while a match run is in progress.



# Midaz error list
Source: https://docs.lerian.studio/en/reference/products/midaz/error-list

Midaz APIs return a structured error object with a stable code, HTTP status, and message so you can quickly diagnose ledger issues and remediate them.

The Midaz API returns errors on `/v2` routes as an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details object, served with the `application/problem+json` content type:

```json theme={null}
{
   "type": "https://errors.lerian.studio/v1/<error_code>",
   "title": "<error_title>",
   "status": <http_status>,
   "detail": "<error_message>",
   "code": "<error_code>"
}
```

> [!NOTE]
>
> Routes under `/v1` return errors as `application/json` with `code`, `title`, and `message`. Validation errors on `/v1` can also carry `entityType` and `fields`.

**Field definitions**

* `type`: A URI that identifies the error type, built as `https://errors.lerian.studio/v1/` followed by the error code.
* `title`: A brief summary of the issue.
* `status`: The HTTP status code of the response.
* `detail`: Detailed guidance for resolving the error. The `message` column in the table below shows the text that the API returns. `%v` stands for a value that the response fills in.
* `code`: A unique, stable identifier for the error.
* `entityType`: The entity the error relates to (for example, `Organization`). Only present when applicable.

> [!NOTE]
>
> For server-side errors (HTTP 5xx), `title` and `detail` carry the catalog text. An unexpected error returns a generic body. Use `code` and `type` to identify the error.

**Field-level error details**

For issues specific to individual fields, an `errors` array lists each field with its problem.

Examples:

```json Missing Required Fields theme={null}
{
   "type": "https://errors.lerian.studio/v1/0009",
   "title": "Missing Fields in Request",
   "status": 400,
   "detail": "Your request is missing one or more required fields: [legalName]. Please refer to the documentation to ensure all necessary fields are included in your request.",
   "code": "0009",
   "entityType": "Organization",
   "errors": [
      { "location": "legalName", "message": "legalName is a required field" }
   ]
}
```

```json Invalid Field Values theme={null}
{
   "type": "https://errors.lerian.studio/v1/0047",
   "title": "Bad Request",
   "status": 400,
   "detail": "The server could not understand the request due to malformed syntax. Please check the listed fields and try again.",
   "code": "0047",
   "errors": [
      { "location": "legalName", "message": "legalName is a required field." },
      { "location": "parentOrganizationId", "message": "parentOrganizationId must be a valid UUID" }
   ]
}
```

```json Unexpected Fields theme={null}
{
   "type": "https://errors.lerian.studio/v1/0053",
   "title": "Unexpected Fields in the Request",
   "status": 400,
   "detail": "The request body contains more fields than expected. Please send only the allowed fields as per the documentation. The unexpected fields are listed in the fields object.",
   "code": "0053",
   "errors": [
      { "location": "unknownField", "message": "unexpected field", "value": "..." }
   ]
}
```

## Midaz errors

***

Refer to the following table for error codes and their descriptions:

| `code` | `title` | `message` |
| - | - | - |
| 0002 | `Ledger Name Conflict` | `A ledger named %v already exists in your organization. Please rename the ledger, or if you want to use the same name, consider creating a new ledger for a different division.` |
| 0003 | `Asset Name or Code Duplicate` | `An asset with the same name or code already exists in your ledger. Please modify the name or code of your new asset.` |
| 0004 | `Code Uppercase Requirement` | `The code must be in uppercase. Please ensure that the code is in uppercase format and try again.` |
| 0005 | `Currency Code Standard Compliance` | `Currency-type assets must comply with the ISO-4217 standard. Please use a currency code that conforms to ISO-4217 guidelines.` |
| 0007 | `Entity Not Found` | `No entity was found for the given ID. Please make sure to use the correct ID for the entity you are trying to manage.` |
| 0008 | `Action Not Permitted` | `The action you are attempting is not allowed in the current environment. Please refer to the documentation for guidance.` |
| 0009 | `Missing Fields in Request` | `Your request is missing one or more required fields: %v. Please refer to the documentation to ensure all necessary fields are included in your request.` |
| 0012 | `Account Balance Deletion Error` | `An account or sub-account cannot be deleted if it has a remaining balance. Please ensure all remaining balances are transferred to another account before attempting to delete.` |
| 0015 | `Duplicate Segment Name Error` | `A segment with the name %v already exists for this ledger ID %v. Please try again with a different ledger or name.` |
| 0018 | `Insufficient Funds Error` | `The transaction could not be completed due to insufficient funds in the account. Please add sufficient funds to your account and try again.` |
| 0019 | `Account Ineligibility Error` | `One or more accounts listed in the transaction are not eligible to participate. Please review the account statuses and try again.` |
| 0020 | `Alias Unavailability Error` | `The alias %v is already in use. Please choose a different alias and try again.` |
| 0024 | `Account Status Transaction Restriction` | `The current statuses of the source and/or destination accounts do not permit transactions. Change the account status(es) and try again.` |
| 0029 | `Invalid Parent Account ID` | `The specified parent account ID does not exist. Please verify the ID is correct and attempt your request again.` |
| 0030 | `Mismatched Asset Code` | `The parent account ID you provided is associated with a different asset code than the one specified in your request. Please make sure the asset code matches that of the parent account, or use a different parent account ID and try again.` |
| 0032 | `Invalid Country Code` | `The provided country code in the 'address.country' field does not conform to the ISO-3166 alpha-2 standard. Please provide a valid alpha-2 country code.` |
| 0033 | `Invalid Code Format` | `The 'code' field must be alphanumeric, in upper case, and must contain at least one letter. Please provide a valid code.` |
| 0034 | `Asset Code Not Found` | `The provided asset code does not exist in our records. Please verify the asset code and try again.` |
| 0035 | `Portfolio ID Not Found` | `The provided portfolio ID does not exist in our records. Please verify the portfolio ID and try again.` |
| 0036 | `Segment ID Not Found` | `The provided segment ID does not exist in our records. Please verify the segment ID and try again.` |
| 0037 | `Ledger ID Not Found` | `The provided ledger ID does not exist in our records. Please verify the ledger ID and try again.` |
| 0038 | `Organization ID Not Found` | `The provided organization ID does not exist in our records. Please verify the organization ID and try again.` |
| 0039 | `Parent Organization ID Not Found` | `The provided parent organization ID does not exist in our records. Please verify the parent organization ID and try again.` |
| 0040 | `Invalid Type` | `The provided 'type' is not valid. Accepted types are currency, fiat, crypto, commodity, or others. Please provide a valid type.` |
| 0042 | `Invalid Token` | `The provided token is expired, invalid or malformed. Please provide a valid token and try again.` |
| 0043 | `Insufficient Privileges` | `You do not have the necessary permissions to perform this action. Please contact your administrator if you believe this is an error.` |
| 0046 | `Internal Server Error` | `The server encountered an unexpected error. Please try again later or contact support.` |
| 0047 | `Bad Request` | `The server could not understand the request due to malformed syntax. Please check the listed fields and try again.` |
| 0050 | `Metadata Key Length Exceeded` | `The metadata key %v exceeds the maximum allowed length of %v characters. Please use a shorter key.` |
| 0051 | `Metadata Value Length Exceeded` | `The metadata value %v exceeds the maximum allowed length of %v characters. Please use a shorter value.` |
| 0052 | `Account ID Not Found` | `The provided account ID does not exist in our records. Please verify the account ID and try again.` |
| 0053 | `Unexpected Fields in the Request` | `The request body contains more fields than expected. Please send only the allowed fields as per the documentation. The unexpected fields are listed in the fields object.` |
| 0055 | `Asset ID Not Found` | `The provided asset ID does not exist in our records. Please verify the asset ID and try again.` |
| 0056 | `No Assets Found` | `No assets were found in the search. Please review the search criteria and try again.` |
| 0057 | `No Segments Found` | `No segments were found in the search. Please review the search criteria and try again.` |
| 0058 | `No Portfolios Found` | `No portfolios were found in the search. Please review the search criteria and try again.` |
| 0059 | `No Organizations Found` | `No organizations were found in the search. Please review the search criteria and try again.` |
| 0060 | `No Ledgers Found` | `No ledgers were found in the search. Please review the search criteria and try again.` |
| 0064 | `No Accounts Found` | `No accounts were found in the search. Please review the search criteria and try again.` |
| 0065 | `Invalid Path Parameter` | `One or more path parameters are in an incorrect format. Please check the following parameters %v and ensure they meet the required format before trying again.` |
| 0066 | `Invalid Account Type` | `The provided 'type' is not valid.` |
| 0067 | `Invalid Metadata Nesting` | `The metadata object cannot contain nested values. Please ensure that the value %v is not nested and try again.` |
| 0068 | `Operation ID Not Found` | `The provided operation ID does not exist in our records. Please verify the operation ID and try again.` |
| 0069 | `No Operations Found` | `No operations were found in the search. Please review the search criteria and try again.` |
| 0070 | `Transaction ID Not Found` | `The provided transaction ID does not exist in our records. Please verify the transaction ID and try again.` |
| 0071 | `No Transactions Found` | `No transactions were found in the search. Please review the search criteria and try again.` |
| 0072 | `Invalid Transaction Type` | `Only one transaction type (%v) must be specified in the '%v' field for each entry. Please review your input and try again.` |
| 0073 | `Transaction Value Mismatch` | `The values for the source, the destination, or both do not match the specified transaction amount. Please verify the values and try again.` |
| 0074 | `External Account Modification Prohibited` | `Accounts of type 'external' cannot be deleted or modified as they are used for traceability with external systems. Please review your request and ensure operations are only performed on internal accounts.` |
| 0077 | `Invalid Date Format Error` | `The 'initialDate', 'finalDate', or both are in the incorrect format. Please use the 'yyyy-mm-dd' format and try again.` |
| 0078 | `Invalid Final Date Error` | `The 'finalDate' cannot be earlier than the 'initialDate'. Please verify the dates and try again.` |
| 0079 | `Date Range Exceeds Limit Error` | `The range between 'initialDate' and 'finalDate' exceeds the permitted limit of %v months. Please adjust the dates and try again.` |
| 0080 | `Pagination Limit Exceeded` | `The pagination limit exceeds the maximum allowed of %v items per page. Please verify the limit and try again.` |
| 0081 | `Invalid Sort Order` | `The 'sort_order' field must be 'asc' or 'desc'. Please provide a valid sort order and try again.` |
| 0082 | `Invalid Query Parameter` | `One or more query parameters are in an incorrect format. Please check the following parameters '%v' and ensure they meet the required format before trying again.` |
| 0083 | `Invalid Date Range Error` | `Both 'initialDate' and 'finalDate' fields are required and must be in the 'yyyy-mm-dd' format. Please provide valid dates and try again.` |
| 0084 | `Duplicate Idempotency Key` | `The idempotency key %v is already in use. Please provide a unique key and try again.` |
| 0085 | `Account Alias Not Found` | `The provided account Alias does not exist in our records. Please verify the account Alias and try again.` |
| 0087 | `Transaction Revert already exist` | `Transaction revert already exists. Please try again.` |
| 0088 | `Transaction is already a reversal` | `Transaction is already a reversal. Please try again` |
| 0089 | `Transaction can't be reverted` | `Transaction can't be reverted. Please try again` |
| 0090 | `Transaction ambiguous account` | `Transaction can't use the same account in sources and destinations` |
| 0091 | `ID cannot be used as the parent ID` | `The provided ID cannot be used as the parent ID. Please choose a different one.` |
| 0093 | `Balance cannot be deleted` | `Balance cannot be deleted because it still has funds in it.` |
| 0094 | `Unmarshalling error` | `invalid value for field '%v': expected type '%v', but got '%v'` |
| 0095 | `Message Broker Unavailable` | `The server encountered an unexpected error while connecting to Message Broker. Please try again later or contact support.` |
| 0096 | `Invalid Account Alias` | `The alias contains invalid characters. Please verify the alias value and try again.` |
| 0098 | `Invalid Pending Transaction` | `External accounts cannot be used for pending transactions in source operations. Please check the accounts and try again.` |
| 0099 | `Invalid Transaction Status` | `The transaction status does not allow the requested action. Please check the transaction status.` |
| 0101 | `Operation Route Not Found` | `The provided operation route does not exist in our records. Please verify the operation route and try again.` |
| 0102 | `No Operation Routes Found` | `No operation routes were found in the search. Please review the search criteria and try again.` |
| 0103 | `Invalid Operation Route Type` | `The provided 'operationType' is not valid. Accepted types are 'source', 'destination', or 'bidirectional'. Please provide a valid type.` |
| 0104 | `Missing Operation Routes in Request` | `Your request must include at least one operation route of each type (debit and credit). Please refer to the documentation to ensure these fields are properly populated.` |
| 0105 | `Transaction Route Not Found` | `The provided transaction route does not exist in our records. Please verify the transaction route and try again.` |
| 0106 | `No Transaction Routes Found` | `No transaction routes were found in the search. Please review the search criteria and try again.` |
| 0107 | `Operation Route Linked to Transaction Routes` | `The operation route cannot be deleted because it is linked to one or more transaction routes. Please remove the operation route from all transaction routes before attempting to delete it.` |
| 0108 | `Duplicate Account Type Key Value Error` | `An account type with the specified key value already exists for this organization and ledger. Please use a different key value or update the existing account type.` |
| 0109 | `Account Type Not Found Error` | `The account type you are trying to access does not exist or has been removed.` |
| 0110 | `No Account Types Found` | `No account types were found in the search. Please review the search criteria and try again.` |
| 0111 | `Invalid Account Rule Type` | `The provided 'account.ruleType' is not valid. Accepted types are 'alias' or 'account_type'. Please provide a valid rule type.` |
| 0112 | `Invalid Account Rule Value` | `The provided 'account.validIf' is not valid. Please provide a string for 'alias' or an array of strings for 'account_type'.` |
| 0113 | `Corrupted Account Rule` | `The account rule data in the operation route is internally inconsistent (unknown rule type or malformed validIf value). This indicates a data integrity issue — please verify the operation route configuration.` |
| 0114 | `Transaction Route Not Informed` | `The transaction route is not informed. Please inform the transaction route for this transaction.` |
| 0115 | `Invalid Transaction Route ID` | `The provided transaction route ID is not a valid UUID format. Please provide a valid UUID for the transaction route.` |
| 0116 | `Accounting Route Count Mismatch` | `The operation routes count does not match the transaction route cache. Expected %v source and %v destination operations, but the route has %v source, %v destination, and %v bidirectional operation routes.` |
| 0117 | `Accounting Route Not Found` | `The operation route ID '%v' was not found in the transaction route cache for operation '%v'. Please verify the route configuration.` |
| 0118 | `Accounting Alias Validation Failed` | `The operation alias '%v' does not match the expected alias '%v' defined in the accounting route rule.` |
| 0119 | `Accounting Account Type Validation Failed` | `The account type '%v' does not match any of the expected account types %v defined in the accounting route rule.` |
| 0120 | `Invalid Characters` | `The field 'keyValue' contains invalid characters. Use only letters, numbers, underscores and hyphens.` |
| 0121 | `Invalid Future Date Error` | `The 'transactionDate' cannot be a future date. Please provide a valid date.` |
| 0122 | `Invalid Field for Pending Transaction Error` | `Pending transactions do not support the 'transactionDate' field. To proceed, please remove it from your request.` |
| 0123 | `Duplicated Alias Key Value Error` | `An account alias with the specified key value already exists for this organization and ledger. Please use a different key value.` |
| 0124 | `Additional Balance Creation Not Allowed` | `Additional balances are not allowed for external account type.` |
| 0125 | `Invalid Transaction Value` | `Negative or zero transaction values are not allowed. The 'send.value' must be greater than zero.` |
| 0127 | `Account Creation Failed` | `The account could not be created because the default balance could not be created. Please try again.` |
| 0128 | `Transaction Backup Cache Failed` | `The server encountered an unexpected error while adding the transaction to the backup cache. Please try again later or contact support.` |
| 0129 | `Transaction Backup Cache Marshal Failed` | `The server encountered an unexpected error while serializing the transaction for the backup cache. This uses the same backup mechanism. Please try again later or contact support.` |
| 0131 | `Invalid Datetime Format Error` | `The '%v' parameter is in the incorrect format. Please use the '%v' format and try again.` |
| 0132 | `Metadata Index Already Exists` | `A metadata index with the same key already exists for this entity. Please use a different key from the existing index.` |
| 0133 | `Metadata Index Not Found` | `The specified metadata index does not exist. Please verify the index name and try again.` |
| 0137 | `Metadata Index Deletion Forbidden` | `System indexes cannot be deleted. Please ensure you are deleting a custom metadata index.` |
| 0138 | `Invalid Entity Name` | `The provided entity name is not valid.` |
| 0139 | `Transaction Backup Cache Retrieval Failed` | `The transaction could not be retrieved from the backup cache internal function. Please ensure the transaction exists in the cache before processing balances.` |
| 0140 | `Invalid Timestamp` | `The provided timestamp '%v' is invalid. Timestamps cannot be in the future.` |
| 0141 | `No Balance Data at Date` | `No balance data is available at the specified date.` |
| 0142 | `Missing Required Query Parameter` | `The required query parameter '%v' is missing from the request.` |
| 0143 | `Payload Too Large` | `The request payload exceeds the maximum allowed size of 64KB.` |
| 0144 | `JSON Nesting Depth Exceeded` | `The JSON payload exceeds the maximum allowed nesting depth of 10 levels. Please flatten your data structure.` |
| 0145 | `JSON Key Count Exceeded` | `The JSON payload exceeds the maximum allowed number of keys (100). Please reduce the number of keys in your payload.` |
| 0146 | `Tenant Not Provisioned` | `Database schema not initialized for this tenant. Contact your administrator.` |
| 0147 | `Unknown Settings Field` | `The settings contain an unknown field: '%v'. Only known settings fields are allowed.` |
| 0148 | `Invalid Settings Field Type` | `The settings field '%v' has an invalid type. Expected %v.` |
| 0149 | `Settings Field at Root Level` | `The settings field '%v' must be nested under '%v'. Expected structure: {"%v": {"%v": value}}.` |
| 0150 | `Route Not Bidirectional` | `The operation route does not allow bidirectional transactions. Only routes with operation type 'bidirectional' can be reverted.` |
| 0151 | `Missing Counterpart` | `Route '%v' requires at least one debit and one credit operation (counterpart validation).` |
| 0152 | `Direction Route Mismatch` | `Operation direction '%v' is not compatible with route operation type '%v' for operation '%v'.` |
| 0153 | `No Source for Action` | `The action '%v' requires at least one source operation route. Please add a source route for this action.` |
| 0154 | `No Destination for Action` | `The action '%v' requires at least one destination operation route. Please add a destination route for this action.` |
| 0157 | `No Routes for Action` | `No routes found for action '%v'. Please configure operation routes for this action in the transaction route.` |
| 0158 | `Too Many Operation Routes` | `The number of operation routes exceeds the maximum allowed. Please reduce the number of operation routes and try again.` |
| 0159 | `Service Suspended` | `service is %v for tenant %v` |
| 0160 | `Tenant Not Found` | `tenant not found: %v` |
| 0161 | `Tenant Service Unavailable` | `failed to resolve tenant %v` |
| 0162 | `Scenario Not Allowed For Direction` | `The accounting scenario is not allowed for the specified operation direction. %v` |
| 0163 | `Reserve Group Incomplete` | `The reserve group (hold, commit, cancel) must be complete. %v` |
| 0164 | `Direct Scenario Required` | `The direct scenario is required when other scenarios are present. %v` |
| 0165 | `Revert Only Bidirectional` | `The revert scenario is only allowed for bidirectional operation routes. %v` |
| 0166 | `Accounting Entry Field Required` | `A required field is missing in the accounting entry. %v` |
| 0167 | `Overdraft Limit Exceeded Error` | `The transaction could not be completed because it would exceed the configured overdraft limit for the balance. Please reduce the amount or increase the overdraft limit and try again.` |
| 0168 | `Direct Operation On Internal Balance Error` | `Direct operations on internal-scope balances are not permitted. Internal balances are managed exclusively by the system. Please target a transactional balance and try again.` |
| 0169 | `Deletion Of Internal Balance Error` | `Internal-scope balances cannot be deleted. They are managed by the system and must remain for accounting consistency.` |
| 0170 | `Reserved Balance Key Error` | `The balance key %v is reserved for system use and cannot be created through the public API. Please choose a different key and try again.` |
| 0171 | `Invalid Balance Direction Error` | `The balance direction %v is not supported. Allowed values are "credit" and "debit".` |
| 0172 | `Invalid Balance Settings Error` | `The balance settings payload is invalid. Please review overdraft, limit, and scope fields and try again.` |
| 0173 | `Overdraft Limit Below Usage Error` | `The new overdraft limit is below the amount currently used. Raise the limit above the current usage or repay the outstanding amount before reducing the limit.` |
| 0174 | `Stale Balance Version Error` | `The balance was modified by another transaction between read and write. Please retry the operation after reading the latest balance state.` |
| 0175 | `Update Of Internal Balance Error` | `Internal balances are system-managed and cannot be updated through the public API. They are maintained by the system for accounting consistency.` |
| 0176 | `Invalid Settings Field Value` | `The settings field '%v' has an invalid value. Allowed values are: %v.` |
| 0177 | `Transaction Reservation Denied Error` | `The transaction could not be completed because it would exceed a configured usage limit. Please reduce the amount or wait for the limit window to reset and try again.` |
| 0178 | `Transaction Reservation Unavailable Error` | `The transaction could not be completed because the usage-limit service is temporarily unavailable and this ledger is configured to reject transactions when it cannot be reached. Please retry shortly.` |
| 0180 | `Invalid fee priority` | `The priority field in fees is invalid. Field can not be repeated.` |
| 0182 | `minimumAmount greater than maximumAmount` | `minimumAmount value is greater than maximumAmount.` |
| 0183 | `Nothing to Update` | `No updatable fields were provided. Please include at least one field to update.` |
| 0184 | `Package already exists` | `A package already exists in the same scope with the same minimumAmount and maximumAmount.` |
| 0185 | `Invalid header parameter` | `One or more header parameters are in an incorrect format. Please check the following parameters %v and ensure they meet the required format before trying again.` |
| 0186 | `Failed to calculate fee` | `Failed to calculate the fee for the transaction. Please check the fee configuration and try again.` |
| 0187 | `Missing calculation model` | `The calculation model is required for fee %v.` |
| 0188 | `originalAmount is required when priority is one` | `For Priority equals to one, referenceAmount must be 'originalAmount' for fee %v.` |
| 0189 | `Failed to apply rule: flatFee or percentual` | `applicationRule flatFee or percentual must have exactly 1 calculation for Fee %v.` |
| 0190 | `Invalid calculation type: percentual` | `The calculation type percentual must be 'percentage' for Fee %v.` |
| 0191 | `Invalid calculation type: flatFee` | `The calculation type flatFee must be 'flat' for Fee %v.` |
| 0192 | `Missing required fee fields` | `All fields of a new Fee must be filled. Please check again the payload passed.` |
| 0193 | `Calculation field is required for fee` | `Please fill the Calculation object correctly. All calculation fields must be filled.` |
| 0194 | `referenceAmount is not valid` | `Field reference amount must be originalAmount or afterFeesAmount.` |
| 0195 | `Invalid applicationRule` | `Field application rule must be maxBetweenTypes, flatFee or percentual.` |
| 0196 | `Invalid calculation type` | `Field calculation type must be percentage or flat.` |
| 0197 | `maximumAmount less than minimumAmount` | `maximumAmount value is less than minimumAmount.` |
| 0198 | `Package filtering error` | `More than one fee package matches this transaction at the same specificity, so none of them can be applied. Re-scope one of these packages: %v.` |
| 0199 | `Package amount range overlap` | `The maximumAmount and minimumAmount of the new package overlap with the amount range of an existing package.` |
| 0200 | `Failed to distribute values` | `Failed to distribute the transaction values. Please check the data passed.` |
| 0201 | `Failed to apply rule: maxBetweenTypes` | `applicationRule maxBetweenTypes must have more than 1 calculation for Fee %v.` |
| 0202 | `Invalid segmentID` | `The specified segmentID is not a valid UUID. Please check the value passed.` |
| 0204 | `Error to convert values` | `The value of the field %v is invalid. Remember to use dot (.) as decimal separator instead of comma (,). Example: use 1000.50 instead of 1000,50.` |
| 0205 | `originalAmount is required when isDeductibleFrom is true` | ``For isDeductibleFrom `true`, referenceAmount must be 'originalAmount' for fee %v.`` |
| 0206 | `applicationRule invalid value` | `applicationRule is invalid, Err: %v.` |
| 0207 | `calculation value percentage invalid` | `Calculation value is invalid, it cannot exceed 100%. Please check the calculation value for Fee %v.` |
| 0208 | `calculation value flat invalid` | `Calculation value is invalid, it cannot exceed the minimum amount %v. Please check the calculation value for Fee %v.` |
| 0210 | `deductible value forbidden` | `Can not update deductible value to true. The calculation value is bigger than 100% for Fee %v.` |
| 0211 | `deductible value forbidden` | `Can not update deductible value to true. Calculation value is bigger than the minimum amount %v for Fee %v.` |
| 0212 | `Invalid Page` | `Query parameter page is invalid. The page must be greater than 0.` |
| 0213 | `Billing package not found` | `No billing package was found for the given ID '%v'.` |
| 0214 | `Invalid billing package type` | `The billing package type is invalid. Valid types are 'volume' and 'maintenance'.` |
| 0215 | `Missing volume fields` | `Volume billing packages require: eventFilter (transactionRoute, status), pricingModel, tiers, assetCode, debitAccountAlias, and creditAccountAlias.` |
| 0216 | `Missing maintenance fields` | `Maintenance billing packages require: feeAmount, assetCode, maintenanceCreditAccount, and accountTarget.` |
| 0217 | `Invalid pricing model` | `The pricing model is invalid. Valid models are 'tiered' and 'fixed'.` |
| 0218 | `Invalid pricing tier` | `Pricing tier configuration is invalid: %v.` |
| 0219 | `Billing route overlap` | `A billing package already exists for this organization, ledger, and transaction route combination.` |
| 0221 | `Billing calculation failed` | `Failed to calculate billing: %v` |
| 0224 | `Invalid billing period` | `The billing period format is invalid. Use 'YYYY-MM' (monthly), 'YYYY-Www' (weekly, e.g. '2026-W13'), or 'YYYY-MM-DD' (daily) format (e.g., '2026-01' or '2026-01-15').` |
| 0225 | `Invalid free quota` | `The free quota value is invalid. Must be a non-negative integer.` |
| 0226 | `Invalid discount tier` | `Discount tier configuration is invalid. Each tier must have minQuantity and discountPercentage between 0 and 100.` |
| 0227 | `Invalid count mode` | `The count mode is invalid. Valid modes are 'perRoute' and 'perAccount'.` |
| 0229 | `Invalid account target` | `The account target is invalid. Exactly one of segmentId, portfolioId, or aliases must be provided.` |
| 0230 | `Invalid fee amount` | `The fee amount is invalid. It must be a positive value greater than zero.` |
| 0231 | `Segment context unavailable` | `Segment-based waivers are configured but the resolution service is not available. This is an internal configuration issue.` |
| 0233 | `Deductible fee exceeds the amount it deducts from` | `A deductible fee cannot be applied because it meets or exceeds the amount it is deducted from, which would leave the recipient with nothing or a negative balance. Reduce the fee, increase the transfer amount, or exempt the account.` |
| 0235 | `Query Parameter Not Accepted` | `The query parameter '%v' is not accepted on this endpoint because the request path already names the ledger. Please remove it and try again.` |
| 0236 | `Duplicate fee key` | `More than one fee in this request resolves to the key '%v', so the fee it applies to is ambiguous. Please send each fee once.` |
| 0249 | `Cross-Ledger Not Enabled Error` | `Ledger %v is not enabled for cross-ledger transactions. Enable crossLedger.enabled on every ledger involved.` |
| 0250 | `Cross-Ledger Asset Mismatch Error` | `Cross-ledger transactions must use the same asset on every leg.` |
| 0251 | `Cross-Organization Route Validation Unsupported Error` | `Cross-ledger transactions that span more than one organization are not supported when accounting route validation is enabled on a participating ledger, because accounting routes belong to a single organization.` |
| 0252 | `Cross-Ledger Lifecycle Requires V2 Error` | `A transaction that belongs to a cross-ledger group must be committed, canceled, or reverted through the v2 API so the complete group is transitioned atomically.` |
| 0253 | `Cross-Ledger Group Incomplete Error` | `The cross-ledger transaction group is incomplete and cannot be transitioned safely.` |
| 0254 | `Cross-Ledger Group Not Pending Error` | `The cross-ledger transaction group is %v and can no longer be committed or canceled.` |
| 0255 | `Cross-Ledger Route Not Configured Error` | `The transaction could not be completed because route validation is enabled on a participating ledger but the transaction route has no operation route with a crossLedger accounting entry for the cross-ledger bridge. Link a bidirectional operation route with a crossLedger entry to the transaction route and try again.` |
| 0256 | `Invalid Cross-Ledger Route Error` | `The cross-ledger bridge route must resolve to exactly one operation route. %v` |
| 0336 | `Metadata Key Invalid Chars` | `Metadata key contains invalid characters.` |
| 0484 | `Route Not Found` | `The requested route does not exist. Please verify the HTTP method and path and try again.` |
| 0485 | `Method Not Allowed` | `The HTTP method is not allowed for the requested route. Please verify the method and try again.` |
| 0486 | `Transaction Locked` | `This transaction is currently being processed by another request. Please retry shortly.` |
| 0488 | `Instrument Ledger Reference Not Found` | `The ledger referenced by this instrument does not exist in this organization. Please provide a ledgerId that belongs to the organization and try again.` |
| 0489 | `Instrument Account Reference Not Found` | `The account referenced by this instrument does not exist in the referenced ledger. Please provide an accountId that belongs to the ledger and try again.` |
| 0490 | `Skip Not Permitted` | `The %v skip requested for this operation is not permitted on this ledger. Enable the matching ledger override to allow it, or remove the skip from your request.` |
| 0491 | `Holder Required` | `This ledger requires every account to name an existing holder. Please provide a valid holderId and try again.` |
| 0492 | `Overdraft Route Not Configured Error` | `The transaction could not be completed because route validation is enabled but the accounting route applied to the overdraft operation does not define an overdraft entry for the required direction. Configure an overdraft accounting entry on the operation route and try again.` |
| 0497 | `Request Header Fields Too Large` | `The request header fields are too large. Please reduce the size of the request headers and try again.` |
| 0498 | `Invalid Dashboard Window` | `Invalid dashboard window: use period (7d, 30d, 90d) or start_date/end_date (RFC3339, at most 90 days apart), never both.` |
| 0499 | `Transaction Scope Mismatch` | `Every leg of the transaction must name the same organization and ledger. Please review your input so that all legs share one scope and try again.` |
| 0500 | `Invalid Account Type Direction` | `The field 'defaultDirection' has an invalid value. Use one of the allowed values: credit or debit.` |
| 0501 | `Schema Migration Pending` | `The request could not be completed because a pending database migration has not been applied to this database yet. Please retry shortly.` |
| 0502 | `Account Blocked` | `A source and/or destination account involved in this transaction is blocked and cannot transact. Unblock the account and try again.` |
| 0503 | `Missing Account Block Exceptions` | `The 'exceptions' field must carry at least one exception. Please provide the exceptions to create and try again.` |
| 0504 | `Account Block Exception Batch Too Large` | `The 'exceptions' field accepts at most 100 items per request. Please split the batch and try again.` |
| 0505 | `Invalid Account Block Exception Amount` | `The 'amount' of the exception at index %v must be a positive decimal value. Please verify the amount and try again.` |
| 0506 | `Invalid Account Block Exception TTL` | `The 'ttl' of the exception at index %v must be between 1 and 86400 seconds. Please verify the ttl and try again.` |
| 0507 | `Account Block Exception Alias Not Found` | `The 'accountAlias' of the exception at index %v does not exist in this ledger: %v. No exception was created. Please verify the alias and try again.` |
| 0508 | `Invalid Account Block Exception` | `The 'accountBlockExceptionId' presented does not exist, has expired or has already been used, or does not authorize this transaction's source account and debited amount. Please create a new exception and try again.` |
| 0509 | `Account Block Exception Not Supported` | `The 'accountBlockExceptionId' field is not accepted on the %v operation. Please present it on the direct, commit or revert operation instead.` |
| 0511 | `Transaction Already Transitioned` | `The transaction has already been committed or canceled, so the requested transition cannot run again. Please check the transaction status.` |
| 0512 | `Reserved Metadata Key` | `The metadata key %v is reserved by the ledger, which writes it itself. Please remove it from your request and try again.` |
| 0513 | `Balance Seed Rebuild Inconsistent Error` | `The request could not be completed because the current state of this balance could not be established from its operation history. Please retry shortly.` |
| 0514 | `Invalid Transaction Batch Cardinality` | `The transaction batch contains %v items, but it must contain between 1 and %v items. Please adjust the 'transactions' array and try again.` |
| 0515 | `Transaction Batch Input Leg Limit Exceeded` | `The transaction batch contains %v input debit and credit legs, exceeding the maximum of %v. Please reduce the number of legs and try again.` |
| 0516 | `Transaction Batch Budget Exceeded` | `The transaction batch exceeds the %v budget at transaction index %v: observed %v, maximum %v. Please reduce the batch work and try again.` |
| 0517 | `Invalid Transaction Batch` | `One or more transactions in the batch failed structural validation. Check errors for details.` |
| 0518 | `Account Closing Persistence Pending Error` | `The account cannot be closed yet because earlier work on it has not finished being persisted. No transaction is reapplied; please try again shortly.` |
| 0519 | `Account Closed Error` | `The operation could not be completed because the account is closed. A closed account accepts no further movements, and unblocking it does not reopen it.` |
| 0520 | `Account Closing Protection Indeterminate Error` | `The request could not be completed because the state of this account could not be established. Please retry shortly.` |
| 0521 | `Account Already Closed Error` | `The account is already closed and cannot be closed again. The recorded closing instant is preserved; please review the account state and try again if this was unexpected.` |
| 0522 | `Account Closing In Progress Error` | `A closing of this account is in progress. Please wait for it to conclude and try again.` |
| 0523 | `Account Balance Not Zero Error` | `The account cannot be closed because at least one of its balances still holds available funds, funds on hold or used overdraft. Please settle every balance to exactly zero and try again.` |
| 0524 | `Account Has Pending Transactions Error` | `The account cannot be closed because a pending transaction still holds its funds. Please commit or cancel those transactions and try again.` |
| 0525 | `Authorization Service Unavailable` | `The request could not be completed because the authorization service did not respond. Please retry shortly.` |
| 0526 | `Account Administrative Operation In Progress Error` | `Another operation on this account is in progress. Please try again shortly.` |
| 0527 | `Balance Has Open Fee Debt Error` | `A balance that still owes pending fees cannot be deleted, and its account cannot be deleted or closed. Please credit the balance so the pending fees are collected and try again.` |
| 0528 | `Balance Owed Fee Debt Error` | `A balance that other balances still owe pending fees to cannot be deleted, and its account cannot be deleted or closed. Please credit the balances that owe those fees so they are collected and try again.` |
| 0529 | `Fee Debt Record Pending Error` | `The pending fees this transaction touches have not finished being recorded. No transaction is reapplied; please try again shortly.` |
| 0530 | `Deductible fee cannot be deferrable` | `Fee %v is deducted from the payment (isDeductibleFrom true), so it cannot be deferrable. Set deferrable to false or isDeductibleFrom to false.` |
| 0531 | `Transaction Reservation Review Error` | `The transaction was flagged for review by a transaction validation rule, or a rule could not be evaluated for it, and this ledger enforces tracer decisions. Review the tracer rules or the ledger tracer settings.` |
| 0532 | `Transaction Reservation Rejected Error` | `The usage-limit service rejected the reservation request for this transaction. Verify that the asset, account type and transaction date are accepted by the tracer configuration.` |
| 0535 | `Transaction Reservation Rule Denied Error` | `The transaction was denied by a transaction validation rule and this ledger enforces tracer decisions. Review the tracer rules or the ledger tracer settings.` |
| 0536 | `Transaction Reservation Unauthorized Error` | `The tracer reservation seam rejected this ledger's credential and the ledger enforces tracer decisions with a closed fail posture. Check the ledger's Access Manager client and the tracer's allowed clients.` |
| CRM-0006 | `Holder ID Not Found` | `The provided holder ID does not exist in our records. Please verify the holder ID and try again.` |
| CRM-0008 | `Instrument ID Not Found` | `The provided instrument ID does not exist in our records. Please verify the instrument ID and try again.` |
| CRM-0010 | `Document Association Error` | `A document can only be associated with one holder.` |
| CRM-0013 | `Account Already Associated` | `An accountId from ledger can only be associated with a single related account on CRM.` |
| CRM-0017 | `Unable to Delete Holder` | `The holder cannot be deleted because it has one or more associated aliases.` |
| CRM-0023 | `Alias Closing Date Before Creation Date` | `The alias closing date cannot be before the creation date. Please provide a valid closing date.` |
| CRM-0024 | `Related Party Not Found` | `The specified related party does not exist. Please verify the related party ID and try again.` |
| CRM-0025 | `Invalid Related Party Role` | `The provided related party role is not valid. Accepted roles are: PRIMARY_HOLDER, LEGAL_REPRESENTATIVE, or RESPONSIBLE_PARTY.` |
| CRM-0026 | `Related Party Document Required` | `The related party document is required. Please provide a valid document.` |
| CRM-0027 | `Related Party Name Required` | `The related party name is required. Please provide a valid name.` |
| CRM-0028 | `Related Party Start Date Required` | `The related party start date is required. Please provide a valid start date.` |
| CRM-0029 | `Related Party End Date Invalid` | `The related party end date must be after the start date. Please provide a valid end date.` |
| CRM-0030 | `Unable to Delete Holder` | `The holder cannot be deleted because it owns one or more active accounts.` |
| CRM-0038 | `Provisioning Failed` | `The provisioning operation failed. Please try again later.` |
| CRM-0041 | `Reserved Tenant ID` | `The tenant id "default" is reserved for internal single-tenant use and cannot be used as a tenant identifier. Please use a different tenant id and try again.` |
| CRM-0042 | `Invalid Instrument Account Type` | `The provided instrument account type is not valid. Accepted values are: DEPOSIT, SAVINGS, INVESTMENT, OTHER_FINANCIAL_INVESTMENTS, NON_RESIDENT, or PAYMENT.` |
| CRM-0043 | `Bank Account Already Registered` | `This bank account is already registered to another instrument in this organization: the same bankId and account, on the same branch or where one of them has no branch. Use that instrument, or delete it before registering the account again.` |


# Activate a spending limit
Source: https://docs.lerian.studio/en/reference/products/tracer/activate-limit

/en/openapi/v3-current/tracer.yaml post /v1/limits/{id}/activate
Use this endpoint to activate a spending limit. Activates the limit for enforcement in validations.



# Activate a fraud rule
Source: https://docs.lerian.studio/en/reference/products/tracer/activate-rule

/en/openapi/v3-current/tracer.yaml post /v1/rules/{id}/activate
Use this endpoint to activate a fraud rule. Activates the fraud rule for evaluation in validations. Valid transitions are DRAFT to ACTIVE and INACTIVE to ACTIVE.



# Create a new spending limit
Source: https://docs.lerian.studio/en/reference/products/tracer/create-limit

/en/openapi/v3-current/tracer.yaml post /v1/limits
Use this endpoint to create a spending limit with scopes array. Limits are created in DRAFT status. Use the activate endpoint to start enforcement. After creation, limitType, asset and resetTime cannot be changed.



# Create a new fraud rule
Source: https://docs.lerian.studio/en/reference/products/tracer/create-rule

/en/openapi/v3-current/tracer.yaml post /v1/rules
Use this endpoint to create a fraud rule with a CEL expression and scopes array. Rules are always created in DRAFT status. Use the activate endpoint to start evaluation.



# Deactivate a spending limit
Source: https://docs.lerian.studio/en/reference/products/tracer/deactivate-limit

/en/openapi/v3-current/tracer.yaml post /v1/limits/{id}/deactivate
Use this endpoint to deactivate a spending limit. Pauses the limit from being enforced in validations.



# Deactivate a fraud rule
Source: https://docs.lerian.studio/en/reference/products/tracer/deactivate-rule

/en/openapi/v3-current/tracer.yaml post /v1/rules/{id}/deactivate
Use this endpoint to deactivate a fraud rule. Pauses the fraud rule from being evaluated in validations. Valid transitions are ACTIVE to INACTIVE and DRAFT to INACTIVE.



# Delete a spending limit
Source: https://docs.lerian.studio/en/reference/products/tracer/delete-limit

/en/openapi/v3-current/tracer.yaml delete /v1/limits/{id}
Use this endpoint to soft-delete a spending limit. Only DRAFT and INACTIVE limits can be deleted. ACTIVE limits must be deactivated first. The limit is preserved in the audit trail.



# Delete a fraud rule
Source: https://docs.lerian.studio/en/reference/products/tracer/delete-rule

/en/openapi/v3-current/tracer.yaml delete /v1/rules/{id}
Use this endpoint to soft-delete a fraud rule. Only DRAFT and INACTIVE rules can be deleted. ACTIVE rules must be deactivated first. The rule is preserved in the audit trail.



# Transition a limit back to draft
Source: https://docs.lerian.studio/en/reference/products/tracer/draft-limit

/en/openapi/v3-current/tracer.yaml post /v1/limits/{id}/draft
Use this endpoint to transition a limit from INACTIVE back to DRAFT. Allows re-editing a previously deactivated limit before re-activating it.



# Transition a rule back to draft
Source: https://docs.lerian.studio/en/reference/products/tracer/draft-rule

/en/openapi/v3-current/tracer.yaml post /v1/rules/{id}/draft
Use this endpoint to transition a fraud rule from INACTIVE back to DRAFT. Allows re-editing a previously deactivated rule before re-activating it.



# Get dashboard flagged-traffic breakdown
Source: https://docs.lerian.studio/en/reference/products/tracer/get-dashboard-fraud-types

/en/openapi/v3-current/tracer.yaml get /v1/dashboard/fraud-types
Use this endpoint to get the DENY and REVIEW decisions in the window, broken down by transaction type, with the share of the flagged traffic for each type. Set the window with `period` (7d, 30d or 90d, default 30d), or with `start_date` and `end_date` (at most 90 days).



# Get dashboard headline metrics
Source: https://docs.lerian.studio/en/reference/products/tracer/get-dashboard-metrics

/en/openapi/v3-current/tracer.yaml get /v1/dashboard/metrics
Use this endpoint to get the headline metrics for the window. The response returns validation counts, decision rates, blocked volume per asset, mean decision latency, and the live counts of active rules and limits. Set the window with `period` (7d, 30d or 90d, default 30d), or with `start_date` and `end_date` (at most 90 days).



# Get the busiest rules in the window
Source: https://docs.lerian.studio/en/reference/products/tracer/get-dashboard-top-rules

/en/openapi/v3-current/tracer.yaml get /v1/dashboard/top-rules
Use this endpoint to get up to ten rules, ordered by how often they matched in the window. For each rule, the response returns the number of validations that evaluated it, its detection rate, and the mean end-to-end latency of the validations it matched. Set the window with `period` (7d, 30d or 90d, default 30d), or with `start_date` and `end_date` (at most 90 days).



# Get dashboard volume series
Source: https://docs.lerian.studio/en/reference/products/tracer/get-dashboard-volume

/en/openapi/v3-current/tracer.yaml get /v1/dashboard/volume
Use this endpoint to get the number of validations per day across the window. Set the window with `period` (7d, 30d or 90d, default 30d), or with `start_date` and `end_date` (at most 90 days).



# List audit events
Source: https://docs.lerian.studio/en/reference/products/tracer/list-audit-events

/en/openapi/v3-current/tracer.yaml get /v1/audit-events
Use this endpoint to list audit events with filters and cursor-based pagination.



# List spending limits
Source: https://docs.lerian.studio/en/reference/products/tracer/list-limits

/en/openapi/v3-current/tracer.yaml get /v1/limits
Use this endpoint to list spending limits with cursor-based pagination and optional filters. DELETED limits are not returned in listings.



# List fraud rules
Source: https://docs.lerian.studio/en/reference/products/tracer/list-rules

/en/openapi/v3-current/tracer.yaml get /v1/rules
Use this endpoint to list fraud rules with cursor-based pagination and optional filters. DELETED rules are not returned in listings.



# List transaction validation records
Source: https://docs.lerian.studio/en/reference/products/tracer/list-validations

/en/openapi/v3-current/tracer.yaml get /v1/validations
Use this endpoint to list transaction validation records with cursor-based pagination and filters. Useful for compliance reporting and trend analysis.



# Get an audit event by ID
Source: https://docs.lerian.studio/en/reference/products/tracer/retrieve-audit-event

/en/openapi/v3-current/tracer.yaml get /v1/audit-events/{id}
Use this endpoint to retrieve a single audit event by its unique identifier.



# Get a spending limit by ID
Source: https://docs.lerian.studio/en/reference/products/tracer/retrieve-limit

/en/openapi/v3-current/tracer.yaml get /v1/limits/{id}
Use this endpoint to retrieve a spending limit by its unique identifier.



# Get usage snapshot for a limit
Source: https://docs.lerian.studio/en/reference/products/tracer/retrieve-limit-usage

/en/openapi/v3-current/tracer.yaml get /v1/limits/{id}/usage
Use this endpoint to retrieve the current usage snapshot for a spending limit.



# Get a fraud rule by ID
Source: https://docs.lerian.studio/en/reference/products/tracer/retrieve-rule

/en/openapi/v3-current/tracer.yaml get /v1/rules/{id}
Use this endpoint to retrieve a fraud rule by its unique identifier.



# Get a transaction validation record by ID
Source: https://docs.lerian.studio/en/reference/products/tracer/retrieve-validation

/en/openapi/v3-current/tracer.yaml get /v1/validations/{id}
Use this endpoint to retrieve a transaction validation record by its unique identifier. Useful for auditing and debugging validation decisions.



# Tracer API quick start
Source: https://docs.lerian.studio/en/reference/products/tracer/tracer-api-quick-start

Get Tracer running: create your first rule and spending limit, validate a transaction, and review the audit trail using the Tracer REST APIs.

> [!TIP]
>
> **This guide is for developers.** If you're looking for a business-level overview of what Tracer does, see [What is Tracer?](/en/products/tracer/what-is-tracer).

This guide takes you from creating your first rule and spending limit to validating a transaction and reviewing the audit trail.

## Before you begin

***

You need:

* A running Tracer instance
* Credentials for one of the two supported auth modes

All examples use `cURL`. Replace `$API_KEY` with your API key or `$JWT` with your Bearer token, and `https://tracer.sandbox.lerian.net` with your Tracer URL.

> [!NOTE]
>
> **Auth mode depends on deployment.** A self-hosted deployment with an API key uses `X-API-Key`. On Lerian Cloud, use `Authorization: Bearer $JWT`, which [Access Manager](/en/platform/access-manager) issues with the `tenantId` claim, and replace every `-H "X-API-Key: $API_KEY"` in this guide with `-H "Authorization: Bearer $JWT"`. Tracer resolves the tenant from the token automatically, so never pass the tenant identifier in any other field.

## Step 1: Create a rule

***

Create a validation rule with a CEL expression. Every new rule starts in `DRAFT` status. They do not affect transactions until you activate them.

> [!TIP]
>
> API reference: [Create rule](/en/reference/products/tracer/create-rule)

```bash cURL theme={null}
curl -X POST "https://tracer.sandbox.lerian.net/v1/rules" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY" \
 -d '{
   "name": "Block high-value transactions",
   "expression": "amount > 1000000",
   "action": "DENY",
   "scopes": [
     {
       "transactionType": "CARD"
     }
   ]
 }'
```

```json theme={null}
{
  "ruleId": "019c96a0-4b20-7123-9a1b-2c3d4e5f6a7b",
  "name": "Block high-value transactions",
  "expression": "amount > 1000000",
  "action": "DENY",
  "scopes": [
    {
      "transactionType": "CARD"
    }
  ],
  "status": "DRAFT",
  "createdAt": "2026-03-05T10:00:00Z",
  "updatedAt": "2026-03-05T10:00:00Z"
}
```

Save the `ruleId`. You will use it to activate the rule.

> [!NOTE]
>
> Monetary values (transaction `amount`, spending limit `maxAmount`, and usage counters) appear as decimal strings, for example `"1500.00"` or `"10000.00"`.

## Step 2: Activate the rule

***

Activate the rule. Tracer then evaluates it against incoming transactions.

> [!TIP]
>
> API reference: [Activate rule](/en/reference/products/tracer/activate-rule)

```bash cURL theme={null}
curl -X POST "https://tracer.sandbox.lerian.net/v1/rules/019c96a0-4b20-7123-9a1b-2c3d4e5f6a7b/activate" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY"
```

```json theme={null}
{
  "ruleId": "019c96a0-4b20-7123-9a1b-2c3d4e5f6a7b",
  "name": "Block high-value transactions",
  "expression": "amount > 1000000",
  "action": "DENY",
  "scopes": [
    {
      "transactionType": "CARD"
    }
  ],
  "status": "ACTIVE",
  "createdAt": "2026-03-05T10:00:00Z",
  "updatedAt": "2026-03-05T10:01:00Z"
}
```

The rule status changes from `DRAFT` to `ACTIVE`.

### Rule lifecycle

| Status | Behavior |
| - | - |
| `DRAFT` | Created but not evaluated during validations |
| `ACTIVE` | Evaluated during validation, on transactions its scope matches |
| `INACTIVE` | Paused and excluded from evaluation |

`INACTIVE` rules can transition back to `DRAFT` for re-editing using `POST /v1/rules/{id}/draft`.

## Step 3: Create a spending limit

***

Create a spending limit to control transaction amounts by scope and time period. Like rules, limits start in `DRAFT` status. The optional `resetTime` starts each period at a UTC time of day. The example starts each day at 03:00 UTC.

> [!TIP]
>
> API reference: [Create limit](/en/reference/products/tracer/create-limit)

```bash cURL theme={null}
curl -X POST "https://tracer.sandbox.lerian.net/v1/limits" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY" \
 -d '{
   "name": "Daily Corporate Limit",
   "description": "Daily spending limit for corporate segment",
   "limitType": "DAILY",
   "maxAmount": "50000.00",
   "asset": "BRL",
   "resetTime": "03:00",
   "scopes": [
     {
       "segmentId": "019c96a0-0b4e-7079-8be0-ab6bdccf975f",
       "transactionType": "CARD"
     }
   ]
 }'
```

```json theme={null}
{
  "limitId": "019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f",
  "name": "Daily Corporate Limit",
  "description": "Daily spending limit for corporate segment",
  "limitType": "DAILY",
  "maxAmount": "50000.00",
  "asset": "BRL",
  "scopes": [
    {
      "segmentId": "019c96a0-0b4e-7079-8be0-ab6bdccf975f",
      "transactionType": "CARD"
    }
  ],
  "status": "DRAFT",
  "resetTime": "03:00",
  "resetAt": "2026-03-06T03:00:00Z",
  "createdAt": "2026-03-05T10:02:00Z",
  "updatedAt": "2026-03-05T10:02:00Z"
}
```

### Limit types

| Type | Period counting | Use case |
| - | - | - |
| `DAILY` | A new count starts each day at the reset time (00:00 UTC by default) | Daily spending caps |
| `WEEKLY` | A new count starts each Monday at the reset time (00:00 UTC by default) | Weekly spending caps |
| `MONTHLY` | A new count starts on the 1st of the month at the reset time (00:00 UTC by default) | Monthly budget control |
| `CUSTOM` | One count for the whole range | Fixed campaign or event windows |
| `PER_TRANSACTION` | Tracer keeps no count and checks each transaction on its own | Per-transaction maximums |

Activate the limit the same way you activated the rule:

```bash cURL theme={null}
curl -X POST "https://tracer.sandbox.lerian.net/v1/limits/019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f/activate" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY"
```

## Step 4: Validate a transaction

***

Send a transaction to Tracer for real-time validation against the rules and limits that apply to it.

> [!TIP]
>
> API reference: [Validate transaction](/en/reference/products/tracer/validate-transaction)

```bash cURL theme={null}
curl -X POST "https://tracer.sandbox.lerian.net/v1/validations" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY" \
 -d '{
   "requestId": "019c96a0-10ce-75fc-a273-dc799079a99c",
   "transactionType": "CARD",
   "subType": "debit",
   "amount": "1500.00",
   "asset": "BRL",
   "transactionTimestamp": "2026-03-05T10:30:00Z",
   "account": {
     "accountId": "019c96a0-0c0c-7221-8cf3-13313fb60081",
     "type": "checking",
     "status": "active"
   },
   "segment": {
     "segmentId": "019c96a0-0b4e-7079-8be0-ab6bdccf975f",
     "name": "corporate"
   },
   "metadata": {
     "channel": "MOBILE_APP"
   }
 }'
```

```json theme={null}
{
  "requestId": "019c96a0-10ce-75fc-a273-dc799079a99c",
  "validationId": "019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f",
  "decision": "ALLOW",
  "matchedRuleIds": [],
  "evaluatedRuleIds": [
    "019c96a0-4b20-7123-9a1b-2c3d4e5f6a7b"
  ],
  "limitUsageDetails": [
    {
      "limitId": "019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f",
      "limitAmount": "50000.00",
      "currentUsage": "1500.00",
      "exceeded": false,
      "period": "DAILY"
    }
  ],
  "processingTimeMs": 23
}
```

### Decision types

| Decision | Meaning | Your system should |
| - | - | - |
| `ALLOW` | All rules passed, all limits within threshold | Proceed with the transaction |
| `DENY` | A deny rule matched or a limit was exceeded | Block the transaction |
| `REVIEW` | A review rule matched, or a rule expression failed for the request | Route to manual review |

> [!NOTE]
>
> Tracer returns decisions as recommendations. Your system must act on the decision (block, approve, or queue the transaction).

### Transaction types

| Type | Example subtypes | Description |
| - | - | - |
| `CARD` | debit, credit, prepaid | Card transactions |
| `WIRE` | domestic, international, ach | Wire transfers |
| `PIX` | instant, scheduled | Brazilian instant payments |
| `CRYPTO` | bitcoin, ethereum, stablecoin | Cryptocurrency transactions |

`transactionType` accepts only the four values above. `subType` is a free-form string (up to 50 characters, normalized to lowercase). The subtypes listed are common examples, not a closed list.

## Step 5: Check limit usage

***

Review a limit's cumulative consumption. For the consumption behind a single decision, read `limitUsageDetails` on the `POST /v1/validations` response.

> [!TIP]
>
> API reference: [Retrieve limit usage](/en/reference/products/tracer/retrieve-limit-usage)

```bash cURL theme={null}
curl -X GET "https://tracer.sandbox.lerian.net/v1/limits/019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f/usage" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY"
```

```json theme={null}
{
  "limitId": "019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f",
  "limitAmount": "50000.00",
  "currentUsage": "15000.00",
  "utilizationPercent": 30.0,
  "nearLimit": false
}
```

`currentUsage` here adds up the usage counters recorded for the limit, across periods and scopes.

## Step 6: Review audit events

***

Tracer records validation decisions and configuration changes in an immutable audit log. Query audit events for compliance reporting and debugging.

> [!TIP]
>
> API reference: [List audit events](/en/reference/products/tracer/list-audit-events)

```bash cURL theme={null}
curl -X GET "https://tracer.sandbox.lerian.net/v1/audit-events?event_type=TRANSACTION_VALIDATED&start_date=2026-03-05T00:00:00Z&end_date=2026-03-06T00:00:00Z" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY"
```

### Audit event types

| Event type | Description |
| - | - |
| `TRANSACTION_VALIDATED` | A transaction was validated |
| `RULE_CREATED` | A new rule was created |
| `RULE_ACTIVATED` | A rule was activated |
| `RULE_DEACTIVATED` | A rule was deactivated |
| `LIMIT_CREATED` | A new limit was created |
| `LIMIT_ACTIVATED` | A limit was activated |
| `LIMIT_DEACTIVATED` | A limit was deactivated |

This table shows the most common event types. For the complete list (including update, delete, draft, and reservation lifecycle events), see [Audit and compliance](/en/products/tracer/audit-compliance).

## Step 7: Verify audit integrity

***

Verify the cryptographic hash chain of audit events.

> [!TIP]
>
> API reference: [Verify audit event](/en/reference/products/tracer/verify-audit-event)

```bash cURL theme={null}
curl -X GET "https://tracer.sandbox.lerian.net/v1/audit-events/019c96a0-4a10-7dfe-b5c1-8a1b2c3d4e5f/verify" \
 -H "Content-Type: application/json" \
 -H "X-API-Key: $API_KEY"
```

```json theme={null}
{
  "isValid": true,
  "totalChecked": 1234,
  "message": "Hash chain integrity verified successfully"
}
```

## Next steps

***

> **[Getting started with Tracer](/en/products/tracer/getting-started)**
>
> Business overview of the validation lifecycle and core concepts.

> **[Rule engine](/en/products/tracer/rule-engine)**
>
> Detailed guide to CEL expressions and advanced rule configuration.

> **[Spending limits](/en/products/tracer/spending-limits)**
>
> Configure and manage limits by scope, period, and transaction type.

> **[Error handling](/en/reference/products/tracer/tracer-error-list)**
>
> Complete list of error codes and how to resolve them.


# Tracer error list
Source: https://docs.lerian.studio/en/reference/products/tracer/tracer-error-list

Tracer APIs return a structured error object with a stable code, HTTP status, and message so you can diagnose issues and route them to the right team.

The Tracer API returns errors as an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem details object, served with the `application/problem+json` content type:

```json theme={null}
{
   "type": "https://errors.lerian.studio/v1/<error_code>",
   "title": "<error_title>",
   "status": <http_status>,
   "detail": "<error_message>",
   "code": "<error_code>"
}
```

**Field definitions**

* `type`: A URI that identifies the error type, built as `https://errors.lerian.studio/v1/` followed by the error code.
* `title`: A brief summary of the issue.
* `status`: The HTTP status code of the response.
* `detail`: Detailed guidance for resolving the error. The tables below list this content in the `message` column.
* `code`: A unique, stable identifier for the error. It is usually a four-digit numeric string drawn from the shared platform error registry (for example, `0347`). Authentication failures are the exception and use the literal string `Unauthenticated` (see the note below).
* `entityType`: The entity the error relates to (for example, `Rule`). Only present when applicable.
* `message`: The human-readable reason, exposed verbatim as a top-level field. Only present on `413 Payload Too Large` and `504 Gateway Timeout` responses. All other errors omit it.

> [!NOTE]
>
> For server-side errors (HTTP 5xx), `title` and `detail` carry generic values so internal causes never leak. Use `code` and `type` to identify the error. For `504` timeouts, the top-level `message` field still carries the specific reason.

**Field-level validation**

Struct-level field validation failures return code `0009` with the title `Validation Error` and a `detail` that names the specific field and constraint, for example `transactionType must be one of [CARD WIRE PIX CRYPTO]`.

Examples:

```json Missing required field theme={null}
{
   "type": "https://errors.lerian.studio/v1/0009",
   "title": "Validation Error",
   "status": 400,
   "detail": "name is a required field",
   "code": "0009"
}
```

```json Invalid expression type theme={null}
{
   "type": "https://errors.lerian.studio/v1/0341",
   "title": "Expression Type",
   "status": 400,
   "detail": "Expression must return boolean.",
   "code": "0341",
   "entityType": "Rule"
}
```

> [!NOTE]
>
> Two response families keep a legacy flat `{"code", "title", "message"}` shape instead of the problem details object. Middleware that runs before the API layer emits them. Authentication failures: a missing or invalid API key returns HTTP 401 with `"code": "Unauthenticated"`, `"title": "Unauthorized"`, and `"message": "API Key missing or invalid"`. Match on the literal `Unauthenticated` string. A Bearer token that parses but lacks the required `sub` claim returns HTTP 401 with `"code": "0474"`. Tenant capacity: code `0466` returns HTTP 503 in the same flat shape.

## General errors

***

Any Tracer API endpoint can return these errors.

| `code` | `title` | `message` |
| :- | :- | :- |
| 0009 | Missing Fields in Request | Your request is missing one or more required fields: %v. Please refer to the documentation to ensure all necessary fields are included in your request. |
| 0046 | Internal Server Error | The server encountered an unexpected error. Please try again later or contact support. |
| 0065 | Invalid Path Parameter | One or more path parameters are in an incorrect format. Please check the following parameters %v and ensure they meet the required format before trying again. |
| 0082 | Invalid Query Parameter | One or more query parameters are in an incorrect format. Please check the following parameters '%v' and ensure they meet the required format before trying again. |
| 0094 | Bad Request | The request body is malformed or contains invalid JSON. Please verify the syntax and try again. |
| 0143 | Payload Too Large | payload too large: exceeds 100KB limit |
| 0183 | Nothing to Update | No updatable fields were provided. Please include at least one field to update. |
| 0330 | Context Cancelled | Context cancelled / service unavailable. |
| 0484 | Route Not Found | The requested route does not exist. Please verify the HTTP method and path and try again. |
| 0485 | Method Not Allowed | The HTTP method is not allowed for the requested route. Please verify the method and try again. |
| 0497 | Request Header Fields Too Large | The request header fields are too large. Please reduce the size of the request headers and try again. |

Code `0009` also appears with the title `Validation Error` when field-level validation rejects a request. See the note above.

The validation endpoint returns code `0143` with HTTP `413` when a request body exceeds the 100KB limit. The reason also appears in the top-level `message` field. The Tracer API returns code `0497` with HTTP `431` when the request headers are too large. It returns code `0484` with HTTP `404` for a path the service does not serve. It returns code `0485` with HTTP `405` for a method the path does not accept.

## Date and time errors

***

| `code` | `title` | `message` |
| :- | :- | :- |
| 0077 | Invalid Date Format Error | The 'initialDate', 'finalDate', or both are in the incorrect format. Please use the 'yyyy-mm-dd' format and try again. |
| 0083 | Invalid Date Range Error | Both 'initialDate' and 'finalDate' fields are required and must be in the 'yyyy-mm-dd' format. Please provide valid dates and try again. |

## Pagination errors

***

| `code` | `title` | `message` |
| :- | :- | :- |
| 0080 | Pagination Limit Exceeded | The pagination limit exceeds the maximum allowed of %v items per page. Please verify the limit and try again. |
| 0081 | Invalid Sort Order | The 'sort\_order' field must be 'asc' or 'desc'. Please provide a valid sort order and try again. |
| 0331 | Pagination Limit Invalid | Pagination limit must be positive. |
| 0332 | Invalid Sort Column | Sort column not in allowed list. |
| 0333 | Invalid Cursor | Invalid or corrupted pagination cursor. |
| 0334 | Cursor With Sort Params | Cursor and sort parameters are mutually exclusive. |

## Metadata errors

***

These errors come from the `metadata` map on a validation request (`POST /v1/validations`).

| `code` | `title` | `message` |
| :- | :- | :- |
| 0050 | Metadata Key Length Exceeded | A metadata key exceeds the maximum allowed length of 64 characters. Please use a shorter key. |
| 0335 | Metadata Entries Exceeded | Metadata entries exceed maximum of 50. |
| 0336 | Metadata Key Invalid Chars | Metadata key contains invalid characters. |

The API returns HTTP `400` for a metadata key longer than 64 characters, or for more than 50 metadata entries on one request.

## CEL expression errors

***

You write rules as CEL (Common Expression Language) expressions. These errors appear during rule expression creation, update, or evaluation.

| `code` | `title` | `message` |
| :- | :- | :- |
| 0340 | Expression Syntax | Invalid CEL syntax. |
| 0341 | Expression Type | Expression must return boolean. |
| 0342 | Expression Cost Exceeded | Cost limit exceeded (cost computed and above threshold). |
| 0343 | Expression Evaluation | Runtime evaluation error. |
| 0344 | Expression Program | Program creation failed (compilation phase). |
| 0345 | Expression Cost Estimation | Failed to estimate expression cost. |
| 0346 | Amount Exceeds Precision | Amount exceeds safe precision for CEL float64 evaluation (max: ±2^53). |
| 0351 | Expression Not Modifiable | Expression cannot be modified for non-DRAFT rules. |

## Rule errors

***

| `code` | `title` | `message` |
| :- | :- | :- |
| 0347 | Rule Not Found | Rule not found by ID. |
| 0348 | Rule Name Already Exists | Rule name must be unique. |
| 0349 | Rule Invalid Status | Invalid rule status transition. |
| 0350 | Rule Evaluation Failed | Rule evaluation failed. |
| 0352 | Rule Nil Input | Rule input cannot be nil. |
| 0353 | Rule Name Required | Rule name is required. |
| 0354 | Rule Name Too Long | Rule name exceeds max length (255). |
| 0355 | Rule Expression Required | Rule expression is required. |
| 0356 | Rule Expression Too Long | Rule expression exceeds max length (5000). |
| 0357 | Rule Invalid Action | Action must be one of \[ALLOW, DENY, REVIEW]. |
| 0358 | Rule Invalid Scope | Scope must have at least one field set. |
| 0359 | Rule Description Too Long | Rule description exceeds max length (1000). |
| 0360 | Rule Scopes Too Many | Rule scopes exceed maximum (100). |
| 0437 | Rule Cache Not Ready | Rule cache is not ready. |
| 0441 | Rule Name Already Exists In Ctx | Rule name already exists in this context. |

## Limit errors

***

| `code` | `title` | `message` |
| :- | :- | :- |
| 0362 | Limit Not Found | Limit not found by ID. |
| 0363 | Limit Invalid Status Change | Invalid limit status transition. |
| 0364 | Limit Invalid Type | Invalid limit type. |
| 0365 | Limit Invalid Max Amount | MaxAmount must not be negative. |
| 0366 | Limit Invalid Asset | Asset must be 1 to 100 uppercase letters. |
| 0367 | Limit Invalid Scope | Scope validation failed. |
| 0368 | Limit Name Required | Limit name is required. |
| 0369 | Limit Name Too Long | Limit name exceeds max length. |
| 0371 | Limit Name Invalid Chars | Limit name contains invalid characters. |
| 0372 | Limit Description Invalid Chars | Limit description contains invalid characters. |
| 0373 | Limit Invalid ID | Limit ID is invalid or nil. |
| 0378 | Limit Check Failed | Limit check failed. |
| 0379 | Limit Nil Input | Limit input cannot be nil. |
| 0380 | Limit Immutable Field | Cannot modify immutable field (limitType, asset, resetTime). |
| 0438 | Limit Time Window Mismatch | ActiveTimeStart and activeTimeEnd must both be set or both be nil. |
| 0440 | Time Of Day Invalid Format | Invalid time of day format, expected HH:MM. |
| 0442 | Limit Name Already Exists | Limit name already exists. |
| 0447 | Limit Invalid Custom Start Format | Invalid customStartDate format, expected RFC3339. |
| 0448 | Limit Invalid Custom End Format | Invalid customEndDate format, expected RFC3339. |
| 0449 | Limit Custom Dates Required | CustomStartDate and customEndDate required for CUSTOM limitType. |
| 0537 | Limit Reset Time Not Allowed | ResetTime only allowed for DAILY, WEEKLY or MONTHLY limitType. |
| 0538 | Limit Reset Time Inside Window | ResetTime must not fall inside the active time window (it may equal activeTimeStart or activeTimeEnd). |

## Audit event errors

***

| `code` | `title` | `message` |
| :- | :- | :- |
| 0381 | Audit Event Not Found | Audit event not found. |
| 0382 | Invalid Audit Event Filters | Invalid audit event filter parameters. |

## Validation request errors

***

The transaction-validation endpoints (`POST /v1/validations` and the validation queries) return these errors.

| `code` | `title` | `message` |
| :- | :- | :- |
| 0413 | Validation Request IDRequired | RequestId is required. |
| 0414 | Validation Invalid Transaction Type | Invalid transactionType. |
| 0415 | Validation Amount Non Positive | Amount must be positive. |
| 0416 | Validation Asset Required | Asset is required. |
| 0417 | Validation Invalid Asset | Asset must be 1 to 100 uppercase letters. |
| 0418 | Validation Timestamp Required | Timestamp is required. |
| 0419 | Validation Timestamp Future | Timestamp cannot be in the future. |
| 0420 | Validation Account Required | Account is required. |
| 0421 | Validation Timestamp Past | Timestamp is too far in the past. |
| 0422 | Gateway Timeout | validation timeout |
| 0423 | Validation Segment IDRequired | SegmentId is required when segment is provided. |
| 0424 | Validation Portfolio IDRequired | PortfolioId is required when portfolio is provided. |
| 0425 | Validation Sub Type Too Long | SubType exceeds maximum length of 50 characters. |
| 0426 | Validation Invalid Account Type | Account.type must be at most 256 characters. |
| 0427 | Validation Invalid Account Status | Account.status must be at most 50 characters. |
| 0428 | Validation Invalid Merchant Category | Merchant.category must be 4-digit MCC code. |
| 0429 | Validation Invalid Merchant Country | Merchant.country must be ISO 3166-1 alpha-2. |
| 0430 | Validation Merchant IDRequired | Merchant.id is required when merchant is provided. |
| 0431 | Invalid Transaction Validation Filters | Invalid transaction validation filter parameters. |
| 0432 | Transaction Validation Not Found | Transaction validation record not found. |
| 0433 | Gateway Timeout | query timeout exceeded |

The API returns codes `0422` and `0433` with HTTP `504 Gateway Timeout`: `0422` when a validation evaluation exceeds its deadline, `0433` when a list-validations query does. As with all 5xx responses, `detail` carries a generic value. The top-level `message` field carries the specific reason.

## Reservation seam errors

***

Tracer returns these codes to the Midaz ledger on the gRPC reservation seam. The Tracer HTTP API does not return them. A Ledger API client receives Midaz codes instead. See the [Midaz error list](/en/reference/products/midaz/error-list).

| `code` | `title` | `message` |
| :- | :- | :- |
| 0476 | Reservation Transaction IDReq | Reservation: transactionId is required. |
| 0482 | Reservation Not Found | Reservation: reservation not found. |
| 0487 | Reservation Tenant Required | Reservation: tenant id is required on the multi-tenant reservation surface. |
| 0533 | Reservation Already Settled | The reservation for this transaction was already settled and cannot be reserved again. |
| 0534 | Reservation Tenant Inactive | The tenant is not provisioned or not active for reservations. |

## Capacity and authentication errors

***

The instance returns HTTP 503 with a `Retry-After` header when it reaches its per-pod tenant worker cap. Clients should back off and retry. A Bearer token that parses but lacks the required `sub` claim returns HTTP 401.

| `code` | `title` | `message` |
| :- | :- | :- |
| 0466 | Tenant Capacity Reached | Tenant capacity reached; please retry shortly |
| 0474 | Unauthorized | Bearer token is missing the required 'sub' claim; identity cannot be attributed. |

## Readiness probe errors

***

The operational `/readyz` endpoint and the worker-supervisor lifecycle surface these codes. They appear in the `error` field of the `/readyz` JSON response (which carries the code only), not in `/v1/*` API responses. The `title` and `message` below describe each code for operator reference.

The `/readyz` cycle probes `postgres`, `rule_cache`, and `streaming`. `streaming` is advisory. It appears in the checks and metrics but never forces a 503.

| `code` | `title` | `message` |
| :- | :- | :- |
| 0436 | Rule Cache Warm Up Failed | Rule cache warm-up failed. |
| 0459 | Readyz Pg Connection Not Established | Postgres readyz: connection not established. |
| 0460 | Readyz Pg Connection Failed | Postgres readyz: connection failed. |
| 0461 | Readyz Pg Ping Failed | Postgres readyz: ping failed. |
| 0462 | Readyz Dependencies Unhealthy | /readyz aggregate: one or more dependencies unhealthy. |
| 0463 | Readyz Cache Not Ready | Rule\_cache readyz: cache not ready. |
| 0464 | Readyz Cache Stale | Rule\_cache readyz: cache data stale. |
| 0465 | Supervisor Shutting Down | Worker supervisor: shutting down, refusing to spawn new tenant workers. |
| 0496 | Readyz Streaming Unhealthy | Streaming readyz: producer unhealthy. |


# Partially update an existing spending limit
Source: https://docs.lerian.studio/en/reference/products/tracer/update-limit

/en/openapi/v3-current/tracer.yaml patch /v1/limits/{id}
Use this endpoint to partially update a spending limit. Only provided fields are updated. limitType, asset and resetTime are immutable and cannot be changed.



# Partially update an existing fraud rule
Source: https://docs.lerian.studio/en/reference/products/tracer/update-rule

/en/openapi/v3-current/tracer.yaml patch /v1/rules/{id}
Use this endpoint to partially update a fraud rule. Only provided fields are updated. Expression can only be modified when rule is in DRAFT status.



# Validate a transaction
Source: https://docs.lerian.studio/en/reference/products/tracer/validate-transaction

/en/openapi/v3-current/tracer.yaml post /v1/validations
Use this endpoint to validate a transaction against configured rules and limits in real-time. Returns a decision (ALLOW, DENY, or REVIEW) along with details about which rules matched and limit usage.



# Verify audit event hash chain integrity
Source: https://docs.lerian.studio/en/reference/products/tracer/verify-audit-event

/en/openapi/v3-current/tracer.yaml get /v1/audit-events/{id}/verify
Use this endpoint to verify the integrity of the audit event hash chain up to a specific event. Detects tampering attempts.



# Add a comment to an exception
Source: https://docs.lerian.studio/en/reference/products/matcher/add-exception-comment

/en/openapi/v3-current/matcher.yaml post /v1/exceptions/{exceptionId}/comments
Use this endpoint to add a comment to a specific exception. Comments help track team discussions, decisions, and investigation notes.



# Adjust entry for an exception
Source: https://docs.lerian.studio/en/reference/products/matcher/adjust-entry-exception

/en/openapi/v3-current/matcher.yaml post /v1/exceptions/{exceptionId}/adjust-entry
Use this endpoint to resolve an exception by creating an adjustment entry. This is used when a monetary correction is needed to reconcile the transaction.



# Archive a reconciliation context
Source: https://docs.lerian.studio/en/reference/products/matcher/archive-context

/en/openapi/v3-current/matcher.yaml post /v1/contexts/{contextId}/archive
Archives (soft-deletes) a reconciliation context by ID. Archiving flips the context to ARCHIVED in place and never erases its reconciled financial history; an archived context with children is valid. Archived contexts are excluded from the default listing. Use restore to bring it back to DRAFT.



# Archive a reconciliation source
Source: https://docs.lerian.studio/en/reference/products/matcher/archive-source

/en/openapi/v3-current/matcher.yaml post /v1/contexts/{contextId}/sources/{sourceId}/archive
Archives (soft-deletes) a reconciliation source by ID. Archiving never erases the source's imported transactions or field map; the source is simply excluded from listings, readiness counts, clone reads, and the matching working set. Use restore to bring it back.



# Assign an exception
Source: https://docs.lerian.studio/en/reference/products/matcher/assign-exception

/en/openapi/v3-current/matcher.yaml post /v1/exceptions/{exceptionId}/assign
Assigns a single exception to a user. Mirrors the bulk-assign auth and validation but acts on exactly one exception addressed by path. Returns the updated exception.



# Browse the supported format catalog
Source: https://docs.lerian.studio/en/reference/products/matcher/browse-format-catalog

/en/openapi/v3-current/matcher.yaml get /v1/imports/formats
Returns the read-only catalog of formats the ingestion engine can parse, namespaced region -> family -> variant. The catalog is global-first and static (built-in parsers carry no tenant), so the response is identical for every authenticated caller. No path, query, or body parameters — the tenant is irrelevant to the built-in catalog.



# Bulk assign exceptions
Source: https://docs.lerian.studio/en/reference/products/matcher/bulk-assign-exceptions

/en/openapi/v3-current/matcher.yaml post /v1/exceptions/bulk/assign
Use this endpoint to assign multiple exceptions to a team member in a single operation. You can assign up to 100 exceptions at a time.



# Bulk dispatch exceptions
Source: https://docs.lerian.studio/en/reference/products/matcher/bulk-dispatch-exceptions

/en/openapi/v3-current/matcher.yaml post /v1/exceptions/bulk/dispatch
Use this endpoint to dispatch multiple exceptions to an external system in a single operation. You can dispatch up to 100 exceptions at a time.



# Bulk resolve exceptions
Source: https://docs.lerian.studio/en/reference/products/matcher/bulk-resolve-exceptions

/en/openapi/v3-current/matcher.yaml post /v1/exceptions/bulk/resolve
Use this endpoint to resolve multiple exceptions in a single operation. You can resolve up to 100 exceptions at a time with a shared resolution and reason.



# Cancel an export job
Source: https://docs.lerian.studio/en/reference/products/matcher/cancel-export-job

/en/openapi/v3-current/matcher.yaml post /v1/export-jobs/{jobId}/cancel
Use this endpoint to cancel a queued or running export job.



# Close a dispute
Source: https://docs.lerian.studio/en/reference/products/matcher/close-dispute

/en/openapi/v3-current/matcher.yaml post /v1/disputes/{disputeId}/close
Use this endpoint to close a dispute with a resolution. The dispute can be marked as won or lost based on the outcome.



# Create an export job
Source: https://docs.lerian.studio/en/reference/products/matcher/create-export-job

/en/openapi/v3-current/matcher.yaml post /v1/contexts/{contextId}/export-jobs
Use this endpoint to create an asynchronous export job for large report exports. Supported formats include CSV, JSON, and XML.



# Create a fee rule
Source: https://docs.lerian.studio/en/reference/products/matcher/create-fee-rule

/en/openapi/v3-current/matcher.yaml post /v1/contexts/{contextId}/fee-rules
Use this endpoint to create a new fee rule that maps transaction metadata to a fee schedule within a context.

Priority must be unique within a context across all sides (LEFT, RIGHT, and ANY rules share the same priority space). The caller must also be allowed to read the referenced fee schedule.




# Create a fee schedule
Source: https://docs.lerian.studio/en/reference/products/matcher/create-fee-schedule

/en/openapi/v3-current/matcher.yaml post /v1/fee-schedules
Use this endpoint to create a new fee schedule. Fee schedules define the fee structure applied to transactions during reconciliation.



# Create a field map
Source: https://docs.lerian.studio/en/reference/products/matcher/create-field-map

/en/openapi/v3-current/matcher.yaml post /v1/contexts/{contextId}/sources/{sourceId}/field-maps
Use this endpoint to create a field map for a specific source within a context. Field maps define how source fields are mapped to reconciliation fields. A source holds at most one field map: a second create is refused with `409`, so update the existing map instead.



# Create a match rule
Source: https://docs.lerian.studio/en/reference/products/matcher/create-match-rule

/en/openapi/v3-current/matcher.yaml post /v1/contexts/{contextId}/rules
Use this endpoint to create a new match rule within a specific context. Match rules define how transactions are matched during reconciliation.



# Create a schedule
Source: https://docs.lerian.studio/en/reference/products/matcher/create-schedule

/en/openapi/v3-current/matcher.yaml post /v1/contexts/{contextId}/schedules
Use this endpoint to create a cron-based reconciliation schedule for automatic matching within a context.



# Create a reconciliation source
Source: https://docs.lerian.studio/en/reference/products/matcher/create-source

/en/openapi/v3-current/matcher.yaml post /v1/contexts/{contextId}/sources
Use this endpoint to create a new reconciliation source under a specific context. Sources define where transaction data comes from for reconciliation.



# Create a source binding
Source: https://docs.lerian.studio/en/reference/products/matcher/create-source-binding

/en/openapi/v3-current/matcher.yaml post /v1/contexts/{contextId}/sources/{sourceId}/bindings
Creates a source binding tying a reconciliation source to a pull rail (file or query) plus an interval schedule. Exactly one rail payload is meaningful per kind: the file rail populates transportConfig, the query rail populates connectionId.



# Delete an actor mapping
Source: https://docs.lerian.studio/en/reference/products/matcher/delete-actor-mapping

/en/openapi/v3-current/matcher.yaml delete /v1/governance/actor-mappings/{actorId}
Use this endpoint to delete an actor mapping by its identifier.



# Delete an exception comment
Source: https://docs.lerian.studio/en/reference/products/matcher/delete-exception-comment

/en/openapi/v3-current/matcher.yaml delete /v1/exceptions/{exceptionId}/comments/{commentId}
Use this endpoint to delete a specific comment from an exception.



# Delete a fee rule
Source: https://docs.lerian.studio/en/reference/products/matcher/delete-fee-rule

/en/openapi/v3-current/matcher.yaml delete /v1/fee-rules/{feeRuleId}
Use this endpoint to permanently remove a fee rule by its identifier.



# Delete a fee schedule
Source: https://docs.lerian.studio/en/reference/products/matcher/delete-fee-schedule

/en/openapi/v3-current/matcher.yaml delete /v1/fee-schedules/{scheduleId}
Use this endpoint to delete a specific fee schedule by its identifier.



# Delete a field map
Source: https://docs.lerian.studio/en/reference/products/matcher/delete-field-map

/en/openapi/v3-current/matcher.yaml delete /v1/field-maps/{fieldMapId}
Use this endpoint to delete a specific field map by its identifier.



# Delete an operator fixed-width layout template
Source: https://docs.lerian.studio/en/reference/products/matcher/delete-layout-template

/en/openapi/v3-current/matcher.yaml delete /v1/imports/formats/templates/{templateId}
Soft-deletes one active per-tenant fixed-width layout template by its id, freeing its format/variant key for reuse. Returns 404 when no active template matches. Tenant from the JWT; never the body.



# Delete a match rule
Source: https://docs.lerian.studio/en/reference/products/matcher/delete-match-rule

/en/openapi/v3-current/matcher.yaml delete /v1/contexts/{contextId}/rules/{ruleId}
Use this endpoint to delete a specific match rule by its identifier.



# Delete a schedule
Source: https://docs.lerian.studio/en/reference/products/matcher/delete-schedule

/en/openapi/v3-current/matcher.yaml delete /v1/contexts/{contextId}/schedules/{scheduleId}
Use this endpoint to delete a reconciliation schedule from a context.



# Delete a source binding
Source: https://docs.lerian.studio/en/reference/products/matcher/delete-source-binding

/en/openapi/v3-current/matcher.yaml delete /v1/contexts/{contextId}/sources/{sourceId}/bindings/{bindingId}
Removes a source binding by ID.



# Dispatch exception to external system
Source: https://docs.lerian.studio/en/reference/products/matcher/dispatch-exception

/en/openapi/v3-current/matcher.yaml post /v1/exceptions/{exceptionId}/dispatch
Use this endpoint to dispatch an exception for tracking and resolution.



# Download an audit log archive
Source: https://docs.lerian.studio/en/reference/products/matcher/download-archive

/en/openapi/v3-current/matcher.yaml get /v1/governance/archives/{id}/download
Use this endpoint to download an audit log archive. Returns a pre-signed URL with a time-limited download link and a SHA-256 checksum for integrity verification.



# Download export file
Source: https://docs.lerian.studio/en/reference/products/matcher/download-export-job

/en/openapi/v3-current/matcher.yaml get /v1/export-jobs/{jobId}/download
Use this endpoint to download the export file. The response includes a presigned URL for downloading the file.



# Force match an exception
Source: https://docs.lerian.studio/en/reference/products/matcher/force-match-exception

/en/openapi/v3-current/matcher.yaml post /v1/exceptions/{exceptionId}/force-match
Use this endpoint to resolve an exception by forcing a match with an override reason. This is used when manual intervention determines the transaction should be considered matched despite discrepancies.



# Get an actor mapping
Source: https://docs.lerian.studio/en/reference/products/matcher/get-actor-mapping

/en/openapi/v3-current/matcher.yaml get /v1/governance/actor-mappings/{actorId}
Use this endpoint to retrieve the display name and email mapped to a specific actor identifier.



# Get a single AI extraction review
Source: https://docs.lerian.studio/en/reference/products/matcher/get-extraction-review

/en/openapi/v3-current/matcher.yaml get /v1/imports/contexts/{contextId}/extraction-reviews/{reviewId}
Returns one extraction review with its candidates, provenance, and lifecycle. Tenant from the JWT, context from the path.



# Get an operator fixed-width layout template
Source: https://docs.lerian.studio/en/reference/products/matcher/get-layout-template

/en/openapi/v3-current/matcher.yaml get /v1/imports/formats/templates/{templateId}
Retrieves one active per-tenant fixed-width layout template by its id. Returns 404 when no active template matches. Tenant from the JWT; never the body.



# Get a source binding
Source: https://docs.lerian.studio/en/reference/products/matcher/get-source-binding

/en/openapi/v3-current/matcher.yaml get /v1/contexts/{contextId}/sources/{sourceId}/bindings/{bindingId}
Returns a source binding by ID.



# Ignore a transaction
Source: https://docs.lerian.studio/en/reference/products/matcher/ignore-transaction

/en/openapi/v3-current/matcher.yaml post /v1/imports/contexts/{contextId}/transactions/{transactionId}/ignore
Use this endpoint to mark a transaction as "Do Not Match" with a required reason. Only UNMATCHED transactions can be ignored.



# List actor mappings
Source: https://docs.lerian.studio/en/reference/products/matcher/list-actor-mappings

/en/openapi/v3-current/matcher.yaml get /v1/governance/actor-mappings
Lists actor mappings by actor ID with optional actor ID prefix filtering. Does not return display name or email. Pagination is forward-only: use the nextCursor value to fetch the next page.



# List audit log archives
Source: https://docs.lerian.studio/en/reference/products/matcher/list-archives

/en/openapi/v3-current/matcher.yaml get /v1/governance/archives
Use this endpoint to list all audit log archives. Archives contain historical audit log data that has been compressed and moved to long-term storage. Supports offset-based pagination.



# List audit logs
Source: https://docs.lerian.studio/en/reference/products/matcher/list-audit-logs

/en/openapi/v3-current/matcher.yaml get /v1/governance/audit-logs
Use this endpoint to retrieve all audit log entries. You can filter the results by actor, date range, action type, and entity type. The response uses cursor-based pagination.



# List audit logs by entity
Source: https://docs.lerian.studio/en/reference/products/matcher/list-audit-logs-by-entity

/en/openapi/v3-current/matcher.yaml get /v1/governance/entities/{entityType}/{entityId}/audit-logs
Use this endpoint to retrieve the audit log entries for a specific entity. The results are ordered by creation time descending.



# List callback credentials
Source: https://docs.lerian.studio/en/reference/products/matcher/list-callback-credentials

/en/openapi/v3-current/matcher.yaml get /v1/exceptions/callbacks/credentials
Lists the caller tenant's callback credentials (live and revoked), newest first. Returns metadata only — never the token or its hash.



# List field maps for a context
Source: https://docs.lerian.studio/en/reference/products/matcher/list-context-field-maps

/en/openapi/v3-current/matcher.yaml get /v1/contexts/{contextId}/field-maps
Returns a cursor-paginated list of every field map under a context, replacing per-source probing.



# List disputes
Source: https://docs.lerian.studio/en/reference/products/matcher/list-disputes

/en/openapi/v3-current/matcher.yaml get /v1/disputes
Use this endpoint to retrieve all disputes. Supports filtering by state, category, and date range with cursor-based pagination.



# List exception comments
Source: https://docs.lerian.studio/en/reference/products/matcher/list-exception-comments

/en/openapi/v3-current/matcher.yaml get /v1/exceptions/{exceptionId}/comments
Use this endpoint to retrieve all comments for a specific exception. Comments provide an audit trail of team discussions and decisions.



# List exceptions
Source: https://docs.lerian.studio/en/reference/products/matcher/list-exceptions

/en/openapi/v3-current/matcher.yaml get /v1/exceptions
Use this endpoint to retrieve all exceptions. You can filter the results by status, severity, assigned user, external system, and date range. The response uses cursor-based pagination.



# List export jobs
Source: https://docs.lerian.studio/en/reference/products/matcher/list-export-jobs

/en/openapi/v3-current/matcher.yaml get /v1/export-jobs
Use this endpoint to retrieve all export jobs for the authenticated tenant.



# List export jobs by context
Source: https://docs.lerian.studio/en/reference/products/matcher/list-export-jobs-by-context

/en/openapi/v3-current/matcher.yaml get /v1/contexts/{contextId}/export-jobs
Use this endpoint to list all export jobs for a specific reconciliation context. Supports cursor-based pagination.



# List AI extraction reviews (the human-review queue)
Source: https://docs.lerian.studio/en/reference/products/matcher/list-extraction-reviews

/en/openapi/v3-current/matcher.yaml get /v1/imports/contexts/{contextId}/extraction-reviews
Cursor-paginated list of extraction reviews for a context, optionally filtered by lifecycle status (e.g. PENDING_REVIEW for the queue). Tenant from the JWT, context from the path. Reads already-stored config-only candidates; it does not egress anything.



# List fee rules
Source: https://docs.lerian.studio/en/reference/products/matcher/list-fee-rules

/en/openapi/v3-current/matcher.yaml get /v1/contexts/{contextId}/fee-rules
Use this endpoint to retrieve all fee rules for a reconciliation context, ordered by priority.



# List fee schedules
Source: https://docs.lerian.studio/en/reference/products/matcher/list-fee-schedules

/en/openapi/v3-current/matcher.yaml get /v1/fee-schedules
Use this endpoint to retrieve all fee schedules for the authenticated tenant.



# List per-row import errors for a job
Source: https://docs.lerian.studio/en/reference/products/matcher/list-ingestion-job-errors

/en/openapi/v3-current/matcher.yaml get /v1/imports/contexts/{contextId}/jobs/{jobId}/errors
Returns the stored per-row parse/normalization errors for an ingestion job (capped at 100 per job), with the uncapped failure total and truncation accounting. Lets clients explain failed or partially-failed imports.



# List ingestion jobs for a context
Source: https://docs.lerian.studio/en/reference/products/matcher/list-ingestion-jobs

/en/openapi/v3-current/matcher.yaml get /v1/imports/contexts/{contextId}/jobs
Use this endpoint to retrieve all ingestion jobs for a specific reconciliation context. You can sort the results by various fields. The response uses cursor-based pagination.



# List transactions for a job
Source: https://docs.lerian.studio/en/reference/products/matcher/list-job-transactions

/en/openapi/v3-current/matcher.yaml get /v1/imports/contexts/{contextId}/jobs/{jobId}/transactions
Use this endpoint to retrieve all transactions extracted from an ingestion job. You can sort the results by various fields. The response uses cursor-based pagination.



# List operator fixed-width layout templates
Source: https://docs.lerian.studio/en/reference/products/matcher/list-layout-templates

/en/openapi/v3-current/matcher.yaml get /v1/imports/formats/templates
Returns every active per-tenant fixed-width layout template. The list is unpaginated: layout templates are bounded operator config. Tenant from the JWT; never the body.



# List match rules
Source: https://docs.lerian.studio/en/reference/products/matcher/list-match-rules

/en/openapi/v3-current/matcher.yaml get /v1/contexts/{contextId}/rules
Use this endpoint to retrieve all match rules under a specific context. You can filter the results by rule type. The response uses cursor-based pagination.



# List schedules for a context
Source: https://docs.lerian.studio/en/reference/products/matcher/list-schedules

/en/openapi/v3-current/matcher.yaml get /v1/contexts/{contextId}/schedules
Use this endpoint to retrieve all reconciliation schedules for a specific context.



# List source bindings
Source: https://docs.lerian.studio/en/reference/products/matcher/list-source-bindings

/en/openapi/v3-current/matcher.yaml get /v1/contexts/{contextId}/sources/{sourceId}/bindings
Returns every source binding under a source's context, enabled and disabled, so a disabled binding stays visible instead of silently vanishing.



# List reconciliation sources
Source: https://docs.lerian.studio/en/reference/products/matcher/list-sources

/en/openapi/v3-current/matcher.yaml get /v1/contexts/{contextId}/sources
Use this endpoint to retrieve all reconciliation sources under a specific context. You can filter the results by source type. The response uses cursor-based pagination.



# Mint a callback credential
Source: https://docs.lerian.studio/en/reference/products/matcher/mint-callback-credential

/en/openapi/v3-current/matcher.yaml post /v1/exceptions/callbacks/credentials
Mints an opaque bearer token bound to the caller's tenant for authenticating inbound external-system exception callbacks, and returns the raw token ONCE. Only the token's SHA-256 hash is stored server-side.



# Open a dispute
Source: https://docs.lerian.studio/en/reference/products/matcher/open-dispute

/en/openapi/v3-current/matcher.yaml post /v1/exceptions/{exceptionId}/disputes
Use this endpoint to open a new dispute for an exception. Disputes are used to formally challenge or investigate discrepancies with external parties.



# Preview a transaction file
Source: https://docs.lerian.studio/en/reference/products/matcher/preview-upload

/en/openapi/v3-current/matcher.yaml post /v1/imports/contexts/{contextId}/sources/{sourceId}/preview
Use this endpoint to preview a transaction file before importing it. Returns sample rows and detected columns to help verify the file structure and field mapping.



# Process exception callback
Source: https://docs.lerian.studio/en/reference/products/matcher/process-exception-callback

/en/openapi/v3-current/matcher.yaml post /v1/exceptions/{exceptionId}/callback
Use this endpoint to process a callback from an external system for a dispatched exception. This updates the exception status based on the external system resolution.



# Propose a config-only field-map/dialect mapping for a source sample
Source: https://docs.lerian.studio/en/reference/products/matcher/propose-mapping

/en/openapi/v3-current/matcher.yaml post /v1/imports/contexts/{contextId}/sources/{sourceId}/mapping-proposal
Inspects a representative sample of a source file and returns a CONFIG-ONLY mapping/dialect proposal (column→canonical-key suggestions, dialect, per-field confidence and rationale). It is ADVISORY and side-effect-free: producing a proposal PERSISTS NOTHING. The operator reviews the proposal and confirms it through the EXISTING field-map declaration path. The tenant is resolved from the JWT and the context/source from the path — never from the body. The response never carries parsed values, amounts, or transactions.



# Pseudonymize an actor
Source: https://docs.lerian.studio/en/reference/products/matcher/pseudonymize-actor

/en/openapi/v3-current/matcher.yaml post /v1/governance/actor-mappings/{actorId}/pseudonymize
Use this endpoint to pseudonymize an actor by replacing their display name and email with "[REDACTED]". This supports GDPR right-to-erasure compliance. This action is irreversible.



# Reorder match rules
Source: https://docs.lerian.studio/en/reference/products/matcher/reorder-match-rules

/en/openapi/v3-current/matcher.yaml post /v1/contexts/{contextId}/rules/reorder
Use this endpoint to reorder the priority of match rules within a specific context. The order determines which rules are evaluated first during reconciliation.



# Resolve an exception
Source: https://docs.lerian.studio/en/reference/products/matcher/resolve-exception

/en/openapi/v3-current/matcher.yaml post /v1/exceptions/{exceptionId}/resolve
Resolves a single exception with a resolution and optional reason. Mirrors the bulk-resolve auth and validation but acts on exactly one exception addressed by path. Returns the updated exception.



# Restore an archived reconciliation context
Source: https://docs.lerian.studio/en/reference/products/matcher/restore-context

/en/openapi/v3-current/matcher.yaml post /v1/contexts/{contextId}/restore
Restores an archived reconciliation context back to DRAFT so it can be re-validated and re-activated. Restoring never auto-resumes matching. Restoring a context that is not archived is rejected with a 409 invalid-state.



# Restore an archived reconciliation source
Source: https://docs.lerian.studio/en/reference/products/matcher/restore-source

/en/openapi/v3-current/matcher.yaml post /v1/contexts/{contextId}/sources/{sourceId}/restore
Restores an archived reconciliation source back into the live working set.



# Get audit log by ID
Source: https://docs.lerian.studio/en/reference/products/matcher/retrieve-audit-log

/en/openapi/v3-current/matcher.yaml get /v1/governance/audit-logs/{id}
Use this endpoint to retrieve the details of a specific audit log entry by its identifier.



# Get a dispute
Source: https://docs.lerian.studio/en/reference/products/matcher/retrieve-dispute

/en/openapi/v3-current/matcher.yaml get /v1/disputes/{disputeId}
Use this endpoint to retrieve the details of a specific dispute by its identifier, including its current state, category, and any submitted evidence.



# Get exception
Source: https://docs.lerian.studio/en/reference/products/matcher/retrieve-exception

/en/openapi/v3-current/matcher.yaml get /v1/exceptions/{exceptionId}
Use this endpoint to retrieve the details of a specific exception by its identifier.



# Get exception history
Source: https://docs.lerian.studio/en/reference/products/matcher/retrieve-exception-history

/en/openapi/v3-current/matcher.yaml get /v1/exceptions/{exceptionId}/history
Use this endpoint to retrieve the audit history for an exception. The history shows all actions taken on the exception.



# Get export job status
Source: https://docs.lerian.studio/en/reference/products/matcher/retrieve-export-job

/en/openapi/v3-current/matcher.yaml get /v1/export-jobs/{jobId}
Use this endpoint to retrieve the status of a specific export job.



# Get a fee rule
Source: https://docs.lerian.studio/en/reference/products/matcher/retrieve-fee-rule

/en/openapi/v3-current/matcher.yaml get /v1/fee-rules/{feeRuleId}
Use this endpoint to retrieve the details of a specific fee rule by its identifier.



# Get a fee schedule
Source: https://docs.lerian.studio/en/reference/products/matcher/retrieve-fee-schedule

/en/openapi/v3-current/matcher.yaml get /v1/fee-schedules/{scheduleId}
Use this endpoint to retrieve the details of a specific fee schedule by its identifier.



# Get a field map by source
Source: https://docs.lerian.studio/en/reference/products/matcher/retrieve-field-map-by-source

/en/openapi/v3-current/matcher.yaml get /v1/contexts/{contextId}/sources/{sourceId}/field-maps
Use this endpoint to retrieve the field map for a specific source within a context. Field maps define how source fields are mapped to reconciliation fields.



# Get ingestion job status
Source: https://docs.lerian.studio/en/reference/products/matcher/retrieve-ingestion-job

/en/openapi/v3-current/matcher.yaml get /v1/imports/contexts/{contextId}/jobs/{jobId}
Use this endpoint to retrieve the status and details of a specific ingestion job by its identifier. The response includes progress metrics and error information.



# Get a match rule
Source: https://docs.lerian.studio/en/reference/products/matcher/retrieve-match-rule

/en/openapi/v3-current/matcher.yaml get /v1/contexts/{contextId}/rules/{ruleId}
Use this endpoint to retrieve the details of a specific match rule by its identifier.



# Get a schedule
Source: https://docs.lerian.studio/en/reference/products/matcher/retrieve-schedule

/en/openapi/v3-current/matcher.yaml get /v1/contexts/{contextId}/schedules/{scheduleId}
Use this endpoint to retrieve a specific reconciliation schedule by its identifier.



# Get a reconciliation source
Source: https://docs.lerian.studio/en/reference/products/matcher/retrieve-source

/en/openapi/v3-current/matcher.yaml get /v1/contexts/{contextId}/sources/{sourceId}
Use this endpoint to retrieve the details of a specific reconciliation source by its identifier.



# Revoke a callback credential
Source: https://docs.lerian.studio/en/reference/products/matcher/revoke-callback-credential

/en/openapi/v3-current/matcher.yaml delete /v1/exceptions/callbacks/credentials/{credentialId}
Revokes a callback credential so it can no longer authenticate inbound callbacks. Revocation is terminal and append-only audited.



# Rotate a callback credential
Source: https://docs.lerian.studio/en/reference/products/matcher/rotate-callback-credential

/en/openapi/v3-current/matcher.yaml post /v1/exceptions/callbacks/credentials/{credentialId}/rotate
Atomically supersedes a live callback credential with a freshly minted one (same label) and returns the new raw token ONCE. The old credential is revoked in the same transaction.



# Search transactions
Source: https://docs.lerian.studio/en/reference/products/matcher/search-transactions

/en/openapi/v3-current/matcher.yaml get /v1/imports/contexts/{contextId}/transactions/search
Use this endpoint to search transactions within a reconciliation context. Supports free-text search, amount range filters, date filters, and status filters with offset-based pagination.



# Select exception ids by filter
Source: https://docs.lerian.studio/en/reference/products/matcher/select-exception-ids

/en/openapi/v3-current/matcher.yaml get /v1/exceptions/ids
Resolves the ids of every exception matching the SAME filter as GET /v1/exceptions (status, severity, contextId, reason, assigned_to, external_system, search, date_from, date_to, min_age_days), up to a cap of 10000, for the bulk "select all matching" path. The response carries the filtered total and a truncated flag; the client chunks the returned ids into the capped bulk-action calls. No pagination/sort: it returns the whole filtered set (capped).



# Simulate fee calculation
Source: https://docs.lerian.studio/en/reference/products/matcher/simulate-fee-schedule

/en/openapi/v3-current/matcher.yaml post /v1/fee-schedules/{scheduleId}/simulate
Use this endpoint to simulate fee calculation for a given gross amount using a specific fee schedule. Returns the net amount, total fee, and per-item breakdown.



# Submit evidence to a dispute
Source: https://docs.lerian.studio/en/reference/products/matcher/submit-evidence

/en/openapi/v3-current/matcher.yaml post /v1/disputes/{disputeId}/evidence
Use this endpoint to add evidence to a dispute. Evidence can include comments and optional file attachments to support the dispute case.



# Submit an operator fixed-width layout template
Source: https://docs.lerian.studio/en/reference/products/matcher/submit-layout-template

/en/openapi/v3-current/matcher.yaml post /v1/imports/formats/templates
Validates and stores a per-tenant fixed-width layout template (region/family/variant-namespaced). The layout is run through the well-formedness gate BEFORE storage: overrun, overlap, missing-required, zero-field, or a mis-marked money column (money MUST be kind=decimal) rejects with 422 and the template is never stored. An approved template is resolved by the parse path as an additive layout source. Tenant from the JWT; never the body.



# Update a fee rule
Source: https://docs.lerian.studio/en/reference/products/matcher/update-fee-rule

/en/openapi/v3-current/matcher.yaml patch /v1/fee-rules/{feeRuleId}
Use this endpoint to update the fields of a specific fee rule by its identifier. If the referenced fee schedule changes, the caller must also be allowed to read that fee schedule.



# Update a fee schedule
Source: https://docs.lerian.studio/en/reference/products/matcher/update-fee-schedule

/en/openapi/v3-current/matcher.yaml patch /v1/fee-schedules/{scheduleId}
Use this endpoint to update the fields of a specific fee schedule by its identifier.



# Update a field map
Source: https://docs.lerian.studio/en/reference/products/matcher/update-field-map

/en/openapi/v3-current/matcher.yaml patch /v1/field-maps/{fieldMapId}
Use this endpoint to update the fields of a specific field map by its identifier.



# Replace an operator fixed-width layout template
Source: https://docs.lerian.studio/en/reference/products/matcher/update-layout-template

/en/openapi/v3-current/matcher.yaml put /v1/imports/formats/templates/{templateId}
Fully replaces a stored per-tenant fixed-width layout template (records/fields/discriminator/recordWidths/requiredFields) by its id — a PUT full replace, not a sparse patch, since the byte-range invariants are whole-layout properties. The replacement is run through the SAME well-formedness gate the submission path enforces BEFORE storage: overrun, overlap, missing-required, zero-field, or a mis-marked money column (money MUST be kind=decimal) rejects with 422 and the stored template is left unchanged. Returns 404 when no active template matches, 409 when the new format key collides with another active template. Tenant from the JWT; never the body.



# Update a match rule
Source: https://docs.lerian.studio/en/reference/products/matcher/update-match-rule

/en/openapi/v3-current/matcher.yaml patch /v1/contexts/{contextId}/rules/{ruleId}
Use this endpoint to update the fields of a specific match rule by its identifier.



# Update a schedule
Source: https://docs.lerian.studio/en/reference/products/matcher/update-schedule

/en/openapi/v3-current/matcher.yaml patch /v1/contexts/{contextId}/schedules/{scheduleId}
Use this endpoint to update an existing reconciliation schedule. You can modify the cron expression and enabled status.



# Update a reconciliation source
Source: https://docs.lerian.studio/en/reference/products/matcher/update-source

/en/openapi/v3-current/matcher.yaml patch /v1/contexts/{contextId}/sources/{sourceId}
Use this endpoint to update the fields of a specific reconciliation source by its identifier. A `side` change is refused with `409` once the context has carried a partial balance, or while a match run is in progress.



# Update a source binding
Source: https://docs.lerian.studio/en/reference/products/matcher/update-source-binding

/en/openapi/v3-current/matcher.yaml patch /v1/contexts/{contextId}/sources/{sourceId}/bindings/{bindingId}
Updates fields on a source binding by ID. The rail (kind) is immutable.



# Upload an evidence file to a dispute
Source: https://docs.lerian.studio/en/reference/products/matcher/upload-evidence

/en/openapi/v3-current/matcher.yaml post /v1/disputes/{disputeId}/evidence/upload
Streams an evidence file (pdf, png, jpeg, or csv) to tenant-scoped object storage and records the resulting object key on the dispute as a new evidence item. The comment arrives as a query parameter and the file bytes as the request body. The tenant is resolved from the JWT and the dispute from the path — never from the body. Fails closed (503) when object storage is not configured; rejects oversize bodies (413) and unsupported content types (415).



# Upload transaction file
Source: https://docs.lerian.studio/en/reference/products/matcher/upload-transaction-file

/en/openapi/v3-current/matcher.yaml post /v1/imports/contexts/{contextId}/sources/{sourceId}/upload
Use this endpoint to upload a transaction file (CSV, JSON, or XML) for ingestion into a reconciliation context. The file is parsed, validated, and transactions are extracted for matching.



# Upsert an actor mapping
Source: https://docs.lerian.studio/en/reference/products/matcher/upsert-actor-mapping

/en/openapi/v3-current/matcher.yaml put /v1/governance/actor-mappings/{actorId}
Use this endpoint to create or update an actor mapping. Actor mappings associate system actor identifiers with human-readable display names and email addresses for audit log readability.



# Verify audit log chain integrity
Source: https://docs.lerian.studio/en/reference/products/matcher/verify-audit-log-chain

/en/openapi/v3-current/matcher.yaml get /v1/governance/audit-logs/verify
Re-verifies the calling tenant's audit hash chain and returns a structured verdict (intact, verified count, and the first broken tenant_seq when a break is found). The check is strictly read-only: it recomputes nothing into storage and never mutates an audit record. Use the optional maxRecords query parameter to bound how many records are inspected. Use the optional fromSeq query parameter to start the check at that tenant_seq. When the first record the check reads is not sequence 1, the check trusts that record's stored link. It does not verify the records before it. The verdict always echoes the effective fromSeq.



# Matcher events
Source: https://docs.lerian.studio/en/reference/events/matcher

Reference the domain events emitted by Lerian Matcher (reconciliation contexts, match runs, exceptions, disputes, and governance) with payloads and delivery semantics.

Matcher's catalog has 42 event definitions, and Matcher emits every one of them. It emits domain events as CloudEvents 1.0 messages in binary content mode. Every event travels in the [shared envelope](/en/reference/events/overview): `ce-type` names the event as `studio.lerian.matcher.<resource>.<event>`, `ce-subject` carries the aggregate id, `ce-tenantid` the owning tenant, and `ce-schemaversion` the payload version. The version is `1.0.0` for every event below.

`ce-source` is `matcher`. Every event uses the application topic `lerian.streaming.matcher` and the source-qualified types shown below. Resource type, event type, and schema version remain in CloudEvents headers. Money amounts (fee values and adjustment amounts) cross the wire as decimal strings, never floats.

Inbound resolution callbacks are a separate HTTP surface, documented in [Webhooks and callbacks](/en/products/matcher/integrations/matcher-webhooks-callbacks#inbound-callbacks).

## Delivery policies

Matcher's catalog uses two delivery policies: 16 definitions use the outbox-backed policy and 26 definitions use direct delivery with circuit-open fallback.

* **Outbox-backed** events go to the outbox in the same database transaction as the state change. A relay publishes committed rows and retries through broker outages. These are the audit-grade facts (matching outcomes, exception resolutions, disputes, governance). A deployment cannot weaken this policy.
* **Direct** events publish after the transaction commits, best-effort, falling back to the outbox only when the broker circuit is open. These are configuration and operational lifecycle signals.

Each table below states the policy for its events.

## Matching events

Outbox-backed: `transaction.matched`, `transaction.pending_review`. Direct: the rest.

| Event (`ce-type`) | Topic | Fires when | Key payload |
| - | - | - | - |
| `studio.lerian.matcher.transaction.matched` | `lerian.streaming.matcher` | A transaction line reaches terminal MATCHED in a match-run commit (one event per matched line). | `transaction_id`, `context_id`, `match_run_id`, `previous_status`, `status`, `match_group_id`?, `candidate_match_group_id`?, `source_id`?, `matched_at` |
| `studio.lerian.matcher.transaction.pending_review` | `lerian.streaming.matcher` | A candidate match needs human review (non-automatic rule). | Same schema, with required `pending_review_at` |
| `studio.lerian.matcher.transaction.ignored` | `lerian.streaming.matcher` | A transaction is excluded from matching. | `transaction_id`, `ingestion_job_id`, `context_id`, `source_id`, `previous_status`, `status`, `extraction_status`, `updated_at` |
| `studio.lerian.matcher.match_run.completed` | `lerian.streaming.matcher` | A match run finishes. | `match_run_id`, `context_id`, `mode`, `status`, `stats`, `started_at`, `completed_at`? |
| `studio.lerian.matcher.match_run.failed` | `lerian.streaming.matcher` | A match run fails. | `match_run_id`, `context_id`, `mode`, `status`, `failure_reason`, `started_at`, `completed_at`? |
| `studio.lerian.matcher.match_group.confirmed` | `lerian.streaming.matcher` | A match group is confirmed. | `match_group_id`, `match_run_id`, `context_id`, `rule_id`, `transaction_ids`, `confidence`, `status`, `confirmed_at`? |
| `studio.lerian.matcher.match_group.unmatched` | `lerian.streaming.matcher` | A confirmed match group is undone. | `match_group_id`, `match_run_id`, `context_id`, `rule_id`, `transaction_ids`, `previous_status`, `status`, `reason`, `unmatched_at` |
| `studio.lerian.matcher.fee_variance.created` | `lerian.streaming.matcher` | A fee-aware rule detects a variance between expected and actual fees. | `fee_variance_id`, `context_id`, `match_run_id`, `match_group_id`, `transaction_id`, `fee_schedule_id`, `fee_schedule_name_snapshot`, `currency`, `expected_fee`, `actual_fee`, `delta`, `variance_type`, `created_at` |

## Exception and dispute events

Outbox-backed except `exception.assigned` and the comment events, which are direct.

| Event (`ce-type`) | Topic | Fires when | Key payload |
| - | - | - | - |
| `studio.lerian.matcher.exception.assigned` | `lerian.streaming.matcher` | An exception is assigned to an operator. | `exception_id`, `status`, `version`, `resolution_type`?, `transaction_id`?, `assigned_at` |
| `studio.lerian.matcher.exception.resolved` | `lerian.streaming.matcher` | An exception is resolved through the single or bulk resolve operation. | `exception_id`, `status`, `version`, `resolution_type`?, `transaction_id`?, `resolved_at` |
| `studio.lerian.matcher.exception.force_match_resolved` | `lerian.streaming.matcher` | An exception is resolved by force-match with an override reason. | Base fields plus `resolution_type` (`FORCE_MATCH`), `override_reason_code`, `resolved_at` |
| `studio.lerian.matcher.exception.adjust_entry_resolved` | `lerian.streaming.matcher` | An exception is resolved by an adjustment entry. | Base fields plus `resolution_type` (`ADJUST_ENTRY`), `reason_code`, `amount`, `currency`, `resolved_at` |
| `studio.lerian.matcher.exception.dispatched` | `lerian.streaming.matcher` | An exception is dispatched. | `exception_id`, `target_system`, `queue`, `external_reference`, `acknowledged`, `dispatched_at` |
| `studio.lerian.matcher.exception.callback_processed` | `lerian.streaming.matcher` | An external system's callback is applied to an exception. | Base fields plus `external_system`, `external_issue_id`, `callback_type`, `processed_at` |
| `studio.lerian.matcher.exception_comment.added` | `lerian.streaming.matcher` | A comment is added to an exception thread. | `comment_id`, `exception_id`, `created_at` |
| `studio.lerian.matcher.exception_comment.deleted` | `lerian.streaming.matcher` | A comment is deleted. | `comment_id`, `exception_id`, `actor`, `deleted_at` |
| `studio.lerian.matcher.dispute.opened` | `lerian.streaming.matcher` | A dispute is opened on an exception. | `dispute_id`, `exception_id`, `state`, `resolution`?, `category`, `opened_at` |
| `studio.lerian.matcher.dispute.won` | `lerian.streaming.matcher` | A dispute closes as won. | `dispute_id`, `exception_id`, `state`, `resolution`?, `closed_at` |
| `studio.lerian.matcher.dispute.lost` | `lerian.streaming.matcher` | A dispute closes as lost. | `dispute_id`, `exception_id`, `state`, `resolution`?, `closed_at` |
| `studio.lerian.matcher.evidence.submitted` | `lerian.streaming.matcher` | Evidence is attached to a dispute. | `evidence_id`, `dispute_id`, `exception_id`, `has_file`, `submitted_at` |

## Configuration and data-intake events

All direct.

| Event (`ce-type`) | Topic | Fires when | Key payload |
| - | - | - | - |
| `studio.lerian.matcher.reconciliation_context.created` | `lerian.streaming.matcher` | A reconciliation context is created. | `context_id`, `name`, `context_type`, `interval`, `status`, `auto_match_on_upload`, `created_at`, `tenant_id` |
| `studio.lerian.matcher.reconciliation_context.updated` | `lerian.streaming.matcher` | A context's metadata or lifecycle status changes. | `context_id`, `name`, `context_type`, `interval`, `status`, `auto_match_on_upload`, `updated_at`, `tenant_id` |
| `studio.lerian.matcher.reconciliation_source.created` | `lerian.streaming.matcher` | A source (input side) is created in a context. | `context_id`, `source_id`, `name`, `source_type`, `side`, `created_at`, `tenant_id` |
| `studio.lerian.matcher.match_rule.created` | `lerian.streaming.matcher` | A match rule is created. | `context_id`, `rule_id`, `rule_type`, `priority`, `config_hash`, `created_at`, `tenant_id` |
| `studio.lerian.matcher.match_rule.reordered` | `lerian.streaming.matcher` | Rule priorities are reordered. | `context_id`, `ordered_rule_ids`, `priority_version`, `reordered_at`, `tenant_id` |
| `studio.lerian.matcher.fetcher_connection.synced` | `lerian.streaming.matcher` | A Discovery connection and its discovered schema snapshot are synchronized. | `connection_id`, `fetcher_connection_id`, `config_name`, `database_type`, `status`, `schema_discovered`, `last_seen_at`, `updated_at` |
| `studio.lerian.matcher.fetcher_connection.unreachable` | `lerian.streaming.matcher` | A Discovery connection becomes unreachable. | `connection_id`, `fetcher_connection_id`, `previous_status`, `status`, `schema_discovered`, `updated_at` |
| `studio.lerian.matcher.extraction_request.created` | `lerian.streaming.matcher` | An extraction request is created against a connection. | `extraction_request_id`, `connection_id`, `status`, `table_count`, `has_filters`, `start_date`, `end_date`, `created_at` |
| `studio.lerian.matcher.extraction_request.submitted` | `lerian.streaming.matcher` | Matcher's embedded extraction engine accepts an extraction request. | `extraction_request_id`, `connection_id`, `status` |
| `studio.lerian.matcher.extraction_request.completed` | `lerian.streaming.matcher` | An extraction request completes after Matcher hands its data to ingestion. | Same schema |
| `studio.lerian.matcher.extraction_request.failed` | `lerian.streaming.matcher` | An extraction request fails. | Same schema, plus `error_code` |
| `studio.lerian.matcher.ingestion.completed` | `lerian.streaming.matcher` | An ingestion job completes. | `job_id`, `context_id`, `source_id`, `status`, `total_rows`, `failed_rows`, `transaction_count`, `date_range_start`?, `date_range_end`?, `completed_at`?, `error_code`? |
| `studio.lerian.matcher.ingestion.failed` | `lerian.streaming.matcher` | An ingestion job fails. | `job_id`, `context_id`, `source_id`, `status`, `total_rows`, `failed_rows`, `error_code`?, `failed_at`? |

## Governance and reporting events

Outbox-backed except the export-job family, which is direct.

| Event (`ce-type`) | Topic | Fires when | Key payload |
| - | - | - | - |
| `studio.lerian.matcher.audit_log.created` | `lerian.streaming.matcher` | A hash-chained audit log entry is persisted. | `audit_log_id`, `tenant_id`, `entity_type`, `entity_id`, `action`, `tenant_seq`, `hash_version`, `record_hash`, `created_at` |
| `studio.lerian.matcher.archive_metadata.created` | `lerian.streaming.matcher` | The archival worker registers an archive partition. | `archive_metadata_id`, `tenant_id`, `partition_name`, `date_range_start`, `date_range_end`, `status`, `created_at`, `updated_at`, plus `checksum`?, `row_count`?, `compressed_size_bytes`?, `storage_class`?, `archived_at`? |
| `studio.lerian.matcher.archive.uploaded` | `lerian.streaming.matcher` | An archive is uploaded to storage. | Same schema |
| `studio.lerian.matcher.archive.completed` | `lerian.streaming.matcher` | An archival cycle completes. | Same schema |
| `studio.lerian.matcher.actor.pseudonymized` | `lerian.streaming.matcher` | An actor's personal data is pseudonymized (GDPR/LGPD). | `actor_id`, `pseudonymized`, `display_name_status`, `email_status`, `updated_at`, `tenant_id` |
| `studio.lerian.matcher.export_job.created` | `lerian.streaming.matcher` | An export job is created. | `export_job_id`, `tenant_id`, `context_id`, `report_type`, `format`, `status`, `schema_version`, `created_at`, `expires_at`, `updated_at` |
| `studio.lerian.matcher.export_job.succeeded` | `lerian.streaming.matcher` | An export job finishes writing its artifact. | Same schema, plus `file_name`?, `sha256`?, `records_written`?, `bytes_written`?, `attempts`?, `finished_at`? |
| `studio.lerian.matcher.export_job.failed` | `lerian.streaming.matcher` | An export job fails. | Same schema, plus `error_code`?, `attempts`?, `finished_at`? |
| `studio.lerian.matcher.export_job.expired` | `lerian.streaming.matcher` | An export artifact expires and is cleaned up. | Same schema, plus `expired_at`? |

## Payload contracts

These types mirror the CloudEvent `data` objects emitted by Matcher v5.0.0. `?` means the property can be absent. Timestamps are UTC RFC 3339 with nanosecond precision. UUID aliases document semantic identity. A field typed as `string` carries no UUID guarantee. `stats` is an open integer map, so consumers must tolerate new keys.

```typescript theme={null}
type RFC3339Nano = string
type DecimalString = string
type UUID = string
type MatchRunStats = Record<string, number>

// reconciliation_context.created
type ReconciliationContextCreatedDataV1 = {
  context_id: UUID
  name: string
  context_type: string
  interval: string
  status: string
  auto_match_on_upload: boolean
  created_at: RFC3339Nano
  tenant_id: string
}

// reconciliation_context.updated
type ReconciliationContextUpdatedDataV1 = {
  context_id: UUID
  name: string
  context_type: string
  interval: string
  status: string
  auto_match_on_upload: boolean
  updated_at: RFC3339Nano
  tenant_id: string
}

// reconciliation_source.created
type ReconciliationSourceCreatedDataV1 = {
  context_id: UUID
  source_id: UUID
  name: string
  source_type: string
  side: string
  created_at: RFC3339Nano
  tenant_id: string
}

// match_rule.created
type MatchRuleCreatedDataV1 = {
  context_id: UUID
  rule_id: UUID
  rule_type: string
  priority: number
  config_hash: string
  created_at: RFC3339Nano
  tenant_id: string
}

// match_rule.reordered
type MatchRuleReorderedDataV1 = {
  context_id: UUID
  ordered_rule_ids: UUID[]
  priority_version: string
  reordered_at: RFC3339Nano
  tenant_id: string
}

// fetcher_connection.synced
type FetcherConnectionSyncedDataV1 = {
  connection_id: UUID
  fetcher_connection_id: string
  config_name: string
  database_type: string
  status: string
  schema_discovered: boolean
  last_seen_at: RFC3339Nano
  updated_at: RFC3339Nano
}

// fetcher_connection.unreachable
type FetcherConnectionUnreachableDataV1 = {
  connection_id: UUID
  fetcher_connection_id: string
  previous_status: string
  status: string
  schema_discovered: boolean
  updated_at: RFC3339Nano
}

// extraction_request.created
type ExtractionRequestCreatedDataV1 = {
  extraction_request_id: UUID
  connection_id: UUID
  status: string
  table_count: number
  has_filters: boolean
  start_date: string
  end_date: string
  created_at: RFC3339Nano
}

// extraction_request.submitted, extraction_request.completed, and extraction_request.failed
type ExtractionRequestLifecycleDataV1 = {
  extraction_request_id: UUID
  connection_id: UUID
  status: string
  error_code?: "EXTRACTION_REQUEST_FAILED"
}

// ingestion.completed
type IngestionCompletedDataV1 = {
  job_id: UUID
  context_id: UUID
  source_id: UUID
  status: string
  total_rows: number
  failed_rows: number
  transaction_count: number
  date_range_start?: RFC3339Nano
  date_range_end?: RFC3339Nano
  completed_at?: RFC3339Nano
  error_code?: string
}

// ingestion.failed
type IngestionFailedDataV1 = {
  job_id: UUID
  context_id: UUID
  source_id: UUID
  status: string
  total_rows: number
  failed_rows: number
  failed_at?: RFC3339Nano
  error_code?: string
}

// transaction.ignored
type TransactionIgnoredDataV1 = {
  transaction_id: UUID
  ingestion_job_id: UUID
  context_id: UUID
  source_id: UUID
  previous_status: string
  status: string
  extraction_status: string
  updated_at: RFC3339Nano
}

// transaction.matched
type TransactionMatchedDataV1 = {
  transaction_id: UUID
  context_id: UUID
  match_run_id: UUID
  previous_status: string
  status: string
  match_group_id?: UUID
  candidate_match_group_id?: UUID
  source_id?: UUID
  matched_at: RFC3339Nano
}

// transaction.pending_review
type TransactionPendingReviewDataV1 = {
  transaction_id: UUID
  context_id: UUID
  match_run_id: UUID
  previous_status: string
  status: string
  match_group_id?: UUID
  candidate_match_group_id?: UUID
  source_id?: UUID
  pending_review_at: RFC3339Nano
}

// match_run.completed
type MatchRunCompletedDataV1 = {
  match_run_id: UUID
  context_id: UUID
  mode: string
  status: string
  stats: MatchRunStats
  started_at: RFC3339Nano
  completed_at?: RFC3339Nano
}

// match_run.failed
type MatchRunFailedDataV1 = {
  match_run_id: UUID
  context_id: UUID
  mode: string
  status: string
  failure_reason: string
  started_at: RFC3339Nano
  completed_at?: RFC3339Nano
}

// match_group.confirmed
type MatchGroupConfirmedDataV1 = {
  match_group_id: UUID
  match_run_id: UUID
  context_id: UUID
  rule_id: UUID
  transaction_ids: UUID[]
  confidence: number
  status: string
  confirmed_at?: RFC3339Nano
}

// match_group.unmatched
type MatchGroupUnmatchedDataV1 = {
  match_group_id: UUID
  match_run_id: UUID
  context_id: UUID
  rule_id: UUID
  transaction_ids: UUID[]
  previous_status: string
  status: string
  reason: string
  unmatched_at: RFC3339Nano
}

// fee_variance.created
type FeeVarianceCreatedDataV1 = {
  fee_variance_id: UUID
  context_id: UUID
  match_run_id: UUID
  match_group_id: UUID
  transaction_id: UUID
  fee_schedule_id: UUID
  fee_schedule_name_snapshot: string
  currency: string
  expected_fee: DecimalString
  actual_fee: DecimalString
  delta: DecimalString
  variance_type: string
  created_at: RFC3339Nano
}

type ExceptionDataBaseV1 = {
  exception_id: UUID
  status: string
  version: number
  resolution_type?: string
  transaction_id?: UUID
}

// exception.assigned
type ExceptionAssignedDataV1 = ExceptionDataBaseV1 & {
  assigned_at: RFC3339Nano
}

// exception.resolved
type ExceptionResolvedDataV1 = ExceptionDataBaseV1 & {
  resolved_at: RFC3339Nano
}

// exception.callback_processed
type ExceptionCallbackProcessedDataV1 = ExceptionDataBaseV1 & {
  external_system: string
  external_issue_id: string
  callback_type: string
  processed_at: RFC3339Nano
}

// exception.force_match_resolved
type ExceptionForceMatchResolvedDataV1 = ExceptionDataBaseV1 & {
  resolution_type: "FORCE_MATCH"
  override_reason_code: string
  resolved_at: RFC3339Nano
}

// exception.adjust_entry_resolved
type ExceptionAdjustEntryResolvedDataV1 = ExceptionDataBaseV1 & {
  resolution_type: "ADJUST_ENTRY"
  reason_code: string
  amount: DecimalString
  currency: string
  resolved_at: RFC3339Nano
}

// exception.dispatched
type ExceptionDispatchedDataV1 = {
  exception_id: UUID
  target_system: string
  queue: string
  external_reference: string
  acknowledged: boolean
  dispatched_at: RFC3339Nano
}

// exception_comment.added
type ExceptionCommentAddedDataV1 = {
  comment_id: UUID
  exception_id: UUID
  created_at: RFC3339Nano
}

// exception_comment.deleted
type ExceptionCommentDeletedDataV1 = {
  comment_id: UUID
  exception_id: UUID
  actor: string
  deleted_at: RFC3339Nano
}

// dispute.opened
type DisputeOpenedDataV1 = {
  dispute_id: UUID
  exception_id: UUID
  state: string
  resolution?: string
  category: string
  opened_at: RFC3339Nano
}

// dispute.won and dispute.lost
type DisputeClosedDataV1 = {
  dispute_id: UUID
  exception_id: UUID
  state: string
  resolution?: string
  closed_at: RFC3339Nano
}

// evidence.submitted
type EvidenceSubmittedDataV1 = {
  evidence_id: UUID
  dispute_id: UUID
  exception_id: UUID
  has_file: boolean
  submitted_at: RFC3339Nano
}

// audit_log.created
type AuditLogCreatedDataV1 = {
  audit_log_id: UUID
  tenant_id: UUID
  entity_type: string
  entity_id: UUID
  action: string
  tenant_seq: number
  hash_version: number
  record_hash: string
  created_at: RFC3339Nano
}

// archive_metadata.created, archive.uploaded, and archive.completed
type ArchiveDataV1 = {
  archive_metadata_id: UUID
  tenant_id: UUID
  partition_name: string
  date_range_start: RFC3339Nano
  date_range_end: RFC3339Nano
  status: string
  created_at: RFC3339Nano
  updated_at: RFC3339Nano
  checksum?: string
  row_count?: number
  compressed_size_bytes?: number
  storage_class?: string
  archived_at?: RFC3339Nano
}

// actor.pseudonymized
type ActorPseudonymizedDataV1 = {
  actor_id: string
  pseudonymized: boolean
  display_name_status: "REDACTED"
  email_status: "REDACTED"
  updated_at: RFC3339Nano
  tenant_id: string
}

// export_job.created, export_job.succeeded, export_job.failed, and export_job.expired
type ExportJobDataV1 = {
  export_job_id: UUID
  tenant_id: UUID
  context_id: UUID
  report_type: string
  format: string
  status: string
  schema_version: "1.0.0"
  created_at: RFC3339Nano
  expires_at: RFC3339Nano
  updated_at: RFC3339Nano
  file_name?: string
  sha256?: string
  records_written?: number
  bytes_written?: number
  attempts?: number
  error_code?: "EXPORT_JOB_FAILED"
  finished_at?: RFC3339Nano
  expired_at?: RFC3339Nano
}
```

`ingestion.completed` includes the date range only when the pipeline calculated one. Terminal timestamps and stable error codes depend on the persisted aggregate. Export counters are absent while zero. `dispute.won` and `dispute.lost` do not repeat the `category` sent by `dispute.opened`.

## Events consumed

Matcher consumes no streaming events. Its integration inputs arrive over HTTP, such as file uploads and Discovery extractions.


# Activate a Workflow
Source: https://docs.lerian.studio/en/reference/products/flowker/activate-workflow

/en/openapi/v3-current/flowker.yaml post /v1/workflows/{id}/activate
Use this endpoint to activate a workflow. Transitions the status from `draft` to `active`.



# Clone a Workflow
Source: https://docs.lerian.studio/en/reference/products/flowker/clone-workflow

/en/openapi/v3-current/flowker.yaml post /v1/workflows/{id}/clone
Use this endpoint to create a copy of an existing workflow with a new name. The cloned workflow is created in `draft` status.



# Count Pending-Review Occurrences
Source: https://docs.lerian.studio/en/reference/products/flowker/count-pending-review-occurrences

/en/openapi/v3-current/flowker.yaml get /v1/workflows/schedule/pending-review-counts
Use this endpoint to count, per workflow, the scheduled occurrences parked in the pending-review state across the caller's tenant. The counts map is sparse: a workflow with no pending-review occurrence is absent from the response.



# Create a Workflow
Source: https://docs.lerian.studio/en/reference/products/flowker/create-workflow

/en/openapi/v3-current/flowker.yaml post /v1/workflows
Use this endpoint to create a new workflow definition. New workflows are created in `draft` status.



# Deactivate a Workflow
Source: https://docs.lerian.studio/en/reference/products/flowker/deactivate-workflow

/en/openapi/v3-current/flowker.yaml post /v1/workflows/{id}/deactivate
Use this endpoint to deactivate a workflow. Transitions the status from `active` to `inactive`.



# Delete a Workflow
Source: https://docs.lerian.studio/en/reference/products/flowker/delete-workflow

/en/openapi/v3-current/flowker.yaml delete /v1/workflows/{id}
Use this endpoint to delete a workflow definition. Only workflows with `draft` or `inactive` status can be deleted.



# Discard All Parked Occurrences
Source: https://docs.lerian.studio/en/reference/products/flowker/discard-all-parked-occurrences

/en/openapi/v3-current/flowker.yaml post /v1/workflows/{id}/schedule/missed/discard-all
Use this endpoint to discard every parked occurrence of a workflow that is in the pending-review state. The operation is idempotent: when no occurrence is pending review, the response reports zero discarded.



# Discard a Parked Occurrence
Source: https://docs.lerian.studio/en/reference/products/flowker/discard-parked-occurrence

/en/openapi/v3-current/flowker.yaml post /v1/workflows/{id}/schedule/missed/{occurrenceId}/discard
Use this endpoint to move a parked occurrence to the terminal discarded state. Only an occurrence in the pending-review state can be discarded; any other state returns 422.



# Execute a Workflow
Source: https://docs.lerian.studio/en/reference/products/flowker/execute-workflow

/en/openapi/v3-current/flowker.yaml post /v1/workflows/{workflowId}/executions
Use this endpoint to start a new workflow execution. The request does not wait for the workflow to finish. A new execution returns with the `running` status. Use the Idempotency-Key header to ensure safe retries.



# Get a Catalog Executor
Source: https://docs.lerian.studio/en/reference/products/flowker/get-catalog-executor

/en/openapi/v3-current/flowker.yaml get /v1/catalog/executors/{id}
Use this endpoint to retrieve the metadata and JSON Schema of a specific catalog executor.



# Get a Catalog Provider
Source: https://docs.lerian.studio/en/reference/products/flowker/get-catalog-provider

/en/openapi/v3-current/flowker.yaml get /v1/catalog/providers/{id}
Use this endpoint to retrieve the metadata and JSON Schema of a specific catalog provider.



# Get a Catalog Template
Source: https://docs.lerian.studio/en/reference/products/flowker/get-catalog-template

/en/openapi/v3-current/flowker.yaml get /v1/catalog/templates/{id}
Use this endpoint to retrieve the metadata and parameter JSON Schema of a specific catalog template. If the template references provider configurations, the schema is dynamically enriched with active provider configuration options.



# Get a Catalog Trigger
Source: https://docs.lerian.studio/en/reference/products/flowker/get-catalog-trigger

/en/openapi/v3-current/flowker.yaml get /v1/catalog/triggers/{id}
Use this endpoint to retrieve the metadata and JSON Schema of a specific catalog trigger.



# Get Dashboard Execution Summary
Source: https://docs.lerian.studio/en/reference/products/flowker/get-dashboard-execution-summary

/en/openapi/v3-current/flowker.yaml get /v1/dashboards/executions
Use this endpoint to retrieve an aggregated summary of workflow executions. You can optionally filter by time range and status.



# Get Dashboard Workflow Summary
Source: https://docs.lerian.studio/en/reference/products/flowker/get-dashboard-workflow-summary

/en/openapi/v3-current/flowker.yaml get /v1/dashboards/workflows/summary
Use this endpoint to retrieve an aggregated summary of workflows, including totals and breakdowns by status.



# Get Execution Results
Source: https://docs.lerian.studio/en/reference/products/flowker/get-execution-results

/en/openapi/v3-current/flowker.yaml get /v1/executions/{id}/results
Use this endpoint to retrieve the results of a completed workflow execution. The execution must be in a terminal state.



# Get an Execution Status
Source: https://docs.lerian.studio/en/reference/products/flowker/get-execution-status

/en/openapi/v3-current/flowker.yaml get /v1/executions/{id}
Use this endpoint to retrieve the current status of a specific workflow execution.



# Get an Executor Configuration
Source: https://docs.lerian.studio/en/reference/products/flowker/get-executor-configuration

/en/openapi/v3-current/flowker.yaml get /v1/executors/{id}
Use this endpoint to retrieve a specific executor configuration by its unique identifier.



# Get a Workflow
Source: https://docs.lerian.studio/en/reference/products/flowker/get-workflow

/en/openapi/v3-current/flowker.yaml get /v1/workflows/{id}
Use this endpoint to retrieve a specific workflow definition by its unique identifier.



# List Catalog Executors
Source: https://docs.lerian.studio/en/reference/products/flowker/list-catalog-executors

/en/openapi/v3-current/flowker.yaml get /v1/catalog/executors
Use this endpoint to retrieve all built-in executors registered in the catalog.



# List Catalog Providers
Source: https://docs.lerian.studio/en/reference/products/flowker/list-catalog-providers

/en/openapi/v3-current/flowker.yaml get /v1/catalog/providers
Use this endpoint to retrieve all registered providers from the catalog.



# List Catalog Templates
Source: https://docs.lerian.studio/en/reference/products/flowker/list-catalog-templates

/en/openapi/v3-current/flowker.yaml get /v1/catalog/templates
Use this endpoint to retrieve all workflow templates registered in the catalog.



# List Catalog Triggers
Source: https://docs.lerian.studio/en/reference/products/flowker/list-catalog-triggers

/en/openapi/v3-current/flowker.yaml get /v1/catalog/triggers
Use this endpoint to retrieve all built-in triggers registered in the catalog.



# List Executions
Source: https://docs.lerian.studio/en/reference/products/flowker/list-executions

/en/openapi/v3-current/flowker.yaml get /v1/executions
Use this endpoint to retrieve a paginated list of workflow executions. You can filter results by workflow ID or status.



# List Executor Configurations
Source: https://docs.lerian.studio/en/reference/products/flowker/list-executor-configurations

/en/openapi/v3-current/flowker.yaml get /v1/executors
Use this endpoint to retrieve a paginated list of executor configurations. You can filter results by status.



# List Executors by Provider
Source: https://docs.lerian.studio/en/reference/products/flowker/list-executors-by-provider

/en/openapi/v3-current/flowker.yaml get /v1/catalog/providers/{id}/executors
Use this endpoint to retrieve all executors that belong to a specific provider.



# List Parked Scheduled Occurrences
Source: https://docs.lerian.studio/en/reference/products/flowker/list-parked-scheduled-occurrences

/en/openapi/v3-current/flowker.yaml get /v1/workflows/{id}/schedule/missed
Use this endpoint to list a workflow's parked scheduled occurrences, both missed and pending review, that await a run or discard decision.



# List Skipped Scheduled Occurrences
Source: https://docs.lerian.studio/en/reference/products/flowker/list-skipped-scheduled-occurrences

/en/openapi/v3-current/flowker.yaml get /v1/workflows/{id}/schedule/skipped
Use this endpoint to list a workflow's skipped scheduled occurrences, ordered oldest first. Each occurrence carries the reason it was skipped.



# List Upcoming Scheduled Occurrences
Source: https://docs.lerian.studio/en/reference/products/flowker/list-upcoming-scheduled-occurrences

/en/openapi/v3-current/flowker.yaml get /v1/workflows/{id}/schedule/upcoming
Use this endpoint to compute the next occurrences of a workflow's schedule trigger, evaluated in the schedule's timezone. A workflow with no schedule trigger returns 422.



# List Workflows
Source: https://docs.lerian.studio/en/reference/products/flowker/list-workflows

/en/openapi/v3-current/flowker.yaml get /v1/workflows
Use this endpoint to retrieve a paginated list of workflows. You can filter results by status.



# Move a Workflow to Draft
Source: https://docs.lerian.studio/en/reference/products/flowker/move-workflow-to-draft

/en/openapi/v3-current/flowker.yaml post /v1/workflows/{id}/draft
Use this endpoint to move a workflow back to draft status for editing. Transitions the status from `inactive` to `draft`.



# Preview an Executor Request
Source: https://docs.lerian.studio/en/reference/products/flowker/preview-executor-request

/en/openapi/v3-current/flowker.yaml post /v1/workflows/preview-request
Use this endpoint to assemble the outgoing HTTP request an executor node would send, without sending it. The preview applies the same interpolation, input mapping, and authentication assembly used at execution time. It never opens a network connection and never reads the vault. The preview replaces the credential that the authentication type declares (its API key, bearer token, password, client secret, or signing secret) with `***` where the credential appears as a value: in the URL, the query string, the headers, the body, and the `curl` command. Where removing the credential would damage the request, the preview shows it as written, for example when the credential is part of a header name or a body field name. Any other value, including a free-form authentication parameter, can appear as Flowker would send it. Store credential material only in the fields that the authentication type declares.



# Run a Parked Occurrence
Source: https://docs.lerian.studio/en/reference/products/flowker/run-parked-occurrence

/en/openapi/v3-current/flowker.yaml post /v1/workflows/{id}/schedule/missed/{occurrenceId}/run
Use this endpoint to re-run a parked occurrence. The occurrence moves to the queued state and is enqueued once. Only an occurrence in the pending-review state can be run; any other state returns 422. The operation is idempotent.



# Update a Workflow
Source: https://docs.lerian.studio/en/reference/products/flowker/update-workflow

/en/openapi/v3-current/flowker.yaml put /v1/workflows/{id}
Use this endpoint to update an existing workflow definition. Only workflows with `draft` status can be updated.



# Validate Catalog Template Parameters
Source: https://docs.lerian.studio/en/reference/products/flowker/validate-catalog-template-params

/en/openapi/v3-current/flowker.yaml post /v1/catalog/templates/{id}/validate
Use this endpoint to validate template parameters against the template's JSON Schema.



# Validate a Node Configuration
Source: https://docs.lerian.studio/en/reference/products/flowker/validate-executor-config

/en/openapi/v3-current/flowker.yaml post /v1/catalog/executors/{id}/validate
Use this endpoint to check a workflow node's configuration against the JSON Schema of the catalog executor it invokes. The check is structural — it never calls the external service.



# Approve an AI extraction review (ingest the candidates)
Source: https://docs.lerian.studio/en/reference/products/matcher/approve-extraction-review

/en/openapi/v3-current/matcher.yaml post /v1/imports/contexts/{contextId}/extraction-reviews/{reviewId}/approve
Approves a PENDING_REVIEW review and runs the SINGLE deterministic handoff into the normal ingestion pipeline (dedup + outbox + match-trigger), linking the resulting job to the review. This is the ONLY path from an AI candidate to a reconciled transaction, and it runs only on explicit human approval. The approving principal is the reviewer (audit attribution). Tenant from the JWT, context from the path.



# Approve an AI match-rule suggestion (create the rule)
Source: https://docs.lerian.studio/en/reference/products/matcher/approve-match-rule-suggestion

/en/openapi/v3-current/matcher.yaml post /v1/matching/contexts/{contextId}/rule-suggestions/{suggestionId}/approve
Approves a PENDING_REVIEW suggestion and creates the match rule through the deterministic configuration write path. This is the ONLY path from an AI suggestion to an active match rule, and it runs only on explicit human approval. The approving principal is recorded for audit. Tenant from the JWT, context from the path.



# Count exceptions
Source: https://docs.lerian.studio/en/reference/products/matcher/count-exceptions

/en/openapi/v3-current/matcher.yaml get /v1/reports/contexts/{contextId}/exceptions/count
Use this endpoint to retrieve the total number of exceptions for a specific context and date range.



# Count matches
Source: https://docs.lerian.studio/en/reference/products/matcher/count-matches

/en/openapi/v3-current/matcher.yaml get /v1/reports/contexts/{contextId}/matches/count
Use this endpoint to retrieve the total number of matched items for a specific context and date range.



# Count transactions
Source: https://docs.lerian.studio/en/reference/products/matcher/count-transactions

/en/openapi/v3-current/matcher.yaml get /v1/reports/contexts/{contextId}/transactions/count
Use this endpoint to retrieve the total number of transactions for a specific context and date range.



# Count unmatched items
Source: https://docs.lerian.studio/en/reference/products/matcher/count-unmatched

/en/openapi/v3-current/matcher.yaml get /v1/reports/contexts/{contextId}/unmatched/count
Use this endpoint to retrieve the total number of unmatched items for a specific context and date range.



# Create an adjustment
Source: https://docs.lerian.studio/en/reference/products/matcher/create-adjustment

/en/openapi/v3-current/matcher.yaml post /v1/matching/adjustments
Use this endpoint to create a balancing journal entry (e.g., bank fee, FX difference) to resolve variance between matched transactions or on a single transaction.



# Create aggregator connection
Source: https://docs.lerian.studio/en/reference/products/matcher/create-aggregator-connection

/en/openapi/v3-current/matcher.yaml post /v1/discovery/aggregator-connections
Creates an Open-Finance data-aggregator (Pluggy/Belvo) connection and seals its credential. The connection's config name is what the webhook token-mint endpoint binds a token to. The supplied credential is sealed before persistence and is never returned.



# Create discovery connection
Source: https://docs.lerian.studio/en/reference/products/matcher/create-discovery-connection

/en/openapi/v3-current/matcher.yaml post /v1/discovery/connections
Provisions a connection scoped to Matcher and synchronizes the local discovery cache.



# Start a connection extraction
Source: https://docs.lerian.studio/en/reference/products/matcher/create-extraction

/en/openapi/v3-current/matcher.yaml post /v1/discovery/connections/{connectionId}/extractions
Use this endpoint to create an extraction request for a discovered connection and submit it to the extraction engine for the authenticated tenant.



# Create a manual match
Source: https://docs.lerian.studio/en/reference/products/matcher/create-manual-match

/en/openapi/v3-current/matcher.yaml post /v1/matching/manual
Use this endpoint to manually link multiple transactions (at least 2) into a match group with 100% confidence. Transactions must be UNMATCHED and belong to the specified context.



# Create REST discovery connection
Source: https://docs.lerian.studio/en/reference/products/matcher/create-rest-discovery-connection

/en/openapi/v3-current/matcher.yaml post /v1/discovery/rest-connections
Use this endpoint to create a REST connection to a payment provider: PagBank, Stripe, or Pix BCB. The credential fields each connector type requires are listed as `requiredFields` on GET /v1/discovery/connector-types. An optional `baseURL` replaces the default provider address for this connection. After you create it, the connection appears in GET /v1/discovery/connections; an update to a REST connection accepts only `configName`.



# Delete aggregator connection
Source: https://docs.lerian.studio/en/reference/products/matcher/delete-aggregator-connection

/en/openapi/v3-current/matcher.yaml delete /v1/discovery/aggregator-connections/{id}
Soft-deletes an Open-Finance data-aggregator (Pluggy/Belvo) connection by id, freeing its config name for reuse. A non-aggregator connection id returns 404.



# Delete discovery connection
Source: https://docs.lerian.studio/en/reference/products/matcher/delete-discovery-connection

/en/openapi/v3-current/matcher.yaml delete /v1/discovery/connections/{connectionId}
Deletes a Matcher-owned connection and marks the local cache unavailable.



# Get discovery status
Source: https://docs.lerian.studio/en/reference/products/matcher/discovery-status

/en/openapi/v3-current/matcher.yaml get /v1/discovery/status
Use this endpoint to retrieve the current discovery status, including how many connections have been discovered.



# Export exceptions report
Source: https://docs.lerian.studio/en/reference/products/matcher/export-exceptions-report

/en/openapi/v3-current/matcher.yaml get /v1/reports/contexts/{contextId}/exceptions/export
Use this endpoint to export an exceptions report in CSV or PDF format for the specified date range.



# Export matched transactions report
Source: https://docs.lerian.studio/en/reference/products/matcher/export-matched-report

/en/openapi/v3-current/matcher.yaml get /v1/reports/contexts/{contextId}/matched/export
Use this endpoint to export a matched transactions report in CSV or PDF format for the specified date range.



# Export summary report
Source: https://docs.lerian.studio/en/reference/products/matcher/export-summary-report

/en/openapi/v3-current/matcher.yaml get /v1/reports/contexts/{contextId}/summary/export
Use this endpoint to export a reconciliation summary report in CSV or PDF format for the specified date range.



# Export unmatched transactions report
Source: https://docs.lerian.studio/en/reference/products/matcher/export-unmatched-report

/en/openapi/v3-current/matcher.yaml get /v1/reports/contexts/{contextId}/unmatched/export
Use this endpoint to export an unmatched transactions report in CSV or PDF format for the specified date range.



# Export variance report
Source: https://docs.lerian.studio/en/reference/products/matcher/export-variance-report

/en/openapi/v3-current/matcher.yaml get /v1/reports/contexts/{contextId}/variance/export
Use this endpoint to export a variance analysis report in CSV or PDF format for the specified date range.



# Enqueue a document for AI extraction (human-review required)
Source: https://docs.lerian.studio/en/reference/products/matcher/extract-document

/en/openapi/v3-current/matcher.yaml post /v1/imports/contexts/{contextId}/sources/{sourceId}/extract-document
Stores the uploaded source document tenant-scoped, runs deterministic + AI extraction, and enqueues the resulting transaction CANDIDATES in a human-review queue. AI output is NEVER authoritative: no transaction is reconciled until a human approves the review. The tenant is resolved from the JWT and the context/source from the path — never from the body.



# Trigger a manual fetch-and-ingest from an external transport
Source: https://docs.lerian.studio/en/reference/products/matcher/fetch-trigger

/en/openapi/v3-current/matcher.yaml post /v1/imports/contexts/{contextId}/sources/{sourceId}/fetch
Lists every object matching the supplied transport coordinates and streams each into the trusted-content ingestion pipeline (dedup + outbox + match-trigger), returning a per-file outcome in fetch order. The tenant is resolved from the JWT and the context/source from the path — NEVER from the body. The body carries connection coordinates plus an OPAQUE credential reference. A transport-level fetch failure (the external endpoint is unreachable or rejects the credential) returns 503; per-file intake failures are reported in the response body without failing the batch.



# Get aggregator connection
Source: https://docs.lerian.studio/en/reference/products/matcher/get-aggregator-connection

/en/openapi/v3-current/matcher.yaml get /v1/discovery/aggregator-connections/{id}
Returns a single Open-Finance data-aggregator (Pluggy/Belvo) connection by id. The result is secret-free by construction: no credential material (clientId/secret/ciphertext) is ever returned. A non-aggregator connection id returns 404.



# Get cash impact summary
Source: https://docs.lerian.studio/en/reference/products/matcher/get-cash-impact

/en/openapi/v3-current/matcher.yaml get /v1/reports/contexts/{contextId}/dashboard/cash-impact
Use this endpoint to retrieve a cash impact summary showing the total unmatched financial exposure. Includes breakdowns by currency and by age bucket to help prioritize resolution efforts.



# Get connection schema
Source: https://docs.lerian.studio/en/reference/products/matcher/get-connection-schema

/en/openapi/v3-current/matcher.yaml get /v1/discovery/connections/{connectionId}/schema
Use this endpoint to retrieve all discovered table schemas for a specific connection.



# Get connection schema history
Source: https://docs.lerian.studio/en/reference/products/matcher/get-connection-schema-history

/en/openapi/v3-current/matcher.yaml get /v1/discovery/connections/{connectionId}/schema/history
Use this endpoint to list the earlier generations of a connection's schema map, oldest first. Each generation records when it stopped being the live schema map, and `retirementCause` records what Matcher observed when it retired it.



# Get all dashboard aggregates
Source: https://docs.lerian.studio/en/reference/products/matcher/get-dashboard-aggregates

/en/openapi/v3-current/matcher.yaml get /v1/reports/contexts/{contextId}/dashboard
Use this endpoint to retrieve combined dashboard aggregates including volume, match rate, and SLA statistics.



# Get comprehensive dashboard metrics
Source: https://docs.lerian.studio/en/reference/products/matcher/get-dashboard-metrics

/en/openapi/v3-current/matcher.yaml get /v1/reports/contexts/{contextId}/dashboard/metrics
Use this endpoint to retrieve complete dashboard metrics including summary, trends, and breakdowns for the Command Center.



# Get match rate statistics
Source: https://docs.lerian.studio/en/reference/products/matcher/get-match-rate-stats

/en/openapi/v3-current/matcher.yaml get /v1/reports/contexts/{contextId}/dashboard/match-rate
Use this endpoint to retrieve match rate percentage and trend data for a reconciliation context within the specified date range.



# Get SLA statistics
Source: https://docs.lerian.studio/en/reference/products/matcher/get-sla-stats

/en/openapi/v3-current/matcher.yaml get /v1/reports/contexts/{contextId}/dashboard/sla
Use this endpoint to retrieve SLA compliance statistics for a reconciliation context within the specified date range.



# Get source breakdown
Source: https://docs.lerian.studio/en/reference/products/matcher/get-source-breakdown

/en/openapi/v3-current/matcher.yaml get /v1/reports/contexts/{contextId}/dashboard/source-breakdown
Use this endpoint to retrieve a breakdown of reconciliation metrics by source for a specific context and date range. Shows match rates, transaction counts, and unmatched amounts per source.



# Get reconciliation summary report
Source: https://docs.lerian.studio/en/reference/products/matcher/get-summary-report

/en/openapi/v3-current/matcher.yaml get /v1/reports/contexts/{contextId}/summary
Use this endpoint to retrieve an aggregated reconciliation summary for a specific context and date range, including matched and unmatched counts and amounts.



# Get volume statistics
Source: https://docs.lerian.studio/en/reference/products/matcher/get-volume-stats

/en/openapi/v3-current/matcher.yaml get /v1/reports/contexts/{contextId}/dashboard/volume
Use this endpoint to retrieve transaction volume statistics for a reconciliation context within the specified date range.



# List aggregator connections
Source: https://docs.lerian.studio/en/reference/products/matcher/list-aggregator-connections

/en/openapi/v3-current/matcher.yaml get /v1/discovery/aggregator-connections
Returns a cursor-paginated list of the tenant's Open-Finance data-aggregator (Pluggy/Belvo) connections, ordered by config name. The list is secret-free by construction: no credential material (clientId/secret/ciphertext) is ever returned. Each row carries `testable`, which tells whether the connectivity test can run for that connection.



# List discovered connections
Source: https://docs.lerian.studio/en/reference/products/matcher/list-discovery-connections

/en/openapi/v3-current/matcher.yaml get /v1/discovery/connections
Use this endpoint to retrieve all discovered connections available for the current tenant.



# List connector types
Source: https://docs.lerian.studio/en/reference/products/matcher/list-discovery-connector-types

/en/openapi/v3-current/matcher.yaml get /v1/discovery/connector-types
Returns the connector types the engine registry has actually registered for this deployment, each tagged with a backend-derived category ('database' or 'rest'). The list reflects the live registry — only the connectors registered at boot appear, with no static enum of all possible types. Aggregator-vendor types (Pluggy/Belvo) are excluded — they are provisioned through the aggregator-connections surface.



# List match candidates for a transaction
Source: https://docs.lerian.studio/en/reference/products/matcher/list-match-candidates

/en/openapi/v3-current/matcher.yaml get /v1/matching/candidates
Returns a ranked list of opposite-side unmatched transactions the engine considers plausible counterparts for the target transaction, each with a confidence score, the rule that drove it, a per-component rationale (the "why"), and amount/date deltas. Powers the exception-resolution and manual-match candidate pickers. Scope: proposals are scored by the deterministic rule engine over raw transaction amounts and do NOT apply run-time fee normalization or the FX-variance band; only 1:1 pairwise counterparts are returned.



# List AI match-rule suggestions (the human-review queue)
Source: https://docs.lerian.studio/en/reference/products/matcher/list-match-rule-suggestions

/en/openapi/v3-current/matcher.yaml get /v1/matching/contexts/{contextId}/rule-suggestions
Cursor-paginated list of rule suggestions for a context, optionally filtered by status (e.g. PENDING_REVIEW). Reads stored config-only candidates; egresses nothing. Tenant from the JWT, context from the path.



# Get match run results
Source: https://docs.lerian.studio/en/reference/products/matcher/list-match-run-groups

/en/openapi/v3-current/matcher.yaml get /v1/matching/runs/{runId}/groups
Use this endpoint to retrieve all match groups from a specific matching run. Each group contains matched transaction pairs and confidence scores. The response uses cursor-based pagination.



# List match runs
Source: https://docs.lerian.studio/en/reference/products/matcher/list-match-runs

/en/openapi/v3-current/matcher.yaml get /v1/matching/contexts/{contextId}/runs
Use this endpoint to retrieve all match runs for a specific reconciliation context. The results are sorted by creation time descending.



# List matched transactions report
Source: https://docs.lerian.studio/en/reference/products/matcher/list-matched-report

/en/openapi/v3-current/matcher.yaml get /v1/reports/contexts/{contextId}/matched
Use this endpoint to retrieve a paginated list of matched transactions for a specific context and date range. The response uses cursor-based pagination.



# List open items
Source: https://docs.lerian.studio/en/reference/products/matcher/list-open-items

/en/openapi/v3-current/matcher.yaml get /v1/matching/contexts/{contextId}/open-items
Returns a cursor-paginated list of open-item residual ledger entries for a reconciliation context — the carried, partially-filled, and aged obligations the context carries forward across match runs. These are structurally distinct from never-matched (UNMATCHED) transactions. Optionally narrowed by lifecycle status. The listing is readable regardless of context status.



# List recorded adjustments
Source: https://docs.lerian.studio/en/reference/products/matcher/list-recorded-adjustments

/en/openapi/v3-current/matcher.yaml get /v1/matching/contexts/{contextId}/adjustments
Use this endpoint to list the balancing entries recorded against a context, newest first. Use `matchGroupId` to narrow the list to one match group.



# List unmatched transactions report
Source: https://docs.lerian.studio/en/reference/products/matcher/list-unmatched-report

/en/openapi/v3-current/matcher.yaml get /v1/reports/contexts/{contextId}/unmatched
Use this endpoint to retrieve a paginated list of unmatched transactions for a specific context and date range. The response uses cursor-based pagination.



# List variance report
Source: https://docs.lerian.studio/en/reference/products/matcher/list-variance-report

/en/openapi/v3-current/matcher.yaml get /v1/reports/contexts/{contextId}/variance
Use this endpoint to retrieve a paginated variance analysis report for a specific context and date range. The response uses cursor-based pagination.



# Matcher error list
Source: https://docs.lerian.studio/en/reference/products/matcher/matcher-error-list

Matcher API error codes and their HTTP statuses, so you can diagnose issues and route them to the right team.

### Error format

```json JSON theme={null}
{
   "type": "https://errors.lerian.studio/v1/<error_code>",
   "title": "<error_title>",
   "status": 400,
   "detail": "<error_detail>",
   "code": "<error_code>"
}
```

### Field definitions

* **`type`** – A URI that identifies the error, built as `https://errors.lerian.studio/v1/<code>`.
* **`title`** – The HTTP status text (for example, `Bad Request`).
* **`status`** – The HTTP status code.
* **`detail`** – A short description of this occurrence of the error. Use `code` to branch programmatically.
* **`code`** – A stable product code that uniquely identifies the error (e.g., `MTCH-0001`). Useful for programmatic handling and support requests.
* **`errors`** – *(optional)* A list with field-level validation details.

### Field-level error details

When the request fails schema validation, Matcher returns `422 Unprocessable Entity` with an `errors` array and no `code`.

Examples:

```json Example 1 theme={null}
{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "validation failed",
  "errors": [
    { "message": "expected required property name to be present", "location": "body" }
  ]
}
```

```json Example 2 theme={null}
{
  "type": "https://errors.lerian.studio/v1/MTCH-0005",
  "title": "Not Found",
  "status": 404,
  "detail": "No reconciliation context matches this id; check the context id and try again.",
  "code": "MTCH-0005"
}
```

## General errors

***

These errors apply to all Matcher API endpoints.

**400**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0001` | Bad Request | The request body is invalid or malformed. Please verify the request format and try again. |
| `MTCH-0011` | Bad Request | The request failed. Please verify the request and try again. |
| `MTCH-0013` | Bad Request | The context ID is invalid. Please verify the ID format and try again. |

**403**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0004` | Forbidden | You do not have permission to perform this action. Please verify your access level. |
| `MTCH-0012` | Forbidden | The reconciliation context is not active. Please activate the context before performing this operation. |

**404**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0005` | Not Found | The requested resource does not exist. Please verify the ID and try again. |

**409**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0007` | Conflict | The request conflicts with the current state of the resource. Please verify and try again. |

**413**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0010` | Request Entity Too Large | The uploaded file exceeds the maximum allowed size. Please reduce the file size and try again. |

**422**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0006` | Unprocessable Entity | The request was well-formed but could not be processed. Please verify the input data and try again. |

**500**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0002` | Internal Server Error | An unexpected error occurred. The `detail` is `internal error`. |

**503**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0008` | Service Unavailable | A required service is temporarily unavailable. Please try again later. |
| `MTCH-0019` | Service Unavailable | Object storage is temporarily unavailable. Please try again later. |

## Configuration errors

***

Matcher returns these errors for a problem in the reconciliation configuration (contexts, sources, field maps, match rules, fee rules, schedules).

**400**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0109` | Bad Request | A context name is required. Please provide a valid name and try again. |

**404**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0111` | Not Found | The specified source was not found. Please verify the source ID and try again. |
| `MTCH-0112` | Not Found | The specified field map was not found. Please verify the field map ID and try again. |
| `MTCH-0113` | Not Found | The specified match rule was not found. Please verify the match rule ID and try again. |
| `MTCH-0114` | Not Found | The specified fee rule was not found. Please verify the fee rule ID and try again. |
| `MTCH-0115` | Not Found | The specified fee schedule was not found. Please verify the fee schedule ID and try again. |
| `MTCH-0116` | Not Found | The specified schedule was not found. Please verify the schedule ID and try again. |

**409**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0101` | Conflict | A context with this name already exists. Please choose a different name and try again. |
| `MTCH-0102` | Conflict | A resource with this priority already exists. Please choose a different priority value and try again. |
| `MTCH-0103` | Conflict | The resource is in an invalid state for this operation. Please verify its current state and try again. |
| `MTCH-0104` | Conflict | The context has been archived. Please use an active context for this operation. |
| `MTCH-0107` | Conflict | A resource with this priority already exists. Please choose a different priority value. |
| `MTCH-0108` | Conflict | The fee schedule is in use and cannot be deleted. |
| `MTCH-0118` | Conflict | The match rule cannot be deleted because a confirmed match group that it created still has an exception. Please change the rule's configuration instead. |

## Discovery errors

***

Matcher returns these errors for data source discovery and connection management. Discovery relies on Matcher's embedded extraction engine. See [Discovery](/en/products/matcher/integrations/matcher-discovery) for how it works.

**400**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0204` | Bad Request | The extraction request is invalid. Please verify the parameters and try again. |
| `MTCH-0208` | Bad Request | The specified connector type is not registered on this deployment. Please verify the connector type and try again. |

**404**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0201` | Not Found | The specified connection was not found. Please verify the connection ID and try again. |
| `MTCH-0202` | Not Found | The specified extraction was not found. Please verify the extraction ID and try again. |

**409**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0205` | Conflict | A discovery refresh is already in progress. Please wait for it to complete before starting a new one. |
| `MTCH-0209` | Conflict | Matcher retired the connection, but it could not confirm the delete on the external system. Please check the external system for a connection that may still be live. |

**422**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0210` | Unprocessable Entity | Matcher cannot run connectivity tests for this aggregator vendor. No test ran and nothing changed. |
| `MTCH-0211` | Unprocessable Entity | The aggregator connection is not linked to an account yet. Matcher did not run the test. Please complete the hosted consent flow, then try again. |
| `MTCH-0212` | Unprocessable Entity | The aggregator vendor did not issue a consent token, and nothing changed. Please test the connection, then try again. |
| `MTCH-0213` | Unprocessable Entity | Matcher cannot open a hosted consent flow for this aggregator vendor, and nothing changed. Please contact support if you need the consent flow for this vendor. |

**503**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0203` | Service Unavailable | The extraction engine is temporarily unavailable. Please try again later. |

## Ingestion errors

***

Matcher returns these errors for transaction file upload and processing.

**400**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0303` | Bad Request | The file format is required. Please specify the format and try again. |
| `MTCH-0304` | Bad Request | The uploaded file is empty. Please provide a non-empty file and try again. |
| `MTCH-0307` | Bad Request | The file was well-formed but contained no record elements to ingest. Please verify the file content and try again. |
| `MTCH-0308` | Bad Request | The uploaded file schema is not supported. Please verify the file structure and try again. |
| `MTCH-0317` | Bad Request | A mapping sample is required. Please provide a sample and try again. |
| `MTCH-0322` | Bad Request | The document body is empty. Please provide a non-empty document and try again. |

**403**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0319` | Forbidden | Document extraction is not enabled. Please contact support to opt in. |

**404**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0301` | Not Found | The specified ingestion source was not found. Please verify the source ID and try again. |
| `MTCH-0302` | Not Found | The specified ingestion field map was not found. Please verify the field map ID and try again. |
| `MTCH-0306` | Not Found | The specified ingestion job was not found. Please verify the job ID and try again. |

**408**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0311` | Request Timeout | The upload stalled because no data was received within the allowed time. Please retry the upload. |

**409**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0305` | Conflict | The ingestion job is in an invalid state for this operation. Please verify its current state. |
| `MTCH-0324` | Conflict | The extraction review is no longer pending and cannot be modified. Please verify its current state. |

**422**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0309` | Unprocessable Entity | The ingestion job exceeded the configured error rate threshold. Please review the source data and try again. |
| `MTCH-0310` | Unprocessable Entity | The source configuration is invalid. Please fix the source configuration and retry the upload. |
| `MTCH-0312` | Unprocessable Entity | The source's field map is invalid. Please fix the field map and retry the upload. |
| `MTCH-0321` | Unprocessable Entity | No transaction candidates could be extracted from the document. Please verify the document and try again. |

**503**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0313` | Service Unavailable | Fetch-and-ingest is not enabled on this deployment. Please upload the file manually. |
| `MTCH-0314` | Service Unavailable | The external transport could not be reached or read. Please try again later. |
| `MTCH-0315` | Service Unavailable | Mapping proposal is not enabled on this deployment. Please configure the field map manually. |
| `MTCH-0316` | Service Unavailable | The mapping advisor is unavailable. Please configure a field map manually. |
| `MTCH-0318` | Service Unavailable | Document extraction is not enabled on this deployment. Please ingest the file manually. |
| `MTCH-0320` | Service Unavailable | The document extractor is unavailable. Please ingest the file manually. |
| `MTCH-0323` | Service Unavailable | Extraction review is not enabled on this deployment. Please try again later. |

## Matching errors

***

Matcher returns these errors for the reconciliation matching process.

**400**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0401` | Bad Request | No sources are configured for this context. Please configure at least one source before running a match. |
| `MTCH-0402` | Bad Request | At least two sources are required for matching. Please configure additional sources. |
| `MTCH-0403` | Bad Request | Each source must have a defined side. Please specify the source side and try again. |
| `MTCH-0404` | Bad Request | The one-to-one topology configuration is invalid. Please verify the source configuration. |
| `MTCH-0405` | Bad Request | The one-to-many topology configuration is invalid. Please verify the source configuration. |

**403**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0409` | Forbidden | Rule suggestion is not enabled. Please contact support to opt in. |

**409**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0408` | Conflict | A matching run is already in progress for this context. Please wait for it to complete. |
| `MTCH-0413` | Conflict | The suggestion is no longer pending and cannot be modified. Please verify its current state. |

**422**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0406` | Unprocessable Entity | Fee rules are required but not configured. Please add fee rules before running a match. |
| `MTCH-0407` | Unprocessable Entity | Fee rules are misconfigured. Please review the fee rule settings and try again. |
| `MTCH-0412` | Unprocessable Entity | The approved suggestion failed validation. Please review the suggestion and try again. |

**503**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0410` | Service Unavailable | Rule suggestion is not enabled on this deployment. Please author match rules manually. |
| `MTCH-0411` | Service Unavailable | The rule advisor is unavailable. Please author match rules manually. |

## Exception errors

***

Matcher returns these errors for exception handling, disputes, and callback processing.

**404**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0501` | Not Found | The specified exception was not found. Please verify the exception ID and try again. |
| `MTCH-0502` | Not Found | The specified dispute was not found. Please verify the dispute ID and try again. |
| `MTCH-0507` | Not Found | The specified comment was not found. Please verify the comment ID and try again. |
| `MTCH-0512` | Not Found | Matcher applied the resolution, but it could not confirm the updated exception record. Please reload the exception to see its current status. |

**409**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0504` | Conflict | A callback for this exception is already being processed. Please wait for it to complete. |
| `MTCH-0505` | Conflict | The callback encountered a transient error and can be retried. Please retry the request. |
| `MTCH-0510` | Conflict | A settlement is already in progress on this exception. Please retry the request in a moment. |
| `MTCH-0511` | Conflict | The exception is already resolved, or a resolution is in progress. Please review its resolution details. |

**422**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0503` | Unprocessable Entity | The exception is in an invalid state for this operation. Please verify its current state. |
| `MTCH-0508` | Unprocessable Entity | The dispatch target type is not supported. Please verify the target configuration. |
| `MTCH-0509` | Unprocessable Entity | The dispatch connector is not configured. Please configure the connector and try again. |

**429**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0506` | Too Many Requests | The callback rate limit has been exceeded. Please wait before retrying. |

## Governance errors

***

Audit log and governance operations return the general errors, such as `MTCH-0005` when an audit log, actor mapping, or archive does not exist.

## Reporting errors

***

Report export operations return the general errors. An export job that does not exist returns `MTCH-0005`, a job that is not ready for download or has already finished returns `MTCH-0007`, a disabled export worker returns `MTCH-0702`, and unavailable object storage returns `MTCH-0019`. An expired export file returns `410` with no `code`.

## Rate limit errors

***

Matcher limits how many requests each caller can send in a time window. A request over the limit returns `429` before it reaches the operation, with a flat body in which `code` is the number `429`. The `Retry-After` header gives the number of seconds to wait before you retry.

```json theme={null}
{
  "code": 429,
  "title": "rate_limit_exceeded",
  "message": "rate limit exceeded"
}
```

When Matcher cannot reach the store that counts requests, it rejects the request with `503` and a flat body of the same shape:

```json theme={null}
{
  "code": 503,
  "title": "service_unavailable",
  "message": "rate limiter temporarily unavailable"
}
```

## Authentication errors

***

Access Manager checks the token and the caller's permissions. A refusal from that check is not a problem object and carries no `MTCH` code. When Access Manager does not answer, Matcher answers `503`.

**401**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0003` | Unauthorized | The request could not be authenticated. Please verify your credentials and try again. |

**403**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0004` | Forbidden | The token does not identify a tenant. Please verify your access level. |

## Idempotency errors

***

Matcher returns these errors for a problem with idempotency key handling.

**400**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0015` | Bad Request | The idempotency key must contain 1 to 128 letters, digits, hyphens, underscores, or colons; no request was processed. |

**409**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0018` | Conflict | A request with this idempotency key is already being processed. Wait for it to complete, then retry with the same key; the original request may still succeed. |

**500**

| `code` | `title` | Description |
| - | - | - |
| `MTCH-0016` | Internal Server Error | An unexpected error occurred. |
| `MTCH-0017` | Internal Server Error | Idempotency processing is temporarily unavailable; retry the same request later with the same idempotency key. If the failure continues, ask an administrator to check idempotency storage. |


# Mint aggregator consent token
Source: https://docs.lerian.studio/en/reference/products/matcher/mint-aggregator-consent-token

/en/openapi/v3-current/matcher.yaml post /v1/discovery/aggregator-connections/{id}/connect-token
Use this endpoint to get the consent token that the aggregator's own consent widget (Pluggy Connect or the Belvo widget) needs for this connection. The request has no body: Matcher reads the vendor from the stored connection. For a connection already bound to a vendor item or link, the token starts a re-consent. After the end customer completes the widget, bind the item or link id to the connection with an update that sets `accountRef`.



# Mint an aggregator webhook token
Source: https://docs.lerian.studio/en/reference/products/matcher/mint-aggregator-webhook-token

/en/openapi/v3-current/matcher.yaml post /v1/discovery/webhooks/tokens
Mints a webhook token bound to an existing aggregator connection and returns the raw token plus its provider-facing webhook URL ONCE. Only the token's SHA-256 hash is stored.



# Receive an aggregator webhook
Source: https://docs.lerian.studio/en/reference/products/matcher/receive-aggregator-webhook

/en/openapi/v3-current/matcher.yaml post /v1/discovery/webhooks/{provider}/{webhookToken}
Receives a Pluggy/Belvo aggregator webhook and asynchronously pulls the signaled data into the ingestion pipeline. This route carries no operator JWT. It is authenticated by an opaque token in the URL path (resolved to a tenant binding server-side, never claimed) PLUS a per-provider source check: a valid HMAC-SHA256 of the raw body in the X-Webhook-Signature header, OR membership in the provider's source-IP allowlist. Both layers fail closed; the tenant is derived solely from the resolved token binding.



# Refresh discovery
Source: https://docs.lerian.studio/en/reference/products/matcher/refresh-discovery

/en/openapi/v3-current/matcher.yaml post /v1/discovery/refresh
Use this endpoint to force an immediate sync with the extraction engine, updating the list of connections and their schemas.



# Reject an AI extraction review (discard the candidates)
Source: https://docs.lerian.studio/en/reference/products/matcher/reject-extraction-review

/en/openapi/v3-current/matcher.yaml post /v1/imports/contexts/{contextId}/extraction-reviews/{reviewId}/reject
Rejects a PENDING_REVIEW review and discards its candidates — nothing is ingested or reconciled. The rejecting principal is recorded for audit. Tenant from the JWT, context from the path.



# Reject an AI match-rule suggestion (discard it)
Source: https://docs.lerian.studio/en/reference/products/matcher/reject-match-rule-suggestion

/en/openapi/v3-current/matcher.yaml post /v1/matching/contexts/{contextId}/rule-suggestions/{suggestionId}/reject
Rejects a PENDING_REVIEW suggestion — nothing is created. The rejecting principal is recorded for audit. Tenant from the JWT, context from the path.



# Get a discovered connection
Source: https://docs.lerian.studio/en/reference/products/matcher/retrieve-discovery-connection

/en/openapi/v3-current/matcher.yaml get /v1/discovery/connections/{connectionId}
Use this endpoint to retrieve a single discovered connection by its internal identifier.



# Get an extraction request
Source: https://docs.lerian.studio/en/reference/products/matcher/retrieve-extraction

/en/openapi/v3-current/matcher.yaml get /v1/discovery/extractions/{extractionId}
Use this endpoint to retrieve the details of a specific extraction request by its identifier.



# Get match run
Source: https://docs.lerian.studio/en/reference/products/matcher/retrieve-match-run

/en/openapi/v3-current/matcher.yaml get /v1/matching/runs/{runId}
Use this endpoint to retrieve the details of a specific match run by its identifier. The response includes status, timing, and aggregate statistics.



# Trigger a matching run
Source: https://docs.lerian.studio/en/reference/products/matcher/run-match

/en/openapi/v3-current/matcher.yaml post /v1/matching/contexts/{contextId}/run
Use this endpoint to trigger a matching run for a reconciliation context. You can use DRY_RUN mode to test rules without committing results, or COMMIT mode to persist matches.



# Simulate a match rule against a context (read-only dry run)
Source: https://docs.lerian.studio/en/reference/products/matcher/simulate-match-rule

/en/openapi/v3-current/matcher.yaml post /v1/matching/simulate
Previews how a single rule — an existing configured rule (ruleId) OR an inline candidate rule (rule) — would match a context's unmatched transactions, WITHOUT committing anything. Returns the number of 1:1 groups the rule would form, a bounded sample of would-match pairs (each with a confidence score, a per-component rationale (the "why"), and matched composite keys), and the per-side unmatched counts. Powers the rule-authoring "will this rule actually match?" preview. Scope: scored by the deterministic rule engine over raw transaction amounts; it does NOT apply run-time fee normalization or the FX-variance band, and previews only 1:1 pairwise grouping (no 1:N/N:M allocation). Nothing is persisted; the tenant is taken from the JWT, never the body.



# Produce AI match-rule suggestions (human-review required)
Source: https://docs.lerian.studio/en/reference/products/matcher/suggest-match-rules

/en/openapi/v3-current/matcher.yaml post /v1/matching/contexts/{contextId}/rule-suggestions
Builds AGGREGATE, privacy-safe history features for the context, asks the AI advisor for config-only candidate rules, and enqueues each surviving candidate in a human-review queue. AI output is NEVER authoritative: producing a suggestion CREATES NO rule. A rule is created only when a human APPROVES a suggestion. Tenant from the JWT, context from the path. The egress payload is aggregates only — no raw transaction, money, or PII.



# Test aggregator connection credentials
Source: https://docs.lerian.studio/en/reference/products/matcher/test-aggregator-connection

/en/openapi/v3-current/matcher.yaml post /v1/discovery/aggregator-connections/test
Runs a live connectivity check for an existing Open-Finance data-aggregator (Pluggy/Belvo) connection using its already-sealed credential, addressed by configName. The vendor is read from the stored connection, not from the request. No credential is supplied or returned: the result is the secret-free boolean health of the connection. A config name that matches no connection returns `404`; a connection whose vendor has no test path (Belvo) returns `422` (`MTCH-0210`), and no test runs.



# Test a connection
Source: https://docs.lerian.studio/en/reference/products/matcher/test-discovery-connection

/en/openapi/v3-current/matcher.yaml post /v1/discovery/connections/{connectionId}/test
Use this endpoint to test connectivity for a specific discovered connection owned by the current tenant.



# Break/Unmatch a match group
Source: https://docs.lerian.studio/en/reference/products/matcher/unmatch-group

/en/openapi/v3-current/matcher.yaml delete /v1/matching/groups/{matchGroupId}
Use this endpoint to break an incorrect match group. Send the reason in the request. The transactions of the group return to UNMATCHED status.



# Update aggregator connection
Source: https://docs.lerian.studio/en/reference/products/matcher/update-aggregator-connection

/en/openapi/v3-current/matcher.yaml put /v1/discovery/aggregator-connections/{id}
Edits an existing Open-Finance data-aggregator (Pluggy/Belvo) connection by id so a mistyped baseUrl is not permanent. The vendor is immutable. clientId/secret are optional: supply both to rotate the sealed credential, or omit both to leave the stored secret intact. The supplied credential is sealed before persistence and is never returned. A non-aggregator connection id returns 404.



# Update discovery connection
Source: https://docs.lerian.studio/en/reference/products/matcher/update-discovery-connection

/en/openapi/v3-current/matcher.yaml patch /v1/discovery/connections/{connectionId}
Updates a Matcher-owned connection and synchronizes the local discovery cache.



# Create a Provider Configuration
Source: https://docs.lerian.studio/en/reference/products/flowker/create-provider-configuration

/en/openapi/v3-current/flowker.yaml post /v1/provider-configurations
Use this endpoint to create a new provider configuration. The configuration is validated against the provider's JSON Schema.



# Delete an Executor Configuration
Source: https://docs.lerian.studio/en/reference/products/flowker/delete-executor-configuration

/en/openapi/v3-current/flowker.yaml delete /v1/executors/{id}
Use this endpoint to delete an executor configuration. Only configurations with `unconfigured`, `configured`, or `disabled` status can be deleted.



# Delete an External OpenAPI Schema
Source: https://docs.lerian.studio/en/reference/products/flowker/delete-openapi-schema

/en/openapi/v3-current/flowker.yaml delete /v1/openapi-schemas/{id}
Use this endpoint to delete an external OpenAPI schema. An active provider configuration or an active workflow that references the schema blocks the delete with 409. References from inactive workflows or disabled provider configurations do not block: the delete proceeds and the response carries the warnings. A schema with no references at all returns 204.



# Delete a Provider Configuration
Source: https://docs.lerian.studio/en/reference/products/flowker/delete-provider-configuration

/en/openapi/v3-current/flowker.yaml delete /v1/provider-configurations/{id}
Use this endpoint to delete a provider configuration.



# Delete an XSD Schema
Source: https://docs.lerian.studio/en/reference/products/flowker/delete-xsd-schema

/en/openapi/v3-current/flowker.yaml delete /v1/xsd-schemas/{id}
Use this endpoint to delete an XSD schema. An active provider configuration or an active workflow that references the schema blocks the delete with 409. References from inactive workflows or disabled provider configurations do not block: the delete proceeds and the response carries the warnings. A schema with no references at all returns 204.



# Derive an Operation Schema
Source: https://docs.lerian.studio/en/reference/products/flowker/derive-openapi-operation-schema

/en/openapi/v3-current/flowker.yaml get /v1/openapi-schemas/{id}/operation-schema
Use this endpoint to derive the input and output contract of a single operation in an external OpenAPI schema. The response carries the dereferenced request-body and 2xx response schemas, the input parameters merged by location, and the body descriptor. Identify the operation with the `path` query parameter, which is the URL-encoded OpenAPI path template, and the `method` query parameter, which is case-insensitive.



# Disable a Provider Configuration
Source: https://docs.lerian.studio/en/reference/products/flowker/disable-provider-configuration

/en/openapi/v3-current/flowker.yaml post /v1/provider-configurations/{id}/disable
Use this endpoint to disable a provider configuration. Transitions the status from `active` to `disabled`.



# Enable a Provider Configuration
Source: https://docs.lerian.studio/en/reference/products/flowker/enable-provider-configuration

/en/openapi/v3-current/flowker.yaml post /v1/provider-configurations/{id}/enable
Use this endpoint to enable a provider configuration. Transitions the status from `disabled` to `active`.



# Flowker error list
Source: https://docs.lerian.studio/en/reference/products/flowker/flowker-error-list

Flowker APIs return RFC 9457 problem documents with a stable error code, so you can diagnose issues and route them to the right team.

### Error format

The `/v1` management API returns errors as an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem document, served with the `application/problem+json` content type. Webhook routes answer in their trigger's configured format. See [Errors on webhook routes](#errors-on-webhook-routes).

```json theme={null}
{
  "type": "https://errors.lerian.studio/v1/FLK-0110",
  "title": "Bad Request",
  "status": 400,
  "detail": "name is a required field",
  "instance": "/v1/workflows",
  "code": "FLK-0110"
}
```

### Field definitions

* **`code`** – The stable Flowker error code. Branch your integration on this field.
* **`type`** – A URI that identifies the error. It is always `https://errors.lerian.studio/v1/` plus the `code`.
* **`title`** – The standard HTTP reason phrase for `status`, such as `Not Found` or `Conflict`. It does not change per error code.
* **`status`** – The HTTP status code, repeated in the body.
* **`detail`** – A human-readable explanation of this occurrence. Responses with a status of 500 or above carry a fixed generic message instead, so use `code` to tell them apart.
* **`instance`** – A URI that identifies this specific occurrence, when the endpoint provides one.
* **`errors`** – An optional array of per-field entries. See [Field-level error details](#field-level-error-details).

### Field-level error details

When a request fails validation on specific fields, the problem document carries an `errors` array. Each entry names the offending input.

```json Example 1 theme={null}
{
  "type": "https://errors.lerian.studio/v1/FLK-0301",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "validation failed",
  "code": "FLK-0301",
  "errors": [
    {
      "location": "body.name",
      "message": "expected required property name to be present"
    }
  ]
}
```

```json Example 2 theme={null}
{
  "type": "https://errors.lerian.studio/v1/FLK-0001",
  "title": "Bad Request",
  "status": 400,
  "detail": "request body is invalid or malformed",
  "code": "FLK-0001",
  "errors": [
    {
      "location": "body.nodes",
      "message": "expected array length >= 1",
      "value": []
    }
  ]
}
```

Each entry carries a `location` (where the problem is, such as `body.nodes` or `path.id`), a `message`, and the offending `value` when it is safe to echo.

### Errors on webhook routes

A webhook route answers in its trigger's configured format.

A JSON webhook route returns a compact error object with the `application/json` content type:

```json theme={null}
{
  "code": "FLK-0361",
  "title": "Not Found",
  "message": "no webhook registered for this path and method"
}
```

* **`code`** – The stable Flowker error code, taken from the tables below. Branch your integration on this field.
* **`title`** – The HTTP reason phrase for the response status, such as `Not Found` or `Payload Too Large`.
* **`message`** – A human-readable explanation of this occurrence.

An XML webhook route returns an `<error>` document instead, because the whole route works in XML.

```xml theme={null}
<error>
  <code>XML_VALIDATION_FAILED</code>
  <message>element 'valor' is not a valid decimal</message>
  <details>line 12, column 5</details>
  <requestId>018f3e2a-1c4d-7b9e-a1b2-c3d4e5f6a7b8</requestId>
</error>
```

The `code` element carries either a Flowker code from the tables below or one of two XML-specific codes:

| Code | What it means |
| - | - |
| `XML_MALFORMED` | The request body is not well-formed XML. Returned with HTTP 400. |
| `XML_VALIDATION_FAILED` | The body is well-formed XML but does not conform to the route's XSD. Returned with HTTP 422, and `details` carries the line and column of the first finding. |

## General errors

***

These errors apply to all Flowker API endpoints.

| Code | What it means |
| - | - |
| FLK-0001 | The request body is invalid or malformed. Verify the JSON format and try again. |
| FLK-0002 | The provided ID is not a valid UUID. Verify the ID and try again. |
| FLK-0003 | Authentication is required to access this resource. Send a valid bearer token. |
| FLK-0004 | You do not have permission to perform this action. Check the permissions granted to your token. |
| FLK-0005 | Flowker could not get an authorization decision from the Access Manager. Try again later. |
| FLK-9999 | An unexpected error occurred. Try again later, or contact support if the issue persists. |

## Request validation errors

***

The API returns these errors when the request does not meet validation requirements.

| Code | What it means |
| - | - |
| FLK-0300 | The request contains unexpected fields. Remove the extra fields and try again. |
| FLK-0301 | One or more required fields are missing. Provide all required fields and try again. |
| FLK-0302 | The request is invalid. Verify the request format and try again. |
| FLK-0303 | A field used in a calculation has an invalid type. Verify the field types and try again. |
| FLK-0304 | One or more query parameters are invalid. Verify the parameters and try again. |
| FLK-0305 | The date must be in RFC 3339 format with a timezone, such as `2026-01-28T10:30:00Z`. Date-only values are rejected. |
| FLK-0306 | The end date must be after the start date. Provide a valid date range. |
| FLK-0307 | The requested date range exceeds the maximum allowed period. Reduce the date range. |
| FLK-0308 | The date range is invalid. Verify the start and end dates. |
| FLK-0309 | The `limit` parameter exceeds the maximum allowed value. Reduce the limit and try again. |
| FLK-0310 | Sort order must be `ASC` or `DESC`. Provide a valid value. |
| FLK-0311 | The provided path parameter is invalid. Verify the parameter value and try again. |
| FLK-0312 | The metadata key exceeds the maximum allowed length of 64 characters. Reduce the key size. |
| FLK-0313 | The metadata value exceeds the maximum allowed length. Reduce the value size. |
| FLK-0314 | Metadata values cannot be nested objects. Provide flat key-value pairs. |
| FLK-0315 | The metadata exceeds the maximum number of entries. Reduce the number of metadata entries. |
| FLK-0321 | The pagination cursor is malformed or could not be decoded. Request the first page again and follow the cursor returned by the API. |

## Entity errors

***

| Code | What it means |
| - | - |
| FLK-0400 | The requested entity does not exist. Verify the ID and try again. |
| FLK-0401 | This action is not permitted in the current state. Check the resource status and try again. |
| FLK-0402 | The referenced parent entity does not exist. Verify the parent ID and try again. |

## Workflow errors

***

| Code | What it means |
| - | - |
| FLK-0100 | The requested workflow does not exist. Verify the workflow ID and try again. |
| FLK-0101 | A workflow with this name already exists. Choose a different name and try again. |
| FLK-0102 | The requested status transition is not allowed. Check the current workflow status and the valid transitions. |
| FLK-0103 | Non-draft workflows cannot be modified. Create a new version, or revert the workflow to draft. |
| FLK-0104 | A node references a catalog executor that does not exist. Verify the `executorId` on the node. |
| FLK-0110 | The `name` field is required. Provide a name for the workflow and try again. |
| FLK-0111 | The workflow name exceeds the maximum allowed length. Reduce the name size. |
| FLK-0112 | A workflow must have at least one node. Add nodes to the workflow and try again. |
| FLK-0113 | The workflow exceeds the maximum number of nodes allowed. Reduce the node count. |
| FLK-0114 | The workflow exceeds the maximum number of edges allowed. Reduce the edge count. |
| FLK-0115 | An edge references a node that does not exist in the workflow. Verify all edge source and target values. |
| FLK-0116 | The workflow must have at least one trigger node. Add a trigger and try again. |
| FLK-0117 | The schedule trigger carries an invalid cron expression. Use a standard 5-field cron. Sub-minute schedules are not supported. |
| FLK-0118 | The workflow has no schedule trigger, so it has no upcoming occurrences to list or manage. |
| FLK-0119 | The schedule trigger carries a timezone that is not a valid IANA name. Use a name such as `America/Sao_Paulo`, or omit the field to use UTC. |
| FLK-0120 | Each node must have an ID. Provide an ID for all nodes. |
| FLK-0121 | Each node must have a type. Provide a type for all nodes. |
| FLK-0122 | An action node's `set_output` `responseStatusCode` override must be an integer between 200 and 599. Correct the value and try again. |
| FLK-0130 | Each edge must have an ID. Provide an ID for all edges. |
| FLK-0131 | Each edge must specify a source node. Provide the source node ID. |
| FLK-0132 | Each edge must specify a target node. Provide the target node ID. |
| FLK-0140 | The input mapping configuration is invalid. Verify the mapping syntax and field references. |
| FLK-0141 | The output mapping configuration is invalid. Verify the mapping syntax and field references. |
| FLK-0142 | The transformation configuration is invalid. Verify the transform expressions. |
| FLK-0143 | A node's `data.body` template could not be resolved against the workflow context, because a `${...}` reference is malformed or does not resolve. The node fails without calling the external service. |
| FLK-0150 | The node's `providerConfigId` is missing, is not a valid UUID, or names a provider configuration that does not exist or is not active. Verify the `providerConfigId` on every executor node, and the existence and status of the configuration it names. |
| FLK-0151 | A node pairs a provider configuration of one provider with an executor of another. Verify that the `providerId` on the configuration and the `executorId` on the node name the same catalog provider. |

## Workflow condition errors

***

The API returns these errors when a node's structured `condition` object fails validation during workflow creation or update.

| Code | What it means |
| - | - |
| FLK-0160 | The condition's `version` field is missing or is not `2`. |
| FLK-0161 | The condition object is structurally malformed, such as a `cases` value that is not an array. |
| FLK-0162 | The condition has no cases. Add at least one case. |
| FLK-0163 | Two cases, or a case and the default branch, share the same output handle ID. Give each branch a unique handle. |
| FLK-0164 | A case has an empty output handle ID. Provide a handle for every case. |
| FLK-0165 | The condition `mode` must be `rules` or `value`. |
| FLK-0166 | A `value` mode condition needs a subject operand. Provide the subject. |
| FLK-0167 | A group's `combinator` must be `and` or `or`. |
| FLK-0168 | A group carries neither rules nor nested groups. Add at least one rule, or remove the group. |
| FLK-0169 | The rule operator is not recognized. Use an operator from the supported taxonomy. |
| FLK-0170 | The rule `valueType` is not recognized. Use a value type from the supported taxonomy. |
| FLK-0171 | The operator is not allowed for the selected `valueType`. Change the operator or the value type. |
| FLK-0172 | An operand has an empty `source` path. Provide the path to read. |
| FLK-0173 | A transform has an invalid operation, or invalid parameters for its operation. |
| FLK-0174 | A right operand's `kind` must be `literal` or `source`, and a `source` right operand needs a source path. |
| FLK-0175 | The default branch has an empty output handle ID. Provide a handle. |
| FLK-0176 | The condition exceeds the maximum number of cases. Reduce the number of cases. |
| FLK-0177 | A group exceeds the maximum number of rules. Split the rules across nested groups. |
| FLK-0178 | An operand's transform pipeline exceeds the maximum number of transforms. Reduce the pipeline. |
| FLK-0179 | A `matchesRegex` or `notMatchesRegex` rule carries a regular expression that exceeds the maximum length. |
| FLK-0180 | An `isIn` or `notIn` rule carries a list that exceeds the maximum number of items. |
| FLK-0181 | The condition is structurally valid but could not be compiled. Review the operands and literals on the reported node. |
| FLK-0182 | The condition tree is too large across all its cases. Reduce the number of groups and rules. |

## Catalog, executor, and trigger errors

***

| Code | What it means |
| - | - |
| FLK-0200 | The requested executor does not exist in the catalog. Verify the executor ID and try again. |
| FLK-0201 | A node's configuration does not match the catalog executor's JSON Schema. Verify it against that schema. |
| FLK-0210 | The requested trigger does not exist in the catalog. Verify the trigger ID and try again. |
| FLK-0211 | The trigger configuration is invalid. Verify the configuration format. |
| FLK-0220 | The requested runner does not exist. Verify the runner ID and try again. |
| FLK-0230 | The requested provider does not exist in the catalog. Verify the provider ID and try again. |
| FLK-0231 | A provider with this identifier already exists. Use the existing provider, or choose a different ID. |
| FLK-0232 | The provider configuration is invalid. Verify the configuration format. |
| FLK-0240 | The requested template does not exist in the catalog. Verify the template ID and try again. |
| FLK-0242 | One or more template parameters are invalid. Verify the parameters against the template schema. |

## Executor configuration errors

***

| Code | What it means |
| - | - |
| FLK-0250 | The requested executor configuration does not exist. Verify the ID and try again. |
| FLK-0251 | An executor configuration with this name already exists. Choose a different name and try again. |
| FLK-0252 | The executor configuration cannot be modified in its current status. Check the status and try again. |
| FLK-0260 | The `name` field is required. Provide a name for the executor configuration. |
| FLK-0261 | The executor configuration name exceeds the maximum allowed length. Reduce the name size. |
| FLK-0262 | The `baseUrl` field is required. Provide a base URL for the executor configuration. |
| FLK-0263 | The provided base URL is not a valid URL. Verify the URL format. |
| FLK-0264 | The base URL exceeds the maximum allowed length. Reduce the URL size. |
| FLK-0265 | At least one endpoint must be configured. Provide endpoint definitions. |
| FLK-0266 | Authentication configuration is required. Provide auth settings. |
| FLK-0267 | The description exceeds the maximum allowed length. Reduce the description size. |
| FLK-0268 | The auth type field is required. Provide an authentication type. |
| FLK-0269 | The auth type is not recognized. Provide a valid authentication type. |
| FLK-0270 | Each endpoint must have a name. Provide names for all endpoints. |
| FLK-0271 | Each endpoint must have a path. Provide paths for all endpoints. |
| FLK-0272 | Each endpoint must specify an HTTP method. Provide methods for all endpoints. |
| FLK-0273 | An endpoint's HTTP method is not recognized. Verify the method on every endpoint and try again. |
| FLK-0284 | The base URL resolves to an address Flowker refuses to call, such as a loopback or link-local host. Use a routable external host. |
| FLK-0285 | The base URL host is not permitted by the configuration's allowed-hosts list. Add the host to the list, or change the URL. |

## Provider configuration errors

***

| Code | What it means |
| - | - |
| FLK-0290 | The requested provider configuration does not exist. Verify the ID and try again. |
| FLK-0291 | A provider configuration with this name already exists. Choose a different name and try again. |
| FLK-0292 | The provider configuration cannot be modified in its current status. Check the status and try again. |
| FLK-0293 | The `config` object does not match the provider's required schema, or a `schemaBindings` entry is malformed. An entry is malformed when it has an unknown `type`, or a `schemaId` that is empty, is not a UUID, or is all zeros. It is also malformed when a binding that is not `openapi` carries `operations`, or an operation's path or HTTP method is missing or invalid. Verify the configuration fields and each schema binding. |
| FLK-0294 | The referenced provider does not exist in the catalog. Verify the provider ID. |
| FLK-0295 | The `name` field is required. Provide a name for the provider configuration. |
| FLK-0296 | The provider configuration name exceeds the maximum allowed length. Reduce the name size. |
| FLK-0297 | The `providerId` field is required for a `catalog` provider configuration. Provide a provider ID. |
| FLK-0298 | The `config` field is required. Provide the provider configuration object. |
| FLK-0299 | The description exceeds the maximum allowed length. Reduce the description size. |
| FLK-0316 | The provider configuration ID is required for this operation. Provide the ID. |
| FLK-0317 | An entry in the allowed-hosts list is not a valid host. Verify each entry. |
| FLK-0320 | A base URL in the configuration points at a host its own allowed-hosts list rejects. Align the URL and the list. |
| FLK-0323 | A configuration for the generic HTTP provider must declare an allowed-hosts list. An empty list would allow calls to any address, so it is rejected. |
| FLK-0952 | The update changed the auth type without supplying a credential the new type requires and the previous one did not. Send that value with the type change. |
| FLK-0953 | The request sent a masked credential placeholder. Omit the field to keep the stored credential, or send its actual value to replace it. |

## External OpenAPI provider configuration errors

***

These errors apply to provider configurations of kind `external_openapi`, which call an operation declared by a stored OpenAPI schema.

| Code | What it means |
| - | - |
| FLK-0946 | The configuration omits the required `config.openapi_schema_id` reference. Provide the schema ID. |
| FLK-0947 | The referenced OpenAPI schema does not exist in your tenant. Verify the schema ID. |
| FLK-0948 | The `config.auth` block is malformed. It has an unknown type, a missing required field, or the wrong shape. |
| FLK-0949 | Neither `config.base_url` nor a usable `servers` entry in the referenced schema resolves a base URL. The node fails without calling the service. |
| FLK-0950 | The bound operation is absent from the referenced schema, or the stored schema no longer parses. The node fails without calling the service. |
| FLK-0951 | The HMAC request-signing scheme could not resolve its secret. The request is never sent unsigned. |

## Provider schema binding errors

***

| Code | What it means |
| - | - |
| FLK-0942 | A schema binding references an XSD or OpenAPI schema ID that does not exist in your tenant. Verify the schema ID. |
| FLK-0943 | An OpenAPI schema binding restricts to an operation that the referenced document does not declare. Verify the path and method. |
| FLK-0944 | The configuration lists the same binding twice. Remove the duplicate. |
| FLK-0945 | The schema cannot be deleted because at least one active provider configuration binds it. The response lists the referring provider configurations and workflows. |

## Workflow execution errors

***

| Code | What it means |
| - | - |
| FLK-0500 | The requested execution does not exist. Verify the execution ID and try again. |
| FLK-0501 | The workflow is not in an active state and cannot be executed. Activate the workflow and try again. |
| FLK-0502 | A previous execution for this workflow is still in progress. Wait for it to complete. |
| FLK-0503 | The workflow execution timed out before completing. Check the workflow logic and the response times of external services. |
| FLK-0504 | A node within the workflow failed during execution. Check the execution details for the specific node error. |
| FLK-0505 | An execution with this idempotency key already exists. Use a new key for distinct executions. |
| FLK-0506 | The request body must not exceed 1 MB. Reduce the input payload size. |
| FLK-0507 | The circuit breaker for this provider configuration is open after repeated failures. Wait before retrying. |
| FLK-0508 | A cycle was detected in the workflow graph. Review the edges and remove the circular references. |
| FLK-0509 | The `Idempotency-Key` header is required for execution requests. Include a unique key in the header. |

## Outbound request errors

***

These errors occur while a node calls an external service. They surface as node failures in the execution details.

| Code | What it means |
| - | - |
| FLK-0322 | The provider's response body exceeds the configured size cap. Retrying does not help, because the response will not shrink. |
| FLK-0324 | The request body Flowker would send exceeds the configured size cap. The request is rejected before any network call. |
| FLK-0937 | An HTTP node declares `request_format` of type `xml_converted` without a valid `root_element`. Provide a syntactically valid XML element name. |
| FLK-0938 | An `xml_passthrough` node has no XML trigger payload to forward. Passthrough forwards the trigger's original bytes, so it needs an XML trigger. |
| FLK-0939 | An `xml_passthrough` node's retained trigger payload is not eligible for byte-exact forwarding, such as a payload that is not valid UTF-8. |
| FLK-0940 | An `xml_converted` node's mapped body is not a structured object. Converted XML needs an object to serialize under `root_element`. |
| FLK-0941 | The mapped body could not be encoded as XML. Review the structure the mappings produce. |
| FLK-0956 | A node that Flowker sends through its generic HTTP connector maps a value to a `path.*` parameter. The generic connector has no path placeholder, so the node fails before any network call. Put the value in the node path, the query, or the headers. |
| FLK-0958 | A node's `content_digest` is malformed or does not resolve to a non-blank digest. Provide a 64-character hexadecimal SHA-256 value. |
| FLK-0959 | The assembled request body does not match `content_digest`, or no body was assembled. Flowker rejects the request before any network call. |

## Concurrency errors

***

| Code | What it means |
| - | - |
| FLK-0350 | The resource state changed concurrently. Retry with the latest version. |

## Webhook errors

***

| Code | What it means |
| - | - |
| FLK-0360 | The webhook path is already registered by another active workflow. Choose a different path, or deactivate the conflicting workflow. |
| FLK-0361 | No webhook is registered for this path and method. Verify the webhook path and method, and try again. |
| FLK-0363 | The webhook request body must not exceed 1 MB. Reduce the payload size. |

## Webhook trigger contract errors

***

The API returns these errors when you save a webhook trigger's `input_contract` or activate the workflow. It also returns them during validation of an incoming payload against the contract.

| Code | What it means |
| - | - |
| FLK-0930 | The trigger's `input_contract` is `xsd`, but its `xsd_schema_id` does not resolve to a stored XSD schema. |
| FLK-0931 | The trigger's `input_contract` is `openapi`, but its `openapi_schema_id` does not resolve to a stored OpenAPI schema. |
| FLK-0932 | The referenced OpenAPI schema declares no operation matching the trigger's `operation_path` and `operation_method`. |
| FLK-0933 | The matched OpenAPI operation declares no JSON request body, so it cannot validate an incoming payload. |
| FLK-0934 | The webhook trigger's configuration does not match the trigger schema. The schema is closed, so the trigger fails when it omits `path` or `method`, misses a field its selected `input_contract` mode requires, names another mode's schema id or operation field, or carries a key or a value the schema does not accept. Check this error first when you configure a webhook trigger. |
| FLK-0935 | The incoming payload is well-formed JSON but does not conform to the operation's request-body schema. |
| FLK-0936 | The OpenAPI schema cannot be deleted because one or more active workflows reference it from a webhook trigger. References from draft or inactive workflows do not block the delete. |
| FLK-0957 | The trigger's optional `accepted_headers` declaration is invalid. Use a list of valid, non-blank, non-duplicate header names; credential-bearing names are refused. |

## External OpenAPI request and configuration errors

***

| Code | What it means |
| - | - |
| FLK-0954 | A required `header` or `query` parameter for an external OpenAPI operation found no value. The node fails before Flowker sends a request. |
| FLK-0955 | An `external_openapi` provider configuration has a malformed `config.headers` block. Use valid, non-blank, case-insensitively unique header names with string values. |

## XSD schema errors

***

| Code | What it means |
| - | - |
| FLK-0700 | The requested XSD schema does not exist. Verify the schema ID and try again. |
| FLK-0701 | An XSD schema with this name and version already exists. Choose a different name or version. |
| FLK-0702 | The uploaded content failed XSD validation. Verify the schema document. |
| FLK-0703 | The XSD schema file exceeds the 1 MiB limit. Reduce the file size. |
| FLK-0704 | The XSD schema cannot be deleted because one or more workflow nodes reference it. |
| FLK-0710 | The `name` field is required. Provide a name for the XSD schema. |
| FLK-0711 | The `version` field is required. Provide a version for the XSD schema. |
| FLK-0712 | The schema content is required. Upload the XSD document. |
| FLK-0713 | The stored content of the XSD schema does not match its recorded hash. Contact support. |
| FLK-0720 | The XML validation service is unreachable or returned a fault, so the payload could not be validated. Flowker rejects the request rather than accepting unvalidated XML. |

## External OpenAPI schema errors

***

These errors apply to the OpenAPI schemas you store per tenant and reference from triggers, provider configurations, and nodes.

| Code | What it means |
| - | - |
| FLK-0807 | The `name` field is required. Provide a name for the OpenAPI schema. |
| FLK-0808 | The `version` field is required. Provide a version for the OpenAPI schema. |
| FLK-0809 | The OpenAPI schema name exceeds the maximum allowed length. Reduce the name size. |
| FLK-0810 | The OpenAPI schema version exceeds the maximum allowed length. Reduce the version size. |
| FLK-0811 | The requested OpenAPI schema does not exist. Verify the schema ID and try again. |
| FLK-0812 | An OpenAPI schema with this name and version already exists. Choose a different name or version. |
| FLK-0813 | The schema content is required. Upload the OpenAPI document. |
| FLK-0900 | The uploaded bytes do not parse as a valid OpenAPI 3.x document, or the document declares no operation. |
| FLK-0901 | The uploaded OpenAPI schema exceeds the 8 MiB limit. Reduce the file size. |
| FLK-0902 | The stored schema declares no operation matching the requested path and method. Verify the path and method. |

## OpenAPI spec registry errors

***

These errors apply to the shared OpenAPI spec registry, which pins the spec version Flowker uses to enrich a service's output schemas.

| Code | What it means |
| - | - |
| FLK-0801 | The version-pin request is missing the service or the version. Provide both. |
| FLK-0802 | The uploaded bytes do not parse as a valid OpenAPI 3.x document. Verify the spec. |
| FLK-0803 | A spec is already stored for this service and version. Versions are immutable, so upload a new version. |
| FLK-0804 | The schema registry has no storage configured, so the upload cannot be accepted. |
| FLK-0805 | The uploaded spec exceeds the registry size cap. Reduce the file size. |
| FLK-0806 | The service or version path identifier is malformed. Remove empty values, slashes, `..`, control characters, and leading dots. |

## Scheduled occurrence errors

***

| Code | What it means |
| - | - |
| FLK-0755 | The occurrence is not in a state that can be run or discarded. Check its current state. |
| FLK-0760 | The requested scheduled occurrence does not exist. Verify the occurrence ID and try again. |
| FLK-0762 | A run of this occurrence is already in progress, so Flowker did not queue another run. |
| FLK-0763 | The scheduler is disabled, or its queue or database was not reachable when Flowker started. Flowker did not queue a run. |


# Get an External OpenAPI Schema
Source: https://docs.lerian.studio/en/reference/products/flowker/get-openapi-schema

/en/openapi/v3-current/flowker.yaml get /v1/openapi-schemas/{id}
Use this endpoint to retrieve an external OpenAPI schema by its ID, including the raw specification content and a summary of each operation it declares.



# Get a Provider Configuration
Source: https://docs.lerian.studio/en/reference/products/flowker/get-provider-configuration

/en/openapi/v3-current/flowker.yaml get /v1/provider-configurations/{id}
Use this endpoint to retrieve a specific provider configuration by its unique identifier. The response never returns the credential that the authentication type declares (its API key, bearer token, password, client secret, or signing secret). Flowker masks any other value, including a free-form authentication parameter, only when it recognizes the field name as sensitive. Store credential material only in the fields that the authentication type declares.



# Get an XSD Schema
Source: https://docs.lerian.studio/en/reference/products/flowker/get-xsd-schema

/en/openapi/v3-current/flowker.yaml get /v1/xsd-schemas/{id}
Use this endpoint to retrieve an XSD schema by its ID, including its full content.



# List External OpenAPI Schema References
Source: https://docs.lerian.studio/en/reference/products/flowker/list-openapi-schema-references

/en/openapi/v3-current/flowker.yaml get /v1/openapi-schemas/{id}/references
Use this endpoint to list the provider configurations and workflows that reference an external OpenAPI schema. Both groups are always present in the response, and every entry is status-tagged: an active reference blocks a delete, a disabled one only warns.



# List External OpenAPI Schemas
Source: https://docs.lerian.studio/en/reference/products/flowker/list-openapi-schemas

/en/openapi/v3-current/flowker.yaml get /v1/openapi-schemas
Use this endpoint to retrieve a paginated list of the tenant's external OpenAPI schemas. The response carries metadata only, without the specification content.



# List OpenAPI Spec Versions
Source: https://docs.lerian.studio/en/reference/products/flowker/list-openapi-spec-versions

/en/openapi/v3-current/flowker.yaml get /v1/catalog/openapi-versions/{service}
Use this endpoint to list the published OpenAPI specification versions available for a native service. The response marks the version the current tenant has pinned.



# List Provider Configurations
Source: https://docs.lerian.studio/en/reference/products/flowker/list-provider-configurations

/en/openapi/v3-current/flowker.yaml get /v1/provider-configurations
Use this endpoint to retrieve a paginated list of provider configurations. You can filter results by status or provider ID.



# List XSD Schema References
Source: https://docs.lerian.studio/en/reference/products/flowker/list-xsd-schema-references

/en/openapi/v3-current/flowker.yaml get /v1/xsd-schemas/{id}/references
Use this endpoint to list the provider configurations and workflows that reference an XSD schema. Both groups are always present in the response, and every entry is status-tagged: an active reference blocks a delete, a disabled one only warns.



# List XSD Schemas
Source: https://docs.lerian.studio/en/reference/products/flowker/list-xsd-schemas

/en/openapi/v3-current/flowker.yaml get /v1/xsd-schemas
Use this endpoint to retrieve a paginated list of the tenant's XSD schemas. The response carries metadata only, without the schema content.



# Pin an OpenAPI Spec Version
Source: https://docs.lerian.studio/en/reference/products/flowker/pin-openapi-spec-version

/en/openapi/v3-current/flowker.yaml put /v1/catalog/openapi-version-pins/{service}
Use this endpoint to select which published OpenAPI specification version the current tenant resolves against for a native service. The operation is idempotent: pinning again updates the version in place.



# Trigger a Webhook
Source: https://docs.lerian.studio/en/reference/products/flowker/trigger-webhook

/en/openapi/v3-current/flowker.yaml post /v1/webhooks/{path}
Receives a webhook callback and triggers the associated workflow execution. The path is dynamically resolved against the webhook registry — each workflow can register its own webhook path. At runtime, GET, PUT, DELETE, and PATCH methods are also accepted, as well as nested paths with multiple segments. A `sync` route can return a status other than `200`. The `passthrough` response view can relay the provider's status and body, and a `set_output` node's `responseStatusCode` can set the status.



# Trigger a Webhook (DELETE)
Source: https://docs.lerian.studio/en/reference/products/flowker/trigger-webhook-delete

/en/openapi/v3-current/flowker.yaml delete /v1/webhooks/{path}
Receives a webhook callback via HTTP DELETE and triggers the associated workflow execution. The path is dynamically resolved against the webhook registry — each workflow can register its own webhook path. The runtime accepts GET, POST, PUT, PATCH, and DELETE on this route, as well as nested paths with multiple segments. A `sync` route can return a status other than `200`. The `passthrough` response view can relay the provider's status and body, and a `set_output` node's `responseStatusCode` can set the status.



# Trigger a Webhook from Streaming Hub
Source: https://docs.lerian.studio/en/reference/products/flowker/trigger-webhook-from-streaming-hub

/en/openapi/v3-current/flowker.yaml post /v1/hub/webhooks/{path}
Use this endpoint as the `endpoint` of a Streaming Hub webhook subscription. It triggers the same workflow execution as `POST /v1/webhooks/{path}`. Only the authentication is different: this route takes no Bearer token. Flowker verifies an HMAC-v1 signature over the raw request body with the tenant's inbound signing secret, which the deployment keeps in its secrets backend. The signing secret of the subscription and the stored secret must be the same value. Flowker refuses a legacy `sha256=` (v0) signature, because v0 has no replay protection. Flowker serves this route only when the deployment turns on the signed Streaming Hub ingress. It is off by default. A `sync` route can return a status other than `200`. The `passthrough` response view can relay the provider's status and body, and a `set_output` node's `responseStatusCode` can set the status.



# Trigger a Webhook (GET)
Source: https://docs.lerian.studio/en/reference/products/flowker/trigger-webhook-get

/en/openapi/v3-current/flowker.yaml get /v1/webhooks/{path}
Receives a webhook callback via HTTP GET and triggers the associated workflow execution. The path is dynamically resolved against the webhook registry — each workflow can register its own webhook path. The runtime accepts GET, POST, PUT, PATCH, and DELETE on this route, as well as nested paths with multiple segments. A `sync` route can return a status other than `200`. The `passthrough` response view can relay the provider's status and body, and a `set_output` node's `responseStatusCode` can set the status.



# Trigger a Webhook (PATCH)
Source: https://docs.lerian.studio/en/reference/products/flowker/trigger-webhook-patch

/en/openapi/v3-current/flowker.yaml patch /v1/webhooks/{path}
Receives a webhook callback via HTTP PATCH and triggers the associated workflow execution. The path is dynamically resolved against the webhook registry — each workflow can register its own webhook path. The runtime accepts GET, POST, PUT, PATCH, and DELETE on this route, as well as nested paths with multiple segments. A `sync` route can return a status other than `200`. The `passthrough` response view can relay the provider's status and body, and a `set_output` node's `responseStatusCode` can set the status.



# Trigger a Webhook (PUT)
Source: https://docs.lerian.studio/en/reference/products/flowker/trigger-webhook-put

/en/openapi/v3-current/flowker.yaml put /v1/webhooks/{path}
Receives a webhook callback via HTTP PUT and triggers the associated workflow execution. The path is dynamically resolved against the webhook registry — each workflow can register its own webhook path. The runtime accepts GET, POST, PUT, PATCH, and DELETE on this route, as well as nested paths with multiple segments. A `sync` route can return a status other than `200`. The `passthrough` response view can relay the provider's status and body, and a `set_output` node's `responseStatusCode` can set the status.



# Update an Executor Configuration
Source: https://docs.lerian.studio/en/reference/products/flowker/update-executor-configuration

/en/openapi/v3-current/flowker.yaml patch /v1/executors/{id}
Use this endpoint to update an existing executor configuration. Only configurations with `unconfigured` or `configured` status can be updated.



# Update a Provider Configuration
Source: https://docs.lerian.studio/en/reference/products/flowker/update-provider-configuration

/en/openapi/v3-current/flowker.yaml patch /v1/provider-configurations/{id}
Use this endpoint to update an existing provider configuration. If the configuration payload changes, it is re-validated against the provider's JSON Schema.



# Upload an External OpenAPI Schema
Source: https://docs.lerian.studio/en/reference/products/flowker/upload-openapi-schema

/en/openapi/v3-current/flowker.yaml post /v1/openapi-schemas
Use this endpoint to upload an external OpenAPI 3.x schema as multipart/form-data. The file must not exceed 8 MiB.



# Upload an OpenAPI Spec Version
Source: https://docs.lerian.studio/en/reference/products/flowker/upload-openapi-spec-version

/en/openapi/v3-current/flowker.yaml post /v1/catalog/openapi-specs/{service}/{version}
Use this endpoint to publish a global OpenAPI 3.x specification version for a native service. Every tenant resolves against the published versions. Versions are immutable: uploading a version that already exists returns 409. Send the specification as multipart/form-data; the file must not exceed 8 MiB. The caller needs the create permission on the catalog resource.



# Upload an XSD Schema
Source: https://docs.lerian.studio/en/reference/products/flowker/upload-xsd-schema

/en/openapi/v3-current/flowker.yaml post /v1/xsd-schemas
Use this endpoint to upload an XSD schema file as multipart/form-data. The file must not exceed 1 MiB.



# Activate loan product
Source: https://docs.lerian.studio/en/reference/products/lender/activate-loan-product

/en/openapi/v3-current/lender.yaml post /api/v1/loan-products/{id}/activate
Transitions a loan product to active status and pins the active product version.



# Activate loan product (BR alias)
Source: https://docs.lerian.studio/en/reference/products/lender/activate-loan-product-br

/en/openapi/v3-current/lender.yaml post /api/v1/br/loan-products/{id}/activate
BR-aliased path for activating a loan product. Resolves to the same handler as the core endpoint.



# Append floating-rate period
Source: https://docs.lerian.studio/en/reference/products/lender/append-floating-rate-period

/en/openapi/v3-current/lender.yaml post /api/v1/rate-tables/{id}/periods
Adds the next period to a curve and closes the open one at the instant before this one opens. A curve is append-only in time: the effective date must be strictly after every period already on it, nothing is ever edited, and nothing is ever deleted.



# Apply loan account PDD stage transition
Source: https://docs.lerian.studio/en/reference/products/lender/apply-loan-account-pdd-stage-transition

/en/openapi/v3-current/lender.yaml post /api/v1/br/loan-accounts/{id}/pdd-stage/transitions
Records a PDD transition or cure and updates prospective accrual eligibility.



# Appoint the tenant's extraordinary-collection agent
Source: https://docs.lerian.studio/en/reference/products/lender/appoint-the-tenant-s-extraordinary-collection-agent

/en/openapi/v3-current/lender.yaml put /api/v1/internal/br/consignado/collection-agent-channel
Points this tenant at the collection agent it instructs, or switches the channel off. It is the act every other behaviour of the channel depends on: with no active agent, borrower collections stay PARKED in `requested` and are only counted. The agent name and account are stamped verbatim on every instruction and the Arquivo de Baixa Extraordinária quotes them back byte-exactly, so the shapes are refused here by name rather than by a database constraint. Re-appointing the same agent is inert; `active: false` parks issuance again WITHOUT deleting the identity an already issued instruction names. Because the identity travels in the SAME call as the on/off switch, a CHANGED name or account is refused with 409 while the current agent still has open instructions: it would abandon them, since the work queue matches the active channel byte-exactly against what each instrument was stamped with. Turn those instructions over first, then the switch goes through. Idempotent via the X-Idempotency header enforced by the platform middleware.



# Approve loan application
Source: https://docs.lerian.studio/en/reference/products/lender/approve-loan-application

/en/openapi/v3-current/lender.yaml post /api/v1/loan-applications/{id}/approve
Transitions a pending-approval loan application to approved.



# Assign consignado contract divergence
Source: https://docs.lerian.studio/en/reference/products/lender/assign-consignado-contract-divergence

/en/openapi/v3-current/lender.yaml post /api/v1/internal/br/consignado/divergences/{id}/assign
Claims an open item for an operator. Compare-and-swap guarded by expectedVersion; idempotent via the X-Idempotency header enforced by the platform middleware.



# Attach evidence to a consignado compensating adjustment
Source: https://docs.lerian.studio/en/reference/products/lender/attach-consignado-compensating-adjustment-evidence

/en/openapi/v3-current/lender.yaml post /api/v1/internal/br/consignado/compensating-adjustments/{id}/evidence
Streams one operator-supplied evidence file (PDF, JPEG or PNG, up to 20 MiB) to the Lender's own object storage and persists its metadata. Without a configured object store, this fails closed. Idempotent via the X-Idempotency header enforced by the platform middleware; re-uploading the SAME bytes for the same operation is inert.



# Create a consignado compensating adjustment
Source: https://docs.lerian.studio/en/reference/products/lender/create-consignado-compensating-adjustment

/en/openapi/v3-current/lender.yaml post /api/v1/internal/br/consignado/compensating-adjustments
Commits a new compensating adjustment operation, its opening history entry and — when the currency has a configured suspense account — the durable posting-intent outbox event, atomically. A 202 response means accepted durably, never posted: the ledger relay posts it separately. Idempotent via the X-Idempotency header enforced by the platform middleware.



# Create document template draft
Source: https://docs.lerian.studio/en/reference/products/lender/create-document-template-draft

/en/openapi/v3-current/lender.yaml post /api/v1/loan-products/{productId}/document-templates
Creates a new DRAFT credit-instrument document template version for a loan product.



# Create floating-rate table
Source: https://docs.lerian.studio/en/reference/products/lender/create-floating-rate-table

/en/openapi/v3-current/lender.yaml post /api/v1/rate-tables
Registers a floating-rate curve by name. The curve starts empty; periods are appended to it.



# Create loan application
Source: https://docs.lerian.studio/en/reference/products/lender/create-loan-application

/en/openapi/v3-current/lender.yaml post /api/v1/loan-applications
Creates a pending approval loan application from an already-previewed schedule snapshot.



# Create loan product
Source: https://docs.lerian.studio/en/reference/products/lender/create-loan-product

/en/openapi/v3-current/lender.yaml post /api/v1/loan-products
Creates a new loan product definition.



# Create loan product accounting profile
Source: https://docs.lerian.studio/en/reference/products/lender/create-loan-product-accounting-profile

/en/openapi/v3-current/lender.yaml post /api/v1/loan-products/{id}/accounting-profiles
Configures the accounting profile for a loan product version that belongs to the path loan product.



# Create loan product (BR alias)
Source: https://docs.lerian.studio/en/reference/products/lender/create-loan-product-br

/en/openapi/v3-current/lender.yaml post /api/v1/br/loan-products
BR-aliased path for creating a loan product. Resolves to the same handler as the core endpoint.



# Apply inherited loan product charge
Source: https://docs.lerian.studio/en/reference/products/lender/create-loan-product-charges

/en/openapi/v3-current/lender.yaml post /api/v1/loan-products/{id}/charges
Applies one product-version charge template to a loan account and persists an immutable charge fact.



# Create loan product version
Source: https://docs.lerian.studio/en/reference/products/lender/create-loan-product-version

/en/openapi/v3-current/lender.yaml post /api/v1/loan-products/{id}/versions
Creates a new version snapshot of a loan product with updated regulatory parameters.



# Create loan product version (BR alias)
Source: https://docs.lerian.studio/en/reference/products/lender/create-loan-product-version-br

/en/openapi/v3-current/lender.yaml post /api/v1/br/loan-products/{id}/versions
BR-aliased path for creating a loan product version. Resolves to the same handler as the core endpoint.



# Declare a qualitative problem-asset assessment
Source: https://docs.lerian.studio/en/reference/products/lender/declare-a-qualitative-problem-asset-assessment

/en/openapi/v3-current/lender.yaml post /api/v1/br/loan-accounts/{id}/problem-asset-assessments
Records an operator's declaration that a contract is, or is not, a problem asset for a qualitative reason under Res. CMN 4.966 art. 3 paragraphs 1 and 2 — the situations that characterise an asset as problematic with no arrears at all. The declaration carries a MANDATORY evidence reference and is immutable: a prior characterisation is withdrawn by declaring the same trigger again with characterizesProblemAsset false and its own evidence, never by deleting. The nightly stage sweep reads the live declarations.



# Declare charge model revision
Source: https://docs.lerian.studio/en/reference/products/lender/declare-charge-model-revision

/en/openapi/v3-current/lender.yaml post /api/v1/loan-product-versions/{id}/charge-templates
Declares one effective-dated revision of a charge model on a product version. Attaching a model to a version that already carries live contracts is allowed and is the point of the table being dated: the revision takes effect from its own date forward and never rewrites a charge already assessed.



# Declare the BR norm classification of a loan product version
Source: https://docs.lerian.studio/en/reference/products/lender/declare-the-br-norm-classification-of-a-loan-product-version

/en/openapi/v3-current/lender.yaml put /api/v1/br/loan-product-versions/{id}/norm-classification
Records the carteira (Res. BCB 352/2023 art. 81) the credit booked under this product version belongs to, and optionally the modality the norm keys a rate on beyond it. Works on a version that is already active: the contracts booked on it were always in that carteira under the norm, the system simply could not name it, and until it is declared the provision engine counts and names every contract it cannot price rather than measuring it at zero. There is no automatic backfill, because guessing a carteira is guessing how much capital the institution must hold. A version may be declared ONCE: a second call is refused with 409 naming the carteira on the record, because replacing one reprices every contract ever booked under the version and posts the difference against results in a single movement. Changing a carteira means creating a new product version.



# Disburse loan application
Source: https://docs.lerian.studio/en/reference/products/lender/disburse-loan-application

/en/openapi/v3-current/lender.yaml post /api/v1/loan-applications/{id}/disburse
Validates disbursement eligibility, dispatches the resolving jurisdictional disbursement pipeline inside the parent transaction, and moves an approved application to disbursed. Idempotent: the lib-commons middleware enforces replay detection via X-Idempotency.



# Dispose consignado contract divergence
Source: https://docs.lerian.studio/en/reference/products/lender/dispose-consignado-contract-divergence

/en/openapi/v3-current/lender.yaml post /api/v1/internal/br/consignado/divergences/{id}/dispose
Records the operator's structured result and closes the item. Compare-and-swap guarded by expectedVersion; idempotent via the X-Idempotency header enforced by the platform middleware.



# Download credit instrument
Source: https://docs.lerian.studio/en/reference/products/lender/download-credit-instrument

/en/openapi/v3-current/lender.yaml get /api/v1/loan-applications/{applicationId}/credit-instruments/{instrumentId}/download
Streams the rendered PDF bytes from the Lender's own custody. Tenant-scoped by construction: an instrument from another tenant, or another application, never resolves.



# Get active document template
Source: https://docs.lerian.studio/en/reference/products/lender/get-active-document-template

/en/openapi/v3-current/lender.yaml get /api/v1/loan-products/{productId}/document-templates/active
Returns the currently active published template version for the given kind; 404 when the product has none.



# Get consignado contract divergence detail
Source: https://docs.lerian.studio/en/reference/products/lender/get-consignado-contract-divergence

/en/openapi/v3-current/lender.yaml get /api/v1/internal/br/consignado/divergences/{id}
Returns the comparative detail (structured fields plus raw secondary evidence) and the full append-only history for one item.



# Get document template version
Source: https://docs.lerian.studio/en/reference/products/lender/get-document-template-version

/en/openapi/v3-current/lender.yaml get /api/v1/loan-products/{productId}/document-templates/{templateId}
Returns one template version by id.



# Get floating-rate table
Source: https://docs.lerian.studio/en/reference/products/lender/get-floating-rate-table

/en/openapi/v3-current/lender.yaml get /api/v1/rate-tables/{id}
Returns one floating-rate table with its full effective-dated curve, oldest period first.



# Get loan account CET disclosure
Source: https://docs.lerian.studio/en/reference/products/lender/get-loan-account-cet-disclosure

/en/openapi/v3-current/lender.yaml get /api/v1/br/loan-accounts/{id}/cet-disclosure
Returns the latest immutable CET disclosure artifact frozen for the active loan account.



# Get credit operation descriptor
Source: https://docs.lerian.studio/en/reference/products/lender/get-loan-account-credit-operation-descriptor

/en/openapi/v3-current/lender.yaml get /api/v1/br/loan-accounts/{id}/credit-descriptor
Returns the Res. CMN 5.004/2022 credit operation descriptor, optionally reconstructed as of a business date.



# Get loan account PDD stage
Source: https://docs.lerian.studio/en/reference/products/lender/get-loan-account-pdd-stage

/en/openapi/v3-current/lender.yaml get /api/v1/br/loan-accounts/{id}/pdd-stage
Returns the current Brazilian PDD delinquency stage and accrual eligibility state.



# Get loan application
Source: https://docs.lerian.studio/en/reference/products/lender/get-loan-application

/en/openapi/v3-current/lender.yaml get /api/v1/loan-applications/{id}
Returns one loan application by identifier. An application belonging to another tenant is reported as not found.



# Get loan product
Source: https://docs.lerian.studio/en/reference/products/lender/get-loan-product

/en/openapi/v3-current/lender.yaml get /api/v1/loan-products/{id}
Returns a loan product by ID.



# Get loan product (BR alias)
Source: https://docs.lerian.studio/en/reference/products/lender/get-loan-product-br

/en/openapi/v3-current/lender.yaml get /api/v1/br/loan-products/{id}
BR-aliased path for retrieving a loan product. Resolves to the same handler as the core endpoint.



# Get loan product version
Source: https://docs.lerian.studio/en/reference/products/lender/get-loan-product-version

/en/openapi/v3-current/lender.yaml get /api/v1/loan-product-versions/{id}
Returns one immutable product version snapshot by its own identifier.



# Get the PDD stage ladder in force
Source: https://docs.lerian.studio/en/reference/products/lender/get-the-pdd-stage-ladder-in-force

/en/openapi/v3-current/lender.yaml get /api/v1/br/pdd-stage-ladders/in-force
Returns the dated delinquency-stage policy deciding the requested business date for this tenant: the version identifier every automated stage transition records, and its carteira x days-overdue x regime bands.



# Ingest BR capitalization clause consent
Source: https://docs.lerian.studio/en/reference/products/lender/ingest-capitalization-clause-consent

/en/openapi/v3-current/lender.yaml post /api/v1/br/loan-applications/{id}/capitalization-consents
Hashes clause text server-side and stores an append-only consent artifact for BR-profile disbursement guards.



# Ingest the collection agent's Arquivo de Baixa Extraordinária
Source: https://docs.lerian.studio/en/reference/products/lender/ingest-the-collection-agent-s-arquivo-de-baixa-extraordinaria

/en/openapi/v3-current/lender.yaml post /api/v1/br/consignado/collection-settlements
Accepts the file in which the client's collection agent declares what it received into its own account, against the instructions the lender issued. Identity is the file's CONTENT: the same file re-uploaded is inert and reduces no debt twice. The file's own header names the agent, and a file this tenant cannot attribute to anybody — neither its active channel nor an agent still holding an open instruction — is refused before a single line is stored. Accepting the file applies nothing: each line becomes durable work, applied independently, so one unrecognised instruction is quarantined for an operator instead of blocking every other borrower's payment in the same upload. A line declaring a receipt the agent cannot have taken yet — a paid instant more than a few minutes ahead of the moment we receive the file — is refused too, and refuses the whole file: that instant is the ACCOUNTING instant of the settlement, so a skewed clock or a broken date formatter would book a repayment in the future.



# Issue credit instrument
Source: https://docs.lerian.studio/en/reference/products/lender/issue-credit-instrument

/en/openapi/v3-current/lender.yaml post /api/v1/loan-applications/{applicationId}/credit-instruments
Renders and durably custodies a credit-instrument (CCB) PDF for an approved loan application, from the product's active document template. Idempotent by caller-supplied key.



# List consignado contract divergences
Source: https://docs.lerian.studio/en/reference/products/lender/list-consignado-contract-divergences

/en/openapi/v3-current/lender.yaml get /api/v1/internal/br/consignado/divergences
Returns a tenant-scoped, deterministically ordered page of the operational divergence queue. Default order: flow-blocking effect first (booking_blocked, then adjustment_required, then posting_pending, then audit_only), then overdue, then largest absolute client-vs-lender difference, then oldest observation.



# List contracts overdue for problem-asset re-assessment
Source: https://docs.lerian.studio/en/reference/products/lender/list-contracts-overdue-for-problem-asset-re-assessment

/en/openapi/v3-current/lender.yaml get /api/v1/br/problem-asset-reassessment-overdue
Returns the contracts whose standing qualitative problem-asset characterisation (Res. CMN 4.966 art. 3 paragraphs 1 and 2) has outlived the re-assessment horizon their product version declares, with no newer declaration of any verdict behind it. It is a WORKLIST and not a verdict: every contract listed keeps exactly the stage, provision and income-recognition decision it already had, because a review nobody performed is not evidence that a borrower recovered. A contract leaves the list when somebody declares again — either verdict, because either one means a person read the evidence. Rows are kept per business date so a past day can be answered as it stood; omit businessDate to read the latest.



# List credit instruments
Source: https://docs.lerian.studio/en/reference/products/lender/list-credit-instruments

/en/openapi/v3-current/lender.yaml get /api/v1/loan-applications/{applicationId}/credit-instruments
Returns the emission history for a loan application, newest first.



# List document template versions
Source: https://docs.lerian.studio/en/reference/products/lender/list-document-template-versions

/en/openapi/v3-current/lender.yaml get /api/v1/loan-products/{productId}/document-templates
Returns the version history for the given kind, newest first.



# List floating-rate tables
Source: https://docs.lerian.studio/en/reference/products/lender/list-floating-rate-tables

/en/openapi/v3-current/lender.yaml get /api/v1/rate-tables
Returns a page of floating-rate table headers, newest first. The effective-dated curve is returned only by the detail endpoint.



# List loan applications
Source: https://docs.lerian.studio/en/reference/products/lender/list-loan-applications

/en/openapi/v3-current/lender.yaml get /api/v1/loan-applications
Returns a page of loan applications for the caller's tenant, newest first, optionally narrowed by status, loan product version, borrower, assigned officer or origination channel.



# Get loan product floating rate table
Source: https://docs.lerian.studio/en/reference/products/lender/list-loan-product-floating-rates

/en/openapi/v3-current/lender.yaml get /api/v1/loan-products/{id}/floating-rates
Resolves the product-version rate mode and effective floating-rate period for the requested as-of date.



# List loan product versions
Source: https://docs.lerian.studio/en/reference/products/lender/list-loan-product-versions

/en/openapi/v3-current/lender.yaml get /api/v1/loan-product-versions
Returns a page of immutable product version snapshots, newest first, optionally narrowed by product, jurisdiction, pricing mode, currency or accrual basis.



# List loan products
Source: https://docs.lerian.studio/en/reference/products/lender/list-loan-products

/en/openapi/v3-current/lender.yaml get /api/v1/loan-products
Returns a paginated list of loan products.



# List loan products (BR alias)
Source: https://docs.lerian.studio/en/reference/products/lender/list-loan-products-br

/en/openapi/v3-current/lender.yaml get /api/v1/br/loan-products
BR-aliased path for listing loan products. Resolves to the same handler as the core endpoint.



# List open extraordinary-collection instructions
Source: https://docs.lerian.studio/en/reference/products/lender/list-open-extraordinary-collection-instructions

/en/openapi/v3-current/lender.yaml get /api/v1/br/consignado/collection-instructions
Returns the instructions the client's collection agent still has to act on, oldest first. Only issued instructions still inside their own validity window appear, and only those issued to the agent this tenant currently has appointed. Leaving the window means different things by kind: a payoff amount is frozen, so a payment made at or after the window closes is no longer the amount owed and must be re-quoted, never collected — though a payment made INSIDE the window is credited whenever the file declaring it arrives. This is identical whether the worker pays it (payoff) or the institution taking the contract over pays it (payoff_portability): the frozen amount, the window and the stale-receipt refusal do not care who pays, and the kind exists so the agent knows from WHOM it collects. An arrear residual does not go stale, so it merely leaves this queue and a payment collected inside the window is still accepted when the agent declares it late. The response carries no digitable line and no barcode — the agent registers the boleto in its own account and the borrower-facing code is never ours to state.



# List over-deduction refunds owed to workers
Source: https://docs.lerian.studio/en/reference/products/lender/list-over-deduction-refunds-owed-to-workers

/en/openapi/v3-current/lender.yaml get /api/v1/internal/br/consignado/overdeduction-refunds
Returns the tenant's over-deduction refund cases, oldest obligation first — payroll deducted MORE than a competência was worth and the residual is owed back to the worker. `recorded` is an open obligation and `disposed` carries the execution fact of who returned it, when, and under which reference.



# List qualitative problem-asset assessments
Source: https://docs.lerian.studio/en/reference/products/lender/list-qualitative-problem-asset-assessments

/en/openapi/v3-current/lender.yaml get /api/v1/br/loan-accounts/{id}/problem-asset-assessments
Returns the contract's qualitative problem-asset declarations, newest first: what was invoked, by whom, on what evidence, and whether it characterised the asset. Withdrawals appear beside the characterisations they withdraw.



# List quarantined extraordinary-collection settlement lines
Source: https://docs.lerian.studio/en/reference/products/lender/list-quarantined-extraordinary-collection-settlement-lines

/en/openapi/v3-current/lender.yaml get /api/v1/internal/br/consignado/collection-settlements/quarantined
Returns the baixa lines the lender could not act on, oldest parked first. Each one is money a borrower ALREADY paid to the client's collection agent and nobody has credited, so the ordering is the borrower who has waited longest. The `id` is what the requeue route takes: without this listing, releasing a parked line meant hand-written SQL against a production tenant schema.



# List refused lines of the collection agent's own settlement files
Source: https://docs.lerian.studio/en/reference/products/lender/list-refused-lines-of-the-collection-agent-s-own-settlement-files

/en/openapi/v3-current/lender.yaml get /api/v1/br/consignado/collection-settlements/refused
Returns the lines of the Arquivo de Baixa Extraordinária this tenant's currently appointed collection agent delivered and the lender could not apply, NEWEST refusal first. Page with the opaque `cursor` from a response's `nextCursor`; the feed never drains, so paging from the oldest end would pin a long-lived client to the same first page forever. A line appears here only once it is terminal: a line still being retried may yet apply and is not refused. Only the appointed agent's own deliveries are visible — the listing is fenced on the active agent channel by name AND receiving account, so appointing a new agent does not hand it the previous agent's lines. `reasonCode` is the contract to branch on; `reason` is the same fact in prose and may be reworded. A refusal this surface cannot attribute to the line itself is reported as `unprocessable` rather than described: the line is held for operator review and the file is not the thing to correct.



# Preview a consignado compensating adjustment
Source: https://docs.lerian.studio/en/reference/products/lender/preview-consignado-compensating-adjustment

/en/openapi/v3-current/lender.yaml post /api/v1/internal/br/consignado/compensating-adjustments/preview
Validates a prospective compensating adjustment against the same domain invariants Create enforces and reports the eventual posting direction, with no database write, object storage call or outbox event.



# Preview amortisation schedule
Source: https://docs.lerian.studio/en/reference/products/lender/preview-loan-schedule

/en/openapi/v3-current/lender.yaml post /api/v1/loan-applications/preview-schedule
Computes a deterministic declining-balance schedule for the supplied loan parameters and records it as the offer, returning the identifier that names it. Re-running an identical preview returns the same identifier and records no second offer.



# Promote a loan product version to current
Source: https://docs.lerian.studio/en/reference/products/lender/promote-a-loan-product-version-to-current

/en/openapi/v3-current/lender.yaml post /api/v1/loan-products/{id}/promote
Repoints a LIVE loan product at another of its versions. New loan applications originate on the promoted version from this moment; every contract and every application already in flight keeps the version it was born on, and its schedule, pricing and charges go on being read from that version. The product must already be active — activation is the door its first version comes through — and the version must be one of this product's own.



# Promote a loan product version to current (BR alias)
Source: https://docs.lerian.studio/en/reference/products/lender/promote-a-loan-product-version-to-current-br-alias

/en/openapi/v3-current/lender.yaml post /api/v1/br/loan-products/{id}/promote
BR-aliased path for promoting a loan product version. Resolves to the same handler as the core endpoint.



# Publish a PDD stage ladder version
Source: https://docs.lerian.studio/en/reference/products/lender/publish-a-pdd-stage-ladder-version

/en/openapi/v3-current/lender.yaml post /api/v1/br/pdd-stage-ladders
Publishes a new dated delinquency-stage policy for this tenant, re-tuning the bands without a release. The effective date must be in the future: a ladder never re-answers a business date that has already been staged, and a published version is immutable.



# Publish document template
Source: https://docs.lerian.studio/en/reference/products/lender/publish-document-template

/en/openapi/v3-current/lender.yaml post /api/v1/loan-products/{productId}/document-templates/{templateId}/publish
Publishes a draft version, atomically superseding whatever version was previously active.



# Read the inbound-portability lineage of a contract
Source: https://docs.lerian.studio/en/reference/products/lender/read-the-inbound-portability-lineage-of-a-contract

/en/openapi/v3-current/lender.yaml get /api/v1/internal/br/consignado/contracts/{numeroContrato}/portability-inbound
Answers whether this contract ARRIVED by portability and, if so, which institution it came from, under which operation reference there, for how much, and as of when. A 404 is the ordinary answer for a contract this lender originated: the lineage row EXISTS only for transferred stock, which is what distinguishes it from new production in portfolio and regulatory reporting. The transferred balance is the principal the contract was booked with — a registered fact whose two numbers disagree is refused at ingestion rather than reconciled — and the record is immutable: a correction is a new fact elsewhere, never a rewrite of where a debt came from.



# Reconcile a consignado compensating adjustment
Source: https://docs.lerian.studio/en/reference/products/lender/reconcile-consignado-compensating-adjustment

/en/openapi/v3-current/lender.yaml post /api/v1/internal/br/consignado/compensating-adjustments/{id}/reconcile
Resolves an operation stuck at posting_intent_recorded by asking the ledger, once, whether a transaction for its correlation identity already exists. Never resubmits the posting. Idempotent via the X-Idempotency header enforced by the platform middleware.



# Record that an over-deduction refund was returned
Source: https://docs.lerian.studio/en/reference/products/lender/record-that-an-over-deduction-refund-was-returned

/en/openapi/v3-current/lender.yaml post /api/v1/internal/br/consignado/overdeduction-refunds/{id}/dispose
Closes one open refund case with the execution fact. The lender registers the obligation and the client's treasury moves the money, so this records a return that already happened and never pays anybody. The disposing actor is the caller's validated identity, never a body field, and a case is closed exactly once: a second disposition is refused rather than overwriting authorship. Idempotent via the X-Idempotency header enforced by the platform middleware.



# Reject loan application
Source: https://docs.lerian.studio/en/reference/products/lender/reject-loan-application

/en/openapi/v3-current/lender.yaml post /api/v1/loan-applications/{id}/reject
Transitions a pending-approval loan application to rejected.



# Requeue a quarantined consignado inbox item
Source: https://docs.lerian.studio/en/reference/products/lender/requeue-a-quarantined-consignado-inbox-item

/en/openapi/v3-current/lender.yaml post /api/v1/internal/br/consignado/inboxes/{inbox}/{id}/requeue
Returns one quarantined item of one durable inbox to work, under operator authority. It resets the attempt budget and clears the failure reason, and it NEVER touches the item's identity, its canonical payload, or any declared money value — a requeue re-runs the fact the inbox already holds, which is why the request carries no body. Lanes: collection_settlement, correction, disbursement, disbursement_posting, portability, refinance, registration. The disbursement inbox's ingestion and posting lanes are separate members on purpose: restarting a posting-stage fact from ingestion could recompute a posting intent that no longer matches what the ledger already holds under the same idempotency key. Idempotent via the X-Idempotency header enforced by the platform middleware.



# Requeue consignado contract divergence
Source: https://docs.lerian.studio/en/reference/products/lender/requeue-consignado-contract-divergence

/en/openapi/v3-current/lender.yaml post /api/v1/internal/br/consignado/divergences/{id}/requeue
Records an explicit retry signal over the same immutable command. Never reopens a disposed item. Compare-and-swap guarded by expectedVersion; idempotent via the X-Idempotency header enforced by the platform middleware.



# Set the problem-asset re-assessment horizon of a loan product version
Source: https://docs.lerian.studio/en/reference/products/lender/set-the-problem-asset-re-assessment-horizon-of-a-loan-product-version

/en/openapi/v3-current/lender.yaml put /api/v1/br/loan-product-versions/{id}/problem-asset-reassessment-horizon
Records how long a qualitative problem-asset characterisation (Res. CMN 4.966 art. 3 paragraphs 1 and 2) may stand on a contract of this version before somebody must look at the evidence again. Such a characterisation never expires on its own: declared once it stands until a second declaration withdraws it, so a judicial reorganisation declared in 2026 can keep a contract provisioned and income-suspended in 2029 on evidence nobody has re-read. Passing the horizon RELEASES NOTHING — the stage, the provision and the income-recognition decision continue exactly as they were, because a review nobody performed is not evidence that a borrower recovered. What it does is put the contract on a review worklist and publish a fact, once per contract per business date, until somebody declares again with either verdict. The call is idempotent and replaces whatever was set: this is an operating policy, not a regulatory classification. Omit the field to clear the horizon; existing versions that never set one are unaffected.



# Settle a chart change onto every contract's balances
Source: https://docs.lerian.studio/en/reference/products/lender/settle-a-chart-change-onto-every-contract-s-balances

/en/openapi/v3-current/lender.yaml post /api/v1/loan-products/{id}/accounting-profiles/supersessions/sweeps
Moves every live contract's balances onto the accounts the product's new chart names, one posting per contract on the effective date, so no contract ends with its balance split across two accounts. Safe to rerun at any point, including after a crash halfway through: rerunning is the recovery procedure and records nothing the first pass already recorded. It carries the same permission as the supersession itself.



# Supersede loan product chart of accounts
Source: https://docs.lerian.studio/en/reference/products/lender/supersede-loan-product-chart-of-accounts

/en/openapi/v3-current/lender.yaml post /api/v1/loan-products/{id}/accounting-profiles/supersessions
Replaces the chart of accounts every configured version of this loan product books against, from a stated month forward. One action, one effective date, every affected version written together or none. A version with no chart is not touched: giving it a first one is the separate configure action, and this route requires its own permission because replacing a live chart moves balances on every live contract.



# Withdraw loan application
Source: https://docs.lerian.studio/en/reference/products/lender/withdraw-loan-application

/en/openapi/v3-current/lender.yaml post /api/v1/loan-applications/{id}/withdraw
Transitions a loan application to withdrawn.



# Lender events
Source: https://docs.lerian.studio/en/reference/events/lender

Reference every CloudEvent Lender emits, with application streams, schema versions, subjects, payload contracts, catalog-only definitions, and wired consumers.

Lender publishes CloudEvents 1.0 in binary content mode through Lerian's streaming library. Business emission is outbox-only and at least once: the domain write and outbox envelope share one database transaction, and the relay publishes after commit.

## Application-stream contract

* `ce-source`: `lender`
* Facts: `lerian.streaming.lender`
* Commands: `lerian.streaming.lender.commands`
* Route dead letters: `lerian.streaming.lender.dlq`
* `ce-type`: `studio.lerian.lender.<resource>.<event>`
* Dispatch key: `<resource>.<event>` from `ce-resourcetype` and `ce-eventtype`

The topic identifies the producing application and stream class, not one event. Route on CloudEvents headers, not on a per-event topic name. Lender serves the exact catalog and application topics at `GET /api/v1/streaming/manifest`.

## Emitted events

The catalog declares 39 definitions. Lender emits 37 of them: 35 facts and 2 commands. The table separates catalog keys from the CloudEvent routing type.

| Definition key | `ce-type` | Stream | Schema | Subject | Fires when |
| - | - | - | - | - | - |
| `accounting_profile.configured` | `studio.lerian.lender.accounting_profile.configured` | Fact | `1.1.0` | `profile_id` | An accounting profile becomes the active configuration. |
| `assignment_set.approved` | `studio.lerian.lender.assignment_set.approved` | Fact | `1.0.0` | `assignment_set_id` | A cession composition is durably approved and its offer file becomes derivable from that approval. |
| `assignment_set.accepted` | `studio.lerian.lender.assignment_set.accepted` | Fact | `1.0.0` | `assignment_set_id` | A fund administrator accepts the whole cession and its receivables leave the tenant portfolio. |
| `collection.payment.applied` | `studio.lerian.lender.collection_payment.applied` | Fact | `1.0.0` | `application_id` | A verified collection payment is applied to one loan path. |
| `collection.payment.unapplied` | `studio.lerian.lender.collection_payment.unapplied` | Fact | `1.0.0` | `application_id` | A verified collection payment is held as unapplied cash. |
| `collection.payment.reapplied` | `studio.lerian.lender.collection_payment.reapplied` | Fact | `1.0.0` | `application_id` | Previously unapplied cash is released into receivables. |
| `collection.payment.refunded` | `studio.lerian.lender.collection_payment.refunded` | Fact | `1.0.0` | `application_id` | Previously unapplied cash is refunded through the provider. |
| `loan_application.submitted` | `studio.lerian.lender.loan_application.submitted` | Fact | `2.0.0` | `loan_application_id` | A validated application is persisted for underwriting. |
| `loan_application.approved` | `studio.lerian.lender.loan_application.approved` | Fact | `2.0.0` | `loan_application_id` | A pending application is approved. |
| `loan_application.rejected` | `studio.lerian.lender.loan_application.rejected` | Fact | `2.0.0` | `loan_application_id` | A pending application is rejected. |
| `loan_application.withdrawn` | `studio.lerian.lender.loan_application.withdrawn` | Fact | `2.0.0` | `loan_application_id` | A pending or approved application is withdrawn. |
| `loan_application.disbursed` | `studio.lerian.lender.loan_application.disbursed` | Fact | `2.0.0` | `loan_application_id` | Funds are disbursed for an approved or already disbursed application. |
| `loan_charge.applied` | `studio.lerian.lender.loan_charge.applied` | Fact | `1.0.0` | `loan_account_id` | A product-version charge is persisted on a loan account. |
| `loan_product.created` | `studio.lerian.lender.loan_product.created` | Fact | `1.0.0` | `loan_product_id` | A draft loan product is created. |
| `loan_product.activated` | `studio.lerian.lender.loan_product.activated` | Fact | `1.0.0` | `loan_product_id` | A loan product becomes active. |
| `loan_product.current_version_promoted` | `studio.lerian.lender.loan_product.current_version_promoted` | Fact | `1.0.0` | `loan_product_id` | A live product is repointed at another of its versions. |
| `loan_product_version.created` | `studio.lerian.lender.loan_product_version.created` | Fact | `1.0.0` | `loan_product_version_id` | An immutable loan-product version is appended. |
| `loan_schedule.prepayment_applied` | `studio.lerian.lender.loan_schedule.prepayment_applied` | Fact | `1.0.0` | `schedule_version_id` | A prepayment creates a successor schedule version. |
| `loan_schedule.rescheduled` | `studio.lerian.lender.loan_schedule.rescheduled` | Fact | `1.0.0` | `schedule_version_id` | A reschedule creates a successor schedule version. |
| `repayment.recorded` | `studio.lerian.lender.repayment.recorded` | Fact | `1.0.0` | `transaction_id` | A repayment and its cash allocation are recorded. |
| `returned_payment_receivable.opened` | `studio.lerian.lender.returned_payment_receivable.opened` | Fact | `1.0.0` | `receivable_id` | A reversed final payment opens a separate borrower debt outside the closed credit operation. |
| `returned_payment_receivable.collected` | `studio.lerian.lender.returned_payment_receivable.collected` | Fact | `1.0.0` | `receivable_id` | The borrower pays that debt by other means and it is closed. |
| `returned_payment_receivable.written_off` | `studio.lerian.lender.returned_payment_receivable.written_off` | Fact | `1.0.0` | `receivable_id` | A debt that aged to the final stage of its product's ladder is written off. |
| `repayment_reversal.recorded` | `studio.lerian.lender.repayment_reversal.recorded` | Fact | `1.0.0` | `transaction_id` | A repayment reversal is recorded with lineage. |
| `loan_account.pdd_stage_transitioned` | `studio.lerian.lender.loan_account.pdd_stage_transitioned` | Fact | `1.0.0` | `loan_account_id` | A BR loan account changes or cures its PDD stage. |
| `prepayment_quote.created` | `studio.lerian.lender.prepayment_quote.created` | Fact | `1.0.0` | `quote_id` | An immutable BR prepayment quote is persisted. |
| `prepayment_settlement.recorded` | `studio.lerian.lender.prepayment_settlement.recorded` | Fact | `1.0.0` | `settlement_id` | An accepted BR prepayment settlement is recorded. |
| `loan_account.debt_balance_changed` | `studio.lerian.lender.loan_account.debt_balance_changed` | Fact | `2.0.0` | `loan_account_id` | The canonical full-settlement debt balance is revised. |
| `loan_account.payment_overdue` | `studio.lerian.lender.loan_account.payment_overdue` | Fact | `1.0.0` | `loan_account_id` | A consignado installment enters or exits overdue state. |
| `loan_account.problem_asset_assessed` | `studio.lerian.lender.loan_account.problem_asset_assessed` | Fact | `1.0.0` | `loan_account_id` | A credit operator declares, with evidence, whether a Brazilian loan account is a problem asset for a qualitative reason. |
| `loan_account.problem_asset_reassessment_overdue` | `studio.lerian.lender.loan_account.problem_asset_reassessment_overdue` | Fact | `1.0.0` | `loan_account_id` | A standing qualitative problem-asset characterization outlives the re-assessment horizon of its product version. |
| `consignado.exclusao.requested` | `studio.lerian.lender.consignado_exclusao.requested` | Command | `1.0.0` | `request_ref` | Lender requests cancellation of a Consignado contract after settlement. |
| `consignado.redirecionamento.requested` | `studio.lerian.lender.consignado_redirecionamento.requested` | Command | `1.0.0` | `request_ref` | Lender requests payroll redirection to an eligible employment bond. |
| `payroll_deduction.refund_required` | `studio.lerian.lender.payroll_deduction.refund_required` | Fact | `1.0.0` | `receipt_id` | Post-payoff payroll cash creates a borrower refund obligation. |
| `payroll_overdeduction.refund_required` | `studio.lerian.lender.payroll_overdeduction.refund_required` | Fact | `1.0.0` | `refund_case_id` | Payroll deducted more than the competência owed. |
| `collection.instruction.issued` | `studio.lerian.lender.collection_instruction.issued` | Fact | `1.0.0` | `instrument_id` | Lender issues an extraordinary-collection instruction. |
| `guarantee_recovery.cash_allocated` | `studio.lerian.lender.guarantee_recovery_cash.allocated` | Fact | `1.0.0` | `receipt_id` | Confirmed guarantee-recovery cash is allocated without violating conservation. |

## Emitted payload contracts

The contracts below mirror the CloudEvent `data` JSON tags in the published Lender contract. `?` means the field can be absent. The Go wire structs declare no nullable pointer fields. `unknown` is raw JSON and may carry any JSON value, including `null`. Decimal values are JSON strings, timestamps are UTC RFC 3339 strings, and `YYYYMM` is a six-digit competência.

```typescript theme={null}
type DecimalString = string
type RFC3339 = string
type YYYYMM = string
```

> **accounting\_profile.configured**
>
> **Definition key:** `accounting_profile.configured`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.1.0`
>
> **Subject:** `profile_id`
>
> ```typescript theme={null}
> type AccountingProfilePostingLeg = {
>   account: string
>   role?: string
>   side: string
>   component?: string
>   optional: boolean
> }
>
> type AccountingProfilePostingRule = {
>   event_type: string
>   legs: AccountingProfilePostingLeg[]
> }
>
> type AccountingProfileConfiguredDataV1 = {
>   profile_id: string
>   loan_product_version_id: string
>   accounting_mode: string
>   posting_rules: AccountingProfilePostingRule[]
>   effective_from: string
>   created_at: RFC3339
> }
> ```
>
> `effective_from` is the civil day the chart it describes starts governing. Without it, two events about one product version describe two different charts and nothing on the wire says which one governs a given month.

> **assignment\_set.approved / assignment\_set.accepted**
>
> **Definition keys:** `assignment_set.approved`, `assignment_set.accepted`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.0.0`
>
> **Subject:** `assignment_set_id`
>
> A cession composition is durably approved. The event identifies the immutable approval that determines the offer file.
>
> ```typescript theme={null}
> type AssignmentSetApprovedDataV1 = {
>   assignment_set_id: string
>   assignment_fund_id: string
>   approval_id: string
>   approval_digest: string
>   approval_schema_version: string
>   valuation_version: string
>   currency: string
>   item_count: number
>   total_assignment_price: DecimalString
>   approved_by: string
>   approved_at: RFC3339
>   trail_observed_at: RFC3339
> }
> ```
>
> A fund administrator accepts the entire cession. The event reports the set-level money totals after the write-off of the receivables from the tenant portfolio. The `risk_retention` field names the retention regime the cession was booked under. The `retained_fraction` field is the share of the expected loss the institution keeps after the sale.
>
> ```typescript theme={null}
> type AssignmentSetAcceptedDataV1 = {
>   assignment_set_id: string
>   assignment_fund_id: string
>   registry_provider: string
>   risk_retention: string
>   retained_fraction: DecimalString
>   provenance: string
>   recorded_by: string
>   accepted_at: RFC3339
>   currency: string
>   item_count: number
>   total_face_value: DecimalString
>   total_assignment_price: DecimalString
>   total_discount_amount: DecimalString
> }
> ```

> **collection.payment.**\*
>
> **Definition keys:** `collection.payment.applied`, `collection.payment.unapplied`, `collection.payment.reapplied`, `collection.payment.refunded`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.0.0`
>
> **Subject:** `application_id`
>
> ```typescript theme={null}
> type CollectionPaymentDataV1 = {
>   application_id: string
>   notification_id: string
>   instrument_id: string
>   provider: string
>   provider_account_id: string
>   provider_payment_id: string
>   received_amount: DecimalString
>   applied_amount: DecimalString
>   unapplied_amount: DecimalString
>   refunded_amount?: DecimalString
>   currency: string
>   applied_transaction_id?: string
>   repair_reason?: string
>   refund_request_id?: string
>   refund_transaction_id?: string
> }
> ```

> **loan\_application.submitted**
>
> **Definition key:** `loan_application.submitted`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `2.0.0`
>
> **Subject:** `loan_application_id`
>
> ```typescript theme={null}
> type LoanApplicationSubmittedDataV2 = {
>   loan_application_id: string
>   loan_product_version_id: string
>   borrower_id: string
>   assigned_officer_id: string
>   status: string
>   requested_principal_amount: DecimalString
>   requested_interest_rate: DecimalString
>   requested_installments: number
>   expected_disbursement_date: RFC3339
>   preview_profile_version: string
>   preview_jurisdiction_code: string
>   preview_schedule_snapshot_id?: string
>   created_at: RFC3339
>   updated_at: RFC3339
> }
> ```

> **loan\_application.approved**
>
> **Definition key:** `loan_application.approved`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `2.0.0`
>
> **Subject:** `loan_application_id`
>
> ```typescript theme={null}
> type LoanApplicationApprovedDataV2 = {
>   loan_application_id: string
>   loan_product_version_id: string
>   borrower_id: string
>   assigned_officer_id: string
>   status: string
>   approved_amount: DecimalString
>   approval_decision_id: string
>   approval_decision_at: RFC3339
>   approved_by: string
>   requested_principal_amount: DecimalString
>   preview_profile_version: string
>   preview_jurisdiction_code: string
>   updated_at: RFC3339
> }
> ```

> **loan\_application.rejected**
>
> **Definition key:** `loan_application.rejected`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `2.0.0`
>
> **Subject:** `loan_application_id`
>
> ```typescript theme={null}
> type LoanApplicationRejectedDataV2 = {
>   loan_application_id: string
>   loan_product_version_id: string
>   borrower_id: string
>   assigned_officer_id: string
>   status: string
>   rejection_decision_id: string
>   rejection_decision_at: RFC3339
>   rejected_by: string
>   requested_principal_amount: DecimalString
>   preview_profile_version: string
>   preview_jurisdiction_code: string
>   updated_at: RFC3339
> }
> ```

> **loan\_application.withdrawn**
>
> **Definition key:** `loan_application.withdrawn`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `2.0.0`
>
> **Subject:** `loan_application_id`
>
> ```typescript theme={null}
> type LoanApplicationWithdrawnDataV2 = {
>   loan_application_id: string
>   loan_product_version_id: string
>   borrower_id: string
>   assigned_officer_id: string
>   status: string
>   withdrawal_decision_id: string
>   withdrawal_decision_at: RFC3339
>   withdrawn_by: string
>   requested_principal_amount: DecimalString
>   preview_profile_version: string
>   preview_jurisdiction_code: string
>   updated_at: RFC3339
> }
> ```

> **loan\_application.disbursed**
>
> **Definition key:** `loan_application.disbursed`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `2.0.0`
>
> **Subject:** `loan_application_id`
>
> ```typescript theme={null}
> type LoanApplicationDisbursedDataV2 = {
>   loan_application_id: string
>   loan_product_version_id: string
>   borrower_id: string
>   assigned_officer_id: string
>   status: string
>   loan_account_id: string
>   disbursement_event_id: string
>   disbursement_transaction_id: string
>   gross_requested_amount: DecimalString
>   net_delivered_amount: DecimalString
>   disbursed_at: RFC3339
>   profile_version: string
>   jurisdiction_extensions?: unknown
>   preview_jurisdiction_code: string
>   updated_at: RFC3339
> }
> ```

> **loan\_charge.applied**
>
> **Definition key:** `loan_charge.applied`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.0.0`
>
> **Subject:** `loan_account_id`
>
> ```typescript theme={null}
> type LoanChargeAppliedDataV1 = {
>   request_id: string
>   loan_account_id: string
>   source_product_version_id: string
>   charge_template_id: string
>   charge_code: string
>   charge_type: string
>   amount: DecimalString
>   rate: DecimalString
>   currency: string
>   account_created_at: RFC3339
>   assessed_at: RFC3339
> }
> ```

> **loan\_product.created**
>
> **Definition key:** `loan_product.created`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.0.0`
>
> **Subject:** `loan_product_id`
>
> ```typescript theme={null}
> type LoanProductCreatedDataV1 = {
>   loan_product_id: string
>   name: string
>   loan_type: string
>   status: string
>   jurisdiction_code: string
>   current_version_id?: string
>   created_at: RFC3339
> }
> ```

> **loan\_product.activated**
>
> **Definition key:** `loan_product.activated`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.0.0`
>
> **Subject:** `loan_product_id`
>
> ```typescript theme={null}
> type LoanProductActivatedDataV1 = {
>   loan_product_id: string
>   current_version_id: string
>   status: string
>   name: string
>   loan_type: string
>   jurisdiction_code: string
>   created_at: RFC3339
> }
> ```

> **loan\_product.current\_version\_promoted**
>
> **Definition key:** `loan_product.current_version_promoted`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.0.0`
>
> **Subject:** `loan_product_id`
>
> The product is the aggregate after the repoint, so `current_version_id` is the new pin. Contracts already written keep the version they were born on. Only new applications originate on the promoted one. The `promoted_by` field holds the authenticated subject verbatim. It is empty when no human asked for the promotion.
>
> ```typescript theme={null}
> type LoanProductCurrentVersionPromotedDataV1 = {
>   loan_product_id: string
>   current_version_id: string
>   status: string
>   name: string
>   loan_type: string
>   jurisdiction_code: string
>   promoted_by: string
>   promoted_at: RFC3339
> }
> ```

> **loan\_product\_version.created**
>
> **Definition key:** `loan_product_version.created`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.0.0`
>
> **Subject:** `loan_product_version_id`
>
> ```typescript theme={null}
> type LoanProductVersionCreatedDataV1 = {
>   loan_product_version_id: string
>   loan_product_id: string
>   jurisdiction_code: string
>   jurisdiction_extensions?: unknown
>   rate_mode: string
>   floating_rate_table_id?: string
>   floating_spread_bps: number
>   fixed_annual_rate_bps: number
>   requires_floating_rate: boolean
>   min_annual_rate_bps?: number
>   max_annual_rate_bps?: number
>   admitted_borrower_kinds: string[]
>   created_at: RFC3339
> }
> ```
>
> min/max rate bands are absent when the version stores none. A version with no band emits neither key rather than a zero-to-zero band, which would read as "only 0% is allowed". The `admitted_borrower_kinds` field is always present. An empty array means the version admits no borrower.

> **loan\_schedule.prepayment\_applied**
>
> **Definition key:** `loan_schedule.prepayment_applied`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.0.0`
>
> **Subject:** `schedule_version_id`
>
> ```typescript theme={null}
> type LoanSchedulePrepaymentAppliedDataV1 = {
>   loan_account_id: string
>   schedule_version_id: string
>   previous_schedule_version_id: string
>   version_number: number
>   reason: string
>   trigger_transaction_id: string
>   request_id: string
>   payload_hash: string
>   prepayment_amount: DecimalString
>   effective_date: RFC3339
>   business_date: RFC3339
>   profile_version: string
>   jurisdiction_code: string
>   created_at: RFC3339
>   installment_count: number
> }
> ```

> **loan\_schedule.rescheduled**
>
> **Definition key:** `loan_schedule.rescheduled`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.0.0`
>
> **Subject:** `schedule_version_id`
>
> ```typescript theme={null}
> type LoanScheduleRescheduledDataV1 = {
>   loan_account_id: string
>   schedule_version_id: string
>   previous_schedule_version_id: string
>   version_number: number
>   reason: string
>   trigger_transaction_id: string
>   request_id: string
>   payload_hash: string
>   effective_date: RFC3339
>   business_date: RFC3339
>   first_rescheduled_due_date: RFC3339
>   profile_version: string
>   jurisdiction_code: string
>   created_at: RFC3339
>   installment_count: number
> }
> ```

> **repayment.recorded**
>
> **Definition key:** `repayment.recorded`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.0.0`
>
> **Subject:** `transaction_id`
>
> ```typescript theme={null}
> type RepaymentAllocation = {
>   installment_number: number
>   due_date: RFC3339
>   principal_amount: DecimalString
>   interest_amount: DecimalString
>   fees_amount: DecimalString
>   penalties_amount: DecimalString
>   total_amount: DecimalString
>   fully_paid: boolean
> }
>
> type RepaymentRecordedDataV1 = {
>   transaction_id: string
>   loan_account_id: string
>   request_id: string
>   funding_mode: string
>   paid_amount: DecimalString
>   overpayment_amount: DecimalString
>   effective_date: RFC3339
>   created_at: RFC3339
>   allocation_count: number
>   allocations: RepaymentAllocation[]
> }
> ```

> **returned\_payment\_receivable.opened / returned\_payment\_receivable.collected / returned\_payment\_receivable.written\_off**
>
> **Definition keys:** `returned_payment_receivable.opened`, `returned_payment_receivable.collected`, `returned_payment_receivable.written_off`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.0.0`
>
> **Subject:** `receivable_id`
>
> The three facts project the same aggregate through one shared projection, so two facts about one debt cannot describe it differently. Every field is always present. A field that does not apply yet holds an empty string. It is never absent and never `null`. Read `status` to tell the states apart, not the emptiness of a field.
>
> The `stage` and `provision_amount` fields carry the aging of the debt. The `provision_consumed` and `loss` fields split the write-off. The `reversal_transaction_id` field is unique per receivable and is the anchor that a redelivery of the same reversal resolves to.
>
> ```typescript theme={null}
> type ReturnedPaymentReceivableDataV1 = {
>   receivable_id: string
>   loan_account_id: string
>   borrower_id: string
>   original_transaction_id: string
>   reversal_transaction_id: string
>   currency: string
>   amount: DecimalString
>   status: string
>   opened_at: RFC3339
>   opened_on: string
>   collected_at: RFC3339 | ""
>   collected_on: string
>   collected_by: string
>   stage: string
>   provision_amount: DecimalString
>   written_off_at: RFC3339 | ""
>   written_off_on: string
>   provision_consumed: DecimalString | ""
>   loss: DecimalString | ""
> }
> ```

> **repayment\_reversal.recorded**
>
> **Definition key:** `repayment_reversal.recorded`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.0.0`
>
> **Subject:** `transaction_id`
>
> ```typescript theme={null}
> type RepaymentAllocation = {
>   installment_number: number
>   due_date: RFC3339
>   principal_amount: DecimalString
>   interest_amount: DecimalString
>   fees_amount: DecimalString
>   penalties_amount: DecimalString
>   total_amount: DecimalString
>   fully_paid: boolean
> }
>
> type RepaymentReversalRecordedDataV1 = {
>   transaction_id: string
>   original_transaction_id: string
>   loan_account_id: string
>   request_id: string
>   paid_amount: DecimalString
>   overpayment_amount: DecimalString
>   effective_date: RFC3339
>   created_at: RFC3339
>   profile_version: string
>   jurisdiction_code: string
>   allocation_count: number
>   allocations: RepaymentAllocation[]
> }
> ```

> **loan\_account.pdd\_stage\_transitioned**
>
> **Definition key:** `loan_account.pdd_stage_transitioned`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.0.0`
>
> **Subject:** `loan_account_id`
>
> ```typescript theme={null}
> type LoanAccountPDDStageTransitionedDataV1 = {
>   loan_account_id: string
>   transition_id: string
>   from_stage: string
>   to_stage: string
>   accrual_state: string
>   reason?: string
>   effective_at: RFC3339
>   business_date: RFC3339
>   triggered_by?: string
>   profile_version?: string
>   jurisdiction_code?: string
>   created_at: RFC3339
> }
> ```

> **prepayment\_quote.created**
>
> **Definition key:** `prepayment_quote.created`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.0.0`
>
> **Subject:** `quote_id`
>
> ```typescript theme={null}
> type PrepaymentQuoteCreatedDataV1 = {
>   quote_id: string
>   loan_account_id: string
>   quote_type: string
>   principal_outstanding: DecimalString
>   interest_rebate: DecimalString
>   charge_rebate: DecimalString
>   iof_reconciliation: DecimalString
>   gross_amount: DecimalString
>   net_settlement_amount: DecimalString
>   rebate_mandatory: boolean
>   expires_at: RFC3339
>   currency: string
>   sla_due_at: RFC3339
>   statement_available_at: RFC3339
>   instrument_id: string
>   instrument_type: string
>   instrument_requested_at: RFC3339
>   profile_version?: string
>   jurisdiction_code?: string
>   consumer_protection_regime?: string
>   created_at: RFC3339
> }
> ```

> **prepayment\_settlement.recorded**
>
> **Definition key:** `prepayment_settlement.recorded`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.0.0`
>
> **Subject:** `settlement_id`
>
> ```typescript theme={null}
> type PrepaymentSettlementRecordedDataV1 = {
>   settlement_id: string
>   quote_id: string
>   loan_account_id: string
>   transaction_id: string
>   schedule_version_id?: string
>   settlement_type: string
>   principal_outstanding: DecimalString
>   interest_rebate: DecimalString
>   charge_rebate: DecimalString
>   iof_reconciliation: DecimalString
>   gross_amount: DecimalString
>   net_settlement_amount: DecimalString
>   final_principal_amount: DecimalString
>   final_interest_amount: DecimalString
>   final_charge_amount: DecimalString
>   final_iof_amount: DecimalString
>   profile_version?: string
>   jurisdiction_code?: string
>   consumer_protection_regime?: string
>   accepted_at: RFC3339
>   created_at: RFC3339
> }
> ```

> **loan\_account.debt\_balance\_changed**
>
> **Definition key:** `loan_account.debt_balance_changed`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `2.0.0`
>
> **Subject:** `loan_account_id`
>
> ```typescript theme={null}
> type LoanAccountDebtBalanceChangedDataV2 = {
>   loan_account_id: string
>   numero_contrato: string
>   reason: string
>   revision: number
>   balance_before: DecimalString
>   balance_after: DecimalString
>   currency: string
>   valuation_version: string
>   profile_version?: string
>   jurisdiction_code?: string
>   effective_at: RFC3339
>   created_at: RFC3339
> }
> ```

> **loan\_account.payment\_overdue**
>
> **Definition key:** `loan_account.payment_overdue`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.0.0`
>
> **Subject:** `loan_account_id`
>
> ```typescript theme={null}
> type LoanAccountPaymentOverdueDataV1 = {
>   loan_account_id: string
>   numero_contrato: string
>   competencia: YYYYMM
>   occurrence: number
>   reason: string
>   installment_number: number
>   installment_due_date: RFC3339
>   overdue_amount: DecimalString
>   currency: string
>   profile_version?: string
>   jurisdiction_code?: string
>   detected_at: RFC3339
>   resolved_at?: RFC3339
>   created_at: RFC3339
> }
> ```

> **loan\_account.problem\_asset\_assessed**
>
> **Definition key:** `loan_account.problem_asset_assessed`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.0.0`
>
> **Subject:** `loan_account_id`
>
> Lender emits it on both verdicts. A declaration with `characterizes_problem_asset` set to `false` is the only way to withdraw an earlier characterization.
>
> ```typescript theme={null}
> type LoanAccountProblemAssetAssessedDataV1 = {
>   assessment_id: string
>   loan_account_id: string
>   trigger: string
>   source: string
>   evidence_reference: string
>   characterizes_problem_asset: boolean
>   declared_by: string
>   evaluated_on: string
>   created_at: RFC3339
> }
> ```

> **loan\_account.problem\_asset\_reassessment\_overdue**
>
> **Definition key:** `loan_account.problem_asset_reassessment_overdue`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.0.0`
>
> **Subject:** `loan_account_id`
>
> This fact is a call to review. It changes nothing on the contract: the stage, the provision, and the income-recognition decision stay as they were. Lender emits it once per contract per business date, and a declaration of either verdict ends it.
>
> ```typescript theme={null}
> type LoanAccountProblemAssetReassessmentOverdueDataV1 = {
>   loan_account_id: string
>   business_date: string
>   trigger: string
>   last_assessed_on: string
>   horizon_days: number
>   days_overdue: number
> }
> ```

> **consignado.exclusao.requested**
>
> **Definition key:** `consignado.exclusao.requested`
>
> **Topic:** `lerian.streaming.lender.commands`
>
> **Schema:** `1.0.0`
>
> **Subject:** `request_ref`
>
> ```typescript theme={null}
> type ConsignadoExclusaoRequestedDataV1 = {
>   request_ref: string
>   settlement_id: string
>   loan_account_id: string
>   contract_id: string
>   numero_contrato: string
>   motivo_exclusao: string
>   settled_at: RFC3339
> }
> ```

> **consignado.redirecionamento.requested**
>
> **Definition key:** `consignado.redirecionamento.requested`
>
> **Topic:** `lerian.streaming.lender.commands`
>
> **Schema:** `1.0.0`
>
> **Subject:** `request_ref`
>
> ```typescript theme={null}
> type ConsignadoRedirecionamentoRequestedDataV1 = {
>   request_ref: string
>   numero_contrato: string
>   source_vinculo_ref: string
>   target_vinculo_ref: string
>   target_matricula: string
>   target_cnpj: string
>   target_esocial_category: string
>   disruption_status: string
>   effective_at: RFC3339
> }
> ```

> **payroll\_deduction.refund\_required**
>
> **Definition key:** `payroll_deduction.refund_required`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.0.0`
>
> **Subject:** `receipt_id`
>
> ```typescript theme={null}
> type PayrollDeductionRefundRequiredDataV1 = {
>   receipt_id: string
>   account_id: string
>   product_version_id: string
>   payoff_effective_at: RFC3339
>   receipt_settled_at: RFC3339
>   amount: DecimalString
>   currency: string
>   required_at: RFC3339
> }
> ```

> **payroll\_overdeduction.refund\_required**
>
> **Definition key:** `payroll_overdeduction.refund_required`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.0.0`
>
> **Subject:** `refund_case_id`
>
> ```typescript theme={null}
> type PayrollOverdeductionRefundRequiredDataV1 = {
>   refund_case_id: string
>   loan_account_id: string
>   product_version_id: string
>   numero_contrato: string
>   competencia: YYYYMM
>   detecting_run_id: string
>   amount: DecimalString
>   currency: string
>   reversal_source_reference: string
>   required_at: RFC3339
> }
> ```

> **collection.instruction.issued**
>
> **Definition key:** `collection.instruction.issued`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.0.0`
>
> **Subject:** `instrument_id`
>
> ```typescript theme={null}
> type CollectionInstructionIssuedDataV1 = {
>   instrument_id: string
>   loan_account_id: string
>   instruction_ref: string
>   agent_name: string
>   agent_account_id: string
>   kind: string
>   numero_contrato: string
>   competencia?: YYYYMM
>   amount: DecimalString
>   currency: string
>   issued_at: RFC3339
>   valid_until: RFC3339
> }
> ```

> **guarantee\_recovery.cash\_allocated**
>
> **Definition key:** `guarantee_recovery.cash_allocated`
>
> **Topic:** `lerian.streaming.lender`
>
> **Schema:** `1.0.0`
>
> **Subject:** `receipt_id`
>
> ```typescript theme={null}
> type GuaranteeRecoveryCashAllocatedDataV1 = {
>   receipt_id: string
>   loan_account_id: string
>   disruption_ref: string
>   source_sequence: number
>   cash_source: string
>   amount: DecimalString
>   repayment_applied: DecimalString
>   prepayment_applied: DecimalString
>   unapplied: DecimalString
>   currency: string
>   settled_at: RFC3339
> }
> ```

## Cataloged but not emitted

These two definitions are present in the manifest but have no non-test Lender emission caller. Do not treat their `lender`-sourced forms as operational integrations.

| Definition key | Derived `ce-type` (not emitted) | Stream | Status |
| - | - | - | - |
| `consignado.averbacao.rejected` | `studio.lerian.lender.consignado_averbacao.rejected` | Fact | Reserved Lender-source mirror. Lender consumes this fact from the gateway; see Events consumed. Consignado emits the operational fact with `ce-source: consignado-gw`. |
| `consignado.reconciliation.received` | `studio.lerian.lender.consignado_reconciliation.received` | Fact | Reserved Lender-source mirror. Lender consumes this fact from the gateway; see Events consumed. Consignado emits the operational fact with `ce-source: consignado-gw`. |

## Events consumed

Lender wires 15 gateway fact keys from `lerian.streaming.consignado-gw` and one Matcher fact from `lerian.streaming.matcher`. Each consumer is configuration-gated and registered in bootstrap.

| Producer | Definition key | `ce-type` |
| - | - | - |
| `consignado-gw` | `consignado.contract.registered` | `studio.lerian.consignado-gw.consignado_contract.registered` |
| `consignado-gw` | `consignado.disbursement.confirmed` | `studio.lerian.consignado-gw.consignado_disbursement.confirmed` |
| `consignado-gw` | `consignado.averbacao.rejected` | `studio.lerian.consignado-gw.consignado_averbacao.rejected` |
| `consignado-gw` | `consignado.employment_status.reported` | `studio.lerian.consignado-gw.consignado_employment_status.reported` |
| `consignado-gw` | `consignado.redirecionamento.confirmed` | `studio.lerian.consignado-gw.consignado_redirecionamento.confirmed` |
| `consignado-gw` | `consignado.redirecionamento.rejected` | `studio.lerian.consignado-gw.consignado_redirecionamento.rejected` |
| `consignado-gw` | `consignado.reconciliation.received` | `studio.lerian.consignado-gw.consignado_reconciliation.received` |
| `consignado-gw` | `consignado.exclusao.confirmed` | `studio.lerian.consignado-gw.consignado_exclusao.confirmed` |
| `consignado-gw` | `consignado.exclusao.rejected` | `studio.lerian.consignado-gw.consignado_exclusao.rejected` |
| `consignado-gw` | `consignado.contract_correction.available` | `studio.lerian.consignado-gw.consignado_contract_correction.available` |
| `consignado-gw` | `consignado.disbursement_correction.available` | `studio.lerian.consignado-gw.consignado_disbursement_correction.available` |
| `consignado-gw` | `consignado_portabilidade.efetivada` | `studio.lerian.consignado-gw.consignado_portabilidade.efetivada` |
| `consignado-gw` | `consignado_portabilidade.rejeitada` | `studio.lerian.consignado-gw.consignado_portabilidade.rejeitada` |
| `consignado-gw` | `consignado_refinanciamento.efetivado` | `studio.lerian.consignado-gw.consignado_refinanciamento.efetivado` |
| `consignado-gw` | `consignado_refinanciamento.revertido` | `studio.lerian.consignado-gw.consignado_refinanciamento.revertido` |
| `matcher` | `match_run.completed` | `studio.lerian.matcher.match_run.completed` |

The gateway has emission paths for the first 13 listed gateway keys. The portability pair reaches Lender only when its outcome consumer is enabled and the deployed gateway manifest declares the event. The manifest does not declare the two refinance outcomes, so those two listeners receive no traffic from the current gateway runtime. Lender does not register `consignado.proposal.accepted`. That key is not a Lender booking input.

## Internal event planes

Lender also writes internal outbox event types for ledger intents, collection work, and signed hub handoffs. They are process-local coordination contracts, not entries of the event catalog. This public inventory omits them on purpose.

## Delivery and compatibility rules

* Deduplicate by `(ce-source, ce-id)` and make handlers idempotent.
* Read `ce-schemaversion` before decoding. The version is a CloudEvents header, never a topic suffix.
* Money and rates are decimal strings. Timestamps are UTC RFC 3339.
* The wired fact consumers filter exact keys. They skip and commit unmatched facts on the shared application topics. Malformed handled records follow the consumer DLQ policy.
* A missing required business identifier prevents emission or command execution. Lender never synthesizes it.


# Approve an assignment set
Source: https://docs.lerian.studio/en/reference/products/lender/approve-an-assignment-set

/en/openapi/v3-current/lender.yaml post /api/v1/assignment/sets/{setId}/approve
Re-reads the rail state behind the composition and approves exactly what that reading covers: a receivable the rail no longer carries leaves the set, an altered one is repriced by the same ruler and stays. The approval is immutable, and a retry over the same composition replays it rather than creating a second authority.



# Assemble an assignment set
Source: https://docs.lerian.studio/en/reference/products/lender/assemble-an-assignment-set

/en/openapi/v3-current/lender.yaml post /api/v1/assignment/sets
Composes a DRAFT set from the chosen receivables: freezes each one's facts and prices it with the fund's own cession rate, so the composition a manager later approves is the composition that was measured. A receivable already travelling inside another set is refused, never silently dropped.



# Create accrual run
Source: https://docs.lerian.studio/en/reference/products/lender/create-accrual-run

/en/openapi/v3-current/lender.yaml post /api/v1/accrual-runs
Queues an accrual batch for a business date and returns available journal/outbox reference data.



# Create assignment fund document template draft
Source: https://docs.lerian.studio/en/reference/products/lender/create-assignment-fund-document-template-draft

/en/openapi/v3-current/lender.yaml post /api/v1/assignment/funds/{fundId}/document-templates
Creates a new DRAFT endorsement-term template version for one assignment fund. The clausulado is legal content of that fund's own regulation, which is why it is versioned per fund rather than per loan product.



# Create prepayment quote
Source: https://docs.lerian.studio/en/reference/products/lender/create-prepayment-quote

/en/openapi/v3-current/lender.yaml post /api/v1/br/loan-accounts/{id}/prepayment-quote
Creates a time-limited, auditable prepayment quote with settlement and rebate breakdown.



# Discard an assignment set
Source: https://docs.lerian.studio/en/reference/products/lender/discard-an-assignment-set

/en/openapi/v3-current/lender.yaml post /api/v1/assignment/sets/{setId}/discard
Calls a composition off and RELEASES its receivables back to the assignable pool. Allowed from every state except accepted, whose receivables were sold and written off, and refused for any composition that already sold part of itself: a line already accepted and written off, or a title already moved to the fund at the registry. Nothing is deleted: the set rests in the terminal cancelled state with its items, its transitions, its approval and its custodied signature evidence intact, and one append-only audit row names who called it off and why. Discarding a set that is already cancelled is inert.



# Download the offer file of an approved assignment set
Source: https://docs.lerian.studio/en/reference/products/lender/download-the-offer-file-of-an-approved-assignment-set

/en/openapi/v3-current/lender.yaml get /api/v1/assignment/sets/{setId}/offer-file
Serializes the set's IMMUTABLE approval into the layout its fund's custodian ingests. The first call authorizes the file and records its digest; every later call re-derives the same bytes and re-verifies them against that digest, so re-generation is byte-identical and the D+1 rollover re-serves the SAME file with no re-emission. A set that was never approved is refused. Downloading does NOT mark the offer as sent — that is a separate confirmed fact.



# End one receivable's funding obligation before its term
Source: https://docs.lerian.studio/en/reference/products/lender/end-one-receivable-s-funding-obligation-before-its-term

/en/openapi/v3-current/lender.yaml post /api/v1/assignment/sets/{setId}/funding-payoff
Ends the obligation raised by a cession booked with the risk retained (Res. CMN 4.966 art. 29) for one of its receivables, at the amount agreed with the fund. The operator informs that amount and what the borrower paid to get out; this service prices the obligation at amortised cost, refuses anything above the face of the instalments still owed, and books the difference as financing expense above the obligation or as released desagio below it. Omitting the agreed amount passes the borrower's payoff straight through; informing zero or less is refused, because a fund settling for nothing is a statement and not an absence. The cession itself reaches 'settled' only when this was the last of its receivables still owing the fund.



# Get accrual run
Source: https://docs.lerian.studio/en/reference/products/lender/get-accrual-run

/en/openapi/v3-current/lender.yaml get /api/v1/accrual-runs/{id}
Returns one accrual run header by id.



# Get active assignment fund document template
Source: https://docs.lerian.studio/en/reference/products/lender/get-active-assignment-fund-document-template

/en/openapi/v3-current/lender.yaml get /api/v1/assignment/funds/{fundId}/document-templates/active
Returns the currently active published version for the given kind; 404 when the fund has none — which is also what makes the term recorder refuse emission for that fund.



# Get active loan account
Source: https://docs.lerian.studio/en/reference/products/lender/get-active-loan-account

/en/openapi/v3-current/lender.yaml get /api/v1/loan-accounts/{id}
Returns the active loan account detail read model. A malformed UUID yields 422 (schema error), distinct from 404 when the account does not exist.



# Get active loan schedule
Source: https://docs.lerian.studio/en/reference/products/lender/get-active-loan-schedule

/en/openapi/v3-current/lender.yaml get /api/v1/loan-accounts/{id}/schedule
Returns ordered active loan installment schedule entries. A malformed UUID yields 422, distinct from 404.



# Get assignment fund
Source: https://docs.lerian.studio/en/reference/products/lender/get-assignment-fund

/en/openapi/v3-current/lender.yaml get /api/v1/assignment/funds/{fundId}
Returns one fund registration by identifier; 404 when the validated tenant has none with that identifier.



# Get assignment fund document template version
Source: https://docs.lerian.studio/en/reference/products/lender/get-assignment-fund-document-template-version

/en/openapi/v3-current/lender.yaml get /api/v1/assignment/funds/{fundId}/document-templates/{templateId}
Returns one of this fund's template versions by id.



# Get assignment set
Source: https://docs.lerian.studio/en/reference/products/lender/get-assignment-set

/en/openapi/v3-current/lender.yaml get /api/v1/assignment/sets/{setId}
Returns one set with its whole composition — survivors and departures alike, each carrying the verdict that removed it and the price it was valued at — plus the immutable approval fact when there is one. 404 when the validated tenant has no set with that identifier.



# Get current session
Source: https://docs.lerian.studio/en/reference/products/lender/get-current-session

/en/openapi/v3-current/lender.yaml get /api/v1/me
Returns the validated subject of the bearer token and the caller's effective permissions in 'resource:action' form.



# Get journal reference by correlation id
Source: https://docs.lerian.studio/en/reference/products/lender/get-journal-reference

/en/openapi/v3-current/lender.yaml get /api/v1/journal-references
Returns journal/outbox reference data resolved by correlation ID.



# Get journal reference by id
Source: https://docs.lerian.studio/en/reference/products/lender/get-journal-reference-by-id

/en/openapi/v3-current/lender.yaml get /api/v1/journal-references/{id}
Returns journal/outbox reference data by journal reference ID.



# Get jurisdiction by code
Source: https://docs.lerian.studio/en/reference/products/lender/get-jurisdiction

/en/openapi/v3-current/lender.yaml get /api/v1/jurisdictions/{code}
Returns the descriptor for a single registered jurisdiction profile. Public (no tenant scope).



# Get payoff statement
Source: https://docs.lerian.studio/en/reference/products/lender/get-payoff-statement

/en/openapi/v3-current/lender.yaml get /api/v1/br/loan-accounts/{id}/payoff-statements/{quote_id}



# Get portfolio dashboard
Source: https://docs.lerian.studio/en/reference/products/lender/get-portfolio-dashboard

/en/openapi/v3-current/lender.yaml get /api/v1/dashboard/portfolio
Returns portfolio-level risk, delinquency, and freshness metrics for the requested business date. A business date the snapshot producer has not measured is refused with 503, never answered with a zeroed page: the caller should retry, not conclude the book is empty.



# Get receivable assignment dossier
Source: https://docs.lerian.studio/en/reference/products/lender/get-receivable-assignment-dossier

/en/openapi/v3-current/lender.yaml get /api/v1/assignment/receivables/{receivableRef}/dossier
Streams the receivable's evidence dossier (PDF). The first call freezes the receivable's facts into an immutable snapshot, renders the artifact and custodies it; every later call replays that snapshot and re-verifies that it still reproduces the recorded normalized-form digest. The response headers carry the whole determinism record, plus the declared strength of the lastro. The dossier never asserts byte-level correspondence with an emitted original.



# Get returned payment receivable
Source: https://docs.lerian.studio/en/reference/products/lender/get-returned-payment-receivable

/en/openapi/v3-current/lender.yaml get /api/v1/returned-payment-receivables/{id}
Returns one returned-payment receivable. A debt the asking identity may not see answers 404.



# Ingest the fund administrator's return file for an assignment set
Source: https://docs.lerian.studio/en/reference/products/lender/ingest-the-fund-administrator-s-return-file-for-an-assignment-set

/en/openapi/v3-current/lender.yaml post /api/v1/assignment/sets/{setId}/remessa
Reads the administrator's Arquivo Remessa and reconciles its verdicts against the composition that was offered. Identity is the file's CONTENT: the same file re-uploaded is inert, and a different file over a set that already accepted one is refused terminally and opens an exception case — a remessa reprocessed never cedes twice. Reconciliation is all-or-nothing: the verdicts must cover exactly the receivables the set still carries, at exactly the approved prices, or the whole file is refused as a divergence. A receivable the fund cuts leaves the composition with its reason and becomes assignable again; once this fund's repeated-cut limit is reached it stops returning automatically and lands in the exception queue instead.



# Lender error list
Source: https://docs.lerian.studio/en/reference/products/lender/lender-error-list

Look up each HTTP status and LENDER error code the Lender API returns, the condition behind it, and the action that resolves it.

**Error format**

Lender returns most errors as RFC 9457 problem details with the `application/problem+json`
media type. A rate-limit refusal answers a flat `{code, title, message}` body on
`application/json`.

```json Problem detail theme={null}
{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "validation failed",
  "errors": [
    {
      "location": "body.grossRequestedAmount",
      "message": "expected string",
      "value": 50000
    }
  ]
}
```

```json Rate-limit body theme={null}
{
  "code": 429,
  "title": "rate_limit_exceeded",
  "message": "rate limit exceeded"
}
```

**Field definitions**

* **`code`** – The stable, machine-readable domain code the refusal carries, in the form `LENDER-NNNN`. Absent when the refusal has not been given one. Branch on this first.
* **`status`** – The HTTP status code.
* **`title`** – The status name, such as `Unprocessable Entity`.
* **`detail`** – What went wrong on this occurrence. Below `500`, it describes the specific refusal. For `500`, `502`, and `503`, it carries a fixed generic value instead of the underlying cause.
* **`errors`** – Optional list of schema-validation details. Each entry carries a `location`, a `message`, and the `value` Lender received.
* **`type`** – `https://errors.lerian.studio/v1/LENDER-NNNN` when `code` is present. The RFC 9457 default `about:blank` otherwise.

The flat rate-limit body carries `code`, `title`, and `message` instead. Its `code` repeats the numeric HTTP status. Its `title` names the refusal and its `message` explains it in one sentence. Neither string varies with the caller or names your remaining quota.

Branch on `code` when the response carries one, and on the HTTP status and the content type when it does not. Read `detail` only as prose for a human. Authorization and idempotency middleware can answer in their own response formats.

## Client errors

***

Lender answers a `4xx` when the request is the problem, and `detail` names the specific refusal.

Lender scopes a lookup to the caller's tenant and to the parent named in the path. An identifier that resolves outside that scope answers the same way as an identifier that resolves to nothing.

A command needs a subject on the caller identity, because Lender records that subject as the actor behind the change. Byte limits apply twice: the framework limits the request body, and each file-ingestion surface limits the file it accepts.

Schema validation runs before the handler and fills `errors` with one entry per rejected location. A business rule runs inside the handler and answers with `detail` alone. Three examples: a currency assertion that disagrees with the loan, a set composition that mixes currencies, and a fund configured without a registry.

| Status | What it means | What to do |
| - | - | - |
| `400` | The request arrives without a body, or the body is not the exact JSON shape the operation reads. | Send a body that matches the operation's schema, then repeat the request. |
| `400` | The `X-Idempotency` header is longer than the operation accepts. | Send a shorter key, then repeat the request. |
| `401` | The request arrives without an authenticated identity. | Send a valid bearer token, then repeat the request. |
| `401` | The identity is authenticated, and its subject is empty. | Use a token whose subject identifies the caller. |
| `403` | The request lacks a validated tenant identity for the resource the operation works on. | Use a token scoped to the tenant that holds the resource, then repeat the request. |
| `404` | The identifier in the path names a resource this tenant does not hold. | Check the identifier, and check the tenant the token is scoped to. |
| `404` | The resource exists, and the parent named in the path does not hold it. | List the parent's own resources, then use an identifier from that list. |
| `409` | Another request carrying the same `X-Idempotency` value is still running. | Wait the `Retry-After` interval, then read the resource. Do not send the command again. |
| `422` | The `X-Idempotency` value was already used for a request with a different body. | Do not send this command under a new key. Read the outcome of the original request first, then decide. |
| `409` | The `idempotencyKey` in the body names a term already recorded with different content. | Read the term on record. A new key records a second term for the same set. |
| `409` | The resource sits at a different lifecycle step, or it was already closed. | Read the resource, then act from the step it is at. |
| `409` | Another writer changed the resource during the request. | Read the resource again, then repeat the request. |
| `409` | An external registry already accepted this exact command. | Read the protocol on record instead of issuing the command again. |
| `413` | The request body is larger than the operation accepts. | Send a smaller body. |
| `413` | The uploaded file is larger than the ingestion surface accepts. | Send a smaller file. |
| `405` | The path exists, and it does not accept this HTTP method. | Use a method the operation declares in the API reference. |
| `415` | The `Content-Type` header names a format the operation does not read. | Send `application/json`. |
| `429` | The caller sent more requests than the deployment's rate limit allows. | Read the `Retry-After` header, wait that many seconds, then repeat the request. |
| `422` | The request does not match the operation's schema. | Correct each entry in `errors`, then repeat the request. |
| `422` | The request matches the schema, and a business rule refuses its content. | Read `detail`, correct the request, then send it again. |
| `409` | A command reached a resource that is already closed, and it is not the redelivery of the command that closed it. | Redelivering the original command under the same request identity answers `200` with the record that already stands. This status means a second, different command. Read the record, then decide; nothing was posted twice. |
| `409` | The refusal is reproducible: repeating the request reproduces the conflict. | Do not repeat it. The state the request was built against changed, so reconcile the record and issue the command the current state calls for. |
| `422` | The refusal is terminal by design: the request can never succeed as stated. | Do not resend it, with or without corrections. `detail` names the case. The operation refused rather than leaving the resource half-changed, and the resource is exactly as it was. |
| `422` | The refusal names deployment or operator configuration rather than a malformed request. | Correcting the body will not help. `detail` names the object and the state it is in. Fix the configuration, then send the original request again. |

## Server errors

***

Lender answers a `5xx` when the request is sound and the call could not complete. For these statuses `detail` carries a fixed generic value, so the underlying cause stays inside the service.

A `503` covers two conditions: a capability the deployment does not run, and a dependency Lender cannot reach at the moment of the call. A `502` covers a third party that refuses a command Lender forwards to it, such as the registry that records an assignment of receivables.

| Status | What it means | What to do |
| - | - | - |
| `500` | Lender could not complete the request. | On a read, repeat the request. On a command that moves money, read the resource first, and repeat only if the command did not land. If the status repeats, contact support with the operation, the tenant, and the time of the call. |
| `502` | The registry Lender forwards to refused the command. | The response does not name the reason. Check the fund's registry configuration and the command's data, then issue the command again. |
| `503` | The deployment does not run the capability the operation needs. | Ask your platform team to enable the capability for your deployment. |
| `503` | A store or a downstream dependency was unreachable. | Retry with backoff. |

## Error codes

***

The tables below list the codes that Lender returns. `title` is the name of the HTTP status, and `detail` describes the specific case for a person, so branch on `code`, not on `detail`.

### General

| Code | Status | Refusal |
| - | - | - |
| `LENDER-0000` | `500` Internal Server Error | Lender could not classify the failure. Treat it as a server error. |

### Products

| Code | Status | Refusal |
| - | - | - |
| `LENDER-0101` | `409` Conflict | The loan product is not active, so you cannot change its current version. |
| `LENDER-0102` | `422` Unprocessable Entity | The version you named is not a version of this loan product. |
| `LENDER-0103` | `400` Bad Request | `chargeEffectiveAt` or `accountCreatedAt` is a calendar date. Send an RFC 3339 instant. |

### Origination

| Code | Status | Refusal |
| - | - | - |
| `LENDER-0201` | `409` Conflict | The application is already disbursed, and this disbursement declares no `trancheNumber`. |
| `LENDER-0202` | `422` Unprocessable Entity | The disbursement amount or its `trancheNumber` contradicts the approved amount. |
| `LENDER-0203` | `404` Not Found | No loan application in your tenant has this identifier. |
| `LENDER-0204` | `409` Conflict | Another request changed this application first. Nothing was written. |
| `LENDER-0205` | `409` Conflict | A different disbursement already uses this idempotency key. |
| `LENDER-0206` | `403` Forbidden | The authenticated subject cannot perform this action on this application. |
| `LENDER-0207` | `422` Unprocessable Entity | Lender cannot resolve the product-version profile that this disbursement needs. |
| `LENDER-0208` | `422` Unprocessable Entity | The net amount does not equal gross minus the withholdings, minus the origination fee. |
| `LENDER-0209` | `422` Unprocessable Entity | The origination fee is equal to or greater than the amount left after the withholdings. |
| `LENDER-0210` | `422` Unprocessable Entity | The product retains an origination fee that its accrual basis cannot amortize. |
| `LENDER-0211` | `409` Conflict | The loan account already has a loan application. |
| `LENDER-0212` | `422` Unprocessable Entity | A field of the request is malformed. |
| `LENDER-0213` | `409` Conflict | The action is not permitted from the application's current status. `detail` names the status. |
| `LENDER-0214` | `422` Unprocessable Entity | A counterparty's payment instant is further ahead of Lender's clock than the permitted skew. |
| `LENDER-0215` | `422` Unprocessable Entity | The requested rate is outside the product version's rate band. |
| `LENDER-0216` | `422` Unprocessable Entity | The product version declares no rate band. |
| `LENDER-0217` | `422` Unprocessable Entity | The currency in the disbursement request is not the application's currency. |
| `LENDER-0218` | `422` Unprocessable Entity | The opening entry that the reschedule request cites does not match this contract. |
| `LENDER-0219` | `422` Unprocessable Entity | A schedule-preview money or rate field is not a decimal. |
| `LENDER-0220` | `422` Unprocessable Entity | A schedule-preview decimal string is longer than Lender accepts. |
| `LENDER-0221` | `422` Unprocessable Entity | A schedule-preview decimal has an exponent outside the accepted range. |
| `LENDER-0222` | `503` Service Unavailable | The deployment has no loan-application reader for this route. |
| `LENDER-0223` | `503` Service Unavailable | Schedule preview is not configured in this deployment. |
| `LENDER-0224` | `503` Service Unavailable | The deployment cannot run the release that a substantial renegotiation needs. |
| `LENDER-0225` | `422` Unprocessable Entity | The loan product behind this application is not active. |
| `LENDER-0226` | `422` Unprocessable Entity | The version you named is not the product's current version. |
| `LENDER-0227` | `422` Unprocessable Entity | The disbursement's `jurisdictionExtensions` carries no `disbursedAt`. |
| `LENDER-0228` | `422` Unprocessable Entity | The product version does not admit the application's borrower kind. |
| `LENDER-0229` | `422` Unprocessable Entity | The first due date is on or before the disbursement date. |
| `LENDER-0230` | `422` Unprocessable Entity | The application declares no borrower kind, and the operation needs one. |
| `LENDER-0231` | `422` Unprocessable Entity | The first due date is so late that the first installment repays no principal. |
| `LENDER-0232` | `422` Unprocessable Entity | The request sets both a first due date and a grace period. |
| `LENDER-0233` | `422` Unprocessable Entity | The deployment prices no tax for the application's borrower kind. |
| `LENDER-0234` | `422` Unprocessable Entity | The schedule produced a period of zero days or fewer under the jurisdiction's calendar. |
| `LENDER-0235` | `422` Unprocessable Entity | The product version does not admit the chosen first due date. |
| `LENDER-0236` | `422` Unprocessable Entity | The application cites a schedule offer that is not on file. |

### Servicing

| Code | Status | Refusal |
| - | - | - |
| `LENDER-0301` | `422` Unprocessable Entity | Lender cannot read the request as a payment: the amount is not positive or has sub-cent precision, the idempotency key is missing, or the instant is invalid. |
| `LENDER-0302` | `409` Conflict | The payment is dated before facts that the loan account already settled. |
| `LENDER-0303` | `409` Conflict | A different payment already uses this idempotency key. |
| `LENDER-0304` | `409` Conflict | The per-installment breakdown allocates more than the installment owes. |
| `LENDER-0305` | `404` Not Found | No active loan account has this identifier. |
| `LENDER-0306` | `409` Conflict | The loan account has more than one live application, so its chart of accounts is ambiguous. |
| `LENDER-0307` | `422` Unprocessable Entity | The loan product version has no accounting profile. |
| `LENDER-0308` | `422` Unprocessable Entity | The product's chart of accounts cannot express this movement. |
| `LENDER-0309` | `422` Unprocessable Entity | The movement cannot be expressed as a ledger posting under the product's accounting profile. |
| `LENDER-0310` | `503` Service Unavailable | A component that this movement needs is not configured in the deployment. |
| `LENDER-0311` | `404` Not Found | The payment to reverse is not on this loan account. |
| `LENDER-0312` | `409` Conflict | The payment already has a reversal. |
| `LENDER-0313` | `422` Unprocessable Entity | A payment dated after the one you reverse stands on the contract. |
| `LENDER-0314` | `422` Unprocessable Entity | The schedule changed after the payment you reverse. |
| `LENDER-0315` | `422` Unprocessable Entity | A later payment and a later schedule version both stand on the contract. |
| `LENDER-0316` | `409` Conflict | A different reversal already uses this idempotency key. |
| `LENDER-0317` | `422` Unprocessable Entity | The reversal request is missing the lineage facts it needs. |
| `LENDER-0318` | `403` Forbidden | No validated identity reached the read, so Lender cannot scope it. |
| `LENDER-0319` | `409` Conflict | The loan has no single live application, so the compensating entry has no chart of accounts. |
| `LENDER-0320` | `409` Conflict | Lender cannot establish whether the original payment reached the ledger. |
| `LENDER-0321` | `422` Unprocessable Entity | The requested page or filter is not valid. |
| `LENDER-0322` | `409` Conflict | An earlier settlement already used part or all of this rebate. |
| `LENDER-0323` | `422` Unprocessable Entity | The returned payment carried unapplied cash, so it cannot become a receivable. |
| `LENDER-0324` | `404` Not Found | No returned-payment receivable has this identifier. |
| `LENDER-0325` | `409` Conflict | The receivable is already collected. |
| `LENDER-0326` | `422` Unprocessable Entity | The collection cannot be applied as sent. |
| `LENDER-0327` | `422` Unprocessable Entity | The payment you reverse booked nothing. |
| `LENDER-0328` | `503` Service Unavailable | Settlement is not configured in this deployment. |
| `LENDER-0329` | `404` Not Found | The schedule version you named is not on this contract. |
| `LENDER-0330` | `422` Unprocessable Entity | A field of the settlement or reschedule request is malformed. |
| `LENDER-0331` | `422` Unprocessable Entity | This contract settles only against a prepayment quote, and the request has none. |
| `LENDER-0332` | `422` Unprocessable Entity | The settlement is for more principal than the contract owes. |
| `LENDER-0333` | `422` Unprocessable Entity | The schedule version carries interest and no rate. |
| `LENDER-0334` | `422` Unprocessable Entity | The accrual run cannot recognize the months that this schedule creates. |
| `LENDER-0335` | `422` Unprocessable Entity | The product has no rule for the gain or loss of a substantial renegotiation. |
| `LENDER-0336` | `422` Unprocessable Entity | The product has no derecognition or recognition rule. |
| `LENDER-0337` | `422` Unprocessable Entity | The replacement contract's terms are incomplete. |
| `LENDER-0338` | `422` Unprocessable Entity | The modification is substantial (Res. CMN 4.966 art. 22), so it is not a successor schedule of this contract. |
| `LENDER-0339` | `422` Unprocessable Entity | The schedule cannot place the first installment on the requested date. |
| `LENDER-0340` | `422` Unprocessable Entity | The contract has no positive carrying amount to renegotiate. |
| `LENDER-0341` | `422` Unprocessable Entity | A payroll-deducted contract cannot be renegotiated substantially. |
| `LENDER-0342` | `409` Conflict | A different schedule-version request already uses this idempotency key. |
| `LENDER-0343` | `409` Conflict | The contract has already left the servicing book: it was settled, assigned, or ported. |
| `LENDER-0344` | `409` Conflict | A substantial renegotiation of this contract already exists. |
| `LENDER-0345` | `409` Conflict | The outbox quarantined a posting for this contract. |
| `LENDER-0346` | `409` Conflict | A posting for this contract was published, and the ledger did not confirm it. |
| `LENDER-0347` | `409` Conflict | A posting for this contract is in transit, and its acknowledgement has not arrived. |
| `LENDER-0348` | `400` Bad Request | The payment instant is a calendar date. Send an RFC 3339 instant. |

### Accounting

| Code | Status | Refusal |
| - | - | - |
| `LENDER-0401` | `503` Service Unavailable | No chart balance-transfer sweep is configured, so a chart change cannot move balances. |
| `LENDER-0402` | `503` Service Unavailable | Lender could not read the ledger, so the sweep moved nothing. |
| `LENDER-0403` | `409` Conflict | The chart change is refused, because the deployment cannot move the balances it would leave behind. |
| `LENDER-0404` | `409` Conflict | A contract has no ledger asset, so Lender cannot read its balances. |
| `LENDER-0405` | `409` Conflict | The retry rebuilt a posting that differs from the one already queued for the same recognition. |
| `LENDER-0406` | `422` Unprocessable Entity | The chart can divert a returned final payment, and it lacks the rules to provision and write off that debt. |
| `LENDER-0407` | `422` Unprocessable Entity | Some item identifiers selected for the retry do not belong to the accrual run. `errors[].value` names up to ten of them. |
| `LENDER-0408` | `422` Unprocessable Entity | The product books this contract into accounts that it shares with other contracts, so the exit cannot be measured. |
| `LENDER-0409` | `409` Conflict | The ledger holds funds on this contract's accounts. |
| `LENDER-0410` | `503` Service Unavailable | Lender could not read the ledger. |
| `LENDER-0411` | `422` Unprocessable Entity | The product books the deferred origination fee into a shared account. |
| `LENDER-0412` | `409` Conflict | The contract's deferred-fee accounts carry a line that no reconciliation bucket covers. |
| `LENDER-0413` | `422` Unprocessable Entity | The deferred-fee reconciliation names no loan account. |
| `LENDER-0414` | `409` Conflict | The chart balance transfers on the deferred-fee accounts do not net to zero. |
| `LENDER-0415` | `404` Not Found | No disbursed contract in your tenant has this loan account. |
| `LENDER-0416` | `409` Conflict | More than one application claims this loan account. |
| `LENDER-0417` | `422` Unprocessable Entity | No chart of the product version was in force on the day that the first tranche was disbursed. |
| `LENDER-0418` | `422` Unprocessable Entity | A stored chart of the product fails accounting-profile validation. |
| `LENDER-0419` | `422` Unprocessable Entity | The product books the revenue tax (PIS/COFINS) into a per-contract account. |

### Assignment of receivables

| Code | Status | Refusal |
| - | - | - |
| `LENDER-0501` | `422` Unprocessable Entity | The payoff amount agreed with the fund exceeds the face value of the installments that the fund still owns. |
| `LENDER-0502` | `422` Unprocessable Entity | The payoff amount agreed with the fund is zero or less. |
| `LENDER-0503` | `422` Unprocessable Entity | The sale sends a retention field with no value: `retainedFraction` is null or blank, or `sellerRetainsControl` is null. |
| `LENDER-0504` | `422` Unprocessable Entity | The retained fraction reaches the substantial-retention threshold. Lender assembles a sale only when the fraction is below it. |
| `LENDER-0505` | `422` Unprocessable Entity | The seller retains control of what it sold (Res. CMN 4.966 art. 26 III). Lender does not book this kind of sale. |
| `LENDER-0506` | `422` Unprocessable Entity | A retained fraction is not a decimal string from 0 to 1 with no more than 8 decimal places. |

### Audit

| Code | Status | Refusal |
| - | - | - |
| `LENDER-0801` | `503` Service Unavailable | The loan audit history store has no database behind it. |

### Brazil

| Code | Status | Refusal |
| - | - | - |
| `LENDER-0900` | `422` Unprocessable Entity | The deployment's rate table has no IOF rate for the borrower kind. |
| `LENDER-0901` | `422` Unprocessable Entity | The problem-asset declaration names no norm article. |
| `LENDER-0902` | `422` Unprocessable Entity | The declaration names no source. |
| `LENDER-0903` | `422` Unprocessable Entity | The declaration cites no evidence. |
| `LENDER-0904` | `422` Unprocessable Entity | The declaration has no signer: no validated identity reached it, and it names no declaring subject. |
| `LENDER-0905` | `422` Unprocessable Entity | The declaration is not valid for another reason: an evaluation date in the future, no idempotency key, or a field over its length limit. |
| `LENDER-0906` | `404` Not Found | No loan account in your tenant has this identifier. |
| `LENDER-0907` | `409` Conflict | This idempotency key already recorded a declaration. |
| `LENDER-0908` | `403` Forbidden | No validated tenant identity reached the declaration route. |
| `LENDER-0909` | `503` Service Unavailable | The declaration store is unreachable. |
| `LENDER-0910` | `422` Unprocessable Entity | No completed re-assessment sweep covers that business date. |
| `LENDER-0911` | `422` Unprocessable Entity | `businessDate` is not a `YYYY-MM-DD` date. |
| `LENDER-0912` | `503` Service Unavailable | The deployment has no schedule generator for the Brazilian tax quote. |


# List accounting profiles
Source: https://docs.lerian.studio/en/reference/products/lender/list-accounting-profiles

/en/openapi/v3-current/lender.yaml get /api/v1/accounting-profiles
Returns a page of the posting configurations attached to loan product versions, newest first, each with how many posting rules it holds and which business events those rules cover.



# List accrual run decisions
Source: https://docs.lerian.studio/en/reference/products/lender/list-accrual-run-decisions

/en/openapi/v3-current/lender.yaml get /api/v1/accrual-runs/{id}/items
Returns what the engine decided for every contract in the accounting month this run closes. One row is one contract-competência, NOT one row the run inserted: `runId` names the run that CLAIMED the month, so on a re-run it differs from the identifier in the path and the page still shows the month's decisions instead of coming back empty. An empty page therefore means the month has no decisions at all, never that a re-run did nothing. `outcome` says where the income went: recognized into P&L, or suspended and withheld under Res. CMN 4.966 art. 17. The recognition fields are ABSENT, not zero, on a withheld month. An unknown run identifier is 404.



# List accrual runs
Source: https://docs.lerian.studio/en/reference/products/lender/list-accrual-runs

/en/openapi/v3-current/lender.yaml get /api/v1/accrual-runs
Returns a page of the accrual runs executed for this tenant, newest first. Filtering by correlationId returns EVERY run sharing that identifier, which is how the full lineage behind one correlation is read.



# List active loan charges
Source: https://docs.lerian.studio/en/reference/products/lender/list-active-loan-charges

/en/openapi/v3-current/lender.yaml get /api/v1/loan-accounts/{id}/charges
Returns assessed charges for an active loan account. A malformed UUID yields 422, distinct from 404.



# List active loan transactions
Source: https://docs.lerian.studio/en/reference/products/lender/list-active-loan-transactions

/en/openapi/v3-current/lender.yaml get /api/v1/loan-accounts/{id}/transactions
Returns recorded repayment transactions for an active loan account. A malformed UUID yields 422, distinct from 404.



# List assignment candidates with eligibility verdicts
Source: https://docs.lerian.studio/en/reference/products/lender/list-assignment-candidates-with-eligibility-verdicts

/en/openapi/v3-current/lender.yaml get /api/v1/assignment/funds/{fundId}/candidates
Scores the tenant's assignable pool against ONE fund's configuration and returns a verdict per receivable: eligible, or cut with exactly one reason. The 20% per-debtor cap is invariable and never configuration; the payment-source and assignor limits come from the fund's regulation. Concentration is measured against the fund's accepted stock plus the admitted set, and the response states that base.



# List assignment fund document template versions
Source: https://docs.lerian.studio/en/reference/products/lender/list-assignment-fund-document-template-versions

/en/openapi/v3-current/lender.yaml get /api/v1/assignment/funds/{fundId}/document-templates
Returns this fund's version history for the given kind, newest first.



# List assignment funds
Source: https://docs.lerian.studio/en/reference/products/lender/list-assignment-funds

/en/openapi/v3-current/lender.yaml get /api/v1/assignment/funds
Returns the tenant's registered funds ordered by name.



# List assignment sets
Source: https://docs.lerian.studio/en/reference/products/lender/list-assignment-sets

/en/openapi/v3-current/lender.yaml get /api/v1/assignment/sets
Returns one page of the validated tenant's sets, newest first, each with the item count and the totals of its SURVIVING composition. Optionally narrowed to one fund or one lifecycle state.



# List delinquent loans
Source: https://docs.lerian.studio/en/reference/products/lender/list-delinquent-loans

/en/openapi/v3-current/lender.yaml get /api/v1/dashboard/delinquent-loans
Returns delinquent loan drill-down rows for a bucket at a requested business date. The freshness anchor is book-wide, so the same unmeasured business date that refuses the metrics refuses this register too, with 503.



# List delinquent loans (Brazil)
Source: https://docs.lerian.studio/en/reference/products/lender/list-delinquent-loans-brazil

/en/openapi/v3-current/lender.yaml get /api/v1/br/dashboard/delinquent-loans
Returns delinquent loan drill-down rows for the validated tenant at a requested business date, filterable by loan product, loan product version and by the regulatory carteira C1..C5 of Res. BCB 352/2023 art. 81. The carteira is derived from the product: it narrows to the loan product versions that declare it, so a carteira no product declares returns an empty page.



# List registered jurisdictions
Source: https://docs.lerian.studio/en/reference/products/lender/list-jurisdictions

/en/openapi/v3-current/lender.yaml get /api/v1/jurisdictions
Returns the set of jurisdiction profiles compiled into the running service. Public (no tenant scope).



# List loan account audit events
Source: https://docs.lerian.studio/en/reference/products/lender/list-loan-account-audit-events-huma

/en/openapi/v3-current/lender.yaml get /api/v1/loan-accounts/{id}/audit-events
Returns immutable correction, replay, and operator-visible audit history for a loan account. Schema-bounded limit (1–100, default 50); out-of-range values yield 422. A malformed UUID yields 422 (schema error).



# List loan accounts
Source: https://docs.lerian.studio/en/reference/products/lender/list-loan-accounts

/en/openapi/v3-current/lender.yaml get /api/v1/loan-accounts
Returns one page of the loan book, newest first, for an operator holding no account identifier. Filters narrow the page; omitting one does not narrow. By default only live accounts are returned — set includeClosed to also see the ones a terminal lifecycle fact closed, each carrying the lifecycleStatus that says whether it was settled, ceded, ported, reversed or renegotiated. An operator restricted to their own book sees only the accounts they borrow or service; a request carrying no authenticated identity is refused rather than served the whole book.



# List quarantined inbound records
Source: https://docs.lerian.studio/en/reference/products/lender/list-quarantined-inbound-records

/en/openapi/v3-current/lender.yaml get /api/v1/internal/streaming/discards
The records this service's inbound consumers could not process and quarantined to its dead-letter topic: what died, for which tenant, why, and where it came from. Scoped to the caller's validated tenant. The quarantined payload is deliberately not served — the origin topic, partition and offset are the route back to it.



# List returned payment receivables
Source: https://docs.lerian.studio/en/reference/products/lender/list-returned-payment-receivables

/en/openapi/v3-current/lender.yaml get /api/v1/returned-payment-receivables
Lists debts opened when a payment was given back on a contract that could not take it back — typically a payroll-deducted loan whose exclusion had been issued to the rail and not rejected. These are collected outside the credit operation and carry no payroll mandate. Narrow by contract, by borrower or by status.



# List the assignment exception queue
Source: https://docs.lerian.studio/en/reference/products/lender/list-the-assignment-exception-queue

/en/openapi/v3-current/lender.yaml get /api/v1/assignment/exceptions
Returns the tenant's exception cases, newest first. A case is opened when the cession flow must not decide by itself: a receivable this fund has now cut as many times as its configuration allows (repeated_cut), a second and different return file over a set that already accepted one (remessa_conflict), or verdicts that do not reconcile against the composition (remessa_divergence). Every filter is optional and narrows.



# Prepay loan account
Source: https://docs.lerian.studio/en/reference/products/lender/prepay-loan-account

/en/openapi/v3-current/lender.yaml post /api/v1/loan-accounts/{id}/prepayments
Appends an immutable prepayment schedule version and recalculation trigger. BR accounts require quoteId; amount-only prepayment is available only for non-BR accounts. When both are provided, amount must equal the quote's net settlement amount. Idempotency is enforced by the lib-commons idempotency middleware via the X-Idempotency header; a reused key with different facts yields 409. A missing required BR quote, malformed UUID, or invalid amount yields 422. Deduplication is by key ALONE: an amount-only settlement resent under a NEW key books a SECOND settlement, so retry under the ORIGINAL key. A BR quote is one-shot and bounds this by itself — a new key carrying an already-accepted quoteId is refused and writes nothing, while a new key carrying a new quote is a newly priced settlement and is meant to book.



# Prepay loan account (BR alias)
Source: https://docs.lerian.studio/en/reference/products/lender/prepay-loan-account-br

/en/openapi/v3-current/lender.yaml post /api/v1/br/loan-accounts/{id}/prepayments
BR-aliased path for prepaying a loan account. Resolves to the same handler as the core endpoint, with the jurisdiction resolver inserted into the chain. BR accounts require quoteId; when amount is also provided, it must equal the quote's net settlement amount. Idempotency is enforced by the lib-commons idempotency middleware via the X-Idempotency header; a reused key with different facts yields 409. A missing quote, malformed UUID, or invalid amount yields 422. Deduplication is by key ALONE, and the one-shot quote bounds it: a new key carrying an already-accepted quoteId is refused and writes nothing, while a new key carrying a new quote is a newly priced settlement and is meant to book.



# Preview repayment allocation
Source: https://docs.lerian.studio/en/reference/products/lender/preview-repayment

/en/openapi/v3-current/lender.yaml post /api/v1/loan-accounts/{id}/preview-repayment
Returns a deterministic repayment allocation preview without recording a transaction. Not idempotency-gated. A malformed UUID yields 422 (schema error). A malformed amount string yields 422.



# Preview jurisdiction tax amounts
Source: https://docs.lerian.studio/en/reference/products/lender/preview-tax

/en/openapi/v3-current/lender.yaml post /api/v1/br/tax/preview
Computes disbursement IOF tax amounts using the active compiled jurisdiction profile without persisting data.



# Publish assignment fund document template
Source: https://docs.lerian.studio/en/reference/products/lender/publish-assignment-fund-document-template

/en/openapi/v3-current/lender.yaml post /api/v1/assignment/funds/{fundId}/document-templates/{templateId}/publish
Publishes a draft version, atomically superseding whatever version was previously active for this fund. A published version is immutable.



# Reconcile a contract's deferred origination fee
Source: https://docs.lerian.studio/en/reference/products/lender/reconcile-a-contract-s-deferred-origination-fee

/en/openapi/v3-current/lender.yaml get /api/v1/loan-accounts/{id}/deferred-fee-reconciliation
Reads the ledger lines of the contract's own deferred-fee accounts, across every chart it lived under, into deferred, recognised, released and remaining, and holds the deferred figure against the fee the contract record says was retained. The contract is named by its loan account alone: product version, disbursement day, currency and retained fee come from the tenant's contract record. A ledger that does not answer is status UNAVAILABLE, not an error.



# Record a disposition against one exception case
Source: https://docs.lerian.studio/en/reference/products/lender/record-a-disposition-against-one-exception-case

/en/openapi/v3-current/lender.yaml post /api/v1/assignment/exceptions/{caseId}/resolve
Closes one OPEN case with what a named operator decided about it. Resolving a case somebody else already disposed of is refused rather than overwriting their disposition, and a resolution with nothing recorded is refused outright.



# Record a returned payment receivable collection
Source: https://docs.lerian.studio/en/reference/products/lender/record-a-returned-payment-receivable-collection

/en/openapi/v3-current/lender.yaml post /api/v1/returned-payment-receivables/{id}/collections
Records that the borrower paid the whole debt by other means, closing it and booking the mirror of the entry that opened it. Redelivering the same X-Request-ID answers the collection that already stands; a different request against a collected debt is refused.



# Record an externally-observed fact about an assignment set
Source: https://docs.lerian.studio/en/reference/products/lender/record-an-externally-observed-fact-about-an-assignment-set

/en/openapi/v3-current/lender.yaml post /api/v1/assignment/sets/{setId}/facts
Records a fact the operator confirms and moves the set accordingly. offer_sent confirms the authorized offer file was delivered to the fund's administrator, and requires an authorized file to exist. paid, transferred and accepted are per-receivable and follow one another in that order over a set whose endorsement term is already signed; each names where it came from, and each applies either to named receivables or to the whole surviving composition. accepted is the flip: the contract leaves this portfolio and its write-off is enqueued in the SAME transaction, or neither happens. A repeated confirmation is inert and reported as replayed rather than recording a second send or a second write-off. Re-stating paid is also the way to re-issue a title transfer the registradora refused: the fact writes nothing the second time, while the registry command is reached again through its own deterministic reference. Only a transferred fact whose provenance is registry_provider settles that command — the acceptance's proof of a moved title is the registradora's own statement and nobody else's.



# Record repayment
Source: https://docs.lerian.studio/en/reference/products/lender/record-repayment

/en/openapi/v3-current/lender.yaml post /api/v1/loan-accounts/{id}/repayments
Records a repayment allocation for an active loan account. Idempotency is enforced in the use case via the X-Request-ID header (X-Idempotency fallback): a reused request ID with different facts yields 409. A malformed UUID or amount yields 422. Deduplication is by request ID ALONE: the same amount, on the same account, on the same effective date, resent under a NEW request ID books a SECOND payment and answers 201. A borrower may legitimately pay the same amount twice, and no field in the request separates that from an accidental resend, so this route carries no business-fact fence — unlike disbursement, which does. Retry under the ORIGINAL request ID, which replays the original answer and moves nothing; a double that did book is undone on POST /api/v1/loan-accounts/{id}/transactions/{transactionId}/reverse, newest payment first.



# Record the assignment set's endorsement term
Source: https://docs.lerian.studio/en/reference/products/lender/record-the-assignment-set-s-endorsement-term

/en/openapi/v3-current/lender.yaml post /api/v1/assignment/sets/{setId}/term
Records the endorsement/assignment term of one APPROVED set. Which of two paths runs is resolved from the fund's own configured term mode, never from this request: for a fund the Lender emits for, the term is rendered from that fund's own published endorsement-term template (a fund with no published template is refused — there is no generic layout); for a fund whose administrator generates the term, nothing is emitted and the administrator's own artifact is registered, digested exactly as received. The row is append-only: the same idempotency key replays, a new key supersedes by order without erasing, and the set state term_signed is reachable only once a term exists.



# Register a receivable's credit instrument at the registradora
Source: https://docs.lerian.studio/en/reference/products/lender/register-a-receivable-s-credit-instrument-at-the-registradora

/en/openapi/v3-current/lender.yaml post /api/v1/assignment/receivables/{receivableRef}/registry-registration
Commands the registration of the receivable's credit instrument at the registradora the named fund is configured with, through the CLIENT's own participation. The command is idempotent by a deterministic reference that names the instrument alone: a second call returns the same protocol, and a registration the registry already accepted is refused rather than issued twice. A fund configured with no registradora is refused by name — registration is legally dispensable in the general case, and its absence never blocks a cession, but a caller who asked for one is never answered with silence.



# Register or update an assignment fund
Source: https://docs.lerian.studio/en/reference/products/lender/register-or-update-an-assignment-fund

/en/openapi/v3-current/lender.yaml post /api/v1/assignment/funds
Creates or replaces the registration of one fund and its administrator, keyed by fundTaxId within the validated tenant. Identifier and creation instant of an existing registration are preserved, so this is the update path as well as the create path.



# Reschedule loan account
Source: https://docs.lerian.studio/en/reference/products/lender/reschedule-loan-account

/en/openapi/v3-current/lender.yaml post /api/v1/loan-accounts/{id}/reschedules
Appends an immutable rescheduled schedule version and recalculation trigger. Idempotency is enforced by the lib-commons idempotency middleware via the X-Idempotency header; a reused key with different facts yields 409. A malformed UUID yields 422.



# Retry accrual run items
Source: https://docs.lerian.studio/en/reference/products/lender/retry-accrual-run-items

/en/openapi/v3-current/lender.yaml post /api/v1/accrual-runs/{id}/retry
Re-sends to the ledger the recognitions of a run that it has not acknowledged. Of the items selected, only those still unposted are re-sent; an acknowledged recognition is never sent twice, and each re-send carries the same deterministic key as the original attempt, so a recognition already in the ledger is deduplicated there rather than booked again. The response lists the items actually re-sent, which may be fewer than those asked for; whatever it could not send is listed in unpostableItems with a reason. Status is "queued" when at least one recognition went out, "nothing_to_retry" only when the ledger had already acknowledged everything selected, and "blocked" when unacknowledged recognitions exist and none of them could be re-sent. An id that belongs to no item of this run is refused with 422 (LENDER-0407) before any of that is decided, and nothing is re-sent — so "nothing_to_retry" can only ever mean the ledger has everything selected. That refusal names AT MOST TEN unknown ids, one per errors[] member at body.itemIds; the detail always states how many there are in total, so a selection with more than ten unknown ids reports the true count and lists the first ten. Safe to repeat: pressing retry twice enqueues one posting per recognition.



# Reverse loan account transaction
Source: https://docs.lerian.studio/en/reference/products/lender/reverse-loan-account-transaction

/en/openapi/v3-current/lender.yaml post /api/v1/loan-accounts/{id}/transactions/{transactionId}/reverse
Creates an immutable compensating transaction and preserves reversal lineage. The reversal's effective date is DERIVED from the payment being reversed and is not accepted in the request; a body carrying `effectiveDate` is refused 422. Idempotency is enforced in the use case via the X-Request-ID header (X-Idempotency fallback): a reused request ID with different facts yields 409. A malformed UUID yields 422; an unknown transaction yields 404; a payment already reversed yields 409. A reversal is REFUSED 422 when the loan account carries a payment or a schedule version whose effective timestamp is strictly later than the reversed payment's. The problem document names which fact blocks, in `errors[0].message`: `REVERSAL_REFUSED_LATER_PAYMENT` (the borrower paid again — use the compensating-adjustment path), `REVERSAL_REFUSED_LATER_SCHEDULE_VERSION` (the schedule was re-agreed — the remedy is a new schedule version), or `REVERSAL_REFUSED_LATER_FACTS_EXIST` (both).



# Score an assignment set against its fund's rule
Source: https://docs.lerian.studio/en/reference/products/lender/score-an-assignment-set-against-its-fund-s-rule

/en/openapi/v3-current/lender.yaml post /api/v1/assignment/sets/{setId}/eligibility
Measures the composition's FROZEN entry snapshots against the fund's eligibility and concentration limits and records the verdicts. A set waiting for the manager may be re-scored; an approved one never is.



# File many templates under one report family
Source: https://docs.lerian.studio/en/reference/products/reporter/assign-report-family

/en/openapi/v3-current/reporter.yaml patch /v1/templates/category
Associates ONE family with many templates in a single call — the shape of the work when templates stored before families existed are filed one CADOC at a time. It is not all-or-nothing: it applies to the ids that match a live template, and answers with `matched` and `modified` so the caller learns that some of what it sent did not exist or was deleted. An id naming a soft-deleted template does not match and is not resurrected. Sending the same body twice is safe and answers `modified: 0` the second time.



# Get a report
Source: https://docs.lerian.studio/en/reference/products/reporter/check-report-status

/en/openapi/v3-current/reporter.yaml get /v1/reports/{id}
Returns report information for the given ID.



# Create a data source
Source: https://docs.lerian.studio/en/reference/products/reporter/create-data-source

/en/openapi/v3-current/reporter.yaml post /v1/data-sources
Registers a data source connection. The password is write-only: it is encrypted at rest and never returned by any operation.



# Create a deadline
Source: https://docs.lerian.studio/en/reference/products/reporter/create-deadline

/en/openapi/v3-current/reporter.yaml post /v1/deadlines
Creates a deadline and returns the persisted entity.



# Register an institution
Source: https://docs.lerian.studio/en/reference/products/reporter/create-institution

/en/openapi/v3-current/reporter.yaml post /v1/institutions
Registers one of the tenant's financial institutions: one regulatory declarant, one CNPJ, numeric or alphanumeric. The CNPJ is stored uppercase and without punctuation, and a second live institution with the same CNPJ is refused with 409. Each data source named in the scope must be one the tenant can read; its tables and columns are not checked here. The answer carries the version in the ETag.



# Create a report
Source: https://docs.lerian.studio/en/reference/products/reporter/create-report

/en/openapi/v3-current/reporter.yaml post /v1/reports
Creates a report from an existing template and dispatches its generation.



# Delete a data source
Source: https://docs.lerian.studio/en/reference/products/reporter/delete-data-source

/en/openapi/v3-current/reporter.yaml delete /v1/data-sources/{dataSourceId}
Soft-deletes a data source. A data source still referenced by live templates is protected and the delete is refused with a conflict. Deleting is a one-way revocation of the name: the name is immediately free for a new data source to claim, but until one does, anything still referencing it fails instead of resolving against a different database. A revocation cannot be undone.



# Delete a deadline
Source: https://docs.lerian.studio/en/reference/products/reporter/delete-deadline

/en/openapi/v3-current/reporter.yaml delete /v1/deadlines/{id}
Soft-deletes a deadline.



# Delete an institution
Source: https://docs.lerian.studio/en/reference/products/reporter/delete-institution

/en/openapi/v3-current/reporter.yaml delete /v1/institutions/{institutionId}
Soft-deletes an institution. Its CNPJ is free to register again at once.



# Delete a template
Source: https://docs.lerian.studio/en/reference/products/reporter/delete-template

/en/openapi/v3-current/reporter.yaml delete /v1/templates/{id}
Deletes the template identified by the given ID.



# Set deadline delivery state
Source: https://docs.lerian.studio/en/reference/products/reporter/deliver-deadline

/en/openapi/v3-current/reporter.yaml patch /v1/deadlines/{id}/deliver
Marks a deadline as delivered or reverts its delivery state.



# Download a report
Source: https://docs.lerian.studio/en/reference/products/reporter/download-report

/en/openapi/v3-current/reporter.yaml get /v1/reports/{id}/download
Downloads the generated report file.



# Generate template code
Source: https://docs.lerian.studio/en/reference/products/reporter/generate-template-code

/en/openapi/v3-current/reporter.yaml post /v1/templates/generate-code
Converts template-builder blocks into Pongo2 template code and mapped fields.



# Get a data source schema
Source: https://docs.lerian.studio/en/reference/products/reporter/get-data-source-schema

/en/openapi/v3-current/reporter.yaml get /v1/data-sources/{dataSourceId}/schema
Introspects the live schema of a data source: queryable tables (or collections) with typed fields.



# Get what a document's file needs
Source: https://docs.lerian.studio/en/reference/products/reporter/get-document-contract

/en/openapi/v3-current/reporter.yaml get /v1/regulatory/documents/{documentId}/contract
Returns the contract: every set the file carries, every field of it, its type, whether it is required and how it is formatted. It is what a client reads to understand what they are mapping, and it is curated — never uploaded.



# Get an institution
Source: https://docs.lerian.studio/en/reference/products/reporter/get-institution

/en/openapi/v3-current/reporter.yaml get /v1/institutions/{institutionId}
Returns one institution, with its version in the ETag.



# Get one regulatory document
Source: https://docs.lerian.studio/en/reference/products/reporter/get-regulatory-document

/en/openapi/v3-current/reporter.yaml get /v1/regulatory/documents/{documentId}
Returns what a document is and which version of it this deployment carries. What the file NEEDS, field by field, is the contract sub-resource.



# Get a template's content
Source: https://docs.lerian.studio/en/reference/products/reporter/get-template-content

/en/openapi/v3-current/reporter.yaml get /v1/templates/{id}/content
Returns the stored source of a template, verbatim as it was uploaded, alongside the format it renders to. The content is bounded by whatever ceiling that deployment enforces on template upload. A stored file that is not valid UTF-8 is refused rather than returned repaired.



# Get template block configuration
Source: https://docs.lerian.studio/en/reference/products/reporter/list-block-definitions

/en/openapi/v3-current/reporter.yaml get /v1/templates/blocks-config
Returns the block definitions supported by the template builder.



# List data sources
Source: https://docs.lerian.studio/en/reference/products/reporter/list-data-sources

/en/openapi/v3-current/reporter.yaml get /v1/data-sources
Returns a page of registered data sources. Connection credentials never appear in responses.



# Get template filters
Source: https://docs.lerian.studio/en/reference/products/reporter/list-filter-definitions

/en/openapi/v3-current/reporter.yaml get /v1/templates/filters
Returns the filters supported by the template builder.



# List institutions
Source: https://docs.lerian.studio/en/reference/products/reporter/list-institutions

/en/openapi/v3-current/reporter.yaml get /v1/institutions
Returns a page of the tenant's institutions. Paginated by page and limit; cursor is refused.



# List the regulatory documents this deployment can file
Source: https://docs.lerian.studio/en/reference/products/reporter/list-regulatory-documents

/en/openapi/v3-current/reporter.yaml get /v1/regulatory/documents
Returns the curated documents mounted on this deployment, each once, whether or not this tenant subscribed to it; which ones the tenant files is the subscriptions list. A document that ships a reference binding is activated by correcting a mapping; one that does not is mapped from nothing, and the difference is on each item.



# List the report families in use
Source: https://docs.lerian.studio/en/reference/products/reporter/list-report-families

/en/openapi/v3-current/reporter.yaml get /v1/templates/categories
Returns every report family that has at least one live template, sorted by name, with the number of templates filed under each. This endpoint does NOT paginate and refuses page, limit and cursor: it answers with the set of families rather than with a page of the templates collection, and its consumer needs the whole set — a paginated family selector would make an operator page through it to discover that a family already exists, which is the discovery they need to make before creating a duplicate. When the answer reaches the ceiling it is cut and `truncated` says so.



# List templates
Source: https://docs.lerian.studio/en/reference/products/reporter/list-templates

/en/openapi/v3-current/reporter.yaml get /v1/templates
Returns templates using the existing filter and pagination semantics.



# Preview a template
Source: https://docs.lerian.studio/en/reference/products/reporter/preview-template

/en/openapi/v3-current/reporter.yaml post /v1/templates/preview
Renders template markup against caller-supplied sample data and returns the output, without creating a template or generating a report. A Pdf template previews as the HTML stage that would feed the PDF engine. The whole request body is capped at 3211264 bytes and a larger one is refused with 413 before it is parsed; content and sampleData carry their own ceilings.



# Propose institutions from Midaz
Source: https://docs.lerian.studio/en/reference/products/reporter/propose-institutions

/en/openapi/v3-current/reporter.yaml get /v1/institutions/proposals
Proposes one institution per live Midaz organization that no institution of the tenant covers yet: none holds its CNPJ, and none names its id in the scope of the data source holding Midaz's organization table. The name is the legal name and the CNPJ the legal document, which Midaz does not check, so cnpjValid says whether its check digits hold. The scope covers the organization table by id and every table of the named data sources with an organization_id column by it; a table with neither is left out. Nothing is written: confirming a proposal is an ordinary create.



# Replace an institution
Source: https://docs.lerian.studio/en/reference/products/reporter/replace-institution

/en/openapi/v3-current/reporter.yaml put /v1/institutions/{institutionId}
Replaces the institution's name, CNPJ and scope, IF If-Match carries the version the caller read. Without a readable If-Match the request is refused with 428; a stale version is refused with 409 naming both versions. The answer carries the new version in the ETag.



# Reporter API quick start
Source: https://docs.lerian.studio/en/reference/products/reporter/reporter-developer-quick-start

Get Reporter running: upload your first template, generate a report, and download the finished output with cURL against the Reporter API.

> [!TIP]
>
> **This guide is for developers.** If you're looking for a business-level overview of what Reporter does, see [What is Reporter?](/en/products/reporter/what-is-reporter).

This guide takes you from uploading your first template to downloading a generated report.

## Before you begin

***

You need:

* A running Reporter instance
* A valid authentication token (if Access Manager is enabled)
* A `.tpl` template file ready to upload

All examples use `cURL`. Replace `***` in each `Authorization` header with your authentication token and `https://reporter.example.com` with your Reporter URL.

## Step 1: Upload a template

***

Upload a `.tpl` file that defines the structure and content of your report, with its output format, a description, and a category. The category names the report family, in lowercase letters, digits, underscores, and hyphens. The template content must match the selected output format: HTML for `HTML` and `PDF`, XML for `XML`, CSV for `CSV`, and non-empty text for `TXT`. The uploaded file itself must have a `.tpl` extension.

> [!TIP]
>
> API reference: [Upload template](/en/reference/products/reporter/upload-template)

```bash cURL theme={null}
curl -X POST "https://reporter.example.com/v1/templates" \
 -H "Authorization: Bearer ***" \
 -F "template=@account_summary.tpl" \
 -F "outputFormat=PDF" \
 -F "description=Daily account summary report" \
 -F "category=account_summary"
```

```json theme={null}
{
  "id": "0196b270-a315-7137-9408-3f16af2685e1",
  "outputFormat": "pdf",
  "description": "Daily account summary report",
  "category": "account_summary",
  "fileName": "0196b270-a315-7137-9408-3f16af2685e1.tpl",
  "createdAt": "2026-03-05T10:00:00Z",
  "updatedAt": "2026-03-05T10:00:00Z"
}
```

Save the template `id`. You will use it to generate reports.

### Supported output formats

| Format | Use case |
| - | - |
| `CSV` | Data exports and spreadsheet integration |
| `XML` | Structured data and regulatory submissions |
| `HTML` | Browser-viewable reports |
| `PDF` | Print-ready and shareable documents |
| `TXT` | Plain text and legacy system integration |

## Step 2: Verify the template

***

List your templates to confirm the upload was successful.

> [!TIP]
>
> API reference: [List templates](/en/reference/products/reporter/list-templates)

```bash cURL theme={null}
curl -X GET "https://reporter.example.com/v1/templates" \
 -H "Authorization: Bearer ***"
```

## Step 3: Generate a report

***

Submit a report generation request with the template ID and the required `filters` object. Add filters to narrow the data, or send `{}` when you want no filter.

> [!TIP]
>
> API reference: [Create report](/en/reference/products/reporter/create-report)

```bash cURL theme={null}
curl -X POST "https://reporter.example.com/v1/reports" \
 -H "Authorization: Bearer ***" \
 -H "Content-Type: application/json" \
 -d '{
   "templateId": "0196b270-a315-7137-9408-3f16af2685e1",
   "filters": {
     "midaz_onboarding": {
       "account": {
         "created_at": {
           "between": ["2026-03-01", "2026-03-05"]
         }
       }
     }
   }
 }'
```

```json theme={null}
{
  "id": "0196c5c0-5044-724f-95f3-4b32076e7ad7",
  "templateId": "0196b270-a315-7137-9408-3f16af2685e1",
  "templateOutputFormat": "pdf",
  "templateDescription": "Daily account summary report",
  "filters": {
    "midaz_onboarding": {
      "account": {
        "created_at": {
          "between": ["2026-03-01", "2026-03-05"]
        }
      }
    }
  },
  "status": "Processing",
  "metadata": null,
  "completedAt": null,
  "createdAt": "2026-03-05T10:05:00Z",
  "updatedAt": "2026-03-05T10:05:00Z",
  "deletedAt": null
}
```

Save the report `id` for the next steps.

### Filter structure

Filters follow the path: **data source > table > field > operator > values**.

| Operator | Description | Example |
| - | - | - |
| `eq` | Equal to | `{ "eq": ["active"] }` |
| `gt` / `gte` | Greater than / greater or equal | `{ "gte": ["2026-01-01"] }` |
| `lt` / `lte` | Less than / less or equal | `{ "lt": [1000] }` |
| `between` | Value within a range | `{ "between": ["2026-03-01", "2026-03-31"] }` |
| `in` / `nin` | Value in / not in a list | `{ "in": ["active", "pending"] }` |

> [!NOTE]
>
> The `filters` field is mandatory. To generate a report without filtering, pass an empty object: `"filters": {}`.

## Step 4: Check report status

***

Report generation is asynchronous. Poll the status endpoint until the report is ready.

> [!TIP]
>
> API reference: [Check report status](/en/reference/products/reporter/check-report-status)

```bash cURL theme={null}
curl -X GET "https://reporter.example.com/v1/reports/0196c5c0-5044-724f-95f3-4b32076e7ad7" \
 -H "Authorization: Bearer ***"
```

| Status | Meaning |
| - | - |
| `Processing` | Reporter is querying data and rendering the template |
| `Finished` | The report is ready for download |
| `Partial` | Some data sections succeeded and others failed; the report's `metadata` carries per-section error codes |
| `Error` | An error prevented the report from being generated. |

Wait for `Finished` before proceeding to download.

## Step 5: Download the report

***

Once the report is finished, download the generated file.

> [!TIP]
>
> API reference: [Download report](/en/reference/products/reporter/download-report)

```bash cURL theme={null}
curl -X GET "https://reporter.example.com/v1/reports/0196c5c0-5044-724f-95f3-4b32076e7ad7/download" \
 -H "Authorization: Bearer ***" \
 -o account_summary.pdf
```

Reporter returns the file with `Content-Disposition` headers that give the filename and format.

## Step 6: Explore data sources

***

To understand what data is available for your templates, list the configured data sources. Then use `GET /v1/data-sources/{dataSourceId}/schema` to inspect the schema of one data source.

> [!TIP]
>
> API reference: [List data sources](/en/reference/products/reporter/list-data-sources) | [Get a data source schema](/en/reference/products/reporter/get-data-source-schema)

```bash cURL theme={null}
curl -X GET "https://reporter.example.com/v1/data-sources" \
 -H "Authorization: Bearer ***"
```

The list response identifies each data source. The schema response lists its tables or collections and their typed fields. A template reads a table as `datasource.table` and each row's fields by name.

## Deadlines and templates

***

The Deadlines API powers deadline management in the Console, and you can also call it directly to integrate deadlines into your own systems. To test `POST /v1/templates`, download [a sample `.tpl` file](https://drive.google.com/file/d/1i8QP2Uk4ZGMy7Zk28b_c9e2Zwb9i65-X/view?usp=sharing).

## Next steps

***

> **[What is Reporter?](/en/products/reporter/what-is-reporter)**
>
> Full overview of template syntax, tags, and filters.

> **[Template formats](/en/products/reporter/template-examples)**
>
> Practical examples for HTML, XML, and TXT templates.

> **[Using Reporter](/en/products/reporter/using-reporter)**
>
> Detailed guide on templates, storage, and data source configuration.

> **[Error handling](/en/reference/products/reporter/reporter-error-list)**
>
> Complete list of error codes and how to resolve them.


# Get a data source
Source: https://docs.lerian.studio/en/reference/products/reporter/retrieve-data-source

/en/openapi/v3-current/reporter.yaml get /v1/data-sources/{dataSourceId}
Returns the connection configuration of one registered data source. The queryable schema lives behind the /schema sub-resource.



# List deadline notifications
Source: https://docs.lerian.studio/en/reference/products/reporter/retrieve-deadline-notifications

/en/openapi/v3-current/reporter.yaml get /v1/deadlines/notifications
Returns active deadlines inside their notification window, ordered by urgency.



# List deadlines
Source: https://docs.lerian.studio/en/reference/products/reporter/retrieve-deadlines

/en/openapi/v3-current/reporter.yaml get /v1/deadlines
Returns a filtered page of deadlines.



# List reports
Source: https://docs.lerian.studio/en/reference/products/reporter/retrieve-reports

/en/openapi/v3-current/reporter.yaml get /v1/reports
Returns reports, narrowed by the published filters and paginated by cursor. Follow nextCursor to read the next page and prevCursor to read the previous one; a cursor is absent when there is no page in that direction.



# Get a template
Source: https://docs.lerian.studio/en/reference/products/reporter/retrieve-template-details

/en/openapi/v3-current/reporter.yaml get /v1/templates/{id}
Returns template information for the given ID, including the generation parameters the template declares.



# Test a data source connection
Source: https://docs.lerian.studio/en/reference/products/reporter/test-data-source-connection

/en/openapi/v3-current/reporter.yaml post /v1/data-sources/{dataSourceId}/test-connection
Probes connectivity with an ephemeral connection. A failed probe is a 200 with status "failed" and a client-safe message; latencyMs measures the full dial+ping round trip.



# Update a data source
Source: https://docs.lerian.studio/en/reference/products/reporter/update-data-source

/en/openapi/v3-current/reporter.yaml patch /v1/data-sources/{dataSourceId}
Partially updates a data source. An omitted password preserves the stored credential; a present password is re-encrypted. Renaming configName revokes the previous name exactly as a delete does: the previous name is free for a new data source to claim, but until one does, anything still referencing it fails instead of resolving against a different database.



# Update a deadline
Source: https://docs.lerian.studio/en/reference/products/reporter/update-deadline

/en/openapi/v3-current/reporter.yaml patch /v1/deadlines/{id}
Partially updates a deadline and returns the persisted entity.



# Update a template
Source: https://docs.lerian.studio/en/reference/products/reporter/update-templates

/en/openapi/v3-current/reporter.yaml patch /v1/templates/{id}
Updates a template's file, output format, or description.



# Create a template
Source: https://docs.lerian.studio/en/reference/products/reporter/upload-template

/en/openapi/v3-current/reporter.yaml post /v1/templates
Creates a report template from a multipart form upload.



# Validate template blocks
Source: https://docs.lerian.studio/en/reference/products/reporter/validate-template-blocks

/en/openapi/v3-current/reporter.yaml post /v1/templates/validate
Validates template-builder blocks and returns semantic validation errors.



# Reporter events
Source: https://docs.lerian.studio/en/reference/events/reporter

Reference the CloudEvents emitted by Lerian Reporter: the 17 event definitions, their payload contracts and schema versions, RabbitMQ routes, the Kafka copy, and delivery policies.

Reporter has **17 emitted business-event definitions**. They are **CloudEvents 1.0** binary-mode messages. Every event travels over RabbitMQ when `STREAMING_ENABLED=true`. When `STREAMING_KAFKA_BROKERS` is also set, the worker publishes `report.finished` and `report.partial` to Kafka as well. When streaming is off, Reporter publishes no events.

## Envelope and routing

Every event uses `ce-source` `reporter` and a source-qualified `ce-type` in the form `studio.lerian.reporter.<resource>.<event>`. The payload is JSON with `snake_case` keys.

| Contract item | Value |
| - | - |
| Exchange | Value of `RABBITMQ_REPORT_EVENTS_EXCHANGE` |
| AMQP routing key | Definition key exactly, such as `report.finished` |
| Kafka topic | `lerian.streaming.reporter`, for `report.finished` and `report.partial` only, when `STREAMING_KAFKA_BROKERS` is set |
| Content type | `application/json` |
| Delivery mode | Persistent AMQP message |
| Resource type | `template`, `report`, `deadline`, or `regulatory` |
| Subject | Template, report, or deadline ID. For `regulatory.version_adopted`, the regulatory document ID |
| Tenant | Context tenant in `ce-tenantid` and `X-Tenant-ID`; `default` in single-tenant mode |
| Manifest | [`GET /v1/streaming/events`](/en/reference/products/reporter/get-streaming-events) |

Both copies carry the same `ce-id`.

Use the [shared envelope](/en/reference/events/overview) for the complete CloudEvents header contract.

## Delivery semantics

Reporter emits after the business-state change has committed. Publication errors do not fail the underlying operation.

* **Important:** direct publication, with durable outbox fallback when the broker circuit is open.
* **Critical:** Reporter skips direct publication. It always persists the event to the durable outbox for dispatch and retry.
* Both policies request `on_routable_failure`, but the routes define no explicit DLQ destination. The publisher sees a routable failure. No copy goes to a dead-letter route.
* Broker delivery is at least once. Consumers must be idempotent and deduplicate with `(ce-source, ce-id)`.

## Emitted event catalog

| Definition key | Emitted by | Policy | Schema | Fires when |
| - | - | - | - | - |
| `template.created` | Manager | Important | `1.0.0` | Template file and metadata are persisted. |
| `template.updated` | Manager | Important | `1.0.0` | A template update and any file replacement complete, or a report-family assignment changes the template's category. |
| `template.deleted` | Manager | Important | `1.0.0` | A template deletion completes; create rollback does not emit it. |
| `report.requested` | Manager | Important | `1.0.0` | A report created through `POST /v1/reports` or by the deadline trigger is persisted as `Processing`, before manager publishes the worker command. It does not prove that the command was queued. A regulatory filing request does not emit it. |
| `report.finished` | Worker | Critical | `2.0.0` | The artifact is stored and the `Finished` status is committed. |
| `report.partial` | Worker | Critical | `2.0.0` | The artifact is stored and the `Partial` status is committed. |
| `report.errored` | Manager and worker | Critical | `2.0.0` | An `Error` status is committed: the worker run failed, manager could not queue the command of a report created through `POST /v1/reports` or by the deadline trigger, or manager found that the worker stopped sending heartbeats. |
| `deadline.created` | Manager | Important | `1.0.0` | A deadline is persisted. |
| `deadline.updated` | Manager | Important | `1.0.0` | A deadline update is persisted and the updated record is loaded. |
| `deadline.deleted` | Manager | Important | `1.0.0` | A deadline soft delete is persisted. |
| `deadline.delivered` | Manager | Critical | `1.0.0` | The delivery mark is persisted. |
| `deadline.delivery_reverted` | Manager | Critical | `1.0.0` | The delivery mark is removed. |
| `deadline.due` | Manager | Critical | `1.0.0` | The deadline trigger announces an occurrence whose day arrived. Requires `DEADLINE_TRIGGER_ENABLED=true`. |
| `deadline.generation_failed` | Manager | Critical | `1.0.0` | The trigger announced an occurrence, and the report it had to generate for a category in `DEADLINE_TRIGGER_GENERATE_CATEGORIES` was refused or failed. |
| `regulatory.draft_ready` | Worker | Critical | `1.0.0` | A regulatory draft and its file are stored and ready for review. `template_id` is an empty string when a subscription generated the draft. |
| `regulatory.filing_approved` | Manager | Critical | `1.0.0` | A person approved a regulatory draft, and it is `Final`. Deliver the filing from this event. |
| `regulatory.version_adopted` | Manager | Critical | `1.0.0` | A subscription moves to another version of its regulatory document. Adopting the version already in force emits nothing. |

A regulatory filing emits `regulatory.draft_ready` instead of `report.finished`. A failed filing run emits `report.errored`.

## Event identifiers

Reporter sets a deterministic `ce-id` on these events:

| Event | `ce-id` |
| - | - |
| `report.finished`, `report.partial` | `reporter.report.<status>.<report_id>`, with `finished` or `partial` |
| `report.errored` | `reporter.report.error.<report_id>` |
| `deadline.delivered` | `reporter.deadline.delivered.<deadline_id>.<delivered_at>` |
| `deadline.delivery_reverted` | `reporter.deadline.delivery_reverted.<deadline_id>.<reverted_at>` |
| `deadline.due` | `reporter.deadline.due.<deadline_id>.<occurrence_at>` |
| `deadline.generation_failed` | `reporter.deadline.generation_failed.<deadline_id>.<occurrence_at>` |
| `regulatory.draft_ready` | `<report_id>:draft:1` |
| `regulatory.filing_approved` | `<report_id>:approved` |
| `regulatory.version_adopted` | `<document_id>:<adopted_version>:<tenant_id>` |

Every `report.errored` variant uses the same `ce-id`. A consumer deduplicating on `(ce-source, ce-id)` therefore keeps only the first `report.errored` received for a `report_id`. Template events, `report.requested`, and deadline create, update, and delete events carry a generated identifier.

## Complete `data` contracts

These TypeScript-style declarations mirror the JSON wire shape. `?` means the property is optional. `| null` means the property is present but can be JSON `null`.

```typescript theme={null}
type RFC3339 = string
type UUID = string

type TemplateCreatedDataV1 = {
  template_id: UUID
  output_format: string
  description: string
  file_name: string
  category: string
  mapped_datasource_keys: string[]
  mapped_fields_count: number
  created_at: RFC3339
}

type TemplateUpdatedDataV1 = {
  template_id: UUID
  output_format: string
  description: string
  category: string
  updated_fields: string[]
  file_replaced: boolean
  updated_at: RFC3339
}

type TemplateDeletedDataV1 = {
  template_id: UUID
  hard_delete: boolean
  cascaded_deadlines_deleted: number
  deleted_at: RFC3339
}

type ReportRequestedDataV1 = {
  report_id: UUID
  template_id: UUID
  output_format: string
  status: string
  request_id: string
  filter_datasource_count: number
  template_description: string
}

type ReportFinishedDataV2 = {
  report_id: UUID
  template_id: UUID
  output_format: string
  status: string
  artifact_object_key: string
  artifact_content_type: string
  document_type: string
  artifact_ttl?: string
  completed_at: RFC3339
  duration_ms: number
  section_count: number
}

type ReportPartialDataV2 = {
  report_id: UUID
  template_id: UUID
  output_format: string
  status: string
  artifact_object_key: string
  artifact_content_type: string
  document_type: string
  section_failures: string[]
  completed_at: RFC3339
  duration_ms: number
  section_count: number
  failed_section_count: number
}

type ManagerReportErroredDataV2 = {
  report_id: UUID
  status: string
  error_code: "report_generation_failed" | "report_worker_lost"
  error_summary: string
  completed_at: RFC3339
}

type WorkerTerminalReportErroredDataV2 = {
  report_id: UUID
  template_id: UUID
  output_format: string
  status: string
  error_code: "report_generation_failed"
  error_summary: "All report data sections failed"
  document_type: string
  document_id: string
  document_version: string
  completed_at: RFC3339
  duration_ms?: number
}

type WorkerFunnelReportErroredDataV2 = {
  report_id: UUID
  status: string
  error_code:
    | "report_generation_failed"
    | "report_generation_timeout"
    | "report_generation_canceled"
  error_summary: string
  document_type: string
  document_id: string
  document_version: string
  completed_at: RFC3339
}

type ReportErroredDataV2 =
  | ManagerReportErroredDataV2
  | WorkerTerminalReportErroredDataV2
  | WorkerFunnelReportErroredDataV2

type DeadlineCreatedDataV1 = {
  deadline_id: UUID
  name: string
  type: string
  template_id: UUID | null
  template_name: string
  due_date: RFC3339
  frequency: string
  months_of_year: number[] | null
  active: boolean
  notify_days_before: number
  color: string
  status_snapshot: string
  created_at: RFC3339
}

type DeadlineUpdatedDataV1 = {
  deadline_id: UUID
  updated_fields: string[]
  template_id: UUID | null
  template_name: string
  due_date: RFC3339
  frequency: string
  months_of_year: number[] | null
  active: boolean
  status_snapshot: string
  updated_at: RFC3339
}

type DeadlineDeletedDataV1 = {
  deadline_id: UUID
  soft_delete: boolean
  deleted_at: RFC3339
}

type DeadlineDeliveredDataV1 = {
  deadline_id: UUID
  template_id: UUID | null
  template_name: string
  type: string
  due_date: RFC3339
  delivered_at: RFC3339 | null
  status_snapshot: string
  frequency: string
  next_occurrence: RFC3339 | null
  updated_at: RFC3339
}

type DeadlineDeliveryRevertedDataV1 = {
  deadline_id: UUID
  template_id: UUID | null
  template_name: string
  type: string
  due_date: RFC3339
  reverted_at: RFC3339
  previous_delivered_at: RFC3339 | null
  status_snapshot: string
  frequency: string
  updated_at: RFC3339
}

type DeadlineDueDataV1 = {
  deadline_id: UUID
  template_id: UUID | null
  type: string
  category?: string
  due_date: RFC3339
  frequency: string
  occurrence_at: RFC3339
}

type DeadlineGenerationFailedDataV1 = {
  deadline_id: UUID
  template_id: UUID | null
  category?: string
  occurrence_at: RFC3339
  retryable: boolean
  reason:
    | "business_refusal"
    | "budget_exceeded"
    | "sweep_cancelled"
    | "transient"
    | "unknown"
  error_summary: string
  failed_at: RFC3339
}

type RegulatoryDraftReadyDataV1 = {
  report_id: UUID
  document_id: string
  document_version: string
  template_id: string
  output_format: string
  draft_version: number
  required_gaps_count: number
  requested_by: string
  generated_at: RFC3339
}

type RegulatoryFilingApprovedDataV1 = {
  report_id: UUID
  document_id: string
  document_version: string
  template_id: string
  output_format: string
  artifact_object_key: string
  artifact_sha256: string
  artifact_size_bytes: number
  draft_version: number
  delivery_attempt: number
  parameters: Record<string, string>
  corrections_count: number
  corrected_by: string
  corrected_at: string
  approved_by: string
  approved_at: RFC3339
}

type RegulatoryVersionAdoptedDataV1 = {
  document_id: string
  previous_version: string
  adopted_version: string
  adopted_by: string
  adopted_at: RFC3339
  binding_gaps_count: number
  mapping_broken: boolean
}
```

`document_type` carries the template category. It holds an empty string on the worker failure variant that carries no `template_id`. Treat an empty value as no category. `document_id` and `document_version` on `report.errored` name the regulatory document when a subscription generated the report, and are empty strings otherwise.

`artifact_object_key` on `report.finished`, `report.partial`, and `regulatory.filing_approved` is the storage key of the file exactly as Reporter wrote it, and it is never empty. Use it as is. Do not rebuild it from other fields. On `regulatory.filing_approved`, verify the stored object against `artifact_sha256` before you send it. `parameters` carries the generation parameters without the ones that start with `system.`.

`binding_gaps_count` on `regulatory.version_adopted` counts the fields of the adopted version that the existing mapping leaves unmapped. The `mapping_broken` field is `true` when Reporter could not assess the existing mapping against the adopted version. In that case, `binding_gaps_count` is 0.

## Separate internal command rail

Manager sends worker a non-CloudEvents JSON command on RabbitMQ. It uses `RABBITMQ_EXCHANGE`, `RABBITMQ_GENERATE_REPORT_KEY`, and `RABBITMQ_GENERATE_REPORT_QUEUE`, with persistent delivery. This command is not part of the public event catalog, and its shape is not a public contract.

## Inbound event status

Reporter consumes no public business event. Its Hub subscriber is unavailable: enabling it is rejected at startup.


# Adopt another version of the subscribed document
Source: https://docs.lerian.studio/en/reference/products/reporter/adopt-document-version

/en/openapi/v3-current/reporter.yaml post /v1/regulatory/subscriptions/{subscriptionId}/adopt
Moves the subscription's pin to another catalog version — a DELIBERATE act: a release published upstream changes nothing here until somebody adopts it. The new version is fetched from the origin, verified and materialized BESIDE the old copy, never over it, so every report already generated stays explainable by its provenance. The answer carries what the new version does to the EXISTING mapping: its readiness against the adopted contract, the exact reason when it no longer plans at all (as information — the adoption stands), and how much of the new reference mapping it already agrees with. Omitting version adopts the newest the origin has; adopting the version already in force re-materializes the copy and leaves the history untouched.



# Approve a draft as the filing
Source: https://docs.lerian.studio/en/reference/products/reporter/approve-regulatory-report

/en/openapi/v3-current/reporter.yaml post /v1/regulatory/reports/{reportId}/approve
Requires the 'regulatory-approval' permission, which is deliberately NOT the one that generates and corrects — that separation is what lets a client put approval in a second pair of hands. Freezes the draft as Final — the file a person accepted, at the version they read (If-Match, required). A draft with a REQUIRED field still blank is refused with 409: an incomplete file must never become the filing. A second approval of the same version by the SAME approver answers 200 again — that is a retry, and the report is approved either way; by a DIFFERENT approver it is refused, because the record would otherwise name whoever won a race. A different version is a conflict, because what they read is not what they would be approving. After approval nothing changes it: corrections are refused and the provenance is frozen for good.



# Check the mapping against the databases as they are now
Source: https://docs.lerian.studio/en/reference/products/reporter/check-mapping-readiness

/en/openapi/v3-current/reporter.yaml get /v1/regulatory/subscriptions/{subscriptionId}/gaps
Re-runs the readiness check: every query with the table it named and the table the database has, every column marked found or not, and every field of the document nothing fills yet. Its own operation because the answer changes without the mapping changing — a table is created, a column renamed, a database comes back up.



# Correct a draft and re-render it
Source: https://docs.lerian.studio/en/reference/products/reporter/correct-regulatory-report

/en/openapi/v3-current/reporter.yaml post /v1/regulatory/reports/{reportId}/overrides
Applies corrections to a regulatory draft and re-renders the file from the SAME rows the draft was generated from — correcting one field never re-extracts, so no other number moves under the reviewer; new data is a new generation. If-Match must carry the draft version the caller read (the report's draftVersion): a stale version is refused with 409 naming both, and without the header the request is refused with 428. Every correction goes through the contract's own rules — type, scale, pattern, and the row it names must exist, exactly one of it — and a correction that does not fit is refused with nothing changed. A correction may not name a field that identifies a row of its set: that would re-identify the row rather than correct a value in it, leaving the recorded trail pointing at a row that no longer exists, so it is refused and the mapping or the source is what gets fixed. The answer carries the new draft version in the ETag and the fields still unfilled.



# Generate a filing of a subscribed document
Source: https://docs.lerian.studio/en/reference/products/reporter/create-regulatory-report

/en/openapi/v3-current/reporter.yaml post /v1/regulatory/reports
Asks the worker to generate one filing: the binding in force is frozen into the request, the version is the one the subscription pinned, and the report comes out a DRAFT a person corrects and approves. The answer carries the fields nothing fills yet, so the blanks in the draft arrive expected rather than looking broken. Everything refusable cheaply is refused here: an inactive subscription, a missing required parameter, a binding that no longer plans.



# Activate a regulatory document
Source: https://docs.lerian.studio/en/reference/products/reporter/create-subscription

/en/openapi/v3-current/reporter.yaml post /v1/regulatory/subscriptions
Activates a document for this tenant, pinning the catalog version in force today, and writes the starting binding — the catalog's reference mapping when one is published, and an empty one when none is. The answer carries the readiness of that starting point: which tables and columns it already finds, and which fields nothing fills yet. A document already activated is refused with a conflict.



# Stop filing a document
Source: https://docs.lerian.studio/en/reference/products/reporter/deactivate-subscription

/en/openapi/v3-current/reporter.yaml delete /v1/regulatory/subscriptions/{subscriptionId}
Marks the subscription inactive and records when, and who when the request carries an authenticated subject. The record is KEPT — reports already generated point at it, and its mapping and adopted version stay with it, so reactivating brings them back as they were. The document also becomes available to subscribe to afresh, which starts a NEW subscription from the catalog's reference mapping. Deactivating a subscription that is already inactive changes nothing.



# Get system metrics
Source: https://docs.lerian.studio/en/reference/products/reporter/get-metrics

/en/openapi/v3-current/reporter.yaml get /v1/metrics
Returns aggregate template, report, data-source, and report-error counters.



# Read what a report was made of, frozen
Source: https://docs.lerian.studio/en/reference/products/reporter/get-report-provenance

/en/openapi/v3-current/reporter.yaml get /v1/regulatory/reports/{reportId}/provenance
Answers the report's provenance: which document at which pinned version, under which subscription, with which binding version and generation parameters, and the SHA-256 of the artifact that was stored. It is what answers, months later, why the filing says what it says — and whether the file in hand is the file that was approved. A custom report has none and answers 404.



# Get the streaming event manifest
Source: https://docs.lerian.studio/en/reference/products/reporter/get-streaming-events

/en/openapi/v3-current/reporter.yaml get /v1/streaming/events
Returns the static catalog of business events Reporter can publish without disclosing broker topology.



# Get one activated document
Source: https://docs.lerian.studio/en/reference/products/reporter/get-subscription

/en/openapi/v3-current/reporter.yaml get /v1/regulatory/subscriptions/{subscriptionId}
Returns the subscription, the version of the document it generates against, and the append-only record of which versions were adopted, by whom and when.



# Get the mapping in force
Source: https://docs.lerian.studio/en/reference/products/reporter/get-subscription-mapping

/en/openapi/v3-current/reporter.yaml get /v1/regulatory/subscriptions/{subscriptionId}/binding
Returns the binding document itself, as YAML, with its version in the ETag. Present that ETag as If-Match to save on top of it.



# Read the trail of corrections
Source: https://docs.lerian.studio/en/reference/products/reporter/list-report-corrections

/en/openapi/v3-current/reporter.yaml get /v1/regulatory/reports/{reportId}/overrides
Answers every correction ever applied to this report, oldest first: who changed which field of which row, from what, to what, and why. Append-only — a correction of a correction is a second entry, never an edit of the first. It is the record that explains to an auditor why a figure in the filing differs from the ledger behind it.



# List the documents this tenant files
Source: https://docs.lerian.studio/en/reference/products/reporter/list-subscriptions

/en/openapi/v3-current/reporter.yaml get /v1/regulatory/subscriptions
Returns the tenant's subscriptions, newest first. A cancelled one is kept and listed as inactive: reports already generated point at it, and their provenance has to stay readable.



# Reactivate a deactivated subscription
Source: https://docs.lerian.studio/en/reference/products/reporter/reactivate-subscription

/en/openapi/v3-current/reporter.yaml post /v1/regulatory/subscriptions/{subscriptionId}/reactivate
Switches a deactivated subscription back on, with the mapping the tenant edited and the version they adopted exactly as they were left — the way back that subscribing again is not, since that starts a new subscription from the catalog's reference mapping. Records who reactivated it and when. Refused with a conflict while ANOTHER subscription of the same document is active: a document is filed by one subscription at a time, and the refusal names the one holding the slot. Reactivating a subscription that is already active answers it unchanged.



# Replace the mapping
Source: https://docs.lerian.studio/en/reference/products/reporter/replace-subscription-mapping

/en/openapi/v3-current/reporter.yaml put /v1/regulatory/subscriptions/{subscriptionId}/binding
Replaces the binding with the document in the request body, IF If-Match carries the version the caller read. Without If-Match the request is refused with 428: saving a mapping without saying what you were editing is how one person's afternoon disappears. A stale version is refused with 409 naming both versions. The body is capped at 262144 bytes and a larger one is refused with 413 before it is parsed. The answer carries the new version and what the mapping just written can and cannot read.



# Reporter error list
Source: https://docs.lerian.studio/en/reference/products/reporter/reporter-error-list

Reporter returns consistent, structured error responses. Look up error codes, HTTP statuses, and remediation steps to resolve API failures quickly.

**Error format**

Reporter returns errors as RFC 9457 problem details with the `application/problem+json` media type:

```json JSON theme={null}
{
  "type": "https://errors.lerian.studio/v1/RPT-0012",
  "title": "Bad Request",
  "status": 400,
  "detail": "The specified templateID is not a valid UUID. Please check the value passed.",
  "code": "RPT-0012"
}
```

**Field definitions**

* **`type`** – A URI that identifies the error in the Lerian error catalog. Built as `https://errors.lerian.studio/v1/<code>`.
* **`title`** – The HTTP status text (for example, `Bad Request`).
* **`status`** – The HTTP status code.
* **`detail`** – Detailed guidance to help you resolve the error. For `5xx` responses, Reporter always sanitizes the detail to `internal error`, so no internal cause leaks. Use `code` to branch programmatically.
* **`code`** – A stable, unique identifier for the error (`RPT-NNNN`). Useful for programmatic handling and support requests.
* **`errors`** – Optional list of per-field validation details, each with a `message` and a `location`.

Some messages contain placeholders such as `%v` or `%s`. Reporter replaces them with the specific values from your request.

## Reporter errors

***

The tables below list the errors that can occur when you call the Reporter endpoints, what each one means, and how to resolve it.

## 400: Validation errors

***

| `code` | Description | `detail` |
| - | - | :- |
| RPT-0001 | Missing required fields | One or more required fields are missing. Please ensure all required fields are included. |
| RPT-0002 | Invalid file format | The uploaded file must be a .tpl file. Other formats are not supported. |
| RPT-0003 | Invalid output format | The outputFormat field must be one of: html, csv, pdf, txt, or xml. |
| RPT-0004 | Invalid header | One or more header values are missing or incorrectly formatted. Please verify required headers %v. |
| RPT-0005 | Invalid File Uploaded | The file you submitted is invalid. Please check the uploaded file with error: %v |
| RPT-0006 | Error File Empty | The file you submitted is empty. Please check the uploaded file. |
| RPT-0007 | Error File Content Invalid | The file content is invalid because is not %s. Please check the uploaded file. |
| RPT-0008 | Invalid Map Fields | The field on template file is invalid. Invalid field %s on %s. |
| RPT-0009 | Invalid Path Parameter | Path parameters is in an incorrect format. Please check the following parameter %v and ensure they meet the required format before trying again. |
| RPT-0010 | Update Output format without template File | Can not update output format without passing template file. Please check information passed and try again. |
| RPT-0012 | Invalid templateID | The specified templateID is not a valid UUID. Please check the value passed. |
| RPT-0013 | Invalid ledgerID | The specified ledgerID inside ledger ID list is not a valid UUID. Please check the value passed %v. |
| RPT-0014 | Missing required fields | The fields mapped on template file are missing in the table schema or may be empty. Please check the fields passed: '%v'. |
| RPT-0015 | Unexpected Fields in the Request | The request body contains more fields than expected. Please send only the allowed fields as per the documentation. The unexpected fields are listed in the fields object. |
| RPT-0016 | Missing Fields in Request | Your request is missing one or more required fields. Please refer to the documentation to ensure all necessary fields are included in your request. |
| RPT-0017 | Bad Request | The server could not understand the request due to malformed syntax. Please check the listed fields and try again. |
| RPT-0019 | Invalid Query Parameter | One or more query parameters are in an incorrect format. Please check the following parameters '%v' and ensure they meet the required format before trying again. |
| RPT-0023 | Invalid Date Range Error | Both 'initialDate' and 'finalDate' fields are required and must be in the 'yyyy-mm-dd' format. Please provide valid dates and try again. |
| RPT-0024 | Pagination Limit Exceeded | The pagination limit exceeds the maximum allowed of %v items per page. Please verify the limit and try again. |
| RPT-0025 | Invalid Sort Order | The 'sort\_order' field must be 'asc' or 'desc'. Please provide a valid sort order and try again. |
| RPT-0026 | Metadata Key Length Exceeded | The metadata key %v exceeds the maximum allowed length of %v characters. Please use a shorter key. |
| RPT-0027 | Metadata Value Length Exceeded | The metadata value %v exceeds the maximum allowed length of %v characters. Please use a shorter value. |
| RPT-0028 | Invalid Metadata Nesting | The metadata object cannot contain nested values. Please ensure that the value %v is not nested and try again. |
| RPT-0030 | Missing Schema Table | The schema table %v is missing for data source '%v'. Please check the information passed. |
| RPT-0031 | Missing Data Source Table | The data source %v is missing. Please check the value passed. |
| RPT-0032 | Script Tag Detected | The template file contains a script tag and is not allowed. Please check the template file and try again. |
| RPT-0035 | Ambiguous Schema Reference | The table '%v' exists in multiple schemas: %v. Qualify it with its schema, as schema\_\_%v. |
| RPT-0036 | Schema Not Found | The schema '%v' was not found in database '%v'. Please verify the schema name. |
| RPT-0037 | Table Not Found in Schema | The table '%v' was not found in schema '%v' of database '%v'. Please verify the table name and schema. |
| RPT-0038 | Database Not Registered | The database '%v' is not registered. Please verify the datasource configuration. |
| RPT-0041 | Bucket Required | The storage bucket name is required. Please check the storage configuration. |
| RPT-0042 | Object Key Required | The object key is required for the storage operation. |
| RPT-0044 | TTL Not Supported | TTL parameter is not supported in S3 mode. Use bucket lifecycle policies instead. |
| RPT-0046 | Invalid Deadline Type | The 'type' field must be 'regulatory' or 'custom'. Please provide a valid deadline type and try again. |
| RPT-0047 | Invalid Deadline Frequency | The 'frequency' field must be one of: 'once', 'daily', 'weekly', 'monthly', 'semiannual', 'annual'. Please provide a valid frequency and try again. |
| RPT-0048 | Invalid Deadline Color | The 'color' field must be a valid hex color code (e.g., '#FF5733'). Please provide a valid color and try again. |
| RPT-0050 | Months of Year Not Applicable | The 'monthsOfYear' field is not applicable for frequency '%v'. It can only be used with 'semiannual' or 'annual' frequencies. |
| RPT-0052 | Months of Year Required | The 'monthsOfYear' field is required for frequency '%v'. Please specify which months of the year the deadline should recur on. |
| RPT-0054 | Months of Year Out of Range | Each value in 'monthsOfYear' must be between 1 and 12. Received invalid value: %v. |
| RPT-0055 | Due Date in the Past | The 'dueDate' must be today or a future date. Please provide a date that is not in the past. |
| RPT-0056 | Months of Year Count Mismatch | The number of months in 'monthsOfYear' does not match the '%v' frequency. 'semiannual' requires exactly 2 months and 'annual' requires exactly 1 month. |
| RPT-0059 | Schema Validation Failed | The schema validation failed. Please verify the fields against the data source schema. |
| RPT-0062 | Invalid UTF-8 Encoding | The '%v' field contains invalid UTF-8 byte sequences. Please provide valid UTF-8 text and try again. |
| RPT-0073 | Data Source Reserved Config Name | The `configName` is reserved for an operator-managed data source and cannot be assigned or renamed through the API. |
| RPT-0075 | CRM Organization Scope Unresolved | The CRM data source organization scope could not be resolved, so the template cannot be safely saved. |
| RPT-0076 | Filter Table Not Extracted | The filter table does not match any table mapped by the report template. Use one of the mapped tables. |
| RPT-0077 | Filter Value Cannot Be Read As A Date | The filter value cannot be read as a date for the field. Use an ISO date or time value appropriate for that field. |
| RPT-0078 | Template File Too Large | The template file exceeds the supported byte limit. Split the report into smaller templates and try again. |
| RPT-0079 | Filter Operators Conflict | The filter combines operators that cannot be used together. Keep one compatible operator for the field. |
| RPT-0080 | Data Source Field Invalid | A data source field is invalid. Correct the identified field and send the request again. |
| RPT-0090 | Template Maps Too Many Columns | The template maps more columns than one report can process. Reduce the mapped columns or split the template. |
| RPT-0095 | Filter Bound Has No Value | A filter operator has no comparable value. Provide a value or remove the operator. |
| RPT-0096 | Filter Costs More Than A Query Can Carry | The filters exceed a query resource limit. Reduce the filter values or narrow the request. |
| RPT-0097 | Filter Operator Carries The Wrong Number Of Values | The filter operator received the wrong number of values. For example, `between` requires exactly two values. |
| RPT-0105 | Filter Value Cannot Be Read Against The Field It Filters | The filter value cannot be read as the type held by the field. Use a compatible value or a date-capable field. |
| RPT-0106 | Invalid Cursor | The cursor was not issued by this API or no longer identifies a usable position. Restart the listing and follow `nextCursor`. |
| RPT-0107 | Template Preview Failed | The template preview could not be rendered. Correct the template or sample data, then try again. The response detail identifies the specific refusal. |
| RPT-0110 | Filter Period Cannot Share Its Field | The filter field uses `period` together with another operator. A period already states both ends of its range. Keep the period alone, or drop it and state both dates yourself. |
| RPT-0111 | Reminder Filter Is Larger Than A Reminder Can Carry | The whole filter of the deadline exceeds what one deadline can store. Split it into more than one deadline, each naming fewer tables. |
| RPT-0112 | Filter Names Something That Cannot Be A Name | A filter key cannot name a data source, a table, or a field. Correct the key. If an automation filled it, check the variable that feeds it. |
| RPT-0120 | Template Category Is Required | The template has no category. Send `category` with the family the report is filed under, such as `cadoc`. |
| RPT-0121 | Template Category Is Not A Usable Family Name | The category must match `^[a-z0-9_-]{1,100}$`. Reporter corrects case and surrounding spaces, but refuses an inner space, a dot, a slash, or an accent. |
| RPT-0122 | Template Has No Category | The deadline names a template that has no category. File the template under a category, then send the deadline again unchanged. |
| RPT-0123 | Too Many Templates In One Category Association | The request associates a category with more templates than one request can carry. Split the work into smaller batches. |
| RPT-0124 | Category Association Names No Template | The request names no template. Send `templateIds` with at least one template ID. |
| RPT-0130 | Invalid Deadline Timezone | The `timezone` field must be a valid IANA time zone name, such as `America/Sao_Paulo`. |
| RPT-0131 | Filter Period Is Not A Known Window | The `period` value is not a window Reporter knows. Spell one of the windows the detail lists, exactly as written. |
| RPT-0134 | Filter Condition Has No Operator | A filter field names no operator, so it would narrow the report by nothing. State an operator with its values, or remove the field from the filter. |
| RPT-0135 | Data Source Uses A Reserved Name | The name `system` is reserved for the report's generation parameters. Choose another `configName`. |
| RPT-0137 | Invalid Document Contract | The regulatory document contract cannot be loaded. The detail names the point to correct. |
| RPT-0138 | Value Rejected By The Document Contract | A value produced for a field is not allowed by the document contract. Correct the binding or the data behind it, then generate the report again. |
| RPT-0139 | Regulatory Document Not In This Catalog | The template refers to a regulatory document this deployment does not carry. Name a document from the catalog. |
| RPT-0140 | Missing Or Invalid Generation Parameter | A generation parameter the template declares is missing or invalid, or the template declares a parameter that is malformed. Correct the request's `parameters` or the declaration. |
| RPT-0141 | Template Marks A Position The Contract Does Not Declare | The template marks a field that the regulatory document contract does not declare. Correct the name in the template. |
| RPT-0142 | A Regulatory Template Is Not Uploaded | A curated regulatory document takes its layout from the catalog, so no template file is uploaded for it. Supply the document and its data source, or create a custom report. |
| RPT-0143 | Invalid Document Binding | The document binding cannot be read. The detail names the point to correct. Correct it and save the binding again. |
| RPT-0146 | Invalid Subscription | The subscription cannot be used as it stands. The detail names what to correct. |
| RPT-0149 | The Correction Cannot Be Applied | The correction is not valid for its position in the document. Correct it at the named position and apply it again. |
| RPT-0153 | The Report's Provenance Is Incomplete | The report's frozen provenance record is missing a required element, so Reporter refused to record it. The detail names the element. |
| RPT-0154 | The Catalog Content Is Not What Was Published | The catalog release failed its integrity check and was refused. The catalog in force is unchanged. Check the release and the path it came by. |
| RPT-0155 | The Regulatory Release Cannot Be Fetched | The catalog origin could not supply the document's files, so nothing was written. Try again when the origin answers. Documents already subscribed are unaffected. |
| RPT-0165 | Template Has A Recursive Macro | A macro in the template calls itself, directly or through another macro, so rendering would never finish. Break the loop and upload the template again. |
| RPT-0166 | Template Formats An Amount And Then Alters It | The template writes another filter after the `decimal` filter, which would put a wrong amount in the file. Move the other filter before `decimal`, or drop it. |
| RPT-0169 | The Institution Is Invalid | A field of the institution is invalid: a blank name, a CNPJ whose check digits fail, or a malformed scope. Correct the field and send the institution again. |
| RPT-0173 | No Midaz Organization Table | None of the named data sources holds the Midaz organization table, so there is no organization to propose an institution for. Name the data source of the Midaz onboarding database. |
| RPT-0174 | The Data Source Is Not PostgreSQL | Reporter proposes institutions only from Midaz PostgreSQL databases. Leave the data source out, or name the data source of the Midaz onboarding database. |
| RPT-0175 | More Than One Midaz Organization Table | The named data sources hold more than one Midaz organization table. Name only the data source of the Midaz onboarding database. |
| RPT-0180 | Choose The Institution | The tenant has several institutions and the request names none. Set `institution` to one institution ID, or to `all` to read every institution's rows in one report. |
| RPT-0181 | The Institution Does Not Cover This Table | The report reads a table that the institution's scope neither filters nor marks as shared. Add the table to the institution's scope, then request the report again. |
| RPT-0183 | The Institution Selection Is Invalid | The `institution` value is neither an institution ID nor `all`, or it is `all` on a regulatory filing, which declares exactly one institution. |
| RPT-0190 | Choose The Institution That Files | A regulatory filing declares exactly one institution. The request names none, and the tenant does not have exactly one. Name the institution that files it, also on the subscription when the subscription predates institutions, and register one first if the tenant has none. |

### RPT-0075: CRM Organization Scope Unresolved

`RPT-0075` is a fail-closed protection for templates that map `plugin_crm`. Reporter does not save or run an unscoped CRM mapping because that could expose records across Midaz organizations. It can occur while importing, creating, or updating a CRM template, and when a worker resolves an already-saved CRM template.

Do not treat this code as proof that one environment variable is absent. It also occurs when Reporter cannot look up `plugin_crm` in the datasource registry. First confirm that the template maps `plugin_crm`, then check the Manager and worker configuration, registry availability, and the non-sensitive CRM connection settings.

For a self-hosted deployment, configure the complete `DATASOURCE_CRM_*` block, including `DATASOURCE_CRM_MIDAZ_ORGANIZATION_ID`, and keep the CRM password and `CRYPTO_HASH_SECRET_KEY_CRM` / `CRYPTO_ENCRYPT_SECRET_KEY_CRM` in Secrets. Those crypto keys must be the same keys used by CRM, and `DATASOURCE_CRED_ENC_KEY` must remain stable. At Manager startup, the reserved datasource seed can fill an absent or empty `metadata.midazOrganizationId`. The seed never overwrites a non-empty persisted value.

Do not create or PATCH `plugin_crm` through the ordinary datasource API. If a non-empty persisted organization ID is incorrect, stop the generic recovery and contact Lerian support. After an approved change, import or save the template, generate a report, confirm CRM fields decrypt, and verify organization isolation. See [Reporter via Helm](https://github.com/LerianStudio/helm/tree/main/charts/reporter) for the chart values.

## 401: Unauthorized

***

| `code` | Description | `detail` |
| - | - | - |
| RPT-0158 | Acting Subject Not Identified | The request was authorized but does not identify who is acting, and Reporter records each correction and approval against a person. Present a token that carries a subject claim. A deployment with authentication disabled cannot approve filings. |

## 404: Not found

***

| `code` | Description | `detail` |
| - | - | :- |
| RPT-0011 | Entity Not Found | No %v entity was found for the given ID. Please make sure to use the correct ID for the entity you are trying to manage. |
| RPT-0020 | Invalid Date Format Error | The 'initialDate', 'finalDate', or both are in the incorrect format. Please use the 'yyyy-mm-dd' format and try again. |
| RPT-0021 | Invalid Final Date Error | The 'finalDate' cannot be earlier than the 'initialDate'. Please verify the dates and try again. |
| RPT-0022 | Date Range Exceeds Limit Error | The range between 'initialDate' and 'finalDate' exceeds the permitted limit of %v months. Please adjust the dates and try again. |
| RPT-0043 | Object Not Found | The requested object was not found in storage. |
| RPT-0057 | Data Source Not Found | The requested data source was not found. Please verify the data source ID. |
| RPT-0147 | Regulatory Document Unavailable | The regulatory document is not in this deployment's catalog, or the deployment has no catalog. List the catalog to see which documents it carries. |

## 409: Conflicts

***

| `code` | Description | `detail` |
| - | - | :- |
| RPT-0039 | Duplicate Request In Flight | A duplicate request is currently being processed. Please wait and try again. |
| RPT-0040 | Idempotency Conflict | A request with this idempotency key has already been processed. |
| RPT-0045 | Duplicate Deadline | A deadline with the same name, type, due date, and frequency already exists. Please use different values or update the existing deadline. |
| RPT-0071 | Data Source Config Name Conflict | A data source with the same `configName` already exists. Use a different `configName` and try again. |
| RPT-0072 | Data Source In Use By Template | The data source is referenced by templates and cannot be deleted or renamed. Update or remove those templates first. |
| RPT-0144 | The Binding Changed While You Were Editing | Someone saved the binding after you opened it. Reload the binding, apply your change on top, and save again. |
| RPT-0145 | The Document Is Already Subscribed | The institution already files this document under another subscription. Edit that subscription's binding, or cancel it first. |
| RPT-0150 | The Draft Changed While You Were Editing | Someone corrected the draft after you opened it. Reload the draft, apply your correction on top, and try again. |
| RPT-0151 | The Report Is Already Approved | An approved report does not change. To file something different, generate a new report. |
| RPT-0152 | The Report Is Not A Draft | A correction applies only to a draft. The report is still generating, or its generation failed. |
| RPT-0156 | Draft Has Required Fields Still Blank | Required fields in the draft carry no value. Fill each one with a correction, then approve or download the draft. |
| RPT-0167 | Another Subscription Of The Document Is Active | Another subscription already files this document for the same institution. Deactivate that subscription first, or leave this one inactive. |
| RPT-0168 | Data Source Built In | The platform provides this data source and it is read-only. You cannot update, delete, or test it, or register another data source under its name. |
| RPT-0170 | The CNPJ Is Already Registered | The tenant already registered an institution with this CNPJ. Edit that institution, or delete it first. |
| RPT-0171 | The Institution Changed While You Were Editing | Someone updated the institution after you read it. Read it again, apply your change on top, and save with the ETag it answers. |
| RPT-0182 | The Institution Is In Use | Deadlines or active regulatory subscriptions still generate reports for this institution. Point the deadlines at another institution or delete them, deactivate the subscriptions, and delete the institution again. |
| RPT-0191 | The Subscription Changed While You Were Editing | Someone changed the subscription after you read it. Read it again and write with the version it answers. |

## 412: Precondition failed

***

| `code` | Description | `detail` |
| - | - | - |
| RPT-0074 | Data Source Credential Protection Not Configured | Credential protection is not configured. Set `DATASOURCE_CRED_ENC_KEY` and retry. |

## 422: Unprocessable

***

| `code` | Description | `detail` |
| - | - | :- |
| RPT-0029 | Report status not Finished | The Report is not ready to download. Report is processing yet. |
| RPT-0157 | Stored Artifact Does Not Match Its Provenance | The stored file's checksum does not match the checksum frozen when the report was rendered, so Reporter does not hand the file out. Regenerate the report, or investigate the storage. |

## 428: Precondition required

***

| `code` | Description | `detail` |
| - | - | - |
| RPT-0148 | The Binding Version Is Required | Saving a binding requires the `If-Match` header with the ETag from the last read. Read the binding again and save with that ETag. |
| RPT-0172 | The Institution Version Is Required | Updating an institution requires the `If-Match` header with the ETag from the last read. Read the institution again and save with that ETag. |
| RPT-0192 | The Subscription Version Is Required | Changing a subscription requires the `If-Match` header with the version from the last read. Read the subscription again and write with that version. |

## 429: Too many requests

***

| `code` | Description | `detail` |
| - | - | :- |
| RPT-0108 | Template Preview Busy | All configured concurrent template preview slots are in use. The template was not rejected; try the preview again shortly. |

## 500: Server errors

***

| `code` | Description | `detail` |
| - | - | :- |
| RPT-0018 | Internal Server Error | internal error |
| RPT-0034 | Communication Error with SeaweedFS | internal error |

> [!NOTE]
>
> Every unexpected failure during synchronous endpoint handling surfaces as HTTP 500. The response carries `code: RPT-0018`, or `code: RPT-0034` when the file storage fails, and a sanitized `internal error` detail. Internal causes never leak into the response body. Asynchronous worker and report-generation failures instead follow the report statuses and metadata described below. Reporter does not return them to the original request as HTTP 500.

## Report-generation errors (asynchronous)

***

Report generation runs asynchronously in the worker. The original HTTP request never receives a failed data-extraction section. The report ends with status `Error` when all sections fail, or `Partial` when some fail.

In either case, `metadata.error_code` is `RPT-0060`. The keys of `metadata.sections` are database names. Each failed entry contains its classified `error_code` (`RPT-0018` for an untyped failure). An `RPT-0075` entry also carries a `remediation` message.

Other worker failures end with status `Error` and a safe non-RPT `metadata.error_code` of `report_generation_failed`, `report_generation_timeout`, `report_generation_canceled`, or `report_message_schema_unsupported`. These failures have no `sections` map and do not retain the underlying RPT code. A report whose worker stopped reporting that it was alive ends with status `Error` and `metadata.error_code` `RPT-0160`.

| `code` | Description | Meaning |
| - | - | :- |
| RPT-0058 | Data Source Unavailable | The data source is currently unavailable. Results may be incomplete. |
| RPT-0060 | Extraction Job Failed | The extraction job failed. Please try again later or contact support. |
| RPT-0061 | Template Rendering Failed | The template could not be rendered with the provided data. This is a permanent error and will not succeed on retry. |
| RPT-0063 | CRM Hash Key Not Configured | CRM hash key not configured. |
| RPT-0064 | CRM Encrypt Key Not Configured | CRM encrypt key not configured. |
| RPT-0065 | Record Decryption Failed | Record decryption failed. |
| RPT-0066 | Cipher Init Failed | Cipher initialization failed. |
| RPT-0067 | Invalid Extracted Data | The extracted data is invalid. |
| RPT-0068 | Unexpected Collection Result | The data collection returned an unexpected result. |
| RPT-0069 | Data Source Not Found | The data source referenced by the report was not found. |
| RPT-0070 | Data Source Unavailable | The data source was unavailable during extraction. |
| RPT-0136 | Unsupported Report Message Schema Version | The worker received a report message written for a newer schema version than it supports, and refused it. The report ends with status `Error` and `metadata.error_code` `report_message_schema_unsupported`. Generate the report again once every worker runs the newer build. |
| RPT-0160 | Report Worker Lost | The worker that owned the report stopped reporting that it was alive, so Reporter ended the report with status `Error`. Look for a stopped or frozen worker. |
| RPT-0161 | Row Ceiling Exceeded | A data section matched more rows than the data source's configured row ceiling. The section fails instead of returning a truncated result. Narrow the report filter or raise the data source's row ceiling. |
| RPT-0162 | Data Source Query Timeout | A data section's query did not finish within the data source's configured query timeout. Narrow the report filter or raise the data source's query timeout. |

## Scheduled generation errors (logged)

***

The deadline scheduler raises these codes. It runs in the Manager when `DEADLINE_TRIGGER_ENABLED=true`. It answers no request, so the codes appear only in its log lines, never in an HTTP response. Each code is in the `error_code` field of its log line, except RPT-0113, which appears only in the `error` field. When a refusal cannot clear by retrying, a second line reports it with `error_code` `RPT-0118` and carries the original code in `error`.

| `code` | Description | Meaning |
| - | - | - |
| RPT-0113 | Reminder Names No Template To Read A Family From | The deadline came due but names no template, so there is no report family to generate. The occurrence is still announced. If the deadline should produce a report, give it a `templateId` whose template has a category. |
| RPT-0114 | Template Has No Family At Dispatch | The deadline's template has no category when the scheduler dispatches it, so no report is generated. File the template under a category. |
| RPT-0115 | Scheduled Generation Could Not Verify Its Tenant | The scheduler could not confirm the tenant that owns the deadline, so it wrote nothing. |
| RPT-0116 | Reminder Window Could Not Be Resolved At Dispatch | The scheduler could not resolve the data window of the occurrence, so no report is generated for it. Save the deadline again with a window Reporter knows. |
| RPT-0117 | Scheduled Report Generation Was Refused | Report generation refused the scheduled request. The log line carries the underlying refusal. |
| RPT-0118 | Scheduled Generation Not Retryable | Qualifies a refusal that repeats on every occurrence until someone changes the deadline, the template, or the filter. |
| RPT-0119 | Scheduled Generation Exhausted | The same refusal repeated on consecutive occurrences, so the scheduler stopped attempting generation for this deadline. The announcement still goes out. |
| RPT-0132 | Scheduled Occurrences Skipped | Occurrences came due and were stepped over when the scheduler advanced. Each skipped occurrence produced no report. This is a notice, not a failure. |
| RPT-0133 | Scheduled Catch-Up Incomplete | The scheduler produced part of a deadline's backlog, and the next run continues from where it stopped. `catch_up_stop_reason` is `tenant_budget_spent` (a warning) or `ceiling_reached` (an error: investigate the delay). |


# Set the institution that files a subscription
Source: https://docs.lerian.studio/en/reference/products/reporter/set-subscription-institution

/en/openapi/v3-current/reporter.yaml put /v1/regulatory/subscriptions/{subscriptionId}/institution
Names the institution that files the subscribed document, IF If-Match carries the subscription version the caller read: without it the request is refused with 428, and a stale version with 409 naming both. A subscription made before filings named an institution generates for the tenant's only one and waits for this when the tenant has none or several. Refused with a conflict while another active subscription of the same document already files for that institution. Reports already generated keep the institution they froze.



# Activate ICP-Brasil certificate on the RSFN (GEN0006)
Source: https://docs.lerian.studio/en/reference/rails/spb/activate-certificate

/en/openapi/v3-current/spb.yaml post /v1/str/certificates/activate
Prerequisite: the certificate must have been rotated first (see rotateCertificate) — its persisted state must be VALID or EXPIRING and carry the recorded serial. Submits a GEN0006 certificate-activation announcement to BACEN for the current OUTBOUND_SIGNING certificate. The submission is persisted with status SUBMITTED before dispatch; BACEN's GEN0006R1 acknowledgment confirms it via NUOp correlation. Idempotent — replaying the same X-Idempotency key with the same body returns the cached response.



# Approve (sign) a parked emission
Source: https://docs.lerian.studio/en/reference/rails/spb/approve-emission

/en/openapi/v3-current/spb.yaml post /v1/str/emission-approvals/{id}/approve
Applies one distinct-actor maker-checker signature to a PENDING_APPROVAL emission. The signer is derived from the bearer token. A signer who already signed (duplicate) or who is the maker (self-approval) is rejected; a sign past the approval deadline or on an already-resolved emission is rejected. When the appended signature reaches the required quorum the emission flips to SUBMITTED and the existing outbox dispatcher liquidates it — no dispatcher change.



# Approve closing a deadline-expired transfer as failed
Source: https://docs.lerian.studio/en/reference/rails/spb/approve-stuck-operation-action

/en/openapi/v3-current/spb.yaml post /v1/str/stuck-operations/actions/{railActionRef}/approve
The checker's step: re-checks, in one transaction, that the transfer is still unanswered in the deadline-expired list, dismisses the case and writes settlement.failed through the outbox exactly once. The requester cannot approve (403); a case already closed answers 409; a transfer BACEN answered meanwhile answers 409 and nothing is emitted.



# Compose and send a curated STR message
Source: https://docs.lerian.studio/en/reference/rails/spb/compose-str-message

/en/openapi/v3-current/spb.yaml post /v1/str/messages/compose
Catalog-gated, maker-checker-routed, per-type CURATED message-compose surface. The chosen capabilityId must be in the compose allowlist (STR0004/STR0005/STR0006/STR0007/STR0008/STR0053), resolve in the catalog, and be PUBLICLY_SUBMITTABLE; otherwise the request is rejected SPB-0003 (HTTP 422). The message builds through the shared compose pipeline and inherits the alçada emission gate: an amount above its band PARKS in PENDING_APPROVAL (visible in GET /v1/str/emission-approvals, emissionApprovalId set) and dispatches on quorum; below band it is SUBMITTED. Idempotent — replaying the same X-Idempotency key returns the same emission. The declared amount is forwarded verbatim; no position is summed.



# Set Conta-PI auto-transfer configuration
Source: https://docs.lerian.studio/en/reference/rails/spb/create-auto-transfer-config

/en/openapi/v3-current/spb.yaml post /v1/str/operations/auto-transfer-config
Prerequisite: the rail must be ready before a submit — an active certificate (see rotateCertificate, activateCertificate), a READY readiness report (see getReadiness), and a passing connectivity test (see createConnectivityTest). Declares the STR's automatic-transfer policy per account class (the platform emits wire code LPI0005): for EACH class (RB/CL and CCME) set exactly ONE of {percent, value} — a value of '0'/'0.00' disables auto-transfer for that class. 'Last message wins': a new config fully replaces the prior one. Persists the last-sent config frame and returns the derived wire code, the submit status, and the NUOp. This means dispatch was accepted, not BACEN confirmation; the STR acknowledges asynchronously (LPI0005R1) and later reports each automatic transfer it performs (LPI0006). Lerian SPB forwards the config values verbatim; it performs NO arithmetic. Idempotent — replaying the same X-Idempotency key with the same body returns the cached response.



# Create bank transfer cancellation operation
Source: https://docs.lerian.studio/en/reference/rails/spb/create-bank-transfer-cancellation-operation

/en/openapi/v3-current/spb.yaml post /v1/str/operations/bank-transfers/{operationId}/cancellations
Prerequisite: the parent operation must exist and admit cancellation — read its state via getOperation (GET /v1/str/operations/{operationId}); the {operationId} path segment structurally ties the cancellation to its parent. A transfer is cancellable until it settles; once settled it takes a return instead (SPB-3006). Two endings: a transfer the STR already holds is cancelled by an STR0011 the STR adjudicates, and the cancellation operation comes back CANCEL_REQUESTED; a transfer that never reached the wire is abandoned locally, nothing is sent to BACEN, and the cancellation operation comes back already CANCELLED. A transfer whose dispatch may have reached the STR but is still unresolved answers SPB-3006; retry the cancellation once its dispatch resolves.



# Create bank transfer operation
Source: https://docs.lerian.studio/en/reference/rails/spb/create-bank-transfer-operation

/en/openapi/v3-current/spb.yaml post /v1/str/operations/bank-transfers
Prerequisite: the rail must be ready before a submit — an active certificate (see rotateCertificate, activateCertificate), a READY readiness report (see getReadiness), and a passing connectivity test (see createConnectivityTest). Accepts a bank transfer operation through the operation-centric API. The client declares the typed debtor and creditor roles (sender.party / recipient.party); the platform DERIVES the BACEN STR transfer code (STR0004 institution→institution, STR0005 non-account-holders, STR0006 client→IF, STR0007 IF→client, STR0008 client→client), persists the operation aggregate and SUBMITTED outbound relay work, and returns the canonical OperationAccepted envelope. This means dispatch was accepted, not BACEN settlement confirmation. Idempotent — replaying the same X-Idempotency key with the same body returns the cached response.



# Create bank transfer return operation
Source: https://docs.lerian.studio/en/reference/rails/spb/create-bank-transfer-return-operation

/en/openapi/v3-current/spb.yaml post /v1/str/operations/bank-transfers/{operationId}/returns
Prerequisite: the parent operation must be SENT, CONFIRMED, or DELIVERED before a return (the settled-outbound states) — read its state via getOperation (GET /v1/str/operations/{operationId}); the {operationId} path segment structurally ties the return to its parent. The handler resolves the original operation by operationId, validates that the lifecycle state admits a return (SPB-3006 otherwise), and delegates to the legacy STR0010 pipeline. Idempotent — replaying the same X-Idempotency key with the same body returns the cached response.



# Initiate connectivity (ECO) test
Source: https://docs.lerian.studio/en/reference/rails/spb/create-connectivity-test

/en/openapi/v3-current/spb.yaml post /v1/str/connectivity-tests
Prerequisite: an active certificate (see rotateCertificate, activateCertificate) and a READY readiness report (see getReadiness) before the connectivity test; a passing connectivity test is itself the prerequisite for a submit operation (see createBankTransferOperation). Builds a GEN0001 echo request addressed to the given participant, persists it as SUBMITTED before rail dispatch, and lets the outbound relay dispatch it to the RSFN. The counterparty answers with GEN0001R1 echoing the message back; the response correlates by NUOp and confirms the test. Idempotent — replaying the same X-Idempotency key with the same body returns the cached response.



# Create IBS repasse operation
Source: https://docs.lerian.studio/en/reference/rails/spb/create-ibs-repasse-operation

/en/openapi/v3-current/spb.yaml post /v1/str/operations/ibs-repasses
Prerequisite: the rail must be ready before a submit — an active certificate (see rotateCertificate, activateCertificate), a READY readiness report (see getReadiness), and a passing connectivity test (see createConnectivityTest). Accepts a STR0053 IBS-repasse operation (reserve repasse of IBS settlement values to the comitê gestor) through the operation-centric API. The handler translates the JSON request into the STR0053 XML request path, persists the operation aggregate and SUBMITTED outbound relay work, and returns the canonical OperationAccepted envelope. Dispatch was accepted, not BACEN settlement confirmation. Idempotent — replaying the same X-Idempotency key with the same body returns the cached response.



# Create SILOC operational deposit (LDL0022)
Source: https://docs.lerian.studio/en/reference/rails/spb/create-ldl-deposit

/en/openapi/v3-current/spb.yaml post /v1/str/operations/ldl-deposits
Commands an outbound LDL0022 operational deposit into the SILOC deferred-net settlement câmara in response to a registered SILOC deposit-required advisory. The client declares the advisory + instruction it settles, the SILOC traceability (echoed as the command NumCtrlIF), the positive money magnitude, and the explicit DEBIT side; the platform SERVER-DERIVES the wire ISPBs (funding IF + SILOC câmara), the OT product, and the movement date — none are client-supplied and none is reconstructed from the advisory. The command is persisted idempotently and its signed LDL0022 frame is enqueued for STR dispatch in the same transaction. This means dispatch was accepted, not SILOC settlement confirmation; the outcome arrives asynchronously on the LDL0022R1 leg. Idempotent — replaying the same X-Idempotency key with the same body returns the cached response. Lerian SPB EMITS the deposit-command fact + correlation and routes settlement; it holds NO SILOC position.



# Create LDL settlement transfer (LDL0004/0006/0008/0011/0014)
Source: https://docs.lerian.studio/en/reference/rails/spb/create-ldl-settlement

/en/openapi/v3-current/spb.yaml post /v1/str/operations/ldl-settlements
Commands one of the five STR settlement transfers of the Liquidação Multilateral de Câmaras family, chosen by messageType: LDL0004 settles this participant's DEBIT net position for a cycle (Reservas Bancárias to the câmara's Conta de Liquidação), LDL0006 returns funds transferred in error quoting the original STR control number, LDL0008 funds the settlement of asset events and emissions, LDL0011 moves the câmara's current account into its settlement account debiting a named branch and account, and LDL0014 funds a deposit at the câmara. The client declares the total, its own control number, and the code-specific detail — the câmara control numbers and the per-participant breakdown reach the wire VERBATIM because they originate on the SILOC leg this rail never receives, so inventing one would forge another system's identifier. The platform SERVER-DERIVES the wire ISPBs (this participant and the câmara) and the movement date; none is client-supplied. A detail field the declared messageType does not carry is refused rather than dropped, and a control number already spent on the same messageType is refused as a conflict. The command is persisted idempotently and its signed frame enqueued for STR dispatch in the same transaction. This means dispatch was accepted, not BACEN settlement confirmation; the outcome arrives asynchronously on the code's R1 leg. Idempotent — replaying the same X-Idempotency key with the same body returns the cached response. Lerian SPB EMITS the settlement-command fact and routes settlement; the LDL cycle belongs to the câmara and the accounting position to the client's ledger — it holds neither, and never reconciles the breakdown against the declared total.



# Create Conta-PI liquidity transfer
Source: https://docs.lerian.studio/en/reference/rails/spb/create-liquidity-transfer-operation

/en/openapi/v3-current/spb.yaml post /v1/str/operations/liquidity-transfers
Prerequisite: the rail must be ready before a submit — an active certificate (see rotateCertificate, activateCertificate), a READY readiness report (see getReadiness), and a passing connectivity test (see createConnectivityTest). Accepts an LPI Conta-PI liquidity transfer through the operation-centric API: direction aporte funds the FI's Conta PI from its RB/CL (the platform DERIVES wire code LPI0001), resgate recalls funds (LPI0003) — the platform never composes the wire code. Persists a PENDING liquidity-transfer projection and returns the operation id, the PENDING status, and the derived wire code. This means dispatch was accepted, not BACEN settlement confirmation; the settlement arrives asynchronously on the inbound STR R-leg and is read via getLiquidityTransfer. An out-of-window aporte is rejected (RLPI0007). Lerian SPB EMITS the movement fact and projects the Conta-PI balance verbatim; it never computes a position. Idempotent — replaying the same X-Idempotency key with the same body returns the cached response.



# Create LTR transfer (LTR0003/0004/0006)
Source: https://docs.lerian.studio/en/reference/rails/spb/create-ltr-transfer

/en/openapi/v3-current/spb.yaml post /v1/str/operations/ltr-transfers
Commands one of the three STR-addressed transfers of the Liquidação Bruta ou Bilateral de Operações family, chosen by messageType: LTR0003 moves Reservas Bancárias to another institution and has the STR notify the Câmara, LTR0004 settles this participant's negotiation result into the Câmara's account, and LTR0006 returns funds transferred in error quoting the original STR control number. The client declares the amount, its own control number, the credited institution where the code names one, and the code-specific detail — the Câmara control number reaches the wire VERBATIM because it originates on the SILOC leg this rail never receives, so inventing one would forge another system's identifier. The platform SERVER-DERIVES the wire ISPBs (this participant and the câmara) and the movement date; none is client-supplied. A detail field the declared messageType does not carry is refused rather than dropped, and a control number already spent on the same messageType is refused as a conflict. The command is persisted idempotently and its signed frame enqueued for STR dispatch in the same transaction. This means dispatch was accepted, not BACEN settlement confirmation; the outcome arrives asynchronously on the code's R1 leg, where only an Efetivado status emits a settled fact — the bilateral confirmation states 50/51/52 emit nothing. Idempotent — replaying the same X-Idempotency key with the same body returns the cached response. Lerian SPB routes settlement and emits the terminal fact; the LBTR obligation belongs to the Câmara and the accounting position to the client's ledger — it holds neither.



# File the compulsory statement (RCO0002)
Source: https://docs.lerian.studio/en/reference/rails/spb/create-rco-filing

/en/openapi/v3-current/spb.yaml post /v1/str/rco-filings
Files the compulsory statement for a calculation period: one or more days, each carrying its incidence items. Every day must fall inside the declared period — a day outside it is refused here rather than spent on a round trip BACEN would reject. The requirement BACEN computes from the filing arrives on the answer and lands on the period row. Idempotent on X-Idempotency.



# Ask for the compulsory period calendar or read a filing back
Source: https://docs.lerian.studio/en/reference/rails/spb/create-rco-filing-query

/en/openapi/v3-current/spb.yaml post /v1/str/rco-filing-queries
Submits one of the two reporting consultas: the period calendar (RCO0001), which publishes both windows and both deadlines, or the filing read-back (RCO0003). A read-back's reference date must fall inside the period being queried (RRCO0002), which is checked before the frame is built. The answer arrives asynchronously and lands on the compulsory period row.



# Command a compulsory-account movement
Source: https://docs.lerian.studio/en/reference/rails/spb/create-rco-movement

/en/openapi/v3-current/spb.yaml post /v1/str/rco-movements
Commands a movement between this institution's compulsory deposits at BACEN and its own Reservas Bancárias: a withdrawal (RCO0010) or a deposit (RCO0011), derived server-side from the direction. The row is persisted BEFORE the frame is sent, so a failed submit leaves a recoverable record rather than a movement nobody can find. The response is an acceptance, never a settlement: the state comes from the BACEN answer (SitLancRCO) and from nothing else. Idempotent — replaying the same X-Idempotency key produces one outbound frame. The amount is forwarded verbatim; no compulsory position is computed or held.



# Run a compulsory compliance read
Source: https://docs.lerian.studio/en/reference/rails/spb/create-rco-report-query

/en/openapi/v3-current/spb.yaml post /v1/str/rco-report-queries
Submits one of the three compliance consultas: the compulsory-account movement statement (RCO0005), the compliance position against the requirement (RCO0006) or the cost ledger (RCO0007). The cost ledger is the one message of the family whose compulsory code is optional — blank asks across every reserve. The answers arrive asynchronously on the message feed.



# Create reconciliation action
Source: https://docs.lerian.studio/en/reference/rails/spb/create-reconciliation-action

/en/openapi/v3-current/spb.yaml post /v1/str/reconciliations/{reconciliationId}/actions
Records an operator recovery action on a reconciliation case. Valid actions are ACKNOWLEDGE, RESOLVE, DISMISS, INVESTIGATE. Terminal cases (RESOLVED / DISMISSED) reject further actions with SPB-3007 / HTTP 409.



# Command a rediscount operation
Source: https://docs.lerian.studio/en/reference/rails/spb/create-rediscount

/en/openapi/v3-current/spb.yaml post /v1/str/operations/rediscounts
Commands a redesconto do Banco Central — collateralised BCB lending against Selic-registered federal securities — and returns the operation id plus a PENDING state. One door serves the four operator-facing kinds and the server derives the RDC wire code: a contract borrows (RDC0002 intraday, RDC0003 one business day, RDC0004 tied to a Selic purchase, RDC0009 tied to a clearing-house collateral release, RDC0013 a consolidation), a payment gives it back (RDC0007 in cash, RDC0008 funded by selling the pledged securities), a conversion liquidates an open operation and opens a repriced replacement (RDC0005), and a cancellation withdraws a request still pending at Selic (RDC0014). The outcome arrives asynchronously on the response leg — and an ACCEPTED answer is NOT a settlement: Selic may hold the request for want of securities, in which case the operation is registered, no money has moved, and no settlement fact is emitted. Lerian SPB records what BACEN answers; it holds no position and performs no balance arithmetic.



# Submit a rediscount query
Source: https://docs.lerian.studio/en/reference/rails/spb/create-rediscount-query

/en/openapi/v3-current/spb.yaml post /v1/str/rediscount-queries
Submits a rediscount consulta and returns a correlation id plus a PENDING state. Two kinds: eligibleTitlePrice asks the unit price of one security accepted as rediscount collateral (RDC0001), and openPositions asks which rediscounts this institution still has open on the movement date (RDC0006). The answer arrives asynchronously. The consultas live outside /v1/str/operations because a consulta mints no operation, and they carry their own scope: reading this institution's collateral standing is not the same grant as commanding a borrowing against it. The open-position query is always sent in message mode — BACEN's file-return modes deliver the answer over a transport this rail does not implement, so offering them would publish a request whose answer could never be collected.



# Submit STR0013 reserve-account balance query
Source: https://docs.lerian.studio/en/reference/rails/spb/create-reserve-balance-query

/en/openapi/v3-current/spb.yaml post /v1/str/reserve-balance-queries
Submits a single-party STR0013 reserve-account balance query to BACEN and returns a correlation id plus a PENDING state. The answer (STR0013R1, carrying SldRB_CL — the conta Reservas Bancárias / Conta de Liquidação balance) arrives asynchronously and is read via GET /v1/str/reserve-balance-queries/{id}. Lerian SPB projects the balance BACEN sends; it never computes a position.



# Submit STR0014 reserve-account statement query (message-mode)
Source: https://docs.lerian.studio/en/reference/rails/spb/create-reserve-statement-query

/en/openapi/v3-current/spb.yaml post /v1/str/reserve-statement-queries
Submits a single-party STR0014 reserve-account statement (extrato) query to BACEN in MESSAGE-MODE (TpRet=M) and returns a correlation id plus a PENDING state. The answer (STR0014R1, carrying the opening/closing balances and up to 200 settled entries) arrives asynchronously and is read via GET /v1/str/reserve-statement-queries/{id}. If BACEN routes the statement to a file (TamArq/IdentdArq) or the window exceeds the 200-entry message-mode ceiling, the read endpoint returns an explicit error — file retrieval (TpRet=P/X) is out of scope. Lerian SPB projects the statement BACEN sends; it never computes a position.



# Submit STR0001 schedule query
Source: https://docs.lerian.studio/en/reference/rails/spb/create-schedule-query

/en/openapi/v3-current/spb.yaml post /v1/str/schedule-queries
Submits a single-party STR0001 schedule query (consulta de horários do STR) to BACEN and returns a correlation id plus a PENDING state. The answer (STR0001R1, carrying the STR operating-schedule grid) arrives asynchronously and is read via GET /v1/str/schedule-queries/{id}. This means the query was accepted for dispatch, not that the schedule is available yet. Lerian SPB surfaces the schedule BACEN sends; it computes nothing.



# Pay BACEN an amount SLB never demanded
Source: https://docs.lerian.studio/en/reference/rails/spb/create-slb-bacen-payment

/en/openapi/v3-current/spb.yaml post /v1/str/slb-bacen-payments
Submits an SLB0007 paying BACEN an amount no SLB0001 charged, including the return of a credit BACEN made with an SLB0005 — name that credit's control number to make the payment a return (RSLB0008). Unlike the charge authorisation this command is bounded by nothing but its own fields, which is why it carries its own scope. When the deployment configures an alçada band covering the amount, the message parks in PENDING_APPROVAL until the required signatures are collected.



# Submit SLB0006 entry query
Source: https://docs.lerian.studio/en/reference/rails/spb/create-slb-entry-query

/en/openapi/v3-current/spb.yaml post /v1/str/slb-entry-queries
Submits an SLB0006 asking what entries exist for this participant, and returns a correlation id plus a PENDING projection. The catalogue defines THREE mutually exclusive modes and no combined one: a reference date asks for that date's entries, an entry control number asks for that one entry, and naming NEITHER asks for everything falling due from today on. Sending both selectors is refused — it asks a question BACEN defines no answer to. The optional debit/credit filter composes with all three.



# Authorise payment of an SLB charge
Source: https://docs.lerian.studio/en/reference/rails/spb/create-slb-payment

/en/openapi/v3-current/spb.yaml post /v1/str/slb-payments
Submits an SLB0002 authorising payment of a charge BACEN raised with an SLB0001, and returns a correlation id plus a PENDING projection. This request IS the authorisation: receiving the notice authorises nothing, so the decision to pay is made here. The amount must equal the charge in full — SLB admits no partial payment (Catálogo v5.13 Vol I) — and is checked against the stored charge before anything reaches the rail. A charge already settled or withdrawn is refused. When the deployment configures an alçada band covering the amount, the message parks in PENDING_APPROVAL and is not transmitted until the required signatures are collected.



# Create SME electronic-money movement
Source: https://docs.lerian.studio/en/reference/rails/spb/create-sme-transfer-operation

/en/openapi/v3-current/spb.yaml post /v1/str/operations/sme-transfers
Prerequisite: the rail must be ready before a submit — an active certificate (see rotateCertificate, activateCertificate), a READY readiness report (see getReadiness), and a passing connectivity test (see createConnectivityTest). Accepts an SME movement of an IEME's conta correspondente a moeda eletrônica (CCME) through the operation-centric API: kind deposit funds the CCME from Reservas Bancárias / Conta de Liquidação (the platform DERIVES wire code SME0001), withdrawal recalls funds out of the CCME (SME0002), and return gives back an entry received in error quoting its original STR control number (SME0004) — the platform never composes the wire code, and the issuer ISPB is resolved server-side. On a deposit, the counterparty ISPB reaches the wire as the ISPBIEME only for an IEME that does NOT participate in the STR (RSME0001): participation is read from the participant directory the STR itself broadcasts, and a deposit naming an institution the STR announced as a participant is refused as a validation error before it becomes a durable movement — while a deposit into the deployment's own CCME carries no ISPBIEME at all. Ignorance does not block: when the directory holds no answer for that ISPB the movement proceeds, and BACEN remains the authoritative validator of the condition. Persists a PENDING movement projection BEFORE the frame is sent and returns the operation id, the PENDING status, and the derived wire code. This means dispatch was accepted, not BACEN settlement confirmation; the settlement arrives asynchronously on the inbound STR R-leg. Every accepted movement durably records the authenticated operator that commanded it. Lerian SPB EMITS the movement fact and projects the settlement verbatim; it never computes or holds a CCME position. Idempotent — replaying the same X-Idempotency key with the same body returns the cached response.



# Deny a parked emission
Source: https://docs.lerian.studio/en/reference/rails/spb/deny-emission

/en/openapi/v3-current/spb.yaml post /v1/str/emission-approvals/{id}/deny
Terminalizes a PENDING_APPROVAL emission: a single distinct authorized actor denying flips it to FAILED with the reason recorded — one deny kills it (a denial is not subject to quorum). A FAILED emission is never claimed by the outbox dispatcher, so it never liquidates.



# Get capability by ID
Source: https://docs.lerian.studio/en/reference/rails/spb/get-capability

/en/openapi/v3-current/spb.yaml get /v1/str/capabilities/{capabilityId}
Returns the detail of a single STR capability identified by its public identifier (e.g. "STR0004").



# Get event delivery
Source: https://docs.lerian.studio/en/reference/rails/spb/get-event-delivery

/en/openapi/v3-current/spb.yaml get /v1/str/event-deliveries/{deliveryId}
Returns a single event_delivery row plus its attempt history. Lookups for unknown ids surface as not-found (SPB-0010), byte-identical to truly-missing.



# Get Conta-PI liquidity transfer status
Source: https://docs.lerian.studio/en/reference/rails/spb/get-liquidity-transfer

/en/openapi/v3-current/spb.yaml get /v1/str/operations/liquidity-transfers/{operationId}
Reads the projection of a previously submitted LPI Conta-PI liquidity transfer by its operation id. Returns PENDING until the inbound STR R-leg (LPI0001R1 / LPI0003R1) arrives, then SETTLED (or REJECTED) with the STR settlement confirmation (numCtrlSTR / sitLancSTR) BACEN sent, projected verbatim. Unknown ids surface as not-found (SPB-0010). Lerian SPB projects the settlement; it never computes a position.



# Get the signed STR message frame
Source: https://docs.lerian.studio/en/reference/rails/spb/get-message-frame

/en/openapi/v3-current/spb.yaml get /v1/str/messages/{nuOp}/frame
Returns the signed on-wire STR frame for a message identified by its NUOp: the persisted on-wire bytes decoded to XML and labeled reconstructed (the literal sent bytes are not separately retained). The artifact is served WHOLE — every identity exactly as transmitted, with no masking and no content transformation. It is guarded separately from the message log: reading the log (list and metadata) does not open the frame. A message with no retained on-wire bytes (an inbound row, or an outbound without a retry payload) answers 200 with payloadFormat "structured" and no reconstructedXml — the message exists and the frame was never retained; that is the legitimate answer, not an error. A NUOp that matches no message answers 404. The NUOp is a 23-character BACEN identifier: ISPB[8]+DATE[8]+SEQ[7].



# Get STR message detail
Source: https://docs.lerian.studio/en/reference/rails/spb/get-message-status

/en/openapi/v3-current/spb.yaml get /v1/str/messages/{nuOp}
Returns the message-log detail for an STR message identified by its NUOp: the status and BACEN-receipt fields, the structured payload, and the resolved original<->correspondent counterpart. The signed on-wire frame is NOT returned here — it is read at GET /v1/str/messages/{nuOp}/frame, guarded by its own scope; this body only labels whether one was retained (payloadFormat). Searches outbound messages first, then inbound. The NUOp is a 23-character BACEN identifier: ISPB[8]+DATE[8]+SEQ[7].



# Get operation detail
Source: https://docs.lerian.studio/en/reference/rails/spb/get-operation

/en/openapi/v3-current/spb.yaml get /v1/str/operations/{operationId}
Returns the sanitized detail of a single operation. Unknown ids surface as not-found (SPB-0010); the service never leaks the existence of an operation it does not own. Raw protocol payload fields never appear in responses.



# List operation timeline
Source: https://docs.lerian.studio/en/reference/rails/spb/get-operation-timeline

/en/openapi/v3-current/spb.yaml get /v1/str/operations/{operationId}/timeline
Returns chronological lifecycle entries for one operation. Unknown ids surface as not-found (SPB-0010). Sort order is occurred_at ASC. Raw protocol payload fields never appear in responses.



# Get operational aggregates
Source: https://docs.lerian.studio/en/reference/rails/spb/get-operational-aggregates

/en/openapi/v3-current/spb.yaml get /v1/str/operational-aggregates
Returns pre-computed aggregate buckets matching the requested window (hour or day) + date range. Source is the operational_aggregate_bucket table populated by a background worker (T-016) — empty until the worker ships. Buckets are ordered by bucket_start ASC.



# Get operational summary
Source: https://docs.lerian.studio/en/reference/rails/spb/get-operational-summary

/en/openapi/v3-current/spb.yaml get /v1/str/operational-summary
Returns a dashboard-ready summary composing readiness, operation counts (grouped by family + status), reconciliation backlog (open/in-progress only), failed deliveries (failed/exhausted), and certificate warnings (any non-VALID status). Computed on demand from live source tables.



# Read one commanded compulsory movement
Source: https://docs.lerian.studio/en/reference/rails/spb/get-rco-movement

/en/openapi/v3-current/spb.yaml get /v1/str/rco-movements/{numCtrlIF}
Reads one commanded movement by its participant control number — the handle the BACEN answer echoes and the only one the answer's body carries.



# Get service readiness
Source: https://docs.lerian.studio/en/reference/rails/spb/get-readiness

/en/openapi/v3-current/spb.yaml get /v1/str/readiness
Prerequisite: an active certificate (see rotateCertificate, activateCertificate) before readiness reports READY; a READY readiness report is itself the prerequisite for a connectivity test (see createConnectivityTest) and any submit operation (see createBankTransferOperation). Returns the operational readiness summary for the service, including database connectivity, certificate validity window, channel settings binding, and any degraded subsystems. Used by ops dashboards and pre-flight gates before STR submission. Independent of the global Kubernetes /readyz probe — this endpoint reports the participant operational readiness state, while /readyz reports process-level dependency health.



# Get reconciliation case
Source: https://docs.lerian.studio/en/reference/rails/spb/get-reconciliation-case

/en/openapi/v3-current/spb.yaml get /v1/str/reconciliations/{reconciliationId}
Returns a single reconciliation case. Lookups for unknown ids surface as not-found (SPB-0010), byte-identical to truly-missing.



# Read rediscount operation status
Source: https://docs.lerian.studio/en/reference/rails/spb/get-rediscount

/en/openapi/v3-current/spb.yaml get /v1/str/operations/rediscounts/{operationId}
Reads the lifecycle of a commanded rediscount by its operation id. PENDING until BACEN answers, then one of five states — and the distinction between two of them is the point of this read. ACCEPTED means BACEN registered the request and Selic is HOLDING it because the institution is short of securities: it is neither settled nor failed, no money moved, and the end-of-day sweep may still cancel it or roll it into one business day. SETTLED means a Reservas Bancárias entry exists, evidenced by the numCtrlSTR BACEN stamped, and it is deliberately NOT terminal — a settled rediscount is still an open borrowing until it is repaid, converted or swept. A payment response also reports the remaining balance BACEN sent, verbatim: Lerian SPB never derives it by subtracting a payment from a contract.



# Read rediscount query result
Source: https://docs.lerian.studio/en/reference/rails/spb/get-rediscount-query

/en/openapi/v3-current/spb.yaml get /v1/str/rediscount-queries/{nuOp}
Reads the result of a previously submitted rediscount consulta by its correlation id (the outbound NUOp). PENDING until BACEN answers, then ANSWERED — or TRUNCATED, which is its own terminal state rather than a flavour of ANSWERED. An open-position answer carries at most 40 operations, and when the day has more BACEN cuts it short and names a file holding the remainder. That file travels over a transport no SPB rail code touches, so the identifier is recorded for an operator to collect out of band and the answer is never presented as complete.



# Movimento financeiro report
Source: https://docs.lerian.studio/en/reference/rails/spb/get-report-movement

/en/openapi/v3-current/spb.yaml get /v1/str/reports/movement
Returns, per (messageType, direction), the SUM of the declared amount + a COUNT over outbound and inbound messages created within the date range, plus a grand total per direction. The decimal sum is accumulated in integer centavos (never float). This sums Lerian SPB's OWN transmitted/received amounts — a derived report view, not a held position. BACEN-supplied reserve balances are NOT projected here (use GET /v1/str/reserve-statement-queries/{id}); movement never rolls movements up into an opening/closing balance.



# Transações rejeitadas report
Source: https://docs.lerian.studio/en/reference/rails/spb/get-report-rejected

/en/openapi/v3-current/spb.yaml get /v1/str/reports/rejected
Returns a COUNT plus a cursor-paginated list of rejected messages (outbound status=REJECTED, inbound rejection reason present) within the date range, ordered by (createdAt DESC, id DESC). The rejection reason is projected verbatim. A pure filter+count over Lerian SPB's own record.



# Volumetria report
Source: https://docs.lerian.studio/en/reference/rails/spb/get-report-volumetria

/en/openapi/v3-current/spb.yaml get /v1/str/reports/volumetria
Returns COUNT(*) grouped by (messageType, status, day) over the raw message tables within the date range — the per-type/day message breakdown (the operational_aggregate_bucket table is empty in production). Non-monetary (counts only).



# Read STR0013 reserve-balance query result
Source: https://docs.lerian.studio/en/reference/rails/spb/get-reserve-balance-query

/en/openapi/v3-current/spb.yaml get /v1/str/reserve-balance-queries/{id}
Reads the result of a previously submitted STR0013 reserve-account balance query by its correlation id. Returns PENDING until the STR0013R1 answer arrives, then the reserve-account balance BACEN sent (SldRB_CL) plus a freshness timestamp.



# Read STR0014 reserve-statement query result (message-mode)
Source: https://docs.lerian.studio/en/reference/rails/spb/get-reserve-statement-query

/en/openapi/v3-current/spb.yaml get /v1/str/reserve-statement-queries/{id}
Reads the result of a previously submitted STR0014 reserve-account statement query by its correlation id. Returns PENDING until the STR0014R1 answer arrives, then the opening/closing balances and the verbatim settled-entry group BACEN sent. Returns 422 when the answer requires file-mode retrieval (BACEN returned file metadata or the window exceeded the 200-entry message-mode ceiling) — the entry list is never silently truncated.



# Get operating-schedule windows
Source: https://docs.lerian.studio/en/reference/rails/spb/get-schedule

/en/openapi/v3-current/spb.yaml get /v1/str/schedule
Returns the operating-window grades announced by GEN0021 schedule-change broadcasts ("GEN avisa alteração de horários"). Each window carries the official grade code, opening/closing datetimes, schedule type and announcing provider, verbatim as announced. A re-announced grade for the same reference date overwrites the previous window. Optionally filter by reference date with dtRef.



# Read STR0001 schedule-query result
Source: https://docs.lerian.studio/en/reference/rails/spb/get-schedule-query

/en/openapi/v3-current/spb.yaml get /v1/str/schedule-queries/{id}
Reads the result of a previously submitted STR0001 schedule query by its correlation id. Returns PENDING until the STR0001R1 answer arrives, then the STR operating-schedule grid BACEN sent (Grupo_STR0001R1_GrdHrio) plus a freshness timestamp.



# Get channel settings
Source: https://docs.lerian.studio/en/reference/rails/spb/get-settings

/en/openapi/v3-current/spb.yaml get /v1/str/settings
Returns the STR channel settings, including the participant ISPB binding, delivery mode, and any registered webhook endpoints. When readiness lookup is wired, the response also embeds the operational readiness summary.



# Read SLB0006 entry query result
Source: https://docs.lerian.studio/en/reference/rails/spb/get-slb-entry-query

/en/openapi/v3-current/spb.yaml get /v1/str/slb-entry-queries/{nuOp}
Reads the result of a previously submitted SLB0006 entry query by its correlation id. Returns PENDING until the SLB0006R1 answer arrives, then every entry BACEN reported, verbatim and in wire order. A consulta answered with zero rows is still ANSWERED — 'nothing matches' is an answer. The list is a snapshot of BACEN's view and deliberately does not rewrite the charge projection: reconciling the two is an operator decision with both in front of them.



# Read one SLB charge
Source: https://docs.lerian.studio/en/reference/rails/spb/get-slb-obligation

/en/openapi/v3-current/spb.yaml get /v1/str/slb-obligations/{numCtrlSLB}
Reads one charge by the control number BACEN minted for it (NumCtrlSLB). Returns 404 when no SLB0001 ever announced it.



# Read an SLB payment
Source: https://docs.lerian.studio/en/reference/rails/spb/get-slb-payment

/en/openapi/v3-current/spb.yaml get /v1/str/slb-payments/{nuOp}
Reads a payment this participant commanded — either kind — by its correlation id. PENDING until BACEN's answer arrives AND that answer reports a settlement: an answer carrying a pending-class situation reports that the entry was taken and not yet settled, and is recorded as such rather than read as payment.



# Get SME electronic-money movement status
Source: https://docs.lerian.studio/en/reference/rails/spb/get-sme-transfer

/en/openapi/v3-current/spb.yaml get /v1/str/operations/sme-transfers/{operationId}
Reads the projection of a previously submitted SME movement of an IEME's conta correspondente a moeda eletrônica (CCME) by its operation id. Returns PENDING until the inbound STR R-leg (SME0001R1 / SME0002R1 / SME0004R1) arrives, then SETTLED (or REJECTED) with the STR settlement confirmation (numCtrlSTR / sitLancSTR) BACEN sent, projected verbatim. Unknown ids surface as not-found (SPB-0010). Lerian SPB projects the settlement; it never computes or holds a CCME position.



# Read the live alçada governance config
Source: https://docs.lerian.studio/en/reference/rails/spb/get-str-governance

/en/openapi/v3-current/spb.yaml get /v1/str/governance
Returns the live alçada value-band table and per-message-type signature requirements. Hot-reloaded at runtime; the configured default is only a seed. This is a classification rule table, never a position.



# List audit records
Source: https://docs.lerian.studio/en/reference/rails/spb/list-audit-records

/en/openapi/v3-current/spb.yaml get /v1/str/audit-records
Lists audit evidence records (T-004) with optional filters by actor, action type, and time window. Cursor-based pagination — pass the nextCursor from a previous response to continue. The cursor is opaque and MUST NOT be parsed by clients.



# List audit records for an operation
Source: https://docs.lerian.studio/en/reference/rails/spb/list-audit-records-for-operation

/en/openapi/v3-current/spb.yaml get /v1/str/operations/{operationId}/audit-records
Lists audit evidence records associated with a specific operation, identified by its UUID. Cursor-based pagination — same semantics as the audit-records list.



# List STR capabilities
Source: https://docs.lerian.studio/en/reference/rails/spb/list-capabilities

/en/openapi/v3-current/spb.yaml get /v1/str/capabilities
Returns the public catalog of STR capabilities (T-005). Every authenticated caller sees the same rows. Supports filtering by operation family, handling mode, direction, and availability. Cursor-based pagination.



# List certificate state
Source: https://docs.lerian.studio/en/reference/rails/spb/list-certificates

/en/openapi/v3-current/spb.yaml get /v1/str/certificates
Returns the current state of the ICP-Brasil/RSFN certificate set, including purpose, status, validity window, and readiness impact. Private keys and key material are never exposed.



# List emissions pending maker-checker approval
Source: https://docs.lerian.studio/en/reference/rails/spb/list-emission-approvals

/en/openapi/v3-current/spb.yaml get /v1/str/emission-approvals
Returns the queue of outbound emissions parked in PENDING_APPROVAL above their alçada band, awaiting the required distinct-actor signatures before they may liquidate. Each row carries the message's OWN declared amount (verbatim — never a summed position), the N-of-M quorum, the signatures collected so far, the approval deadline, and the maker. Read model only.



# List event catalog
Source: https://docs.lerian.studio/en/reference/rails/spb/list-event-catalog

/en/openapi/v3-current/spb.yaml get /v1/str/events/catalog
Returns the public, shared catalog of control-plane event types and versions. Every authenticated caller sees the same rows. Subscribers consume this catalog to negotiate webhook delivery payload shapes.



# List event deliveries
Source: https://docs.lerian.studio/en/reference/rails/spb/list-event-deliveries

/en/openapi/v3-current/spb.yaml get /v1/str/event-deliveries
Returns a page of event delivery records with attempt history. Filters by status, event type, webhook id, operation id, and date range. Cursor-based pagination — pass the nextCursor from a previous response to continue.



# List inbound GEN notices
Source: https://docs.lerian.studio/en/reference/rails/spb/list-gen-notices

/en/openapi/v3-current/spb.yaml get /v1/str/gen-notices
Returns the durable, queryable log of inbound GEN-family notices (GEN0001 connectivity echo, GEN0004 transmission error, GEN0005 administrative notice) received from BACEN. Each notice carries the sanitized official fields verbatim — never a raw frame echo. Most recent first; optionally filter by noticeType or announcing-participant senderIspb.



# List quarantined inbound frames (operator triage)
Source: https://docs.lerian.studio/en/reference/rails/spb/list-inbound-quarantine

/en/openapi/v3-current/spb.yaml get /v1/str/inbound-quarantine
Returns a page of inbound frames the STR path could not turn into a persisted message, newest first. Given the stage and message code an INBOUND_QUARANTINED reconciliation case prints, this is how an operator reaches the sibling frames without database access. stage / messageCode / nuOp are exact-match filters; receivedAt bounds are inclusive. Each row publishes its parkKey — the subject of the replay command — plus whether a replay already ran and why the last attempt failed. The response NEVER carries the frame itself (no field on the row can hold it) and carries no monetary field.



# List STR messages
Source: https://docs.lerian.studio/en/reference/rails/spb/list-messages

/en/openapi/v3-current/spb.yaml get /v1/str/messages
Lists outbound and inbound STR messages with optional filters and cursor-based pagination. The cursor is opaque — pass the nextCursor value from a previous response to continue. Filters can be combined freely; results are merged in the requested sort order.



# List operations
Source: https://docs.lerian.studio/en/reference/rails/spb/list-operations

/en/openapi/v3-current/spb.yaml get /v1/str/operations
Lists operations with optional filters. Cursor-based pagination — pass the nextCursor from a previous response to continue. The cursor is opaque and MUST NOT be parsed by clients. Raw protocol payload fields never appear in responses.



# List third-party compulsory deposits
Source: https://docs.lerian.studio/en/reference/rails/spb/list-rco-advices

/en/openapi/v3-current/spb.yaml get /v1/str/rco-advices
Lists the RCO0019 notices the STR delivered: compulsory deposits a THIRD party made into this institution's account, which this rail never commanded and only learned about. They correlate to nothing sent from here, so each carries only BACEN's own control number. Every value is served verbatim.



# List compulsory periods and their requirements
Source: https://docs.lerian.studio/en/reference/rails/spb/list-rco-filings

/en/openapi/v3-current/spb.yaml get /v1/str/rco-filings
Lists the compulsory periods this rail knows about — what has been filed, when each period closes for filing and for amendment, and the requirement BACEN last published against it, carried verbatim.



# List commanded compulsory movements
Source: https://docs.lerian.studio/en/reference/rails/spb/list-rco-movements

/en/openapi/v3-current/spb.yaml get /v1/str/rco-movements
Lists the compulsory-account movements this rail commanded, newest first, with the situation BACEN answered with carried verbatim beside the derived lifecycle class.



# List reconciliation cases
Source: https://docs.lerian.studio/en/reference/rails/spb/list-reconciliation-cases

/en/openapi/v3-current/spb.yaml get /v1/str/reconciliations
Returns a page of reconciliation cases with operator-actionable filters. Cases are ordered by openedAt DESC. Cursor-based pagination — pass the nextCursor from a previous response to continue.



# List outstanding SLB charges
Source: https://docs.lerian.studio/en/reference/rails/spb/list-slb-obligations

/en/openapi/v3-current/spb.yaml get /v1/str/slb-obligations
Lists the charges BACEN raised against this participant with an SLB0001 and that are still owed, soonest due first. Receiving the notice authorises nothing — the participant decides whether and when to pay — so a charge listed here is owed, never paid. An empty list means nothing is owed, which is an answer and not a missing projection. Every amount crosses as text, verbatim; no total is computed.



# List received electronic-money advices
Source: https://docs.lerian.studio/en/reference/rails/spb/list-sme-advices

/en/openapi/v3-current/spb.yaml get /v1/str/sme-advices
Returns the durable log of electronic-money movements the STR ADVISED us about over a client's conta correspondente a moeda eletrônica (CCME) — movements this rail did NOT command. Each leg reaches the side that did not command it: SME0001R2 (an FI funded a CCME) reaches the credited IEME, SME0002R2 (funds were recalled out of a CCME) reaches the FI, SME0004R2 (an entry received in error was given back) reaches the credited party. An advice is therefore never an answer to a frame we sent, and correlating it to one is wrong by construction. Amounts and the BACEN date stamps cross VERBATIM as the frame spelled them, with no arithmetic and no parsing; the response carries NO total, so a client learns how many advices it loaded and never how many exist. Most recent first by receipt; optionally filter by advice leg or by the window in which this rail received them.



# List stuck operations (operator dashboard)
Source: https://docs.lerian.studio/en/reference/rails/spb/list-stuck-operations

/en/openapi/v3-current/spb.yaml get /v1/str/stuck-operations
Returns the cross-rail operator dashboard page of operations needing attention, conformed to the shared recovery vocabulary. Each row carries only the verbs SPB can actually perform on it (a verb SPB cannot perform is absent) and the disposition ('what happens if I do nothing'). Reconciliation cases are shown with their affordances; pre-case stuck-outbound rows the dispatch sweep is retrying are shown informationally with no affordances. No monetary or position fields are returned.



# Replace the alçada governance config
Source: https://docs.lerian.studio/en/reference/rails/spb/put-str-governance

/en/openapi/v3-current/spb.yaml put /v1/str/governance
Validates and replaces the alçada band table + per-message-type signature requirements. Validation failure → HTTP 422 (SPB-0003). On success the classifier hot-reloads with no restart, so newly-parked emissions immediately reflect the new requiredSignatures. SPB-only (SPI has no alçada engine). This replaces a rule table, never a balance.



# Replay one quarantined inbound frame
Source: https://docs.lerian.studio/en/reference/rails/spb/replay-inbound-quarantine-frame

/en/openapi/v3-current/spb.yaml post /v1/str/inbound-quarantine/{parkKey}/replay
Puts one parked frame's stored bytes back through the inbound path, exactly as a live delivery runs them, because the reason it was refused — a message code or an element from a newer BACEN catalogue, a datastore that was down — has stopped being true. THE REPLAY SENDS NO NOTICE OF ITS OWN TO BACEN: no second courtesy notice, no correction, no retraction — the notice they already hold for these bytes stays a historical fact. But a frame that decodes and whose processing requires an answer PRODUCES that answer through the normal inbound path, possibly long after the original. The bytes are replayed verbatim; nothing is re-framed, re-addressed or repaired. One frame per command, never a sweep. An unknown parkKey is refused; a frame that was already replayed is refused naming who replayed it and when; a frame that fails again is refused and stays parked and replayable, with the reason readable as lastReplayError on the triage listing. Every attempt is recorded on the audit trail under the operator derived from the bearer token. Requires str-inbound-quarantine:replay — the triage read grant does not carry it.



# Retry event delivery
Source: https://docs.lerian.studio/en/reference/rails/spb/retry-event-delivery

/en/openapi/v3-current/spb.yaml post /v1/str/event-deliveries/{deliveryId}/retry
Requests a manual retry of a failed event delivery. Conflicts (already DELIVERED, retry already in flight) return SPB-3007 / HTTP 409. The request body is optional — a retry POST with no body is valid.



# Rotate ICP-Brasil certificate
Source: https://docs.lerian.studio/en/reference/rails/spb/rotate-certificate

/en/openapi/v3-current/spb.yaml post /v1/str/certificates/rotate
Prerequisite: this is the first step of the onboarding chain (certificate → readiness → connectivity-test → submit); rotate the certificate before activating it (see activateCertificate), checking readiness (see getReadiness), or submitting any operation. Performs an evidence-emitting hot-reload of the ICP-Brasil/RSFN certificate pair (T-007). The new certificate must already exist on disk under the configured base path; this endpoint only swaps the in-memory pointer and emits an audit record. Idempotent — replaying the same X-Idempotency key with the same body returns the cached response. The response NEVER includes the private key path or key material.



# Ask to close a deadline-expired transfer as failed
Source: https://docs.lerian.studio/en/reference/rails/spb/submit-stuck-operation-action

/en/openapi/v3-current/spb.yaml post /v1/str/stuck-operations/actions
The maker's step of MANUAL_RESOLUTION on an STR0008 past its BACEN settlement deadline with no answer: opens a close-as-failed case (returned as railActionRef) inside the transaction that checks the transfer is still in the deadline-expired list. Nothing is emitted until a different operator approves. BACEN is not notified.



# Update participant responsibles (GEN0019)
Source: https://docs.lerian.studio/en/reference/rails/spb/update-responsibles

/en/openapi/v3-current/spb.yaml post /v1/str/responsibles
Submits a GEN0019 "Participante informa atualização de responsáveis" announcement to BACEN, declaring the participant's complete responsável roster. FULL-REPLACEMENT: the body carries the entire set (1..100 responsáveis), never a partial update. The submission is persisted with status SUBMITTED before dispatch; BACEN's GEN0019R1 acknowledgment confirms it via NUOp correlation. Idempotent — replaying the same X-Idempotency key with the same body returns the cached response.



# Update channel settings
Source: https://docs.lerian.studio/en/reference/rails/spb/update-settings

/en/openapi/v3-current/spb.yaml patch /v1/str/settings
Patches the STR channel settings. Only the provided fields are updated; absent fields keep their current value. At least one field must be provided. Setting the participant ISPB requires an explicit 8-character value (placeholders such as 00000000 are rejected). Idempotent — replaying the same X-Idempotency key with the same body returns the cached response.



# Register webhook endpoint
Source: https://docs.lerian.studio/en/reference/rails/spb/create-event-webhook

/en/openapi/v3-current/spb.yaml post /v1/str/webhooks
Registers a webhook endpoint that receives control-plane event deliveries. The provided secret is encrypted at rest with AES-256-GCM. The eventTypes array is required and must contain canonical control-plane event constants (str.operation.*, str.readiness.*, str.certificate.*, str.approval.*). Idempotent — replaying the same X-Idempotency key with the same body returns the cached response.



# Submit SME0003 CCME statement (extrato) query
Source: https://docs.lerian.studio/en/reference/rails/spb/create-sme-statement-query

/en/openapi/v3-current/spb.yaml post /v1/str/sme-statement-queries
Submits an SME0003 statement (extrato) query for an IEME's conta correspondente a moeda eletrônica (CCME) and returns a correlation id plus a PENDING state. The answer (SME0003R1) arrives asynchronously; its projection and read endpoint are a later scope. The business date (DtMovto) is derived server-side and echoed back — SME0003 declares no return mode and no window, so it is the only filter the message accepts. Lerian SPB projects the statement BACEN sends; it never computes a CCME position.



# Delete webhook endpoint
Source: https://docs.lerian.studio/en/reference/rails/spb/delete-event-webhook

/en/openapi/v3-current/spb.yaml delete /v1/str/webhooks/{webhookId}
Soft-deletes a webhook endpoint. After deletion the endpoint stops receiving deliveries; historical event_delivery / audit_record rows remain for support investigation. Deletes of unknown ids surface as not-found (SPB-0010), byte-identical to truly-missing.



# Get webhook endpoint
Source: https://docs.lerian.studio/en/reference/rails/spb/get-event-webhook

/en/openapi/v3-current/spb.yaml get /v1/str/webhooks/{webhookId}
Returns a single event-webhook endpoint by id. Encrypted secrets are not exposed. Lookups for unknown ids surface as not-found (SPB-0010), byte-identical to truly-missing.



# Read SME0003 CCME statement (extrato) query result
Source: https://docs.lerian.studio/en/reference/rails/spb/get-sme-statement-query

/en/openapi/v3-current/spb.yaml get /v1/str/sme-statement-queries/{nuOp}
Reads the result of a previously submitted SME0003 conta correspondente a moeda eletrônica (CCME) statement query by its correlation id (the outbound SME0003 NUOp). Returns PENDING until the SME0003R1 answer arrives, then the opening and closing balances BACEN sent, every lançamento in wire order, BACEN's own timestamp and the business date it answered with. A statement with zero entries is still ANSWERED — a CCME with no movement on the day is an answer, not a missing one. Every monetary value crosses as text, verbatim: Lerian SPB never parses or sums a CCME balance and never reconciles the entry sum against the closing balance.



# List webhook endpoints
Source: https://docs.lerian.studio/en/reference/rails/spb/list-event-webhooks

/en/openapi/v3-current/spb.yaml get /v1/str/webhooks
Returns all registered event-webhook endpoints. Encrypted secrets are not exposed.



# SPB error list
Source: https://docs.lerian.studio/en/reference/rails/spb/spb-error-list

Look up any SPB error code, the HTTP status that answers it, and the rejection vocabulary that the BACEN network sends back.

**Error format**

SPB returns errors as RFC 9457 problem details. The API reference declares the `application/problem+json` media type and the `Detail` schema for these responses.

```json JSON theme={null}
{
  "type": "https://errors.lerian.studio/v1/SPB-0003",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "validation failed",
  "code": "SPB-0003",
  "correlationId": "req-7a3f9c2e"
}
```

**Field definitions**

* **`type`** – A URI that identifies the error in the Lerian error catalog, built as `https://errors.lerian.studio/v1/<code>`. A response with no `code` carries the RFC default `about:blank`.
* **`title`** – The HTTP status text, for example `Unprocessable Entity`.
* **`status`** – The HTTP status code.
* **`detail`** – A human-readable explanation of this occurrence. For most `5xx` responses SPB replaces the text with `internal error`, so the internal cause stays out of the response. Branch on `code` instead.
* **`code`** – The stable SPB error code, in the format `SPB-NNNN`.
* **`errors`** – An optional list of per-field validation details. Each entry carries a `message` and a `location`, and can carry the rejected `value`.
* **`correlationId`** – The request-scoped correlation identifier. SPB reuses a valid `X-Request-ID` or generates one. Quote this value in a support request.

The HTTP status depends on the layer that refuses the request. A request that reaches the handler and then breaks a business rule answers with the status in the tables below. A request that the framework refuses before the handler also carries a code. The code is SPB-0001 for a body that SPB cannot parse (`400`), an unsupported method (`405`), or an unsupported media type (`415`). An unknown route answers `404` with SPB-0010, and a request that does not match the published schema answers `422` with SPB-0003.

The idempotency layer runs before the handler. A missing `X-Idempotency` header answers `422` with SPB-0001. A malformed key, or a key reused with a different body, answers `422` with SPB-0003. A replay of a key still in flight answers `409` with SPB-0011.

The `detail` column summarizes the text that SPB puts in the `detail` field. The exact wording depends on the call site, because a call site can replace it with request-specific text.

## Validation and input errors

***

The `SPB-0xxx` range covers a request that SPB read and then refused.

### HTTP 422 Unprocessable Entity

| `code` | Description | `detail` |
| - | - | - |
| SPB-0001 | Missing or invalid required input | invalid input |
| SPB-0003 | Business-rule validation failed | validation failed |

### HTTP 413 Request Entity Too Large

| `code` | Description | `detail` |
| - | - | - |
| SPB-0004 | Request body larger than the configured limit | request body too large |

### HTTP 404 Not Found

| `code` | Description | `detail` |
| - | - | - |
| SPB-0010 | Resource not found | resource not found |

### HTTP 409 Conflict

| `code` | Description | `detail` |
| - | - | - |
| SPB-0011 | Duplicate resource. A replay that arrives while the original request is still in flight also answers this code. | request is already being processed |

## Authentication and authorization errors

***

The `SPB-2xxx` range covers a request whose credential is absent or unusable, and a request that asks for an action outside its permissions. It also covers a request sent over plaintext HTTP in production or staging.

### HTTP 401 Unauthorized

| `code` | Description | `detail` |
| - | - | - |
| SPB-2001 | Authentication required | authentication required |

### HTTP 403 Forbidden

| `code` | Description | `detail` |
| - | - | - |
| SPB-2002 | The caller is not authorized for the action | not authorized |
| SPB-2003 | The request used plaintext HTTP where the deployment requires TLS | HTTPS required |

## Processing and state errors

***

The `SPB-3xxx` range covers a request that SPB accepted and then could not apply. Three of these codes describe a state conflict that you can act on, so they answer `409` rather than a `5xx`.

### HTTP 409 Conflict

| `code` | Description | `detail` |
| - | - | - |
| SPB-3004 | Service readiness blocks the command | service readiness blocks the requested operation |
| SPB-3006 | The operation lifecycle state does not allow the requested action | operation state does not allow the requested action |
| SPB-3007 | The requested retry conflicts with the current resource state | retry conflicts with current resource state |

### HTTP 500 Internal Server Error

| `code` | Description | `detail` |
| - | - | - |
| SPB-3001 | Persistence failure | internal error |

## Rate limiting errors

***

The `SPB-4xxx` range covers a caller that exceeded its request budget.

### HTTP 429 Too Many Requests

| `code` | Description | `detail` |
| - | - | - |
| SPB-4001 | Rate limit exceeded. Retry after a backoff interval. | rate limit exceeded |

## Fallback errors

***

The `SPB-9xxx` range covers a failure on the Lerian side or in a component that SPB depends on. Retry a request that answers `503` or `504`. For the other codes, quote the `correlationId` in a support request.

### HTTP 500 Internal Server Error

| `code` | Description | `detail` |
| - | - | - |
| SPB-9000 | Unexpected internal server error | internal error |
| SPB-9003 | Message pipeline failure | internal error |

### HTTP 503 Service Unavailable

| `code` | Description | `detail` |
| - | - | - |
| SPB-9001 | A downstream dependency is unavailable | internal error |

### HTTP 504 Gateway Timeout

| `code` | Description | `detail` |
| - | - | - |
| SPB-9002 | The operation timed out | internal error |

## Rejections from the BACEN network

***

An `SPB-NNNN` code describes a decision that Lerian SPB made. A message that SPB transmits can still fail at the STR, and that rejection carries BACEN's own vocabulary rather than an `SPB-NNNN` code.

`GET /v1/str/reports/rejected` lists the rejected messages for a date range. Each rejected item carries a `rejectReason` field when BACEN supplied one. The value is BACEN's own error code for the rejection, projected without change. SPB reads it from the error-code field on the STR error return that BACEN sends back.

Treat `rejectReason` as an open vocabulary. The set of values belongs to BACEN, and it grows with the STR catalogue. Pass the value through to your operator rather than matching it against a fixed list in your client.

The settlement outcome travels separately, in the `sitLancSTR` field. SPB projects the STR settlement status verbatim into that field. It does this on the events for an inbound reply and on the Conta PI and electronic-money status reads. On those reads, the field stays empty while the movement is `PENDING`.


# Update webhook endpoint
Source: https://docs.lerian.studio/en/reference/rails/spb/update-event-webhook

/en/openapi/v3-current/spb.yaml patch /v1/str/webhooks/{webhookId}
Patches a webhook endpoint. URL, secret, eventTypes, isActive and metadata are each independently patchable. URL changes re-run the HTTPS + SSRF check; secret changes re-encrypt at rest; eventTypes changes re-validate against the canonical control-plane catalog. nil fields mean "leave unchanged"; an explicit empty eventTypes slice means "clear the subscription list".



# Acknowledge claim
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/acknowledge-claim

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/claims/{claimID}/acknowledge
Donor acknowledges the claim, transitioning it from OPEN to WAITING_RESOLUTION.



# Acknowledge DICT infraction
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/acknowledge-infraction

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/infractions/{id}/acknowledge
Transitions an infraction OPEN→ACKNOWLEDGED and reports the transition to BACEN.



# Watch a CPF/CNPJ for antifraud signal
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/add-person-watchlist-document

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/persons/watchlist
Admits a document to the antifraud watchlist. Once watched, BACEN's ecosystem-wide antifraud counters for that document (getPersonStatistics) are observed on a configured cadence, and a canonical observation fact is emitted whenever BACEN's own watermark moves. Idempotent: re-adding a watched document changes nothing; re-adding a removed one resumes it with its dedupe baseline intact. Rejected with 422 once the participant's document cap is reached, because every watched document is a recurring call against a shared BACEN budget.



# Cancel claim
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/cancel-claim

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/claims/{claimID}/cancel
Cancels a claim. The cancelling side is derived from the authenticated participant; the reason is validated against the claim type, side, and current status per the BACEN DICT cancelClaim matrix.



# Cancel fraud marker
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/cancel-fraud-marker

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/fraud-markers/{id}/cancel
Transitions a fraud marker ACTIVE→INACTIVE and reports the transition to BACEN.



# Cancel DICT funds recovery
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/cancel-funds-recovery

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/funds-recoveries/{id}/cancel
Transitions a funds recovery →CANCELLED (before REFUNDING) and reports the cancellation to BACEN.



# Cancel DICT infraction
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/cancel-infraction

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/infractions/{id}/cancel
Transitions an infraction →CANCELLED and reports the transition to BACEN.



# Complete claim
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/complete-claim

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/claims/{claimID}/complete
Completes a confirmed claim, finalizing the key transfer.



# Confirm claim
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/confirm-claim

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/claims/{claimID}/confirm
Donor confirms the claim, allowing the key transfer to proceed.



# Create fraud marker
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/create-fraud-marker

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/fraud-markers
Persists a minimized fraud marker locally after hashing PII inputs for storage, and submits the corresponding BACEN fraud-marker report synchronously-after-persist, tracked by report_status (PENDING/SENT/FAILED) + request_id.



# Create DICT funds recovery
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/create-funds-recovery

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/funds-recoveries
Creates a local DICT MED 2.0 funds-recovery record and reports it to BACEN (createFundsRecovery). The root transaction is either the contested payment's EndToEndID (pacs.008) or the contested return operation's RtrId (pacs.004), which BACEN reads as a contestação de transação de devolução. BACEN dedups a recovery per RootTransactionId.



# Request the refund of a funds recovery
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/create-funds-recovery-refund

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/funds-recoveries/{id}/refund
Asks BACEN to move an ANALYSED funds recovery into its refunding phase (refundFundsRecovery). Only the participant that created the recovery may ask. BACEN derives the transactions and amounts from the recovery's own tracking graph and answers with the recovery, so no refund record is created locally.



# Fraud marker statistics
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/fraud-marker-stats

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/fraud-markers/stats
Returns fraud-marker counts.



# Get claim
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/get-claim

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/claims/{claimID}
Retrieves a single claim by its UUID. Local-first: a claim this participant lodged is answered from its own record; a DONOR-side claim another PSP opened against one of this participant's keys has no local record and is projected verbatim from BACEN's getClaim. Answers the whole claim entity, the claimer block included, the same shape every claim endpoint answers; a claim streaming fact carries the claim id, the claimed key and the two institutions, never the claimer.



# Get BACEN entry antifraud statistics
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/get-entry-statistics

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/entries/{key}/statistics
Fetches BACEN's system-wide key-level antifraud statistics (owner + key blocks) by Pix key and projects them verbatim, with no local aggregation.



# Get fraud marker
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/get-fraud-marker

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/fraud-markers/{id}
Retrieves a fraud marker by its BACEN-assigned resource UUID, projecting the full ExtendedFraudMarker snapshot including TaxIdNumber in the clear.



# Get DICT funds recovery
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/get-funds-recovery

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/funds-recoveries/{id}
Retrieves a funds recovery by its BACEN-assigned resource UUID, projecting the full ExtendedFundsRecovery snapshot.



# Get DICT funds-recovery tracking graph
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/get-funds-recovery-tracking-graph

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/funds-recoveries/{id}/tracking-graph
Fetches the AUTOMATED-flow fraud-tracking graph from BACEN and projects it verbatim. The manual createTrackingGraph POST is BACEN-deprecated; only this read is current.



# Get DICT infraction
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/get-infraction

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/infractions/{id}
Retrieves an infraction by its BACEN-assigned resource UUID, projecting the full ExtendedInfractionReport snapshot.



# Get BACEN person antifraud statistics
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/get-person-statistics

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/persons/statistics
Fetches BACEN's system-wide person-level antifraud statistics by tax id from the authenticated JSON body and projects them verbatim, with no local aggregation (distinct from local fraud-marker stats).



# Initiate claim
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/initiate-claim

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/participants/{participantISPB}/claims
Initiates a new PIX key ownership or portability claim for the participant identified in the route. Claim deadlines are seven calendar days and claimer/donor ISPB equality is rejected by domain validation.



# Take in client-supplied funds-recovery ids
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/intake-funds-recoveries

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/funds-recoveries/intake
Accepts an inventory of BACEN funds-recovery ids the client already holds and runs each one through the canonical snapshot pipeline: authoritative GET at BACEN, then apply through the same compare-and-set seam every other path uses. This is the only way a recovery older than BACEN's seven-day event-notification window — or one whose notification was lost — becomes visible here; the window is not an inventory. Idempotent by construction: an id already at BACEN's current version is a no-op that emits no second event, so the same batch may be re-sent safely. Each id is answered independently; a batch is capped at 50 ids per request.



# List claims
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/list-claims

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/claims
Returns a paginated list of claims. Scoped server-side to the participants this deployment serves — its own direct and the indirects it sponsors — so a claim neither side of which we serve is never listed. The page carries the whole claim entity, the claimer block included.



# List fraud markers
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/list-fraud-markers

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/fraud-markers
Returns paginated minimized fraud markers.



# List DICT funds recoveries
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/list-funds-recoveries

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/funds-recoveries
Returns paginated local DICT funds-recovery records.



# List a funds recovery's infraction reports
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/list-funds-recovery-infraction-reports

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/funds-recoveries/{id}/infraction-reports
Lists the local DICT infraction reports cross-linked to a funds recovery (local read of our persisted reports, not a BACEN fetch).



# List a funds recovery's refunds
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/list-funds-recovery-refunds

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/funds-recoveries/{id}/refunds
Lists the local DICT refunds cross-linked to a funds recovery (local read of our persisted refunds, not a BACEN fetch).



# List DICT infractions
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/list-infractions

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/infractions
Returns paginated local DICT infraction records.



# List watched CPFs/CNPJs
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/list-person-watchlist

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/persons/watchlist
Lists the documents under antifraud surveillance with the freshness of each one's last observation. BACEN's counters lag reality by up to 12 hours by regulation, so lastWatermark — BACEN's own marker — is the honest 'as of when', never the read time.



# Process claim deadlines
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/process-claim-deadlines

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/internal/claims/process-deadlines
Internal endpoint that processes expired claim deadlines. Intended for cron/scheduler invocation.



# Reject claim (decline)
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/reject-claim

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/claims/{claimID}/reject
Declines a claim. BACEN DICT has no reject verb; this is a USER_REQUESTED cancellation that aborts the key transfer while keeping the existing key link unchanged. The cancelling side is derived from the authenticated participant; the reason×type matrix then constrains the cell (a donor declining an OWNERSHIP claim via USER_REQUESTED is rejected — the donor's ownership lever is FRAUD).



# Stop watching a CPF/CNPJ
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/remove-person-watchlist-document

/en/openapi/v3-current/spi-dict.yaml delete /api/v1/dict/persons/watchlist/{id}
Stops observing a document. This is a soft stop: polling ceases immediately, and every observation fact already emitted stays emitted — nothing is retracted or deleted. Re-adding the same document later resumes the same entry.



# Correct an open funds recovery
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/update-funds-recovery

/en/openapi/v3-current/spi-dict.yaml put /api/v1/dict/funds-recoveries/{id}
Corrects the situation type and report details of a funds recovery still awaiting analysis, and re-pushes the participant's registered regulator contact (updateFundsRecovery). Without it a wrong contact can only be fixed by cancelling and reopening the recovery.



# Request a Conta PI account report
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/create-account-report-request

/en/openapi/v3-current/spi.yaml post /api/v1/spi/account-reports/requests
Prerequisite: this is the request step of the account-reporting chain (camt.060 request → camt.052/053/054 result read); the camt.060 request MUST be submitted and correlated first — the camt.05x result is read back only after this request is acknowledged. Builds a camt.060 account-reporting request (BALANCE → camt.053 the SALDO/balance, STATEMENT → camt.052 the entry-list file pointer, ENTRIES → camt.054 the entry detail), records an ACCOUNT_INFORMATION_REQUEST operation keyed on the generated correlation id, and submits the signed payload to the BACEN catalogue surface.



# Create approval request
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/create-approval

/en/openapi/v3-current/spi.yaml post /api/v1/spi/approvals
Creates a new approval_decisions row in REQUESTED state.



# Initiate SPI connectivity test
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/create-connectivity-test

/en/openapi/v3-current/spi.yaml post /api/v1/spi/connectivity-tests
Prerequisite: this is the rail-liveness step of the onboarding chain (connectivity-test → submit); a passing connectivity test is the prerequisite for a submit operation (see createPayment, createStructuredOperation). Builds a pibr.001 echo request, records a CONNECTIVITY_TEST operation keyed on the generated correlation id, and submits the signed payload to the BACEN catalogue surface.



# Create evidence export job
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/create-evidence-export

/en/openapi/v3-current/spi.yaml post /api/v1/spi/evidence/exports
Creates an evidence_export_jobs row in QUEUED state. Idempotent — a duplicate X-Idempotency returns the existing job.



# Cancel a Pix Automático mandate (pain.011)
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/create-mandate-cancellation

/en/openapi/v3-current/spi.yaml post /api/v1/spi/mandates/cancellations
Builds a pain.011 cancellation for an EXISTING mandate, validates the mandate state machine, and submits the signed payload to BACEN.



# Request confirmation of a Pix Automático mandate (pain.009)
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/create-mandate-request

/en/openapi/v3-current/spi.yaml post /api/v1/spi/mandates
Builds a pain.009 mandate-confirmation request, validates the mandate state machine, records the PIX_AUTOMATIC_AUTHORIZATION operation, and submits the signed payload to the BACEN catalogue surface.



# Accept or reject a Pix Automático mandate (pain.012)
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/create-mandate-resolution

/en/openapi/v3-current/spi.yaml post /api/v1/spi/mandates/resolutions
Builds a pain.012 acceptance report for a mandate the platform holds, validates the mandate state machine, and submits the signed payload to BACEN. A PDNG acceptance is the jornada-1 receipt acknowledgement: it is recorded and sent without changing the mandate, so the payer's later decision (CFDB or a rejection) goes through this same route. A CFDB through a QR-code journey (AUT2, AUT3 or AUT4) is the one resolution that needs no held mandate: when no pain.009 preceded it, it registers the mandate from the request as active and names the recurrence creation instant read from the Rec.



# Create payment
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/create-payment

/en/openapi/v3-current/spi.yaml post /api/v1/spi/payments
Prerequisite: a passing connectivity test (see createConnectivityTest) confirms the rail is reachable before a submit. Initiates a new BRL-only SPI payment via BACEN. Generates an EndToEndID if not provided. The EndToEndID format is E{ISPB}{YYYYMMDD}{uniqueID}, exactly 32 characters.



# Request cancellation of a Pix Automático schedule (camt.055)
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/create-schedule-cancellation

/en/openapi/v3-current/spi.yaml post /api/v1/spi/scheduled-payments/cancellations
Builds a camt.055 cancellation request for a schedule the platform tracks, validates the schedule state machine, and submits the signed payload to BACEN.



# Resolve a received cancellation request (camt.029)
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/create-schedule-cancellation-resolution

/en/openapi/v3-current/spi.yaml post /api/v1/spi/scheduled-payments/cancellations/resolutions
Builds a camt.029 resolution (ACCR/RJCR) for a camt.055 the platform actually RECEIVED; unknown correlations are rejected.



# Schedule a Pix Automático payment instruction (pain.013)
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/create-scheduled-payment

/en/openapi/v3-current/spi.yaml post /api/v1/spi/scheduled-payments
Builds a pain.013 scheduled payment instruction, enforces the ACTIVE-mandate precondition, records the SCHEDULED_PAYMENT_INSTRUCTION operation, and submits the signed payload to BACEN.



# Accept or reject a Pix Automático scheduled payment (pain.014)
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/create-scheduled-payment-resolution

/en/openapi/v3-current/spi.yaml post /api/v1/spi/scheduled-payments/resolutions
Builds a pain.014 status report (ACSP/RJCT) for a schedule the platform holds, validates the schedule state machine, and submits the signed payload to BACEN.



# Report internally settled Pix transactions (MED 2.0)
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/create-settlement-report

/en/openapi/v3-current/spi.yaml post /api/v1/spi/settlement-reports
Builds a trck.002 internal-settlement report, records a TRACKING_REPORT operation keyed on the generated correlation id, and submits the signed payload to the BACEN catalogue surface.



# Create structured operation
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/create-structured-operation

/en/openapi/v3-current/spi.yaml post /api/v1/spi/operations
Prerequisite: a passing connectivity test (see createConnectivityTest) confirms the rail is reachable before a submit. Submits a structured business operation to the SPI rail. Raw regulated payloads are forbidden anywhere in the request body.



# Deactivate a Pix certificate
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/deactivate-pix-certificate

/en/openapi/v3-current/spi.yaml delete /api/v1/spi/certificates/{id}
Flips an ACTIVE certificate to DEACTIVATED and appends a DEACTIVATE audit row. Never a hard delete — the inventory and its audit trail are retained.



# Decide approval
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/decide-approval

/en/openapi/v3-current/spi.yaml post /api/v1/spi/approvals/{approvalId}/decision
Records an Approve or Deny decision on an approval_decisions row.



# Evaluate recovery eligibility
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/evaluate-recovery

/en/openapi/v3-current/spi.yaml post /api/v1/spi/operations/{operationId}/recovery/evaluate
Read-only preview of recovery eligibility for an operation. No persistence; no state mutation.



# Execute recovery action
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/execute-recovery

/en/openapi/v3-current/spi.yaml post /api/v1/spi/recovery/actions/{recoveryActionId}/execute
Executes a previously requested recovery action.



# Read a Conta PI balance (camt.053 result)
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/get-account-report-balance

/en/openapi/v3-current/spi.yaml get /api/v1/spi/account-reports/{correlationId}/balance
Result step of the account-reporting chain (camt.060 request → camt.053 balance read). Returns the Conta PI SALDO balances BACEN sent in the inbound camt.053, projected verbatim and keyed by the camt.060 correlation id. Reads PENDING until the camt.053 arrives, then ANSWERED with the typed balance set (raw BalanceTypeCode + verbatim amounts) plus a freshness timestamp. Lerian SPI projects the balance BACEN sends; it never computes a position.



# Read a Conta PI extrato (camt.052 RCO lançamentos result)
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/get-account-report-extract

/en/openapi/v3-current/spi.yaml get /api/v1/spi/account-reports/{correlationId}/extract
Result step of the account-reporting chain (camt.060 SOLIC_REL_LANCAMENTO request → camt.052 extrato read). Returns the RCO lançamentos rows BACEN generated on the ARQ rail, fetched + SHA-256-verified + parsed + projected verbatim, keyed by the camt.060 correlation id. Reads PENDING until the camt.052 extrato is received and verified, then ANSWERED with the parsed rows plus the integrity and row-COUNT recon status (declaredEntryCount vs parsedEntryCount). Lerian SPI projects the extrato BACEN sends and reconciles its integrity + row count; it never sums an amount nor computes a position.



# Get approval
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/get-approval

/en/openapi/v3-current/spi.yaml get /api/v1/spi/approvals/{approvalId}
Retrieves an approval_decisions row by id.



# Get evidence export job
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/get-evidence-export

/en/openapi/v3-current/spi.yaml get /api/v1/spi/evidence/exports/{exportId}
Returns the export job state for the given id.



# Inspect a recorded Pix Automático mandate operation (internal operator read)
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/get-mandate

/en/openapi/v3-current/spi.yaml get /api/v1/spi/mandates/{mandateId}
INTERNAL operator read. Returns the recorded PIX_AUTOMATIC_AUTHORIZATION operation for the mandate id, with its lifecycle state. Unknown mandate ids return 404 so existence is non-enumerable. Projects stored facts verbatim — no monetary value or position. This is an operational read surface, NOT a BACEN API-Pix conformant endpoint.



# Inspect a message-log entry and its correspondent
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/get-message-log-detail

/en/openapi/v3-current/spi.yaml get /api/v1/spi/messages/{messageRecordId}
Returns the requested message_records row plus its correspondent — the sibling row sharing operation_id (Mensagem Original + Mensagem Correspondente). Hash-only metadata; no raw XML and no payload body are returned, and the original<->correspondent pairing is a single indexed lookup, never a monetary aggregate.



# Get operation evidence
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/get-operation-evidence

/en/openapi/v3-current/spi.yaml get /api/v1/spi/operations/{operationId}/evidence
Returns a chronological page of normalized evidence records for an operation. Raw payload references are denied by default.



# Get operation timeline
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/get-operation-timeline

/en/openapi/v3-current/spi.yaml get /api/v1/spi/operations/{operationId}/timeline
Returns a chronological page of timeline events for one operation. Limit defaults to 50, capped at 200.



# Get one parked ICOM message
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/get-parked-icom-message

/en/openapi/v3-current/spi.yaml get /api/v1/spi/icom/parked/{resourceId}
Returns one parked message's metadata by PI-ResourceId. Never returns the message body.



# Get payment
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/get-payment

/en/openapi/v3-current/spi.yaml get /api/v1/spi/payments/{endToEndID}
Retrieves a single payment by its EndToEndID, including event history when available.



# Get payment history
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/get-payment-history

/en/openapi/v3-current/spi.yaml get /api/v1/spi/payments/{endToEndID}/history
Retrieves the full event history for a payment, ordered chronologically.



# Get payment return status
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/get-payment-return-status

/en/openapi/v3-current/spi.yaml get /api/v1/spi/payments/{endToEndID}/returns/status
Alias of Get payment for clients polling return state.



# Get a Pix certificate with its audit trail
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/get-pix-certificate

/en/openapi/v3-current/spi.yaml get /api/v1/spi/certificates/{id}
Returns one certificate's structured public metadata plus its append-only audit trail (UPLOAD/DEACTIVATE), newest first.



# Get a participant's last-known Conta-PI responsibles
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/get-responsibles

/en/openapi/v3-current/spi.yaml get /api/v1/spi/responsibles/{ispb}
Returns the last-known Conta-PI responsibles snapshot (CONTATOPSP contact, DIRETORPSP director, palavra-chave) for the participant ISPB, plus its source (SUBMITTED / COMP_CONFIRMED) and recorded-at. reda.022 is fire-to-BACEN; this read-model is written on submit-success and refreshed on the inbound reda.016 COMP advice. Structured fields only — never signed bytes. The palavra-chave is a regulatory identifier returned verbatim; it is masked on display.



# Inspect a recorded Pix Automático schedule operation (internal operator read)
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/get-schedule

/en/openapi/v3-current/spi.yaml get /api/v1/spi/scheduled-payments/{scheduleId}
INTERNAL operator read. Returns the recorded SCHEDULED_PAYMENT_INSTRUCTION operation for the schedule id, with its lifecycle state. Unknown schedule ids return 404 so existence is non-enumerable. Projects stored facts verbatim — no monetary value or position. This is an operational read surface, NOT a BACEN API-Pix conformant endpoint.



# Get SPI capability by ID
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/get-spi-capability

/en/openapi/v3-current/spi.yaml get /api/v1/spi/capabilities/{capabilityId}
Returns the detail of a single SPI/Pix capability identified by its message type (e.g. "pacs.008").



# Conta-PI balance-window report
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/get-spi-report-balances

/en/openapi/v3-current/spi.yaml get /api/v1/spi/reports/balances
Lists the spi_account_balance snapshots (camt.053 saldo) received in a mandatory date window (max 92 days), projected verbatim. The amount is the BACEN-supplied figure projected as-is — never recomputed, never summed.



# Conta-PI extract-list report
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/get-spi-report-extracts

/en/openapi/v3-current/spi.yaml get /api/v1/spi/reports/extracts
Lists the spi_account_extract rows (camt.052/RCO) received in a mandatory date window (max 92 days) with their report_kind and integrity (verified) + COUNT-recon (countsMatch) flags. The RCO entries stay opaque and are not inlined; no arithmetic is performed over balances.



# SPI rejected-payments report
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/get-spi-report-rejected

/en/openapi/v3-current/spi.yaml get /api/v1/spi/reports/rejected
Returns the COUNT and a paginated list of payments in a terminal-rejected state (REJECTED / FAILED / RETURN_PENDING) over a mandatory date window (max 92 days). The detailed reject reason is not retained — only status + EndToEndID are returned, and the absence is labelled honestly.



# SPI volumetria report (COUNT-only)
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/get-spi-report-volumetria

/en/openapi/v3-current/spi.yaml get /api/v1/spi/reports/volumetria
Returns COUNT(*) buckets grouped by message type, status, or participant over a mandatory date window (max 92 days). COUNT-only: the SPI payments record persists no amount, so there is no monetary sum on the SPI side.



# Initiate payment return
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/initiate-payment-return

/en/openapi/v3-current/spi.yaml post /api/v1/spi/payments/{endToEndID}/returns
Prerequisite: the parent payment must be SETTLED before a return — read its state via getPayment (GET /api/v1/spi/payments/{endToEndID}); the {endToEndID} path segment structurally ties the return to its parent. Initiates an idempotent full payment return via BACEN.



# List recorded Pix Automático mandate operations (internal operator read)
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/list-mandates

/en/openapi/v3-current/spi.yaml get /api/v1/spi/mandates
INTERNAL operator read. Returns a page of the platform's PIX_AUTOMATIC_AUTHORIZATION operations with their mandate lifecycle state, optionally filtered by status. Projects stored operation facts verbatim — no monetary value or position is returned or computed. This is an operational read surface, NOT a BACEN API-Pix conformant endpoint.



# List the SPI message log
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/list-message-log

/en/openapi/v3-current/spi.yaml get /api/v1/spi/messages
Returns a chronological, filterable page of message_records rows (Data/Hora, Tipo, Fluxo, Situação). Each row carries metadata + the SHA-256 payload hash only — the raw signed XML is never persisted at rest — and no monetary or position field is returned.



# List parked ICOM messages
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/list-parked-icom-messages

/en/openapi/v3-current/spi.yaml get /api/v1/spi/icom/parked
Lists inbound BACEN messages the rail boundary refused past the threshold, and messages whose body was empty or exceeded the size cap. Each was stored durably and acked toward ICOM so the out-stream could advance; an empty or oversized one keeps no body (an oversized one keeps its first bytes) and cannot be replayed, every other one waits for an operator replay. Metadata only: PI-ResourceId, channel, message type, size, a closed-vocabulary reason, attempts and timestamps — never the message body, a tax id, a key or an account. Nothing in this surface discards a message.



# List payments sent and received
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/list-payments

/en/openapi/v3-current/spi.yaml get /api/v1/spi/payments
Returns one page of the Pix this rail sent and received, newest first, filterable by direction, status, creation window and counterparty ISPB. An operational rail read, not a BACEN API-Pix endpoint: the BACEN recebidos listing is listReceivedPix.



# List arriving Pix awaiting a funding decision
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/list-pix-awaiting-funding

/en/openapi/v3-current/spi.yaml get /api/v1/spi/pix/awaiting-funding
Returns the arriving Pix this rail received from BACEN and parked awaiting the funding decision only the client's own system can make. Each item carries the endToEndId that processInboundMessage (POST /api/v1/spi/messages/inbound/process) is addressed by, plus the amount that arrived. This is an operational rail read, not a BACEN API-Pix conformant endpoint: a Pix listed here has NOT settled.



# List Pix certificates
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/list-pix-certificates

/en/openapi/v3-current/spi.yaml get /api/v1/spi/certificates
Returns the managed Pix-side certificate inventory (PIC/PIA/QR-code/CERTPIC/signing) with type, origin, status, custody, and validity window — structured public metadata only. Key material is never exposed.



# Consultar Pix recebidos
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/list-received-pix

/en/openapi/v3-current/spi.yaml post /api/v1/spi/pix
Returns the BACEN PixConsultados envelope of received Pix (those settled to this FI as creditor) within the inicio/fim window, each projected with its devoluções. cpf and cnpj are mutually exclusive and are accepted only in the authenticated JSON body so they never enter URLs or access logs.



# List recorded Pix Automático schedule operations (internal operator read)
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/list-schedules

/en/openapi/v3-current/spi.yaml get /api/v1/spi/scheduled-payments
INTERNAL operator read. Returns a page of the platform's SCHEDULED_PAYMENT_INSTRUCTION operations with their schedule lifecycle state, optionally filtered by status. Projects stored operation facts verbatim — no monetary value or position is returned or computed. This is an operational read surface, NOT a BACEN API-Pix conformant endpoint.



# List SPI capabilities
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/list-spi-capabilities

/en/openapi/v3-current/spi.yaml get /api/v1/spi/capabilities
Returns the public catalog of SPI/Pix capabilities. Every authenticated caller sees the same rows. Supports filtering by operation family, handling mode, direction, and availability.



# List stuck operations (operator dashboard)
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/list-stuck-operations

/en/openapi/v3-current/spi.yaml get /api/v1/spi/operations/stuck
Returns the cross-rail operator dashboard page of operations needing attention, conformed to the shared recovery vocabulary. Each row carries only the verbs SPI can actually perform on it (a verb SPI cannot perform is absent) and the disposition ('what happens if I do nothing'). No monetary or position fields are returned.



# Manually resolve operation
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/manual-resolve-operation

/en/openapi/v3-current/spi.yaml post /api/v1/spi/operations/{operationId}/recovery/manual-resolution
Closes a stuck operation by operator decision, gated by an APPROVED approval_decisions row.



# Decide a parked inbound Pix
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/process-inbound-message

/en/openapi/v3-current/spi.yaml post /api/v1/spi/messages/inbound/process
Prerequisite: the Pix must be parked awaiting funding — enumerate it via listPixAwaitingFunding (GET /api/v1/spi/pix/awaiting-funding) and use the endToEndId it returns. Concludes that payment one of three ways, and a request states exactly one of them. Supply the funding evidence your own system holds (availableBalance, availableLimit, riskScore) and this rail assesses it against the amount: the Pix is accepted, or it is refused with the reason the assessment produced. An accepted Pix is answered ACSP to BACEN and is not settled yet (settled is false): it settles when the SPI confirms with ACCC, which spi.payment.settled announces, or is refused if the SPI rejects it. Supply authorized instead, with no evidence, when your own system has already authorized the credit: the Pix is accepted exactly as an assessed approval is and nothing is assessed, because you decided and you measured no balance for this rail to weigh. Supply refusalReason instead, with no evidence, when your system has already refused the credit for a reason that is not about money — the key resolving to nothing (AC03), an account that cannot receive (AC06) or an account held by someone other than the stated receiver (BE01): the Pix is refused with that reason and nothing is assessed. A request carrying none of the three, or more than one, is refused (422) and changes nothing. An endToEndId this rail is not holding is refused (404) and changes nothing; a payment that already concluded is refused (409). A verdict that arrives after the Pix ran out of its regulatory window is also refused (409), and that one is final: the rail has closed the window itself and no other evidence reopens it, so abandon the decision rather than retrying it. These and every other rejection here are reported through this operation's generic error response (Detail), not a distinguished per-status schema entry.



# Internal rail inbound callback
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/rail-inbound-callback

/en/openapi/v3-current/spi.yaml post /internal/v1/spi/rail/inbound
Internal-only inbound rail callback guarded by the X-Internal-Callback shared secret. Not a client API surface.



# Register Conta PI responsible contacts
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/register-responsibles

/en/openapi/v3-current/spi.yaml post /api/v1/spi/responsibles
Builds the reda.022 four-block envelope (CONTATOPSP contact, DIRETORPSP director, palavra-chave, CPFDIRETOR), records a PARTICIPANT_ADMINISTRATION operation keyed on the generated correlation id, and submits the signed payload to the BACEN catalogue surface.



# Replay a parked ICOM message
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/replay-parked-icom-message

/en/openapi/v3-current/spi.yaml post /api/v1/spi/icom/parked/{resourceId}/replay
Re-presents a parked message at the rail boundary with its original bytes and original receipt time, through the same channel and the same idempotency key the first forward used. A terminal outcome closes the row; a non-terminal one leaves it parked with one more attempt. This is the ONLY way a message leaves the parked set — there is no discard verb. An empty or oversized message is refused with 409: its body was not stored.



# Solicitar devolução
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/request-devolucao

/en/openapi/v3-current/spi.yaml put /api/v1/spi/pix/{e2eid}/devolucao/{id}
Prerequisite: the parent payment must be SETTLED before a return — read its state via getPayment (GET /api/v1/spi/payments/{endToEndID}). Requests a (possibly partial) Pix return identified by the client-generated DevolucaoId {id}; the sum of all returns must not exceed the original Pix value. A repeat PUT with the same {id} replays the existing devolução. Emits a pacs.004 (reason MD06 for ORIGINAL, SL02 for RETIRADA).



# Request recovery action
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/request-recovery

/en/openapi/v3-current/spi.yaml post /api/v1/spi/operations/{operationId}/recovery/actions
Creates a new recovery action. ALLOWED → REQUESTED; BLOCKED → refused (409 RECOVERY_NOT_ALLOWED, reported through this operation's generic error response, not a distinguished per-status schema entry); APPROVAL_REQUIRED → APPROVAL_REQUIRED row.



# Submit an operator verb against a stuck row
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/submit-stuck-operation-action

/en/openapi/v3-current/spi.yaml post /api/v1/spi/operations/stuck/actions
Spends one of the affordances the stuck-operations listing offered on a row. The verb is re-evaluated against the LIVE row at submit time, so an affordance that has since become unsafe is refused here even though the listing offered it. A devolução release requires an operator justification and asserts only that the return did not happen — it publishes nothing a ledger reads as money moving.



# Upload a Pix certificate (public .cer)
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/upload-pix-certificate

/en/openapi/v3-current/spi.yaml post /api/v1/spi/certificates
Imports a PUBLIC certificate (.cer; base64-encoded PEM or DER). The private key NEVER crosses this boundary — a .p12/private-key payload is rejected with 422 (fail-closed), reported through this operation's generic error response (Detail), not a distinguished per-status schema entry. For an HSM-custody key (the KMIP signing leaf) the flow is CSR-generate-in-HSM then upload the issued .cer only.



# Validate inbound message
Source: https://docs.lerian.studio/en/reference/rails/spi/spi/validate-inbound-message

/en/openapi/v3-current/spi.yaml post /api/v1/spi/messages/inbound/validate
Validates an inbound ISO 20022 XML message (schema and signature) without processing it.



# Get one tenant config key
Source: https://docs.lerian.studio/en/reference/rails/slc/get-tenant-config

/en/openapi/v3-current/slc.yaml get /admin/config/{key}
Returns the request tenant's effective value for a fenced config key: the stored override when present, else the catalog default. An off-catalog key is 404. RBAC: config:read; tenant is always derived from the validated request identity, never a path or payload value.



# List dead letters
Source: https://docs.lerian.studio/en/reference/rails/slc/list-dead-letters

/en/openapi/v3-current/slc.yaml get /admin/dlq/{queue}
Lists the request tenant's parked dead letters for the given queue (rsfn or sfn) NON-destructively — the messages the RSFN / SILOC ingest drivers could not process — available for administrative replay. queue is validated against the allowlist (unknown → 404). RBAC: dlq:read; tenant is always derived from the validated request identity, never a path or payload value.



# List effective tenant config
Source: https://docs.lerian.studio/en/reference/rails/slc/list-tenant-config

/en/openapi/v3-current/slc.yaml get /admin/config
Lists the request tenant's EFFECTIVE per-tenant runtime config: every fenced connectivity key with its overridden value or the catalog default, ordered by key. RBAC: config:read; tenant is always derived from the validated request identity, never a path or payload value. Selection/policy only — no secret material.



# Reset one tenant config key
Source: https://docs.lerian.studio/en/reference/rails/slc/reset-tenant-config

/en/openapi/v3-current/slc.yaml delete /admin/config/{key}
Clears the request tenant's override for a fenced config key, returning it to the catalog default. Idempotent: resetting a key with no override is a successful no-op. An off-catalog key is 404. Returns 204 No Content. RBAC: config:write; the actor and tenant are always derived from the validated request identity, never a path or payload value.



# Set one tenant config key
Source: https://docs.lerian.studio/en/reference/rails/slc/set-tenant-config

/en/openapi/v3-current/slc.yaml put /admin/config/{key}
Persists a per-tenant override for a fenced config key. Body: {"value":"..."}. The value is scope-fenced + validated against the catalog: a missing value is a schema 422, an empty value a coded 400, an off-catalog key 404, an off-enum / non-bool value 422. RBAC: config:write; the writing actor and the tenant are always derived from the validated request identity, never a path or payload value.



# Create payload location
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/create-location

/en/openapi/v3-current/spi-brcode.yaml post /api/v1/brcode/loc
Creates a location (loc) for a cob- or cobv-type charge. Pix API POST /loc.



# Create recurrence location
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/create-location-rec

/en/openapi/v3-current/spi-brcode.yaml post /api/v1/brcode/locrec
Creates a recurrence location (locrec). The request has no body. Pix API POST /locrec.



# Decode BR Code
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/decode-br-code

/en/openapi/v3-current/spi-brcode.yaml post /api/v1/brcode/decode
Decodes a raw BR Code string into its structured payload components.



# Unlink recurrence from a location
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/delete-location-rec-id-rec

/en/openapi/v3-current/spi-brcode.yaml delete /api/v1/brcode/locrec/{id}/idRec
Unlinks the recurrence (idRec) from a recurrence location. Pix API DELETE /locrec/{id}/idRec.



# Unlink charge from a location
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/delete-location-tx-id

/en/openapi/v3-current/spi-brcode.yaml delete /api/v1/brcode/loc/{id}/txid
Unlinks the charge (txid) from a location. The charge loses its location; the status remains unchanged. Pix API DELETE /loc/{id}/txid.



# Download the CNAB 750 retorno
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/download-file-batch-retorno

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/arquivos/{id}/retorno
Downloads the batch's retorno file: the CNAB 750 receipt of what the rail did with each record of the remessa. It is served byte for byte as it was generated, never re-rendered, because a retorno already downloaded is the client's only proof. 404 when the batch does not exist; 409 while the batch has not produced a retorno.



# Download the CNAB 750 settlement file
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/download-liquidacoes

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/arquivos/liquidacoes
Downloads the settlement file (Febraban CNAB 750 collection return) for the Pix received by ONE recebedor within the requested window. Exactly one of cpf OR cnpj of the recebedor is required: a window with no recebedor would name all of them, and this file aggregates settlement PII. The window selects PAYMENTS, not charges: each Pix is reported in the file of the day on which IT settled, which is the date of its own DATA DO MOVIMENTO, so a second Pix on an already completed charge goes into the file of ITS day, not the day of the first payment. No line carries a movement outside the window, and windows that do not overlap never report the same payment twice. The file is built on demand, with no 'already reported' marker: the same window over the SAME DATA returns the same bytes, in the same order. A past window is not final: a settlement fact delivered late, with an instant inside the window, enters that window's file after the file was already downloaded. Reconcile by downloading the windows again; deduplication across overlapping windows is the client's, by endToEndId. An empty window is a valid file with no detail records (200), not a 404.



# Generate BR Code
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/generate-br-code

/en/openapi/v3-current/spi-brcode.yaml post /api/v1/brcode/
Prerequisite: for a dynamic QR, the cob/cobv charge must be created first (see putCob, putCobV) — the payload links to it by txid/locator. Generates a new BR Code (QR code) payload following the EMV QRCPS-MPM standard.



# Get BR Code info
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/get-br-code-info

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/info/{payload}
Returns structured metadata for a raw BR Code payload.



# BR Code payload JWK Set
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/get-br-code-jwks

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/.well-known/jwks.json
Publishes the recebedor PSP's JWK Set (RFC 7517). A payer PSP resolves the JWS verification key for a public cob/cobv/rec payload by matching the payload's JWS header kid to an entry kid here. Returns 404 when JOSE payload signing is not configured.



# Get BR Code payload
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/get-br-code-payload

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/{id}
Retrieves a single BR Code payload by its UUID.



# Retrieve immediate charge
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/get-cob

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/cob/{txid}
Retrieves an immediate charge by its txid. Pix API v2.9 GET /cob/{txid}.



# Retrieve recurring charge
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/get-cob-r

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/cobr/{txid}
Retrieves a recurring charge by its txid. Pix API GET /cobr/{txid}.



# Retrieve due-date charge
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/get-cob-v

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/cobv/{txid}
Retrieves a due-date charge by its txid. Pix API v2.9 GET /cobv/{txid}.



# Get file batch status
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/get-file-batch

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/arquivos/{id}
Returns the status of a batch submitted through the file channel (ANEXO VI, CNAB 750) and the result of each record of the remessa. The submitted content is not projected: the remessa carries the debtor's document and name.



# Retrieve location
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/get-location

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/loc/{id}
Retrieves a location by its id. Pix API GET /loc/{id}.



# Retrieve recurrence location
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/get-location-rec

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/locrec/{id}
Retrieves a recurrence location by its id. Pix API GET /locrec/{id}.



# Retrieve due-date charge batch
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/get-lote-cob-v

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/lotecobv/{id}
Retrieves a due-date charge batch by its id. Pix API GET /lotecobv/{id}.



# Retrieve recurrence (Pix Automático)
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/get-rec

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/rec/{idRec}
Retrieves a recurrence by its idRec. Pix API GET /rec/{idRec}. Projects the stored Rec fields verbatim, including recebedor.convenio. An unknown idRec returns 404 (canonical Problem envelope).



# Get recebedor profile
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/get-recebedor-profile

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/recebedores/{chave}
Returns the FI-registered recebedor identity for a Pix key, or 404 when no profile is registered.



# Retrieve recurrence request (Pix Automático)
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/get-solic-rec

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/solicrec/{idSolicRec}
Retrieves a request by its idSolicRec. Pix API GET /solicrec/{idSolicRec}. Projects the stored fields verbatim. An unknown idSolicRec returns 404 (canonical Problem envelope).



# List BR Code payloads
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/list-br-code-payloads

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/
Returns a paginated list of BR Code payloads.



# List immediate charges
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/list-cob

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/cob
Lists immediate charges by start date, end date, cpf, cnpj, locationPresente, and status. Pix API v2.9 GET /cob.



# List recurring charges
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/list-cob-r

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/cobr
Lists recurring charges by start date, end date, idRec, and status. Pix API GET /cobr.



# List due-date charges
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/list-cob-v

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/cobv
Lists due-date charges by start date, end date, cpf, cnpj, locationPresente, status, and loteCobVId. Pix API v2.9 GET /cobv.



# List locations
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/list-location

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/loc
Lists locations by start date, end date, txIdPresente, and tipoCob. Pix API GET /loc.



# List recurrence locations
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/list-location-rec

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/locrec
Lists recurrence locations by start date, end date, and idRecPresente. Pix API GET /locrec.



# List due-date charge batches
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/list-lote-cob-v

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/lotecobv
Lists due-date charge batches by start date and end date. Pix API GET /lotecobv.



# List recurrences (Pix Automático)
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/list-rec

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/rec
Lists recurrences by start date, end date, cpf, cnpj, convênio, and status. Pix API GET /rec.



# Revise immediate charge
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/patch-cob

/en/openapi/v3-current/spi-brcode.yaml patch /api/v1/brcode/cob/{txid}
Revises an immediate charge. status=REMOVIDA_PELO_USUARIO_RECEBEDOR removes the charge. Pix API v2.9 PATCH /cob/{txid}.



# Revise recurring charge (cancel)
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/patch-cob-r

/en/openapi/v3-current/spi-brcode.yaml patch /api/v1/brcode/cobr/{txid}
Revises a recurring charge. status=CANCELADA cancels the charge (only before the first settlement attempt). Pix API PATCH /cobr/{txid}.



# Revise due-date charge
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/patch-cob-v

/en/openapi/v3-current/spi-brcode.yaml patch /api/v1/brcode/cobv/{txid}
Revises a due-date charge. status=REMOVIDA_PELO_USUARIO_RECEBEDOR removes the charge. Pix API v2.9 PATCH /cobv/{txid}.



# Revise due-date charge batch
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/patch-lote-cob-v

/en/openapi/v3-current/spi-brcode.yaml patch /api/v1/brcode/lotecobv/{id}
Revises specific charges within a batch. The cobsv array may contain fewer items than the originating batch, but it cannot add or remove charges. Pix API PATCH /lotecobv/{id}.



# Revise recurrence (Pix Automático)
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/patch-rec

/en/openapi/v3-current/spi-brcode.yaml patch /api/v1/brcode/rec/{idRec}
Partially revises a recurrence (Rec) by its idRec: changes calendario.dataInicial and ativacao.dadosJornada.txid (only while status == CRIADA), vinculo.devedor.nome and loc (links a locrec; both can change after confirmation too), and/or the status (CANCELADA cancels the mandate). Pix API PATCH /rec/{idRec}. Rejects any change when the recurrence is EXPIRADA/CANCELADA/REJEITADA (422). An unknown idRec returns 404 (canonical Problem envelope).



# Revise (cancel) recurrence request (Pix Automático)
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/patch-solic-rec

/en/openapi/v3-current/spi-brcode.yaml patch /api/v1/brcode/solicrec/{idSolicRec}
Cancels a request by its idSolicRec (target status CANCELADA). Pix API PATCH /solicrec/{idSolicRec}.



# Create immediate charge (PSP-generated txid)
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/post-cob

/en/openapi/v3-current/spi-brcode.yaml post /api/v1/brcode/cob
Prerequisite: create this charge before generating its QR/payload (see generateBRCode and resolveCobPayload). Creates an immediate charge (Cob) with a server-generated txid. Pix API v2.9 POST /cob.



# Create recurring charge (PSP-generated txid)
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/post-cob-r

/en/openapi/v3-current/spi-brcode.yaml post /api/v1/brcode/cobr
Creates a recurring charge (CobR) with a server-generated txid. Pix API POST /cobr.



# Request settlement retry
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/post-cob-r-retentativa

/en/openapi/v3-current/spi-brcode.yaml post /api/v1/brcode/cobr/{txid}/retentativa/{data}
Requests a new settlement attempt for the given date. Requires the PERMITE_3R_7D policy. Pix API POST /cobr/{txid}/retentativa/{data}.



# Create recurrence (Pix Automático)
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/post-rec

/en/openapi/v3-current/spi-brcode.yaml post /api/v1/brcode/rec
Creates a recebedor-side recurrence (Rec) with a server-generated idRec. Pix API POST /rec.



# Create recurrence request (Pix Automático)
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/post-solic-rec

/en/openapi/v3-current/spi-brcode.yaml post /api/v1/brcode/solicrec
Creates a recurrence confirmation request (SolicRec) with a server-generated idSolicRec. Pix API POST /solicrec.



# Create immediate charge (idempotent txid)
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/put-cob

/en/openapi/v3-current/spi-brcode.yaml put /api/v1/brcode/cob/{txid}
Creates an immediate charge (Cob) identified by the path txid (idempotent). Pix API v2.9 PUT /cob/{txid}.



# Create recurring charge (idempotent txid)
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/put-cob-r

/en/openapi/v3-current/spi-brcode.yaml put /api/v1/brcode/cobr/{txid}
Creates a recurring charge (CobR) identified by the path txid (idempotent). Pix API PUT /cobr/{txid}.



# Create due-date charge (idempotent txid)
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/put-cob-v

/en/openapi/v3-current/spi-brcode.yaml put /api/v1/brcode/cobv/{txid}
Prerequisite: create this charge before generating its QR/payload (see generateBRCode and resolveCobVPayload). Creates a due-date charge (CobV) identified by the path txid (idempotent). Pix API v2.9 PUT /cobv/{txid}.



# Create due-date charge batch
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/put-lote-cob-v

/en/openapi/v3-current/spi-brcode.yaml put /api/v1/brcode/lotecobv/{id}
Prerequisite: create the batch charges before generating their QR/payloads (see generateBRCode and resolveCobVPayload). Creates a due-date charge batch identified by the path id. Items are processed synchronously: each results in CRIADA or NEGADA. Pix API PUT /lotecobv/{id}.



# Reconcile charge
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/reconcile-charge

/en/openapi/v3-current/spi-brcode.yaml post /api/v1/brcode/charges/reconcile
Admin-only endpoint that concludes a charge from a settlement receipt the rail could not attribute on its own. The receipt's endToEndId and valor are required.



# Resolve Cob payload (JWS)
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/resolve-cob-payload

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/payload/{locator}
Prerequisite: the referenced Cob charge must already exist (see postCob). Resolves, by the opaque access token, the signed JSON payload (JWS, application/jose) of an immediate charge (CobPayload). valor.original is projected verbatim. The verification key is published at /.well-known/jwks.json.



# Resolve CobV payload (JWS)
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/resolve-cob-v-payload

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/payload/cobv/{locator}
Resolves, by the opaque access token, the signed JSON payload (JWS, application/jose) of a due-date charge (CobVPayload). valor.final is calculated (fine/interest/rebate/discount) for the expected payment date (dpp). The verification key is published at /.well-known/jwks.json.



# Resolve Rec payload (JWS)
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/resolve-rec-payload

/en/openapi/v3-current/spi-brcode.yaml get /api/v1/brcode/payload/rec/{recUrlAccessToken}
Resolves, by the opaque access token of the recurrence location (recUrlAccessToken), the signed JSON payload (JWS, application/jose) of a recurrence (RecPayload). The recurrence configuration is projected verbatim. A terminal recurrence (REJEITADA/EXPIRADA/CANCELADA) returns 410 Gone (location permanently exhausted). The verification key is published at /.well-known/jwks.json.



# Register recebedor profile
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/upsert-recebedor-profile

/en/openapi/v3-current/spi-brcode.yaml put /api/v1/brcode/recebedores/{chave}
FI-admin surface (not a BACEN endpoint): upsert the FI-registered recebedor identity for a Pix key. CobV responses require a recebedor with a postal address (DadosRecebedor), which DICT cannot supply; the FI registers it here. Idempotent by nature.



# Validate BR Code
Source: https://docs.lerian.studio/en/reference/rails/spi/brcode/validate-br-code

/en/openapi/v3-current/spi-brcode.yaml post /api/v1/brcode/validate
Validates a raw BR Code payload and returns stable EMV validation codes.



# Activate participant
Source: https://docs.lerian.studio/en/reference/rails/spi/core/activate-participant

/en/openapi/v3-current/spi-core.yaml post /api/v1/core/participants/{ispb}/activate
Reactivates a suspended participant.



# Confirm portability relationship end (reda.031)
Source: https://docs.lerian.studio/en/reference/rails/spi/core/confirm-portability-relationship-end

/en/openapi/v3-current/spi-core.yaml post /api/v1/core/participants/{ispb}/portability/confirm
Confirms the end of a portability relationship for an indirect participant and dispatches the reda.031 (PtyDeltnReq) message to the BACEN. Applies only to indirect participants; a direct participant is rejected. It does not enforce the open reda.017 confirmation window — the 24-hour PRAZOCONFI deadline is the operator's responsibility, not a precondition checked here.



# Get participant
Source: https://docs.lerian.studio/en/reference/rails/spi/core/get-participant

/en/openapi/v3-current/spi-core.yaml get /api/v1/core/participants/{ispb}
Retrieves a single participant by their 8-digit ISPB code.



# List participants
Source: https://docs.lerian.studio/en/reference/rails/spi/core/list-participants

/en/openapi/v3-current/spi-core.yaml get /api/v1/core/participants/
Returns a paginated list of participants; filterable by sponsor ISPB.



# Offboard participant
Source: https://docs.lerian.studio/en/reference/rails/spi/core/offboard-participant

/en/openapi/v3-current/spi-core.yaml post /api/v1/core/participants/{ispb}/offboard
Permanently offboards a participant (terminal state).



# Orchestrate Core operation
Source: https://docs.lerian.studio/en/reference/rails/spi/core/orchestrate-operation

/en/openapi/v3-current/spi-core.yaml post /api/v1/core/operations/
Resolves participant routing, consumes quota when indirect, records settlement tracking, attributes fees/commissions, persists saga state, and emits Core domain events.



# Register the direct participant this rail operates as
Source: https://docs.lerian.studio/en/reference/rails/spi/core/register-direct-participant

/en/openapi/v3-current/spi-core.yaml post /api/v1/core/participants/direct
Establishes the institution this rail IS at the SPI: the ACTIVE DIRECT participant that anchors the closed set of participants whose arriving Pix settle here (its own accounts, plus every indirect it is BACEN-confirmed liquidante for). Admin-only, and at most one may be ACTIVE. There is no reda flow for a direct participant — the SPI refuses a reda.014/reda.031 naming one (reda.016 error DIR1) — so nothing external confirms this act and it is not client-callable.



# Request registration of an indirect participant
Source: https://docs.lerian.studio/en/reference/rails/spi/core/register-participant

/en/openapi/v3-current/spi-core.yaml post /api/v1/core/participants/
Opens a reda.014 (PtyCreReq) asking the SPI to record this rail as the indirect participant's liquidante. The participant is created PENDING and stays there: only the BACEN reda.016 COMP advice makes it ACTIVE, and only an ACTIVE indirect has its arriving Pix settled here. A body naming a DIRECT participant is refused — the rail's own identity is established on the admin route POST /api/v1/core/participants/direct.



# Resolve payment routing
Source: https://docs.lerian.studio/en/reference/rails/spi/core/resolve-routing

/en/openapi/v3-current/spi-core.yaml post /api/v1/core/routing/resolve
Resolves the routing path for a payment based on the sender's ISPB and amount.



# Suspend participant
Source: https://docs.lerian.studio/en/reference/rails/spi/core/suspend-participant

/en/openapi/v3-current/spi-core.yaml post /api/v1/core/participants/{ispb}/suspend
Suspends an active participant.



# Update the participant's MED 2.0 regulator contact
Source: https://docs.lerian.studio/en/reference/rails/spi/core/update-participant-contact

/en/openapi/v3-current/spi-core.yaml put /api/v1/core/participants/{ispb}/contact
Replaces the e-mail and phone BACEN uses to reach this participant about a MED 2.0 funds-recovery case (DICT 2.12.1 ContactInformation). Both elements move together — BACEN requires the pair — and both are validated against the DICT patterns, so a contact this rail would be refused on is refused here instead of on a signed body with a case already half-open. This is registry data: NO reda message carries the contact (the reda.014 envelope is ISPB / IDRT / CNPJIDRT and nothing else), and the funds-recovery flows read the registry fresh at send time, so no re-transmission to BACEN is needed and the change takes effect on the next case opened for this participant. Refused for a participant in a terminal status (OFFBOARDED, REGISTRATION_REJECTED); allowed while a reda.014/reda.031 is in flight, because neither message carries the contact.



# Abandon one unreadable record on a DICT poll feed
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/abandon-dict-discovery-feed-record

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/discovery-feeds/{feed}/abandon-record
Permanently gives up on ONE record BACEN serves that this deployment cannot read or store, so the feed can move past it. A DICT poll feed holds its position on such a record rather than passing it by silently, which is correct and has no other ending: clearing the feed's blocked marker resumes the walk at the same position and it stops again on the same record. This route is the human decision that ends that loop, and it is deliberately not the unblock route with a flag — unblocking says try again, this says give up on this one. It is refused for a caller with no identifiable principal, requires a reason, and writes an audit row naming who, which record and why. The record then stays listed on GET /api/v1/dict/discovery-feeds forever: an abandonment that ages out of a log is exactly the silent loss this verb exists to avoid. Only the named record is passed; every other held record still holds the feed. Idempotent — re-sending the same record is a no-op that is still audited. The write-off list is bounded per feed and is never trimmed to make room: at the limit this route refuses with 409 and says so plainly, because that many records given up on one feed is a systemic refusal rather than that many accidents. GET /api/v1/dict/discovery-feeds reports abandonedRecordsRemaining on every feed, and the brspi_dict_feed_abandoned_records_remaining gauge carries the same number, so the limit is visible long before it is met.



# Apply a judicial block on a PIX key
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/apply-key-judicial-block

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/internal/keys/block
Mirrors a Banco Central ofício onto this deployment's own key book (DICT 8.4 section 1.1): the key stops resolving on every internal query, which answers the block indication with none of the key's permitted data, and update, delete and claim all refuse it. The ofício reaches the participant on paper, so without this route the rail learns of the block only when a later call to BACEN happens to come back EntryBlocked — and keeps resolving the key with full owner and account data until then. One identified operator, no second approval: mirroring a court order is an obligation and not a judgement call. The ofício reference is mandatory and the act is audited under the caller's identity before and after the effect. Idempotent: a key already blocked answers 200 with alreadyApplied. A key whose current state cannot hold the block (never confirmed by BACEN, or already deregistered) is refused with 422.



# Block an end user's DICT key queries
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/block-dict-query-payer

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/internal/query-blocks
Stops serving DICT key queries for one end user: DICT 8.4 section 13.2.3's "o participante deve bloquear imediatamente o(s) usuario(s) em questao", which the same sentence conditions on a human having verified fundada suspeita and elevado indicio of misuse. Every later key lookup naming this payer is refused 403 before any read — before the retained directory answer and before this deployment's own registry — because the block is a statement about the person, not about our wire traffic. One identified operator, no second approval, mandatory justification, audited under the caller's identity before and after the effect. Idempotent: an end user already blocked answers 200 with alreadyApplied. Name the end user by the hash the monitor read reports, or by their CPF/CNPJ, which is hashed here and never stored.



# Cancel DICT refund
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/cancel-refund

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/refunds/{id}/cancel
Transitions a refund OPEN→CANCELLED (payer side, while still open) and reports it to BACEN.



# Batch check PIX key existence
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/check-keys

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/keys/check
Probes up to 200 PIX key values for existence in one call, backed by the BACEN DICT keys/check (dict-np host). Returns one existence-only result per submitted key, in submission order, plus BACEN's own operational envelope (bacen.correlationId / bacen.responseTime) for the probe this call made — one envelope per call, omitted when every verdict was already retained locally and no probe reached BACEN. This capability requires the dict-np seam: a deployment that does not carry it answers 501 with code SPI-1012 — a PERMANENT refusal, not a retryable one, so a client must stop rather than retry. 503 (SPI-1010) keeps its usual meaning here and only that one: BACEN DICT is reachable in principle but down or failing right now, and the call may be retried.



# Cleanup orphaned PIX keys
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/cleanup-orphaned-keys

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/internal/keys/cleanup-orphaned
Finds PIX keys stuck in PENDING_BACEN_SYNC and retries BACEN registration or deletes them. Internal admin endpoint.



# Close DICT infraction
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/close-infraction

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/infractions/{id}/close
Transitions an infraction →CLOSED with an AGREED/DISAGREED analysis and reports it to BACEN; on AGREED, BACEN creates the fraud marker.



# Close DICT refund
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/close-refund

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/refunds/{id}/close
Transitions a refund OPEN→CLOSED with an analysisResult (TOTALLY_ACCEPTED|PARTIALLY_ACCEPTED|REJECTED) and reports it to BACEN.



# Create DICT refund
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/create-refund

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/refunds
Persists a DICT refund request locally and submits the corresponding BACEN refund synchronously-after-persist, tracked by report_status (PENDING/SENT/FAILED) + request_id.



# Delete PIX key
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/delete-key

/en/openapi/v3-current/spi-dict.yaml delete /api/v1/dict/keys
Deletes a PIX key by its value. Only ACTIVE or INACTIVE keys can be deleted. Keys under claim or pending BACEN sync are rejected. A key under a BCB judicial block is refused with the EntryBlocked token and HTTP 400, the same answer BACEN gives (DICT 8.4 section 1.1).



# DICT claims-summary report (COUNT-only)
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/get-dict-report-claims-summary

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/reports/claims-summary
Returns COUNT(*) buckets grouped by (claimType, status) over claims requested in a mandatory date window (max 92 days), plus the COUNT of currently-open claims past their 7-day deadline. COUNT-only. Infraction summaries are out of scope.



# DICT keys-summary report (COUNT-only)
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/get-dict-report-keys-summary

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/reports/keys-summary
Returns COUNT(*) buckets grouped by (keyType, status) over PIX keys registered in a mandatory date window (max 92 days). COUNT-only — DICT holds no money. Raw key values are never returned.



# Get DICT refund
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/get-refund

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/refunds/{id}
Retrieves a refund by its BACEN-assigned resource UUID, projecting the full ExtendedRefund snapshot.



# Get DICT MED operation status
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/get-regulatory-operation

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/operations/{id}
Retrieves a durable MED operation intent's status by its own id (operationId) — the identity a create/lifecycle-transition backlog route returns or references on every outcome. Status only: kind, verb, status, the BACEN resource id once known, timestamps, and BACEN's sanitized envelope. Never the original request body, tax id, key, account, or analysis details.



# PIX key statistics
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/key-stats

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/keys/stats
Returns PIX key counts grouped by key type and status.



# Lift a judicial block on a PIX key
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/lift-key-judicial-block

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/internal/keys/unblock
Releases a block whose ofício was revoked: the key resolves again and its mutation verbs stop refusing it. The revocation also arrives on paper, and the only automatic exit needs BACEN to serve the entry again on a reconciliation sweep, which can lag the revocation by hours — this route is the operator's own. One identified operator, mandatory ofício reference, audited under their identity. Idempotent: a key carrying no block answers 200 with alreadyApplied.



# List DICT poll feed states
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/list-dict-discovery-feeds

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/discovery-feeds
Reports which DICT poll feeds (claim discovery, MED infraction/refund discovery, the fraud-marker inventory sweep, funds-recovery event notifications) are frozen on a durable blocked marker, with the closed-vocabulary reason and the instant the freeze started. It also reports the funds-recovery feed's replay list: BACEN records it permanently stepped over and never stored, named by BACEN resource id, which are replayed through POST /api/v1/dict/funds-recoveries/intake. It also names the records a feed is currently stuck on and the ones a named operator has permanently abandoned: a held record listed here is the id an operator supplies to POST /api/v1/dict/discovery-feeds/{feed}/abandon-record, which is how a walk pinned on a record this deployment can never store is made to move on. A frozen feed deliberately does NOT degrade readiness — this rail also serves Pix keys, entries and claims, and the routes an operator needs to resolve a freeze are served by the same replicas — so this route, the brspi_dict_feed_blocked gauge and the operational event are the alarm.



# List PIX keys
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/list-keys

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/keys
Returns a paginated list of PIX keys. Optionally filter by participant ISPB.



# List DICT refunds
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/list-refunds

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/refunds
Returns paginated local DICT refund records.



# List DICT MED operation statuses
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/list-regulatory-operations

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/operations
Enumerates durable MED operation-intent statuses — the operator surface: no pending status, including MANUAL_REVIEW, is invisible. Optional status/kind facets; cursor-paginated (the underlying table is actively mutated by the sweep, so an offset page could skip or repeat a row). Same sanitized per-item projection as GET /operations/{id}.



# Lookup PIX key
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/lookup-key

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/keys/lookup
Looks up a PIX key by JSON body value. This deployment's own key registry is read FIRST — a retained BACEN answer can never outrank a local row (DICT 8.4 §1.1) — and only a key with no local row falls through to the retained BACEN answer and then to BACEN DICT. Returns ownerTaxId full and unmasked per BACEN API-DICT. A judicially blocked key answers EntryBlocked with HTTP 400 and none of the key's data, identically to a BACEN-relayed block.



# Read DICT request-limiting buckets
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/read-dict-policy-buckets

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/internal/policies
Projects the DICT's own request-limiting state for this participant, verbatim: available tokens, bucket capacity, refill amount and refill period per policy, plus the category (A→H) the BCB assigned — which is what fixes the size and refill of the key-query bucket. Read live from BACEN on every call (nothing is cached here) and never computed locally, so it is the authoritative answer to 'how much DICT quota do we have left'. Supply ?policy=<name> to read a single bucket. Internal admin endpoint.



# Read DICT query-monitoring indicators
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/read-dict-query-monitor

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/internal/query-monitor
Reports the two query indicators DICT 8.4 section 13.2.3 obliges every participant to keep: DICT key queries per payment order sent to the SPI (VCD/EOS) and NOT FOUND/(NOT FOUND+FOUND), for the participant as a whole and for each end user, over the configured rolling window. It also lists the end users whose own ratio breached the per-user threshold over at least the minimum query count, and the blocks currently in force. A listing is an indication to verify, not a verdict — the section requires a human to establish that the behaviour is unjustified before anyone is blocked. End users appear only as a keyed digest of their CPF/CNPJ; no document is stored or returned. Internal admin endpoint.



# Refresh DICT infraction from BACEN
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/refresh-infraction

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/infractions/{id}/refresh
Fetches the infraction's current record from BACEN (getInfractionReport) and projects the counterparty-determined outcome onto the local row verbatim: no computation, no interpretation. No scheduler runs this — the operator triggers it explicitly.



# Refresh DICT refund from BACEN
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/refresh-refund

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/refunds/{id}/refresh
Fetches the refund's current record from BACEN (getRefund) and projects the counterparty-determined outcome onto the local row verbatim: no computation, no interpretation. No scheduler runs this — the operator triggers it explicitly.



# Register PIX key
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/register-key

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/keys
Registers a new PIX key after validating the request, enforcing owner limits, and successfully synchronizing with BACEN DICT. Registration fails closed if BACEN DICT is unavailable or rejects the key.



# Resolve a MANUAL_REVIEW DICT MED operation
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/resolve-regulatory-operation

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/operations/{operationId}/resolution
Relays a four-eyes ATTACH_BACEN_RESOURCE or CONFIRM_NOT_APPLIED decision for a MANUAL_REVIEW durable MED operation intent. ATTACH_BACEN_RESOURCE authoritative-GETs the proposed BACEN resource and validates it against this operation's own reserved business identity BEFORE ever associating it, then applies the snapshot and completes the operation. CONFIRM_NOT_APPLIED declares BACEN never received the attempt, freeing the resource for the client's own retry via its existing X-Idempotency. Idempotent by the request's own X-Idempotency: a replayed delivery of the SAME decision returns the original outcome without repeating any side effect. A failed GET or a business-identity mismatch never transitions anything — the operation stays MANUAL_REVIEW.



# Reconcile DICT keys against a BACEN event-list
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/run-events-reconciliation

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/internal/reconciliation/run-events
CONTINGENCY reconciliation: reconciles an operator-supplied BACEN DICT event-list (CID) against local key state, flagging divergences. Used when the live CID/VSync inventory channel is unavailable. Enumeration/divergence only — no BACEN call, no money, no position.



# Search PIX keys
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/search-keys

/en/openapi/v3-current/spi-dict.yaml get /api/v1/dict/keys/search
Searches PIX keys by optional key type, status, and participant ISPB filters.



# Trigger DICT reconciliation
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/trigger-reconciliation

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/internal/reconciliation/run
Triggers an on-demand reconciliation run against BACEN DICT.



# Unblock a frozen DICT poll feed
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/unblock-dict-discovery-feed

/en/openapi/v3-current/spi-dict.yaml post /api/v1/dict/discovery-feeds/{feed}/unblock
Clears a DICT poll feed's durable blocked marker so the next tick runs. A frozen feed discovers nothing and does not thaw on restart, and every walk refuses to start while its marker is set — without this route the only recovery is a hand-written UPDATE on the watermark table of a regulated deployment. When the feed froze on an unusable window watermark (local corruption, not a BACEN anomaly), a replacement instant may be supplied in the same call, because nothing else ever rewrites that value. When the feed instead froze holding a BACEN entry it could not store, clearing the marker moves nothing else: the walk resumes at the same position and freezes again after the same tolerance unless that entry has become storable, and the response says so — on the two refund walks, whose position is BACEN's own opaque cursor, that is the only outcome available today. The funds-recovery notification feed is deliberately NOT unblockable here: its block means notifications are gone from BACEN's seven-day window for good, and lifting it is an attestation taken on the funds-recovery intake route, where the missing ids are supplied. Every call is recorded in the audit trail under the caller's identity, including the old and new watermark values.



# Release an end user's DICT key queries
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/unblock-dict-query-payer

/en/openapi/v3-current/spi-dict.yaml delete /api/v1/dict/internal/query-blocks
Releases a block once the operator has established that the behaviour was justified, or that the suspicion no longer holds: the end user's key queries are served again, subject to the section 13.1 buckets that never stopped applying. Same posture as placing it — one identified operator, mandatory justification, audited under their identity. Idempotent: an end user carrying no block answers 200 with alreadyApplied.



# Update PIX key
Source: https://docs.lerian.studio/en/reference/rails/spi/dict/update-key

/en/openapi/v3-current/spi-dict.yaml put /api/v1/dict/keys/{key}
Updates a PIX key's mutable bindings (account branch/number/type and owner name/trade name) and reports the change to BACEN DICT (signed updateEntry). keyType and ownerTaxId are immutable; an attempt to change them is rejected. The body carries no participant: the wire Participant is always the key's stored owning participant — the one this call is authorized against — so this verb can never rebind a key to another participant. A key under a BCB judicial block is refused with the EntryBlocked token and HTTP 400, the same answer BACEN gives (DICT 8.4 section 1.1).



# SPI error list
Source: https://docs.lerian.studio/en/reference/rails/spi/spi-error-list

Look up the error codes the SPI Pix rail returns, the HTTP status each one carries, and what to do about it.

**Error format**

The SPI API returns errors as RFC 9457 problem details with the `application/problem+json` media type:

```json JSON theme={null}
{
  "type": "https://errors.lerian.studio/v1/SPI-1002",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "bacen rejected payment",
  "code": "SPI-1002",
  "correlationId": "req-7a3f9c2e"
}
```

**Field definitions**

* **`type`** – A URI that identifies the error in the Lerian error catalog, built as `https://errors.lerian.studio/v1/<code>`.
* **`title`** – The HTTP status text (for example, `Unprocessable Entity`).
* **`status`** – The HTTP status code.
* **`detail`** – A human-readable explanation for this occurrence. The text varies with the occurrence, so branch on `code`.
* **`code`** – A stable identifier for the condition. This API uses two vocabularies here: the rail's own `SPI-NNNN` codes, and the Pix key directory tokens described further down.
* **`errors`** – Optional list of per-field validation details, each with a `message`, a `location`, and the offending `value`.
* **`correlationId`** – The request-scoped correlation identifier. Quote this value in a support request.

For `5xx` responses, the rail replaces `detail` with `internal error` so internal causes stay inside. Use `code` to branch programmatically.

## Rail codes

***

The `SPI-NNNN` codes name conditions the SPI rail itself judges. The digit after the prefix groups them: `0` input, `1` rail transport, `2` authorization, `3` processing, `4` rate and quota, `9` fallback.

A code can carry more than one status when the condition it names has more than one shape on this rail.

`SPI-1002` means BACEN refused the message when the rail submitted it. A refused payment moves to `REJECTED`. BACEN can also refuse a payment later, in its status reply (`pacs.002`). That refusal is not an HTTP error, and the payment moves to `REJECTED`. To find which payments the network refused, read the rejected payments report. It lists each one by status and end-to-end id.

### 400: Bad request

***

| `code` | Description | `detail` |
| - | - | - |
| SPI-0003 | The request body is missing or cannot be parsed. | request body is required |

### 401: Unauthenticated

***

| `code` | Description | `detail` |
| - | - | - |
| SPI-2001 | The request does not identify a principal. The bearer is missing, malformed, or unrecognized. | authenticated actor unavailable |

### 403: Forbidden

***

| `code` | Description | `detail` |
| - | - | - |
| SPI-2002 | The caller is identified and is not authorized for this action. | forbidden |

### 404: Not found

***

| `code` | Description | `detail` |
| - | - | - |
| SPI-0010 | The resource the request names does not exist. | payment not found |

### 409: Conflict

***

| `code` | Description | `detail` |
| - | - | - |
| SPI-0011 | A resource with this identity already exists. | participant already exists |
| SPI-3006 | The resource's current lifecycle state refuses the operation. | payment is not eligible for return |
| SPI-3007 | Another writer changed the resource between your read and your write. Re-read and retry. | participant status changed concurrently |

### 413: Payload too large

***

| `code` | Description | `detail` |
| - | - | - |
| SPI-0003 | The request body exceeds the size limit. `HTTP_BODY_LIMIT_BYTES` sets the limit for most routes. | request body too large |

### 422: Unprocessable

***

| `code` | Description | `detail` |
| - | - | - |
| SPI-0001 | A required input is missing or empty. | return reason is required |
| SPI-0002 | A field carries the wrong format. | mode must be FULL or INCREMENTAL |
| SPI-0003 | A business rule refused the request. | invalid payment request |
| SPI-0011 | The charge surface refuses a duplicate identifier, such as a txid another charge already holds. | charge already exists |
| SPI-1002 | BACEN rejected the message. | bacen rejected payment |
| SPI-1011 | The Pix key directory rejected the request. Where the directory named the reason, the token arrives instead. See the directory tokens below. | bacen dict rejected request |
| SPI-3002 | Internal processing refused to route the request. | operation routing decision unavailable |
| SPI-3006 | The charge or batch lifecycle refuses the operation. | invalid charge state transition |
| SPI-4001 | The participant's own operation quota is exhausted. | quota limit exceeded |

### 429: Too many requests

***

| `code` | Description | `detail` |
| - | - | - |
| SPI-4001 | The rail's BACEN-outbound quota is exhausted, or the Pix key directory throttled the request. A directory throttle carries the wait in the `Retry-After` header when the directory prescribed one. | bacen outbound quota exceeded |

### 500: Server error

***

| `code` | Description | `detail` |
| - | - | - |
| SPI-9000 | An unexpected internal failure. Retry, then contact support with the `correlationId` value. | internal error |

### 501: Not implemented

***

| `code` | Description | `detail` |
| - | - | - |
| SPI-1012 | The Pix key directory batch key check is not installed in this deployment. Do not retry. | internal error |

### 502: Bad gateway

***

| `code` | Description | `detail` |
| - | - | - |
| SPI-1005 | Communication with BACEN failed for a reason the rail could not classify further. | internal error |

### 503: Service unavailable

***

These codes name dependency conditions. Back off and retry.

| `code` | Description | `detail` |
| - | - | - |
| SPI-1001 | The BACEN transport is unavailable. | internal error |
| SPI-1004 | Transport security validation failed. The rail refused to send on a channel it could not validate. | internal error |
| SPI-1010 | The Pix key directory is unavailable, for maintenance or outside its service window. | internal error |
| SPI-3001 | Persistence or event publication is unavailable. | internal error |
| SPI-9001 | A downstream dependency the request needs is unavailable. | internal error |

### 504: Gateway timeout

***

| `code` | Description | `detail` |
| - | - | - |
| SPI-1003 | BACEN did not answer within the rail's window. The outcome is undetermined, so query the resource before you resend. | internal error |

## Pix key directory tokens

***

The Pix key directory keeps its own error vocabulary, and the rail forwards it. A directory refusal reaches you with the directory's own token in `code` and the directory's own HTTP status in `status`. The `type` URI carries the same token as its last segment.

This vocabulary belongs to the directory, so treat it as open. Handle a token you do not recognize by its `status`, and read the token itself as the reason. The tables below list directory tokens for key registration, key lookup, key deletion, and the claim operations.

> [!NOTE]
>
> A rate-limit refusal from the directory reaches you as `SPI-4001` with HTTP 429. When the directory prescribed a wait, the response carries it in `Retry-After`. See the rail codes above.

### General

***

| `code` | Description | Status |
| - | - | - |
| Forbidden | The request violates an authorization rule. | 403 |
| BadRequest | The request format is invalid at the schema level. | 400 |
| NotFound | The entity the request names does not exist. | 404 |
| Gone | The resource existed and is not available. | 410 |
| InternalServerError | An unexpected condition on the directory side. | 500 |
| ServiceUnavailable | The directory is unavailable, for maintenance or outside its window. | 503 |
| RequestSignatureInvalid | The request digital signature is invalid. | 400 |
| RequestIdAlreadyUsed | The same RequestId came back with different parameters. | 400 |
| InvalidReason | The reason given for the operation is invalid. | 400 |
| ParticipantInvalid | The participant cannot take part in this operation. | 400 |
| TaxIdNumberBlocked | The CPF or CNPJ is blocked by judicial order. | 400 |

### Key registration

***

| `code` | Description | Status |
| - | - | - |
| EntryInvalid | The fields that create or update the entry are invalid. | 400 |
| EntryLimitExceeded | The account holds the maximum number of keys already. | 400 |
| EntryAlreadyExists | The key is registered already for this participant and owner. | 400 |
| EntryCannotBeQueriedForBookTransfer | The key belongs to the same PSP. Resolve it internally rather than through the directory. | 400 |
| EntryKeyOwnedByDifferentPerson | A different person owns the key. Open a possession claim. | 400 |
| EntryKeyInCustodyOfDifferentParticipant | The same owner holds the key at another PSP. Open a portability claim. | 400 |
| EntryTaxIdNumberByDifferentOwner | The CPF or CNPJ on the entry differs from the key owner's. | 400 |
| EntryLockedByClaim | An active claim locks the entry, so it cannot be deleted. | 400 |
| EntryBlocked | A judicial order blocks the entry. | 400 |

### Key claims

***

| `code` | Description | Status |
| - | - | - |
| ClaimInvalid | The fields that create or update the claim are invalid. | 400 |
| ClaimTypeInconsistent | The claim type is inconsistent with the entry's state. | 400 |
| ClaimKeyNotFound | The claimed key does not have a registered entry. | 404 |
| ClaimAlreadyExistsForKey | An active claim exists for the key already. | 400 |
| ClaimResultingEntryAlreadyExists | The resulting entry exists already for the claimant. | 400 |
| ClaimOperationInvalid | The claim's status forbids the operation you requested. | 400 |
| ClaimResolutionPeriodNotEnded | The resolution period has not ended, so the operation is premature. | 400 |
| ClaimCompletionPeriodNotEnded | The completion period has not ended, so finalizing is premature. | 400 |

## BR Code file rejections

***

The BR Code batch file channel answers a submitted remessa in a return file. A refused line carries a three-digit rejection code. It also carries the field name and description that the Pix scheme publishes for that code. A refused file carries one code, and no line in it is judged. Your reconciliation maps the answer against the scheme's own error sheet.

`063` (Cadastro, Cliente nao cadastrado) refuses the whole file: its header names a recebedor that this deployment does not hold a registered profile for. `096` (Registro, Inválido) says the scheme publishes no more specific code for the field at fault. A record of the wrong length is one of these.

Four more cover the two identifiers that most lines carry. `012` (Chave pix, Chave inválida) says the line collects on a Pix key that this deployment does not hold a registered recebedor for. `014` (Chave pix, Não é compatível com o cnpj ou agência e conta informada) names a key registered to another recebedor. The file header resolves to a different one. `016` (Identificador (txid), Em duplicidade) says the txid repeats. `017` (Identificador (txid), Inválido ou não encontrado) says the txid is malformed or names a charge this rail does not hold.

The scheme's error sheet publishes many more codes. The channel renders the subset that its own refusals map onto. Each rejected line names its field, so read the field name first and the code second.


# Withdraw a situação change registered in the Câmara PAG
Source: https://docs.lerian.studio/en/reference/rails/siloc/cancel-status-change

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/status-change-cancellations
Issues a PAG0203 "IF requisita cancelamento de alteração de situação" to the Câmara PAG (Catálogo de Serviços do SFN v5.13, Vol II). Withdraws a situação change this institution had already registered — typically a PAG0201 that has not taken effect yet — naming it by the câmara's own control number (NumCtrlPAGOr) rather than by the NumCtrlIF this institution minted. It is the undo of the stop switch, so it carries the same operator-command treatment as the change it retires. The instruction is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (PAG0203R1) arrives asynchronously and is read back with getPAG0203. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Get a homologation scenario
Source: https://docs.lerian.studio/en/reference/rails/siloc/get-a-homologation-scenario

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/homologation/scenarios/{scenarioId}
One certification scenario: its objective, expected input, pass criterion, the status of its latest run, and when it last ran.



# Get a certificate
Source: https://docs.lerian.studio/en/reference/rails/siloc/get-certificate

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/certificates/{certificateId}



# Get an OT settlement cycle
Source: https://docs.lerian.studio/en/reference/rails/siloc/get-cycle

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/cycles/{cycleId}
The cycle detail including the FI's net position (projected from the single correlated instruction, never a sum), windows, and settlement moment.



# Get a cycle's recálculo round chain
Source: https://docs.lerian.studio/en/reference/rails/siloc/get-cycle-recalculations

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/cycles/{cycleId}/recalculations
The ordered Art.18 recálculo rounds for the cycle (oldest first), each projected verbatim — the excluded participant, the recomputed side + amount, the complement window (a later round surfaces the +15min prorrogation), and the internal resolution label — plus a note that any post-exclusion residual is a bilateral participant TED (surfacing, not routing). An unknown cycle is 404; a cycle that never entered recálculo is an empty chain.



# Get a cycle's reconciliation result
Source: https://docs.lerian.studio/en/reference/rails/siloc/get-cycle-reconciliation

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/cycles/{cycleId}/reconciliation
The reconciliation of the settled instruction against the active FINAL ROC revision, with reason, completeness, and any mismatch flagged.



# Get notification configuration
Source: https://docs.lerian.studio/en/reference/rails/siloc/get-notification-config

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/notifications/config
The singleton notification configuration and its optimistic-concurrency version.



# Get a participant
Source: https://docs.lerian.studio/en/reference/rails/siloc/get-participant

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/participants/{participantId}



# Get a participant's operational status
Source: https://docs.lerian.studio/en/reference/rails/siloc/get-participant-status

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/participants/{participantId}/status
The current PAG0101 operational status and its history.



# Get the card-domain relay status
Source: https://docs.lerian.studio/en/reference/rails/siloc/get-relay-status

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/relay/status
Whether the card-domain relay to Lerian SLC is healthy. When down, card settlement is blocked — this is the single point of SILOC connectivity for the card product.



# Get an OT settlement instruction
Source: https://docs.lerian.studio/en/reference/rails/siloc/get-settlement-instruction

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/settlement-instructions/{instructionId}



# Ingest a semantic ROC revision
Source: https://docs.lerian.studio/en/reference/rails/siloc/ingest-roc

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/rocs
Decodes and admits one revision of the semantic ROC (Resultado da Compensação) into its per-document chain. An exact replay (same natural key + content hash) is a committable no-op — the response is identical. The revision is projected verbatim, never netted or recomputed.



# List a homologation scenario's runs
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-a-homologation-scenario-s-runs

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/homologation/scenarios/{scenarioId}/runs
The scenario's recorded certification history, newest first: every run with its outcome, its start and finish instants, and its evidence document. This is where the evidence of a run outlives the request that created it — a reload, a second operator, and an exported history all read it here. Runs whose lease expired before an outcome was recorded appear as FAILED carrying their abandoned evidence; hiding them would make the history lie about what happened.



# List settlement-coverage capabilities
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-capabilities

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/capabilities
Settlement-coverage transparency — the messages/flows the rail implements versus what SILOC defines.



# List regulated certificates
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-certificates

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/certificates
The certificate lifecycle view with expiry. The private key stays in the FI's custody and is never stored or accessed by the rail.



# List OT settlement cycles
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-cycles

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/cycles
A filterable, cursor-paginated page of the rail's own OT deferred-net cycles, newest first.



# List homologation scenarios
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-homologation-scenarios

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/homologation/scenarios
The operator's certification scenarios with per-scenario status, objective, expected input, and pass criterion, in certification order. Each scenario's status is the status of its latest run.



# List parked deferred inbound messages
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-parked-deferred-inbound-messages

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/dlq/deferred
A cursor-paginated feed of inbound messages parked for semantic replay (OT_DEFERRED and STATUS_DEFERRED), newest first, optionally narrowed to one lifecycle status. status=SEMANTIC_REJECTED lists the messages this rail terminally REFUSED on their content — parked with zero business effect, never replayed — which is what the INBOUND_SEMANTIC_REJECTED alarm points at. Distinct from relay failures (awaiting replay) and from quarantined frames (refused past the backout threshold and moved off the queue). Read-only: a refused message is never re-fed, and the alarm is closed on the alert surface.



# List participants
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-participants

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/participants



# List quarantined inbound frames
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-quarantined-inbound-frames

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/dlq/quarantine
A cursor-paginated feed of inbound frames this rail refused past the configured backout threshold, which the queue manager's backout queue now holds. Each entry carries the queue-manager evidence that ties it to the copy on that queue. Distinct from relay failures, which are frames awaiting replay.



# List parked relay failures
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-relay-failures

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/dlq/relay-failures
A cursor-paginated feed of funding frames parked (RELAY_FAILED) during a sustained relay outage, awaiting administrative replay. Distinct from QM-quarantined poison frames.



# List relayed card-domain messages
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-relayed-messages

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/relay/messages
A cursor-paginated audit feed of funding/clearing messages relayed to Lerian SLC over the SILOC connection.



# List OT settlement instructions (obligations)
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-settlement-instructions

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/settlement-instructions
A cursor-paginated page of settlement obligations and their funding lifecycle state.



# Read one PAG0201 instruction and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-pag0201-instruction-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/inoperative-status-changes/{id}
The stored PAG0201 request projected verbatim, its dispatch state, and — once the câmara has answered — what it replied, also verbatim. The answer carries the câmara's own control number for the change it registered — the value a PAG0203 names to withdraw it. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the PAG0201E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it).



# Read one PAG0202 instruction and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-pag0202-instruction-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/operative-status-changes/{id}
The stored PAG0202 request projected verbatim, its dispatch state, and — once the câmara has answered — what it replied, also verbatim. The answer carries the câmara's own control number for the change it registered — the value a PAG0203 names to withdraw it. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the PAG0202E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it).



# Read one PAG0203 instruction and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-pag0203-instruction-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/status-change-cancellations/{id}
The stored PAG0203 request projected verbatim, its dispatch state, and — once the câmara has answered — what it replied, also verbatim. The answer carries the câmara's own control number for the cancellation it registered. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the PAG0203E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it).



# Register a certificate reference
Source: https://docs.lerian.studio/en/reference/rails/siloc/register-certificate

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/certificates
Registers the public certificate + custody reference for lifecycle tracking. The private key is never transmitted.



# Register a participant
Source: https://docs.lerian.studio/en/reference/rails/siloc/register-participant

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/participants
Registers a direct or indirect participant in scope. Emits a participant.registered fact.



# Replay a parked relay failure
Source: https://docs.lerian.studio/en/reference/rails/siloc/replay-relay-failure

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/dlq/relay-failures/{id}/replay
Re-relays the parked funding frame {id} to Lerian SLC once the relay has recovered. Idempotent via the inbound dedup ledger; an unknown or already-resolved id is a 404.



# Request this participant to become inoperante
Source: https://docs.lerian.studio/en/reference/rails/siloc/request-this-participant-to-become-inoperante

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/inoperative-status-changes
Issues a PAG0201 "IF requisita alteração de situação para inoperante" to the Câmara PAG (Catálogo de Serviços do SFN v5.13, Vol II). Asks the câmara to make this participant INOPERANTE from a stated date, which makes the exchange of messages with it impossible. ⛔ THIS IS THE STOP SWITCH FOR THIS PARTICIPANT ON THE PAG CÂMARA: nothing this rail sends afterwards reaches the câmara until a PAG0202 puts it back. The câmara requires the date of the change to differ from the current date (RPAG0007) and enforces that itself. The instruction is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (PAG0201R1) arrives asynchronously and is read back with getPAG0201. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Request this participant to become operante
Source: https://docs.lerian.studio/en/reference/rails/siloc/request-this-participant-to-become-operante

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/operative-status-changes
Issues a PAG0202 "IF requisita alteração de situação para operante" to the Câmara PAG (Catálogo de Serviços do SFN v5.13, Vol II). Asks the câmara to put this participant back to OPERANTE, making the exchange of messages possible again. The layout carries no date of its own. ⚠️ The change takes effect in D+1 and is accepted ONLY while the participant is inoperante (the Catálogo's own Observação), so a REFUSED row here most often means the participant was already operante. Both conditions are the câmara's and the câmara enforces them. The instruction is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (PAG0202R1) arrives asynchronously and is read back with getPAG0202. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Resolve a quarantined inbound frame
Source: https://docs.lerian.studio/en/reference/rails/siloc/resolve-a-quarantined-inbound-frame

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/dlq/quarantine/{id}/resolve
Acknowledges the quarantined frame {id} once an operator has dealt with the copy on the backout queue, and clears the INBOUND_QUARANTINED alert when no unresolved frame remains. It never re-feeds the frame. An unknown, already-resolved or non-quarantine id is a 404.



# Revoke a certificate
Source: https://docs.lerian.studio/en/reference/rails/siloc/revoke-certificate

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/certificates/{certificateId}/revoke
Disables the running MQ credential before recording revocation. The request fails if runtime enforcement is unavailable. Repeated requests preserve the original revocation timestamp.



# Run a homologation scenario
Source: https://docs.lerian.studio/en/reference/rails/siloc/run-a-homologation-scenario

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/homologation/scenarios/{scenarioId}/runs
Evaluates the scenario's pass criterion against the rail's own persisted state and readiness — the registered local certificate and trust store, the relayed-message ledger, the settlement cycles — and records the run with its evidence document. Nothing is injected onto the wire. A criterion that does not hold, and a criterion whose underlying state could not be read, both record a FAILED run carrying the reason; neither is reported as passing. A scenario with a run already in progress is a 409. Run history persists and is exportable.



# Update notification configuration
Source: https://docs.lerian.studio/en/reference/rails/siloc/update-notification-config

/en/openapi/v3-current/siloc.yaml put /api/v1/siloc/notifications/config
Replaces the notification configuration under optimistic locking; the update applies only if expectedVersion still matches the stored version (else 409).



# Update a participant
Source: https://docs.lerian.studio/en/reference/rails/siloc/update-participant

/en/openapi/v3-current/siloc.yaml put /api/v1/siloc/participants/{participantId}



# Advance an operation via audited admin override
Source: https://docs.lerian.studio/en/reference/rails/slc/advance-operation

/en/openapi/v3-current/slc.yaml post /v1/operations/{operationId}/advance
Drives an EXISTING state-machine edge via MANUAL_OVERRIDE, emitting operation.manually_advanced with the reason/evidence. Admin-only (operations:admin). Missing reason/evidence returns 400 MISSING_OVERRIDE_JUSTIFICATION; a nonexistent edge returns 409 INVALID_STATE_TRANSITION; cancelling an operation whose file is already at Núclea (transmit hold in_flight) returns 409 CONFLICT, since it would erase the only record of the disagreement — reconcile and advance to the hold-resolving state; POST /v1/connectivity/unpark refuses in-flight claims.



# Cancel a pending settlement operation
Source: https://docs.lerian.studio/en/reference/rails/slc/cancel-operation

/en/openapi/v3-current/slc.yaml delete /v1/operations/{operationId}
Cancels an operation in CREATED or QUEUED via a USER_CANCELLATION transition, emitting operation.cancelled. A non-cancelable state returns 409 with code SLC-0105 (INVALID_STATE_TRANSITION): the problem+json body carries only type/title/status/detail/code, and its detail is a fixed sentence that names neither the operation's current state nor the states it would accept — read the current state from GET /v1/operations/{operationId}. For a regulatory chargeback (contestação regulada que vira débito) use POST /v1/operations with operationType=CANCELLATION + reasonCategory instead.



# Report an operation's transmission status
Source: https://docs.lerian.studio/en/reference/rails/slc/connectivity-operation-transmission-status

/en/openapi/v3-current/slc.yaml get /v1/connectivity/operations/{id}/transmission-status
Reports the transmission/transport status of an operation: its lifecycle state, the tenant's active outbound transport, the in-flight transmit-claim marker (transmitClaimedAt), and the derived transport diagnostics (waitingFor / stuckSince / lastError). Every field is derived from existing columns/state and the append-only state log. RBAC: connectivity:admin. The tenant is ALWAYS taken from the validated request context.



# Retransmit a QUEUED operation
Source: https://docs.lerian.studio/en/reference/rails/slc/connectivity-retransmit-operation

/en/openapi/v3-current/slc.yaml post /v1/connectivity/operations/{id}/retransmit
Re-sends a QUEUED operation's ASLC envelope over its tenant-selected active transport, reusing the transmit-claim guard so a concurrent/duplicate retransmit cannot double-send (a transmit already in flight returns 409). RBAC: connectivity:admin. The tenant is ALWAYS taken from the validated request context, never the path. The REST rail is functional; a managed file-transfer or message-broker transport is not currently available and returns 503. A non-QUEUED operation returns 409 with code SLC-0105 (INVALID_STATE_TRANSITION): the problem+json body carries only type/title/status/detail/code, and its detail is a fixed sentence that names neither the operation's current state nor QUEUED, the only state this verb accepts — read the current state from GET /v1/connectivity/operations/{id}/transmission-status.



# Create an arrangement
Source: https://docs.lerian.studio/en/reference/rails/slc/create-arrangement

/en/openapi/v3-current/slc.yaml post /v1/participants/{id}/arrangements
Registers a card/scheme arrangement for a participant. Field presence/type is validated against the schema (422); a duplicate (participant, code, role) returns 409; an unknown participant 404; an invalid role/code 422. RBAC: arrangements:write.



# Create a settlement operation
Source: https://docs.lerian.studio/en/reference/rails/slc/create-operation

/en/openapi/v3-current/slc.yaml post /v1/operations
Submits a single settlement operation for intake. Idempotent via the X-Idempotency header. Field presence/type is validated against the schema (422); business-rule failures return coded 400/409/422 problem+json.



# Submit a batch of settlement operations
Source: https://docs.lerian.studio/en/reference/rails/slc/create-operations-batch

/en/openapi/v3-current/slc.yaml post /v1/operations/batch
Accepts newline-delimited JSON (application/x-ndjson). Each line is one operation, validated and created through the same pipeline as POST /v1/operations, grouped under one generated batchId. The batch is validated against a configured line limit (default 50000) before any operation is persisted; exceeding it returns 413 with no operations persisted. Processing is synchronous; one bad line is rejected with a per-line error without aborting the batch. Optionally idempotent via the X-Idempotency header. Errors are RFC 9457 problem+json.



# Create a participant
Source: https://docs.lerian.studio/en/reference/rails/slc/create-participant

/en/openapi/v3-current/slc.yaml post /v1/participants
Registers a participant in the tenant's catalog. Field presence/type is validated against the schema (422); business-rule failures return coded 422/409 problem+json. connectivityOk/lastConnectivityAt are read-only (owned by the test-connectivity flow). RBAC: participants:write; tenantId is derived from the validated identity, never the payload.



# Register a webhook subscription
Source: https://docs.lerian.studio/en/reference/rails/slc/create-webhook

/en/openapi/v3-current/slc.yaml post /webhooks
Registers a webhook subscription for the request tenant. The raw secret is used only to derive a SHA-256 hash (never persisted in cleartext); in BYOC the real signing secret comes from the client's Kubernetes Secret. Field presence/type is validated against the schema (422); business-rule failures return coded 400/409/422 problem+json.



# Confirm or reject an announced operation between two non-liquidantes
Source: https://docs.lerian.studio/en/reference/rails/slc/decide-lbtr-non-settlor-operation

/en/openapi/v3-current/slc.yaml post /v1/lbtr/nonliquidante-operations/{operationId}/decision
Answers an operation between two of this settlement bank's own non-liquidantes, announced by the câmara (LTR0007), with the institution's LTR0008: CONFIRM accepts it, REJECT refuses it. Asynchronous intake — 202 means the command and its outbound event are committed and nothing has been sent yet. announcedAmount must equal the amount that was announced (422 otherwise). An operation the câmara did NOT ask to have confirmed is 422; one already decided is 409; one that changed since it was read is 409. X-Idempotency is REQUIRED: a retry carrying the same key replays the stored response, and the same key with a different body is 409. RBAC: lbtr:write; the deciding operator and the tenant are always taken from the validated request identity, never from the payload.



# Confirm or diverge from an announced settlement result
Source: https://docs.lerian.studio/en/reference/rails/slc/decide-lbtr-result

/en/openapi/v3-current/slc.yaml post /v1/lbtr/results/{resultId}/decision
Answers a result the câmara announced (LTR0001) with the institution's LTR0002: CONFIRM accepts it, DIVERGE disputes it. Asynchronous intake — 202 means the command and its outbound event are committed and nothing has been sent yet; poll the command to see the câmara's answer. announcedAmount must equal the amount that was announced (422 otherwise), compared as a decimal. A result the câmara cancelled, or one already decided, is 409; an announcement that changed since it was read is 409 and should be read again. X-Idempotency is REQUIRED: a retry carrying the same key replays the stored response instead of sending a second answer, and the same key with a different body is 409. RBAC: lbtr:write; the deciding operator and the tenant are always taken from the validated request identity, never from the payload.



# Delete an arrangement
Source: https://docs.lerian.studio/en/reference/rails/slc/delete-arrangement

/en/openapi/v3-current/slc.yaml delete /v1/participants/{id}/arrangements/{arrangementId}
Hard-deletes an arrangement. Returns 204 No Content. 404 when the arrangement does not exist. RBAC: arrangements:write.



# Delete a participant
Source: https://docs.lerian.studio/en/reference/rails/slc/delete-participant

/en/openapi/v3-current/slc.yaml delete /v1/participants/{id}
Soft-deletes a participant (stamps deleted_at). Returns 204 No Content. 404 when the participant does not exist.



# Deactivate a webhook subscription
Source: https://docs.lerian.studio/en/reference/rails/slc/delete-webhook

/en/openapi/v3-current/slc.yaml delete /webhooks/{id}
Deactivates a webhook subscription (delivery history is preserved). Returns 204 No Content. 404 when the subscription does not exist.



# Get an arrangement
Source: https://docs.lerian.studio/en/reference/rails/slc/get-arrangement

/en/openapi/v3-current/slc.yaml get /v1/participants/{id}/arrangements/{arrangementId}
Returns an arrangement by id, scoped to its participant and the request tenant. 404 when the arrangement does not exist.



# Get a file status
Source: https://docs.lerian.studio/en/reference/rails/slc/get-file

/en/openapi/v3-current/slc.yaml get /v1/files/{id}
Returns the status view of one file (id, intakeMode, status, linked operationIds, createdAt). Tenant-scoped. No byte download. 404 when the file does not exist. RBAC: operations:read.



# Read one command and the câmara's answer to it
Source: https://docs.lerian.studio/en/reference/rails/slc/get-lbtr-command

/en/openapi/v3-current/slc.yaml get /v1/lbtr/commands/{commandId}
Reads one command, including the câmara's answer projected exactly as it arrived. For a position query (LTR0009) that answer IS the position the câmara returned: this rail shows it and never computes, nets or re-derives one. Each position carries its own raw sitLancLTR, verbatim and untranslated. An unknown id answers 404. RBAC: lbtr:read; the tenant is always derived from the validated request identity, never the payload.



# Read one announced operation between two non-liquidantes
Source: https://docs.lerian.studio/en/reference/rails/slc/get-lbtr-non-settlor-operation

/en/openapi/v3-current/slc.yaml get /v1/lbtr/nonliquidante-operations/{operationId}
Reads one announced operation between two non-liquidantes, including both legs, the amount a decision must state, and whether the câmara asked for a confirmation. An unknown id answers 404. RBAC: lbtr:read; the tenant is always derived from the validated request identity, never the payload.



# Read one announced settlement result
Source: https://docs.lerian.studio/en/reference/rails/slc/get-lbtr-result

/en/openapi/v3-current/slc.yaml get /v1/lbtr/results/{resultId}
Reads one announced settlement result, including the amount a decision must state and the version that decision is authorised against. An unknown id answers 404. RBAC: lbtr:read; the tenant is always derived from the validated request identity, never the payload.



# Get a settlement operation
Source: https://docs.lerian.studio/en/reference/rails/slc/get-operation

/en/openapi/v3-current/slc.yaml get /v1/operations/{operationId}
Returns the full detail of one settlement operation, including its recorded eslcErrors and recoverability diagnostics.



# Look up an operation by NUliquid
Source: https://docs.lerian.studio/en/reference/rails/slc/get-operation-by-n-uliquid

/en/openapi/v3-current/slc.yaml get /v1/operations/nuliquid/{nuliquid}
Resolves an operation by its 21-position NUliquid. The format is validated before the lookup: a malformed NUliquid returns 422, an absent one 404. LOCAL lookup by default; when participantIspb is supplied AND the local store misses AND the NUliquid is inside the 30-day online horizon, the SLC0908 online fallback consults Núclea. The 200 body is an OperationDetailResponse (local) or a NUliquidOnlineResponse (online fallback). tenant is ALWAYS taken from the validated request context, never the query.



# Get operation state history
Source: https://docs.lerian.studio/en/reference/rails/slc/get-operation-history

/en/openapi/v3-current/slc.yaml get /v1/operations/{operationId}/history
Returns the append-only state-transition log for an operation, ordered oldest first (the auditability proof). 404 when the operation does not exist.



# Get a participant
Source: https://docs.lerian.studio/en/reference/rails/slc/get-participant

/en/openapi/v3-current/slc.yaml get /v1/participants/{id}
Returns a participant by id, scoped to the request tenant. 404 when the participant does not exist.



# Get a participant's operational status
Source: https://docs.lerian.studio/en/reference/rails/slc/get-participant-operational-status

/en/openapi/v3-current/slc.yaml get /v1/participants/{id}/operational-status
Returns the latest PAG0101 operational status recorded for the participant, plus nonOperating — whether the submission gate blocks it, computed with the SAME predicate the gate uses. A participant with no notice yet answers 200 with status NO_NOTICE and nonOperating false (the gate's own rule: no notice does not block), NOT a 404; a participant absent from the tenant's catalog is a 404. RBAC: participants:read; tenant is always derived from the validated request identity.



# Get the settlement grid this instance is enforcing
Source: https://docs.lerian.studio/en/reference/rails/slc/get-schedule

/en/openapi/v3-current/slc.yaml get /v1/schedule
Returns the settlement schedule this instance is applying at the instant of the request: every window of the grid with its nominal boundaries, modeled STR cutoff and current phase, plus the EFFECTIVE credit dispatch posture — which gate the instance applies (the configured credit window, the opt-in grid gate, or the dev always-open relaxation), under which Núclea special grade, and over which boundaries. The credit dispatch block is the authoritative answer for outbound credit: the enforced credit window is NOT in the grid unless the grid gate is enabled, so a grid-only reading can name hours the instance does not apply. All instants are RFC3339 UTC; date and the window boundaries are the LOCAL São Paulo day. Window boundaries are the published grade and are reported even on a weekend or holiday, where businessDay is false and nextOpenAt names the next business opening. Takes no parameters: the phases are defined at an instant, and the grid is global, with no tenant or participant dimension. RBAC: schedule:read (non-tenant).



# Get one embedded XSD schema
Source: https://docs.lerian.studio/en/reference/rails/slc/get-xsd-schema

/en/openapi/v3-current/slc.yaml get /v1/xsd-schemas/{type}
Returns the raw XSD document for a schema type (bare name, e.g. ASLC027; a trailing .xsd is tolerated). Read-only; served as application/xml. 404 when the type is unknown. RBAC: xsd-schemas:read (non-tenant).



# Intake an ASLC file
Source: https://docs.lerian.studio/en/reference/rails/slc/intake-file

/en/openapi/v3-current/slc.yaml post /v1/files
Receives an ASLC file. aslc_passthrough accepts an already-signed, opaque artifact: it is received, stored and audited WITHOUT parsing its content, and the signature outcome is recorded (never a hard reject). aslc_xml intake is not implemented (501). The uploading participantId is an explicit, validated body field; the tenant comes from the request identity, never the body. Field presence/type is validated against the schema (422); a bad participantId or non-base64 content is a coded 400. RBAC: operations:write.



# List a participant's arrangements
Source: https://docs.lerian.studio/en/reference/rails/slc/list-arrangements

/en/openapi/v3-current/slc.yaml get /v1/participants/{id}/arrangements
Lists a participant's arrangements, newest first. Offset-paginated. RBAC: arrangements:read.



# List cancellation repasses awaiting manual reconciliation
Source: https://docs.lerian.studio/en/reference/rails/slc/list-cancellation-relay-intents

/en/openapi/v3-current/slc.yaml get /v1/connectivity/cancellation-relay-intents
Lists the ASLC063/067 acquirer repasses (repasse ao acquirer) whose delivery to Núclea was never established, for the request tenant, oldest first. RBAC: connectivity:admin. This is the population every "MANUAL RECONCILIATION REQUIRED" log line and every cancellation_relay_manual_reconciliation_total increment on this leg points at: a repasse submitted whose conclusion marker was not written, an earlier attempt whose intention was already unresolved, or an attempt that provably never reached the wire whose release failed. Each row BLOCKS its (operationId, aslcType) pair from relaying again — that refusal is what stops a duplicate regulatory notification — so an operator reconciles the reported controlNumber with Núclea and closes it with POST /v1/connectivity/cancellation-relay-intents/resolve, which is the ONLY way to clear one. An empty page is the healthy day, not an error. Offset/limit pagination WITHOUT a total count; the tenant is always derived from the validated request identity.



# List clearing positions
Source: https://docs.lerian.studio/en/reference/rails/slc/list-clearing-positions

/en/openapi/v3-current/slc.yaml get /v1/clearing/positions
Lists the settlement institution's (IF Liquidante) clearing positions for the request tenant: the SLC0001 (clearing net-position notice) net position per participant by stage (PREVIEW/FINAL). This is the clearing PREVIEW/POSITION notice only — it carries NO deposit window or action. Filters: referenceDate (YYYY-MM-DD), cycle, stage. Offset/limit pagination WITHOUT a total count. RBAC: clearing:read; tenant is always derived from the validated request identity.



# List recorded client deposit acks across settlement instructions
Source: https://docs.lerian.studio/en/reference/rails/slc/list-funding-acks

/en/openapi/v3-current/slc.yaml get /v1/funding/acks
Lists client settlement-deposit acks across every settlement instruction, newest first, filtered by result and by a recordedAt window, paged. It is the operator's failed-deposit review surface: result=FAILED answers which deposits the client could not make and the reason it gave for each. result may be SENT or FAILED (coded 400 otherwise) and is omitted to return both; from/to are RFC3339. RBAC: funding:read; tenant is always derived from the validated request identity, never the payload.



# List the commands this institution sent to the câmara
Source: https://docs.lerian.studio/en/reference/rails/slc/list-lbtr-commands

/en/openapi/v3-current/slc.yaml get /v1/lbtr/commands
Lists the commands this institution originated towards the câmara, newest first, paged (limit default 50, max 500). Each row carries who authorised it, what was sent, and how far it got — ACCEPTED means Lerian SILOC accepted and QUEUED the command, not that it reached the câmara, and is NOT a settlement claim. RBAC: lbtr:read; the tenant is always derived from the validated request identity, never the payload.



# List the announced operations between this bank's own non-liquidantes
Source: https://docs.lerian.studio/en/reference/rails/slc/list-lbtr-non-settlor-operations

/en/openapi/v3-current/slc.yaml get /v1/lbtr/nonliquidante-operations
Lists the operations between two of this settlement bank's own non-liquidantes that the câmara announced, newest movement date first, paged (limit default 50, max 500). indrConfc says whether the câmara asked for a confirmation at all; deciding one it did not ask about is refused. RBAC: lbtr:read; the tenant is always derived from the validated request identity, never the payload.



# List the settlement results the câmara announced
Source: https://docs.lerian.studio/en/reference/rails/slc/list-lbtr-results

/en/openapi/v3-current/slc.yaml get /v1/lbtr/results
Lists the gross and bilateral settlement results the câmara announced, newest movement date first, paged (limit default 50, max 500). Every amount is the value the câmara sent, echoed unchanged: this rail holds no position and computes no balance. status says where each announcement stands — ANNOUNCED is awaiting a decision. RBAC: lbtr:read; the tenant is always derived from the validated request identity, never the payload.



# List settlement operations
Source: https://docs.lerian.studio/en/reference/rails/slc/list-operations

/en/openapi/v3-current/slc.yaml get /v1/operations
Lists settlement operations for the request tenant, filtered and paginated. Filters: state, operationType, batchId, externalId, dateFrom/dateTo (over created_at). Offset/limit pagination.



# List participants
Source: https://docs.lerian.studio/en/reference/rails/slc/list-participants

/en/openapi/v3-current/slc.yaml get /v1/participants
Lists the request tenant's participants, newest first. Offset-paginated. RBAC: participants:read; tenant is always derived from the validated request identity.



# List generated reports
Source: https://docs.lerian.studio/en/reference/rails/slc/list-reports

/en/openapi/v3-current/slc.yaml get /v1/reports
Lists the request tenant's generated/available SLC (Serviço de Liquidação Centralizada) reports (reports table), newest first. This is a read-only facade — the rows are written by the ASLC9xx (família de mensagens de intake de relatório) intake pipeline. Filter: limit (default page size when omitted). RBAC: reports:read; tenant is always derived from the validated request identity, never a query or path param.



# List the client deposit acks recorded for a settlement instruction
Source: https://docs.lerian.studio/en/reference/rails/slc/list-settlement-instruction-acks

/en/openapi/v3-current/slc.yaml get /v1/funding/settlement-instructions/{instructionId}/acks
Lists the client settlement-deposit acks recorded against one settlement instruction, NEWEST FIRST, both SENT and FAILED, each with the failure reason the client gave. The response is PAGED (limit default 50, max 500) and pagination.hasNext says whether older acks remain, so a long history is never silently truncated. A client may legitimately send a FAILED then a SENT ack for one instruction (the FAILED does not change the instruction's state; the later SENT advances it), so both halves of that recovery sequence are returned. An unknown instruction id answers 404; a known instruction the client has not answered yet answers 200 with an empty list. RBAC: funding:read; tenant is always derived from the validated request identity, never the payload.



# List a webhook's delivery history
Source: https://docs.lerian.studio/en/reference/rails/slc/list-webhook-deliveries

/en/openapi/v3-current/slc.yaml get /webhooks/{id}/deliveries
Returns the paginated delivery attempts (including retries) for a subscription, scoped to the request tenant. Each item carries its created_at partition key so a later replay can address the partitioned row.



# List webhook subscriptions
Source: https://docs.lerian.studio/en/reference/rails/slc/list-webhooks

/en/openapi/v3-current/slc.yaml get /webhooks
Lists the request tenant's webhook subscriptions, including delivery metrics (successCount, failureCount, lastDeliveryAt, lastDeliveryStatus).



# List embedded XSD schema types
Source: https://docs.lerian.studio/en/reference/rails/slc/list-xsd-schemas

/en/openapi/v3-current/slc.yaml get /v1/xsd-schemas
Lists the schema type names (bare names, e.g. ASLC027, SLC0001) of the official Núclea ASLC and RSFN XSDs embedded in the service. Read-only introspection; the bytes are identical for every tenant. RBAC: xsd-schemas:read (non-tenant).



# Reconcile an operation against the counterpart's settlement status
Source: https://docs.lerian.studio/en/reference/rails/slc/reconcile-operation

/en/openapi/v3-current/slc.yaml post /v1/operations/{operationId}/reconcile
Consults Núclea for the AUTHORITATIVE SLC0908 settlement status of one operation and synchronises the local record under NUCLEA_RECONCILED, leaving an operation_state_log row whose trigger separates a machine synchronisation from an operator's override. Admin-only (operations:admin). The reason is mandatory and enforced by the domain (400 MISSING_OVERRIDE_JUSTIFICATION); the reconciling subject is taken from the validated request identity, never from the payload. WHY THIS PATH EXISTS ALONGSIDE THE DRAINS: the /v1/connectivity/* recovery verbs (dispatch, forward, repoll, status-relay, reprocess, unpark) re-drive OUR OWN internal transport and never consult the counterpart, so they cannot report what Núclea believes — this operation asks Núclea and records the answer. Disjoint capabilities, not substitutes. Only FORWARDED->CONFIRMED and CONFIRMED->SETTLED are driveable: a counterpart state further away is refused rather than walked (409 INVALID_STATE_TRANSITION), because walking it would fabricate an intermediate transition nobody observed. An operation carrying no NUliquid has no key to run the consulta with and answers 409 SLC-0119 with the state-specific remediation. A counterpart status outside the mapped vocabulary answers 409 SLC-0121 and writes nothing.



# Record a client settlement-deposit ack
Source: https://docs.lerian.studio/en/reference/rails/slc/record-funding-ack

/en/openapi/v3-current/slc.yaml post /v1/funding/settlement-instructions/{instructionId}/ack
Records the client's STR deposit ack for a relayed position notify and drives the settlement instruction to ACKED for a SENT deposit (from PENDING or NOTIFIED) (the client owns the STR connection; the SLC emits NO LDL0022). A FAILED result is recorded but leaves the instruction unchanged so the deposit can be re-driven. Synchronous and definitive. Idempotent via the X-Idempotency header (a retry carrying the same key replays the stored response). result must be SENT or FAILED (coded 400 otherwise). RBAC: funding:write; tenant is always derived from the validated request identity, never the payload.



# Trigger a credit-dispatch catch-up drain
Source: https://docs.lerian.studio/en/reference/rails/slc/recovery-dispatch

/en/openapi/v3-current/slc.yaml post /v1/connectivity/dispatch
Drains the QUEUED credit backlog once for the request tenant, the same work the schedule worker runs. RBAC: connectivity:admin. Window-gated internally: outside the credit window it is a no-op that still returns 202. OUTBOUND (transmits to Núclea): serialized per tenant with the schedule worker via a shared drain lock — 409 on contention, 503 when the lock backend is unavailable (never transmits unlocked).



# Trigger an ASLC022 forward-to-domicile catch-up drain
Source: https://docs.lerian.studio/en/reference/rails/slc/recovery-forward

/en/openapi/v3-current/slc.yaml post /v1/connectivity/forward
Drains the ACCEPTED backlog once for the request tenant, forwarding each operation to its IF Domicílio (ASLC022), the same work the schedule worker runs. RBAC: connectivity:admin. Window-gated internally: outside the forward window it is a no-op that still returns 202. OUTBOUND (transmits to Núclea): serialized per tenant with the schedule worker via a shared drain lock — 409 on contention, 503 when the lock backend is unavailable.



# Trigger a return-poll catch-up drain
Source: https://docs.lerian.studio/en/reference/rails/slc/recovery-repoll

/en/openapi/v3-current/slc.yaml post /v1/connectivity/repoll
Derives the participants awaiting a return for the request tenant and drives the ProcessReturn pipeline (poll PRO/RET → correlate → transition) once per participant, the same work the schedule worker runs. RBAC: connectivity:admin. INBOUND and NOT window-gated. It drives the idempotent ProcessReturn pipeline, so it runs lock-free and is safe to run concurrently with the worker.



# Reprocess pending returns for one participant
Source: https://docs.lerian.studio/en/reference/rails/slc/recovery-reprocess

/en/openapi/v3-current/slc.yaml post /v1/connectivity/reprocess/{participantIspb}
Drives the ProcessReturn pipeline once for a single participant (poll PRO/RET → correlate → transition), the same per-participant work the return poll runs. RBAC: connectivity:admin. The participant ISPB is a path RESOURCE selector; the tenant is ALWAYS taken from the validated request context, never the path. INBOUND and NOT window-gated; it drives the idempotent ProcessReturn pipeline, so it runs lock-free.



# Trigger an ASLC028 status-relay catch-up drain
Source: https://docs.lerian.studio/en/reference/rails/slc/recovery-status-relay

/en/openapi/v3-current/slc.yaml post /v1/connectivity/status-relay
Relays the CONFIRMED / IF-REJECTED status of the request tenant's operations to the creditor (ASLC028), filtering out the already-relayed ones, the same work the schedule worker runs. RBAC: connectivity:admin. Window-gated internally: outside the relay window it is a no-op that still returns 202. OUTBOUND (transmits to Núclea): serialized per tenant with the schedule worker via a shared drain lock — 409 on contention, 503 when the lock backend is unavailable.



# Un-park operations held after exhausting their outbound attempt budget
Source: https://docs.lerian.studio/en/reference/rails/slc/recovery-unpark

/en/openapi/v3-current/slc.yaml post /v1/connectivity/unpark
Clears the outbound transmit claim of the named operations, returning them to the eligible backlog so the next drain tick re-drives them. RBAC: connectivity:admin. It is the ONLY recovery path for a PARKED operation. BOTH outbound stages park for the SAME reason, reported in parkReason as attempt_budget_exhausted: N consecutive counterpart refusals exhausted the operation's attempt budget (SCHEDULE_DISPATCH_MAX_TRANSMIT_ATTEMPTS, default 20). What differs is the stage and the state left behind, which the alert reports in stage: a FORWARD file (ASLC022/024/032/061/065 to the IF Domicilio) leaves the operation ACCEPTED, re-driven by the forward tick; a DISPATCH file (ASLC027/029/031/060/064 to Nuclea) leaves it QUEUED, re-driven by the dispatch tick. The value permanent_rejection is RETIRED and no longer emitted - no single 4xx response carries the evidence to park a file - but historical alerts still carry it. Either way the held claim makes it invisible to every drain, and every other admin verb is a dead end: /advance rejects the no-op self-edge, /requeue is CREATED-only, /retry is REJECTED-only, and /retransmit either rejects the state (a parked forward op is ACCEPTED, not QUEUED) or loses its own claim CAS and answers 409 in-flight (a parked dispatch op IS QUEUED). Enumerate the ids with GET /v1/operations?transmitHold=parked, which is the authoritative, paginated, tenant-scoped list; the operation.forward_rejected alert (payload operationIds) and the park's ERROR log field parked_operation_ids are first-response excerpts of the same set, and the daily webhook names only the first file parked that day. There is no scope-wide form: a held transmit claim is AMBIGUOUS between a parked operation and one whose file is already at Nuclea, and only the caller decides which set to release. This verb REFUSES the second kind with 409 when it is marked as such (transmitHold=in_flight) - reconcile those with Nuclea and drive each one with POST /v1/operations/{operationId}/advance instead, never un-park them. Idempotent: re-running releases nothing further and reports released=0. Claims younger than the 5-minute safety floor are skipped (they may belong to a pass that is mid-submit). Un-parking also zeroes the attempt budget, so a recovered operation gets a full budget rather than re-parking on its next refusal. Runs lock-free: it transmits nothing.



# Redispatch an outbox entry
Source: https://docs.lerian.studio/en/reference/rails/slc/redispatch-outbox-entry

/en/openapi/v3-current/slc.yaml post /admin/outbox/{id}/redispatch
Resets the terminally-INVALID transactional-outbox row {id} back to PENDING for the request tenant so the relay dispatcher republishes it on its next tick. The row id is PRESERVED (the event is never recreated). Idempotent: a row that is not INVALID is left untouched and returns redispatched=false with its current status — a PUBLISHED row is never re-sent. An unknown id → 404. A multi-tenant deployment answers 501. RBAC: outbox:redispatch; tenant is always derived from the validated request identity, never a path or payload value.



# Replay a dead letter
Source: https://docs.lerian.studio/en/reference/rails/slc/replay-dead-letter

/en/openapi/v3-current/slc.yaml post /admin/dlq/{queue}/{id}/replay
Reprocesses the dead letter {id} on the given queue (rsfn or sfn) for the request tenant by re-invoking the same in-process ingest path (NOT a work-queue re-publish). Idempotent: the processed_messages dedup trap makes a re-dispatch of an already-processed message a no-op. queue is validated against the allowlist (unknown → 404); an unknown id → 404. RBAC: dlq:replay; tenant is always derived from the validated request identity, never a path or payload value.



# Replay a failed webhook delivery
Source: https://docs.lerian.studio/en/reference/rails/slc/replay-webhook-delivery

/en/openapi/v3-current/slc.yaml post /webhooks/{id}/deliveries/{deliveryId}/replay
Re-enqueues a non-delivered delivery (FAILED/RETRYING/PENDING) for re-delivery, reconstructed from the persisted payload. The delivery must belong to {id} (else 404); a terminal-success delivery is rejected with 409. Requires the createdAt partition key. Returns 202 Accepted; idempotent at the consumer.



# Re-queue a stuck operation
Source: https://docs.lerian.studio/en/reference/rails/slc/requeue-operation

/en/openapi/v3-current/slc.yaml post /v1/operations/{operationId}/requeue
Re-admits an operation stuck in CREATED into the dispatch queue via a WINDOW_ASSIGNED transition, emitting operation.queued. A non-CREATED state returns 409 with code SLC-0105 (INVALID_STATE_TRANSITION): the problem+json body carries only type/title/status/detail/code, and its detail is a fixed sentence that names neither the operation's current state nor the states it would accept — read the current state from GET /v1/operations/{operationId}.



# Record what was established about an unresolved cancellation repasse
Source: https://docs.lerian.studio/en/reference/rails/slc/resolve-cancellation-relay-intents

/en/openapi/v3-current/slc.yaml post /v1/connectivity/cancellation-relay-intents/resolve
Records the outcome an operator ESTABLISHED for ASLC063/067 repasses whose delivery this service could not determine on its own. RBAC: connectivity:admin. It is the ONLY way to clear an unresolved repasse intention, and each clearing is one-way. CONFIRMED means you established the file DID reach Núclea: the repasse's duty is discharged and the (operationId, aslcType) pair STAYS blocked, because relaying again would duplicate a regulatory notification to the acquirer. ABANDONED means you established it NEVER reached Núclea: the pair is returned to a relayable state, while the burnt control number and the attempt count survive on the row so the attempt budget still sees what this repasse has spent. IN_FLIGHT is REFUSED as an outcome with 400 — that state belongs to the relay itself, which writes it alongside a fresh control number and a charged attempt, so re-arming a repasse through this verb would unblock a submission whose outcome is unknown and charge nothing for it. reason is ALWAYS required and is logged at ERROR with the targets: it is the audit record of a human overriding an automated refusal on a regulatory rail. There is no scope-wide form: each intention records a finding about a DIFFERENT file at Núclea, and only the caller knows which ones they checked — the same posture POST /v1/connectivity/unpark takes. Enumerate the targets with GET /v1/connectivity/cancellation-relay-intents. Idempotent: re-running reports the already-recorded intentions as not_in_flight and rewrites nothing, so a repeat can never overturn a finding. Per-target results are resolved / not_in_flight / not_found. It transmits nothing, drives no operation transition and emits no business event.



# Retry a rejected operation
Source: https://docs.lerian.studio/en/reference/rails/slc/retry-operation

/en/openapi/v3-current/slc.yaml post /v1/operations/{operationId}/retry
Resends a REJECTED operation as a NEW operation chained to the original via originalOperationId, respecting the retry limit. A non-REJECTED state returns 409 INVALID_STATE_TRANSITION; a chain at the limit returns 409 RETRY_LIMIT_EXCEEDED. An operation that was rejected AFTER it settled (a D+1 refusal by the IF Domicilio) is NOT retryable and returns 409 RETRY_AFTER_SETTLEMENT: the money already moved, so a retry would settle it twice.



# Complete a BYOK Model-A signing-key import (SaaS)
Source: https://docs.lerian.studio/en/reference/rails/slc/signing-key-import

/en/openapi/v3-current/slc.yaml post /v1/signing-key
Forwards the tenant's already-wrapped, opaque key material (Model A — never cleartext) to KMS via the signer sidecar, then persists ONLY the public certificate + the per-tenant KMS reference + custody_provider=KMS (never key material). RBAC: signing-key:import (admin-only provisioning role). Field presence/type is validated against the schema (422); a malformed ISPB or invalid base64 is a coded 400. Idempotent via the MANDATORY X-Idempotency header.



# Start a BYOK Model-A signing-key import (SaaS)
Source: https://docs.lerian.studio/en/reference/rails/slc/signing-key-import-params

/en/openapi/v3-current/slc.yaml post /v1/signing-key/import-params
Creates a fresh EXTERNAL-origin KMS key for the caller's tenant and returns the wrapping public key + import token the tenant uses to wrap their ICP-Brasil private key material LOCALLY (Model A — the SLC never sees the private key in cleartext). RBAC: signing-key:import (admin-only provisioning role). Idempotent via the MANDATORY X-Idempotency header.



# SLC error list
Source: https://docs.lerian.studio/en/reference/rails/slc/slc-error-list

Look up the Lerian SLC error codes, the HTTP status each one carries, and the Núclea rejection codes that reach you on a settlement operation.

**Error format**

Lerian SLC returns errors as RFC 9457 problem details with the `application/problem+json` media type:

```json JSON theme={null}
{
  "type": "https://errors.lerian.studio/v1/SLC-0105",
  "title": "Conflict",
  "status": 409,
  "detail": "operation is not in a state that permits this transition",
  "code": "SLC-0105",
  "correlationId": "req-7a3f9c2e"
}
```

**Field definitions**

* **`type`** – A URI that identifies the error in the Lerian error catalog, built as `https://errors.lerian.studio/v1/<code>`.
* **`title`** – The HTTP status text, for example `Conflict` or `Unprocessable Entity`. It comes from the status, not from the name of the error.
* **`status`** – The HTTP status code, repeated from the response status line.
* **`detail`** – An explanation specific to this occurrence. A response with status 500 or above carries the fixed text `internal error`, so branch on `code` instead of parsing this field.
* **`code`** – The stable machine identifier, in the form `SLC-NNNN`. Branch on this field.
* **`correlationId`** – The request-scoped correlation identifier, the same value as the response `X-Request-Id` header. Quote this value in a support request.
* **`errors`** – A list of per-field details, each with a `location`, a `message`, and the offending `value`. A schema validation failure lists one entry per field.

## Platform and request errors

***

These codes can arrive from any endpoint. Each one describes the request, the credential, or the availability of the service rather than the settlement operation itself.

| `code` | Description | Status |
| - | - | - |
| SLC-0001 | The request is malformed. The body does not parse, a required header is missing, or a value fails a format check. | 400 |
| SLC-0002 | The service met an unexpected condition. The `detail` reads `internal error`. | 500 |
| SLC-0003 | The request reached a protected route without a valid bearer token. | 401 |
| SLC-0004 | The credential is authenticated but lacks the permission the route requires. | 403 |
| SLC-0005 | The requested resource does not exist. | 404 |
| SLC-0006 | The request fails schema validation, or a business rule refuses it. A schema failure lists each field in `errors`. | 422 |
| SLC-0007 | The request conflicts with the current state, such as a replay of a webhook delivery that already went out, or an `X-Idempotency` key that is in use or that came with a different body. | 409 |
| SLC-0008 | A transport or a dependency is unavailable. | 503 |
| SLC-0009 | The request exceeds the rate limit. The `Retry-After` header says when to retry. | 429 |
| SLC-0010 | The request body is above the accepted size. | 413 |
| SLC-0011 | A 4xx condition without a more specific code. A `405 Method Not Allowed` keeps its own status and carries this code. | 4xx |
| SLC-0012 | The route is mounted, and your deployment configuration does not make it available. | 501 |

## Settlement operation errors

***

These codes come from the operations domain. They describe the settlement instruction you submitted, the original operation a cancellation targets, or the answer a reconcile received from the counterparty.

| `code` | Description | Status |
| - | - | - |
| SLC-0102 | An ISPB in the request is not eight characters of digits or uppercase letters. It covers the creditor, domicile, and settlement ISPBs, a participant registration, and the reconcile participant. | 422 |
| SLC-0103 | The `operationType` is a recognised value that is not enabled for submission. | 422 |
| SLC-0104 | The `externalId` already belongs to another operation. | 409 |
| SLC-0105 | The operation sits in a state that does not permit the transition you asked for. | 409 |
| SLC-0106 | A command names an operation that does not exist. On a reconcile, it can also mean that Núclea holds no record for the NUliquid. | 404 |
| SLC-0107 | The NDJSON batch carries more lines or more bytes than the configured cap. Lerian SLC checks both caps before it saves anything, so it saves no operation. | 413 |
| SLC-0108 | The NUliquid you supplied is not 21 digits, or its `AAAAMMDD` prefix is not a valid date. The format check runs before any lookup. | 422 |
| SLC-0109 | The `participantId` is not registered. | 422 |
| SLC-0110 | The retry chain of the operation reached its limit. | 409 |
| SLC-0111 | An advance or a reconcile arrived without its justification. An advance needs a reason and evidence. A reconcile needs a reason. | 400 |
| SLC-0112 | A retry finds a live operation for the same `externalId`. Converge on that operation instead of creating a second instruction. | 409 |
| SLC-0113 | The original operation no longer accepts a cancellation. Its state is CONFIRMED, SETTLED, D1\_CONFIRMED, or CANCELLED, or its money already settled. | 409 |
| SLC-0114 | The `originalOperationId` a cancellation references does not exist. | 422 |
| SLC-0115 | The original operation carries a type that does not accept a cancellation. Only CREDIT and DEBIT movements are cancellable. | 422 |
| SLC-0116 | Núclea has not accepted the original operation yet, so it holds no NUliquid and the cancellation has no movement to block. | 409 |
| SLC-0117 | A cancellation is already in progress for the same original operation. | 409 |
| SLC-0118 | The retry targets a rejected operation whose money already settled. | 409 |
| SLC-0119 | The operation holds no NUliquid, so the reconcile has no key to query with. The `detail` names the recovery that suits the current state. | 409 |
| SLC-0120 | The NUliquid of the operation falls outside the 30-day online query horizon. A retry does not help, because the horizon moves further away. | 409 |
| SLC-0121 | The counterparty answered a settlement status outside the mapped vocabulary, and the reconcile recorded nothing. The `detail` quotes the token so you can raise it with Núclea. | 409 |
| SLC-0122 | The counterparty answered about a different NUliquid from the one queried, so the answer describes another operation and the reconcile recorded nothing. | 409 |
| SLC-0123 | The settlement query produced no answer about the operation because of a condition on the channel. The `detail` names the condition. | 409 |
| SLC-0150 | A cancellation arrived without the numeric reason category the Núclea layout requires. | 422 |

## Núclea rejection codes

***

Núclea, the clearing house that operates the SLC, answers a submission or a return file with its own business error codes, in the form `ESLCNNNN`. Lerian SLC records them against the operation and hands them back unchanged. The operation detail response carries `eslcErrors`, an array of the recorded codes that is empty when the operation has none. It also carries `lastError`, the recorded codes joined into one string, or null when there are none. `eslcErrors` can also carry the occurrence code that an IF Domicílio returns. Each value arrives verbatim from the network, so read it as counterparty vocabulary rather than a Lerian code.

Núclea defines 85 of these codes. The table below covers the ones that change what you do next.

| `code` | Description | What to do |
| - | - | - |
| ESLC0006 | The date is invalid. | Correct the date and submit again. |
| ESLC0007 | The CPF or CNPJ is invalid. | Correct the document number and submit again. |
| ESLC0029 | The request arrived outside the scheduled window. | Submit in the next window. See [SLC operations](/en/rails/slc/slc-operations). |
| ESLC0042 | An enrolment for this feature does not exist. | Complete the enrolment with Núclea, then submit again. |
| ESLC0097 | The settlement number is not registered. | Check the NUliquid the request references. |
| ESLC0119 | The administered participant is not administered by the principal participant. | Correct the participant registration with Núclea. The same file succeeds once the registration matches. |
| ESLC0123 | The participant did not enrol in the feature. | Complete the enrolment with Núclea. The same file succeeds afterwards. |
| ESLC0140 | The arrangement institutor code is not permitted for the file type sent. | Correct the arrangement registration or the arrangement code in the file, then submit again. |
| ESLC0161 | An administered participant may not submit over HTTP. | Submit through the transport registered for that participant. |
| ESLC0163 | The payment date is not permitted for a cancellation. | Cancel inside the date range the original operation permits. |
| ESLC0164 | The record is already cancelled, settled, or in settlement, so it does not accept a cancellation. | Stop the cancellation. Lerian SLC refuses the same condition locally with `SLC-0113`. |
| ESLC1017 | The settlement numbers for a cancellation on the date given were not found. | Check the date and the settlement numbers the request references. |

> [!NOTE]
>
> Núclea can refuse a file submission synchronously with one of four codes: `ESLC0119`, `ESLC0123`, `ESLC0140`, and `ESLC0161`. The table above names the remedy for each code. [SLC operations](/en/rails/slc/slc-operations) describes the transmit-attempt budget.

**The remaining codes**

The rest of the catalog describes the submitted record or the participant registration. The largest families are:

* **Field domain and format** – A value sits outside the domain the layout permits, or a segment carries the wrong format. Currency codes, person types, arrangement institutors, and occurrence codes appear here.
* **Registration and enrolment** – A CNPJ, an ISPB, or a participant relationship differs from what Núclea holds for the acquirer.
* **Duplicate control numbers** – A control number or a file name repeats one Núclea already registered.
* **Dates and reporting periods** – A payment date, a reference date, or a report range sits outside what the product type permits.
* **Record state and occurrence codes** – The occurrence code does not suit the current state of the record, such as a settled record or a cancelled one.
* **Return periods** – The record sits inside a return period, and Núclea names the file type that carries the correction.
* **Limits and volumes** – A payment amount, a file count, or a record count sits above the accepted maximum.

Núclea sends a code from these families on a line of a return file or in its verdict on a submission. Lerian SLC records it in `eslcErrors` on the operation. Quote the code when you raise the case with Núclea, because it is the identifier Núclea support works from.


# Ask the câmara for this institution's LBTR position
Source: https://docs.lerian.studio/en/reference/rails/slc/submit-lbtr-position-query

/en/openapi/v3-current/slc.yaml post /v1/lbtr/position-queries
Asks the câmara for this institution's own financial position (LTR0009). dtMovto is required; every other field is a filter. Asynchronous intake — 202 means the query is committed and nothing has been sent yet; the câmara's answer is read back from GET /v1/lbtr/commands/{commandId}, projected exactly as it arrived. The câmara's ISPB is not a field here: this message answers nothing, so there is nothing to echo it from, and Lerian SILOC supplies it. sitLancLTR is the raw 3-digit situation code, passed through verbatim. X-Idempotency is REQUIRED and a repeat query needs a NEW key: two identical queries are two questions and each is entitled to its own answer. RBAC: lbtr:write; the asking operator and the tenant are always taken from the validated request identity, never from the payload.



# Test connectivity to Núclea for a participant
Source: https://docs.lerian.studio/en/reference/rails/slc/test-connectivity

/en/openapi/v3-current/slc.yaml post /v1/participants/{participantIspb}/test-connectivity
Sends a role-correct connectivity probe over the REST channel (AGEN001 for the DOMICILE_IF role, AGEN999 for other participant roles) and reports the round-trip echo and latency in the nucleaApi channel status. The path param is the participant's 8-character ISPB, NOT the participant UUID the sibling /v1/participants operations take. 404 when the ISPB is not a participant in the tenant's catalog. RBAC: connectivity:test (admin). The cdConnection and rsfnConnection channels report NOT_CONFIGURED because the managed file-transfer and message-broker transports are not currently available. An open-breaker transport returns a retryable 503.



# Send a synthetic test event to a webhook
Source: https://docs.lerian.studio/en/reference/rails/slc/test-webhook

/en/openapi/v3-current/slc.yaml post /webhooks/{id}/test
Synchronously dispatches a synthetic test envelope (eventType=webhook.test) to the subscription and returns the delivery result. 404 when the subscription does not exist.



# Update an arrangement
Source: https://docs.lerian.studio/en/reference/rails/slc/update-arrangement

/en/openapi/v3-current/slc.yaml put /v1/participants/{id}/arrangements/{arrangementId}
Updates an arrangement's mutable fields. Omitted fields are left unchanged. A duplicate (participant, code, role) returns 409; an invalid role/code 422. RBAC: arrangements:write.



# Update a participant
Source: https://docs.lerian.studio/en/reference/rails/slc/update-participant

/en/openapi/v3-current/slc.yaml put /v1/participants/{id}
Updates a participant's mutable fields. Omitted fields are left unchanged. connectivityOk/lastConnectivityAt cannot be set here. 404 when the participant does not exist.



# Update a webhook subscription
Source: https://docs.lerian.studio/en/reference/rails/slc/update-webhook

/en/openapi/v3-current/slc.yaml put /webhooks/{id}
Updates a webhook subscription. Omitted fields are left unchanged. A new secret rotates the signing secret (rehashed; never stored in cleartext). 404 when the subscription does not exist.



# Acknowledge an operational alert
Source: https://docs.lerian.studio/en/reference/rails/siloc/acknowledge-an-operational-alert

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/alerts/{id}/acknowledge
Records that an operator saw alert {id} and deactivates it, so it leaves the default (active-only) feed; it remains readable with activeOnly=false. The dismissal, its acknowledgement event and its audit row commit together. EVERY alert type is acknowledgeable, including the condition alarms (RELAY_DOWN, CONNECTION_DOWN, CERTIFICATE_EXPIRY, WINDOW_CLOSING): acknowledging asserts that a person saw the alarm, never that the condition ended, so while the condition holds the watcher's next poll raises a FRESH alert and it reappears. An unknown id is 404; an alert another operator already acknowledged (or that cleared itself) is 409, never a silent success. The response omits complementWindowClosesAt: the dismissal reads the alert row alone and performs no recálculo join.



# Ask the câmara for its LDL schedule grid
Source: https://docs.lerian.studio/en/reference/rails/siloc/ask-the-camara-for-its-ldl-schedule-grid

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/schedule-queries
Issues an LDL0023 "IF consulta Horários Câmara LDL" to the SILOC câmara on product OT (Catálogo de Serviços do SFN v5.13, Vol II). The request is minted, built, signed, encrypted and durably recorded before anything reaches the queue: this returns 202 with the control number the câmara will echo, and the answer (LDL0023R1) arrives asynchronously — read it back with getScheduleQuery. A deployment with no send leg configured answers 503.



# Ask the câmara for the institution's LBTR position
Source: https://docs.lerian.studio/en/reference/rails/siloc/ask-the-camara-for-the-institution-s-lbtr-position

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/ltr-position-queries
Issues an LTR0009 "IF consulta Posição financeira" to the câmara (Catálogo de Serviços do SFN v5.13, Vol II). Every field but movementDate is an optional filter: omit one to leave that dimension unconstrained. Returns 202; the answer (LTR0009R1) carries up to 200 position entries and is projected verbatim — this rail never sums, nets or rounds them.



# Ask the câmara for the net position
Source: https://docs.lerian.studio/en/reference/rails/siloc/ask-the-camara-for-the-net-position

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/net-position-queries
Issues an LDL0026 "IF consulta Posição de resultado líquido de negociação" to the Câmara LDL (Catálogo de Serviços do SFN v5.13, Vol II). It asks for this institution's net result for a settlement date, or the remaining balance of partial payments, for itself and for its non-settling members. It moves no money. The query is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (LDL0026R1) arrives asynchronously and is read back with getLDL0026. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Ask the câmara to accept a collateral deposit
Source: https://docs.lerian.studio/en/reference/rails/siloc/ask-the-camara-to-accept-a-collateral-deposit

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/deposit-acceptance-requests
Issues a LDL1002 to the Câmara LDL on behalf of an Entidade Responsável (Catálogo de Serviços do SFN v5.13, Vol II). Requests the câmara's acceptance of a deposit — voluntary or required — of guarantee, margin or securities, for one or more assets under a named holder (Vol II, Evento LDL1002 Descrição). The aceite the câmara grants here is what LDL1003 later draws on: its answer carries a Número Controle Aceite LDL per asset, and the deposit request names it back. The request is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (LDL1002R1) arrives asynchronously and is read back with getLDL1002. Every amount and quantity is a decimal STRING carried to the wire exactly as written. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Ask the câmara to accept a collateral withdrawal
Source: https://docs.lerian.studio/en/reference/rails/siloc/ask-the-camara-to-accept-a-collateral-withdrawal

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/withdrawal-acceptance-requests
Issues a LDL1006 to the Câmara LDL on behalf of an Entidade Responsável (Catálogo de Serviços do SFN v5.13, Vol II). Requests the câmara's acceptance of a withdrawal — voluntary or required — of guarantee, margin or securities (Vol II, Evento LDL1006 Descrição). The câmara answers per asset, accepting or rejecting each one it was sent (Evento LDL1006 Observação), so a single answer can carry both outcomes. The request is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (LDL1006R1) arrives asynchronously and is read back with getLDL1006. Every amount and quantity is a decimal STRING carried to the wire exactly as written. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Ask to amend a guarantee's maturity or amount
Source: https://docs.lerian.studio/en/reference/rails/siloc/ask-to-amend-a-guarantee-s-maturity-or-amount

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/guarantee-maturity-amendments
Issues a LDL1010 to the Câmara LDL on behalf of an Entidade Responsável (Catálogo de Serviços do SFN v5.13, Vol II). Requests an amendment to the maturity date or the amount of a fiança already deposited as collateral (Vol II, Evento LDL1010 Descrição). The answer is a single S/N situação (SitAditt, official type Indr): the câmara either took the amendment or did not. The request is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (LDL1010R1) arrives asynchronously and is read back with getLDL1010. Every amount and quantity is a decimal STRING carried to the wire exactly as written. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Cancel a pending entry in the Câmara PAG
Source: https://docs.lerian.studio/en/reference/rails/siloc/cancel-a-pending-entry-in-the-camara-pag

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/pending-entry-cancellations
Issues a PAG0112 "IF requisita Cancelamento de lançamento pendente na Câmara PAG" to the Câmara PAG (Catálogo de Serviços do SFN v5.13, Vol II). Cancels a transfer already registered in the câmara that is still sitting in the pending queue, naming it by the câmara's own control number (NumCtrlPAGOr). ⚠️ A lançamento the câmara has already finalised CANNOT be cancelled: the Catálogo's own Observação says the message returns an error, so a REFUSED row here most often means the movement had already settled. The instruction is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (PAG0112R1) arrives asynchronously and is read back with getPAG0112. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Confirm a guarantee issuance or amendment
Source: https://docs.lerian.studio/en/reference/rails/siloc/confirm-a-guarantee-issuance-or-amendment

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/guarantee-issuance-confirmations
Issues an LDL1019 "IF informa Confirmação de emissão ou aditamento de fiança" to the Câmara LDL (Catálogo de Serviços do SFN v5.13, Vol II). It confirms, or rejects, the guarantee position the câmara announced on its LDL1018: SitConfc is S (Sim) or N (Não), and NumCtrlLDLOr is filled with the Número Controle LDL that LDL1018 carried (RLDL0013). Both are the operator's to supply, because the câmara sent them and this rail derives no reply of its own. The command is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo. THE CATÁLOGO REGISTERS NO POSITIVE ANSWER LEG FOR THIS MESSAGE, so an accepted confirmation stays DISPATCHED and only a refusal (LDL1019E) moves it again. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Confirm or dispute the day's net result
Source: https://docs.lerian.studio/en/reference/rails/siloc/confirm-or-dispute-the-day-s-net-result

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/net-result-confirmations
Issues an LDL0003 "IF informa Resultado líquido de negociações confirmado ou divergente" to the Câmara LDL (Catálogo de Serviços do SFN v5.13, Vol II). It states which of the lançamentos the câmara announced on its LDL0001 this institution accepts, and at what value: a lançamento accepted in part is reported at the value actually recognised, one NOT accepted is reported as ZERO, and one accepted in full at its original value. NumCtrlLDLOr names the LDL0001 being confirmed and is the operator's to supply, because the câmara sent it and this rail derives no reply of its own. The command is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (LDL0003R1) arrives asynchronously and is read back with getLDL0003. Every amount is a decimal STRING carried to the wire exactly as written. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Confirm or diverge from an announced LBTR result
Source: https://docs.lerian.studio/en/reference/rails/siloc/confirm-or-diverge-from-an-announced-lbtr-result

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/ltr-result-decisions
Issues an LTR0002 "IF informa Resultado da negociação confirmado ou divergente" to the câmara (Catálogo de Serviços do SFN v5.13, Vol II), answering the LTR0001 it announced. The request is minted, built, signed, encrypted and durably recorded before anything reaches the queue: this returns 202 with the control number the câmara will echo, and the answer (LTR0002R1) arrives asynchronously. tpConfDivg is carried to the wire verbatim — the official type enumerates no value.



# Confirm or reject a settlement between two non-settling members
Source: https://docs.lerian.studio/en/reference/rails/siloc/decide-non-settling-member-settlement

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/ltr-nonliquidante-decisions
Issues an LTR0008 "IF informa Confirmação ou rejeição de liquidação entre Não Liquidantes" to the câmara (Catálogo de Serviços do SFN v5.13, Vol II), answering the LTR0007 it announced. Returns 202; the answer (LTR0008R1) arrives asynchronously.



# Get the business-day calendar
Source: https://docs.lerian.studio/en/reference/rails/siloc/get-business-day-calendar

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/schedule/calendar
The honored national holiday calendar for a year plus the verified BCB-artifact provenance (source, retrieval instant, sha256, covered years), projected verbatim from the compiled artifact. year defaults to the current year; a year outside the artifact's coverage returns a clean 404.



# Get the câmara's last session announcements
Source: https://docs.lerian.studio/en/reference/rails/siloc/get-the-camara-s-last-session-announcements

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/schedule/camara-session
The newest LDL0028 (abertura), LDL0029 (fechamento), LDL0030 (interrupção das atividades) and LDL0031 (retomada) the câmara sent, each projected verbatim with the câmara's OWN announced instant. A kind the câmara has never announced is omitted. No open/closed verdict is derived here: the live verdict is the active CAMARA_CLOSED / CAMARA_INTERRUPTED alert on listAlerts, flipped by the arriving notice. These notices ALARM and never affect readiness.



# List operational alerts
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-alerts

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/alerts
The operational alerts, filtered by type and (by default) active only, keyset-paged newest first. A RECALCULATION alert carries its correlated cycle's active recálculo round complement window, read verbatim from ot_recalculations — never netted, summed, or recomputed. A connection-level alert (e.g. RELAY_DOWN) carries no cycle and no window. activeOnly=false includes deactivated alerts (history), which is where an acknowledged alarm goes.



# List audit records
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-audit-records

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/audit-records
The append-only audit trail of privileged mutations (obligations, configuration changes, relayed messages, access), keyset-paged newest occurred first. Filterable by occurred_at range (from/to, inclusive), action type, and participant ISPB. Every field is a stored column projected verbatim — no counts, no aggregates, no derived durations. Read-only: the trail is never mutated through this surface.



# List the advices the SILOC câmara sent this institution
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-camara-advices

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/advices
Every message the SILOC câmara originated at this institution and this rail stored, newest movement date first. Narrow with codMsg to read one kind — the net result of negotiations (LDL0001), the events-and-emissions settlement forecast (LDL0007), a transfer request (LDL0010), a deposit request (LDL0013), a guarantee position to confirm (LDL1018), a collateral requirement met (LDL1026) or a movement outcome (LDL1027) — or with numCtrlLDL to find the one advice a confirmation answers. Projected verbatim (Catálogo de Serviços do SFN v5.13, Vol II): amounts are the câmara's own decimal strings, body carries that code's own fields exactly as they arrived, and nothing here nets, sums or confirms anything.



# List câmara bilateral settlement balances
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-camara-bilateral-settlement-balances

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/bilateral-balances
The bilateral settlement balances the PAG câmara stated (PAG0200 — saldos bilaterais para liquidação de movimento de Prestador de Serviços de Compensação e de Liquidação), keyset-paged newest announced first. Every amount is the wire string the câmara sent: the stated multilateral amount, the stated payment and receipt totals, and the per-counterparty legs behind each. Read-only, and nothing here is computed — Lerian SILOC holds no position, nets no balance and does not reconcile the câmara's totals against its own legs. Acting on a statement is the client's ledger's business.



# List câmara collateral advisories
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-camara-collateral-advisories

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/collateral/advisories
The collateral advisories the câmara sent — LDL1001 (exigibilidade de colateral), LDL1011 (ativos a serem substituídos) and LDL1014 (alteração na lista de ativos elegíveis) — keyset-paged newest announced first, each projected verbatim including the amounts, deadlines and asset identifiers the câmara carried. Read-only: Lerian SILOC values no asset, computes no exposure and originates no deposit; acting on an advisory is a command an operator or the ledger consumer sends. Each arriving advisory also raises its operator alarm (COLLATERAL_REQUIRED, COLLATERAL_SUBSTITUTION, ELIGIBLE_ASSETS_CHANGED) on listAlerts and never affects readiness.



# List file-availability notices from other participants
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-file-notices

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/file-notices
The GEN0015 notices other SFN participants sent this institution to say a file is available — answering a GEN0014 request, or announcing the file unprompted — keyset-paged newest announced first, each projected verbatim. Unlike every other arriving message on this rail, the sender is another participant rather than the câmara, so it is carried on each row and verified against the certificate that sent the frame. Read-only, and the notice half only: Lerian SILOC records that a file was announced and publishes the fact; fetching the file is a consumer's decision and a separate leg.



# List outbound messages of every code
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-outbound-messages-of-every-code

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/messages
Every message this institution has issued to the câmara, newest first, whatever its code. Narrow with status to work a backlog: FAILED is the set the rail will never deliver as stored and an operator has to act on, REFUSED the set the câmara received and returned as its E twin, and this list is the only way to see a message whose code this build does not recognise. The projection is the columns every SFN request carries; the stored request is not interpreted here, so read a code's own operation for its own fields.



# List contingency schedule changes
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-schedule-changes

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/schedule/changes
The operator-recorded contingency schedule changes, keyset-paged newest announced first. Each row is an out-of-band-received Núclea announcement (OP002 §14 = telephone/e-mail) recorded verbatim by an operator; the câmara's own wire grids are read at listScheduleGrids, and nothing here computes a schedule. Read-only — the feed is projected, never mutated through this surface.



# List the grades de horário the câmara published
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-schedule-grids

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/schedule/grids
Every grade de horário this rail received from the SILOC câmara, newest reference date first — both the unsolicited change advice (LDL0024) and the answers to schedule queries this institution issued (LDL0023R1), with source saying which leg delivered each row. Narrow with source to read one leg, or with referenceDate to read the hours that apply to one day. Projected verbatim (Catálogo de Serviços do SFN v5.13, Vol II): the câmara's own clock, its own 5-character grid code, and no canonical window resolved from either.



# List OT cycle windows
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-schedule-windows

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/schedule/windows
The compiled canonical OT deposit/settlement window grid (two windows per business day), projected verbatim from the pinned regulated policy — a pure read that needs no datastore and serves with the DB down. Operator-entered prorrogações are NOT merged here; they stay on listScheduleChanges.



# List the card-route commands Lerian SLC issued
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-the-card-route-commands-lerian-slc-issued

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/card-commands
Every command received on the card route, newest first, with the outcome the câmara returned. It is the operator half of the card-route alarm: a stalled consumer, a câmara that stopped answering and a broker that went quiet all look the same from outside, and this is where the commands stuck in RECEIVED or ACCEPTED become visible. Readiness is deliberately not the signal — a stalled feed alarms, it does not take the rail out of rotation.



# List the PAG transfer credit notices the câmara sent this institution
Source: https://docs.lerian.studio/en/reference/rails/siloc/list-transfer-credit-notices

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/advices/transfer-credit-notices
The "Resposta a Terceiros" (<CODE>R2) the PAG câmara sends the CREDITED institution of a fund transfer another institution requested — PAG0107R2, PAG0108R2, PAG0111R2, PAG0121R2, PAG0122R2, PAG0134R2, PAG0137R2, PAG0141R2, PAG0142R2, PAG0143R2 and PAG0151R2 (Catálogo de Serviços do SFN v5.13, Vol II) — keyset-paged newest posted first. Each notice is the câmara stating that a movement was POSTED in this institution's favour; it settles in the LDL cycle, and nothing here books, sums or settles it. The fields every notice carries are projected verbatim and rawBody holds the whole document as delivered. Narrow with movementDate, codMsg or numCtrlPAG.



# Move collateral between holders or purposes
Source: https://docs.lerian.studio/en/reference/rails/siloc/move-collateral-between-holders-or-purposes

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/collateral-movements
Issues a LDL1016 to the Câmara LDL on behalf of an Entidade Responsável (Catálogo de Serviços do SFN v5.13, Vol II). Requests a transfer of collateral or securities between holders, sub-holders or cover purposes within one Entidade Responsável (Vol II, Evento LDL1016 Descrição). RLDL0012: Número Controle LDL Original names the control number of the LDL1001 that required the collateral. The request is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (LDL1016R1) arrives asynchronously and is read back with getLDL1016. Every amount and quantity is a decimal STRING carried to the wire exactly as written. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Move one holder's collateral by asset number
Source: https://docs.lerian.studio/en/reference/rails/siloc/move-one-holder-s-collateral-by-asset-number

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/same-holder-collateral-movements
Issues a LDL1017 to the Câmara LDL on behalf of an Entidade Responsável (Catálogo de Serviços do SFN v5.13, Vol II). Requests a movement of collateral for a single holder, naming the asset by the câmara's own Número Ativo and carrying the previous and new value or quantity (Vol II, Evento LDL1017 Descrição). RLDL0012: Número Controle LDL Original names the control number of the LDL1001 that required the collateral. The request is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (LDL1017R1) arrives asynchronously and is read back with getLDL1017. Every amount and quantity is a decimal STRING carried to the wire exactly as written. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Query the reference prices the câmara used on a day
Source: https://docs.lerian.studio/en/reference/rails/siloc/query-reference-prices

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/price-history-queries
Issues a LDL1015 to the Câmara LDL on behalf of an Entidade Responsável (Catálogo de Serviços do SFN v5.13, Vol II). Asks the prices the câmara used on a given quotation date for a given asset (Vol II, Evento LDL1015 Descrição). RLDL0010 describes which identifiers narrow the query to one asset; the official schema declares each of them optional, so the câmara rather than this rail decides whether a query is specific enough. The request is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (LDL1015R1) arrives asynchronously and is read back with getLDL1015. Every amount and quantity is a decimal STRING carried to the wire exactly as written. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Query the assets deposited at the câmara
Source: https://docs.lerian.studio/en/reference/rails/siloc/query-the-assets-deposited-at-the-camara

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/deposited-asset-queries
Issues a LDL1012 to the Câmara LDL on behalf of an Entidade Responsável (Catálogo de Serviços do SFN v5.13, Vol II). Asks the câmara which assets are deposited for a named holder and sub-holder, with the totals it holds against them (Vol II, Evento LDL1012 Descrição). Only assets deposited for the Titular and Subtitular named in the request come back (Evento LDL1012 Observação), so a query that names the wrong holder answers empty rather than failing. The request is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (LDL1012R1) arrives asynchronously and is read back with getLDL1012. Every amount and quantity is a decimal STRING carried to the wire exactly as written. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Query the assets the câmara accepts as collateral
Source: https://docs.lerian.studio/en/reference/rails/siloc/query-the-assets-the-camara-accepts-as-collateral

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/eligible-collateral-queries
Issues a LDL1013 to the Câmara LDL on behalf of an Entidade Responsável (Catálogo de Serviços do SFN v5.13, Vol II). Asks which assets the Câmara LDL accepts as collateral and at what prices (Vol II, Evento LDL1013 Descrição). Its answer carries a price per settlement-term indicator, which is what makes it a different question from LDL1015's price history for one asset on one day. The request is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (LDL1013R1) arrives asynchronously and is read back with getLDL1013. Every amount and quantity is a decimal STRING carried to the wire exactly as written. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Query the entries the Câmara PAG holds
Source: https://docs.lerian.studio/en/reference/rails/siloc/query-the-entries-the-camara-pag-holds

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/entry-queries
Issues a PAG0113 "IF consulta Lançamentos na Câmara PAG" to the Câmara PAG (Catálogo de Serviços do SFN v5.13, Vol II). Asks the câmara which entries it holds for this institution on a movement date. Every optional field in the body is a FILTER that narrows the universe returned (RSTR0007); supplying none asks for all of them. ⚠️ The answer NEVER includes a message the câmara refused for a format or basic-consistency error (RPAG0004), so an empty result means "no entry matches these filters" and never "nothing was sent". The instruction is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (PAG0113R1) arrives asynchronously and is read back with getPAG0113. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Query the synthetic statement in the Câmara PAG
Source: https://docs.lerian.studio/en/reference/rails/siloc/query-the-synthetic-statement-in-the-camara-pag

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/synthetic-statement-queries
Issues a PAG0114 "IF consulta Extrato sintético na Câmara PAG" to the Câmara PAG (Catálogo de Serviços do SFN v5.13, Vol II). Asks the câmara for the synthetic statement of the operations compensated on a movement date: per operational period, the opening deposit, the complementary deposits, the debit and credit totals, and the closing balance. The movement date is the whole of the question — the layout carries no filters. ⛔ EVERY BALANCE IN THE ANSWER IS THE CÂMARA'S, RECEIVED AND NOT COMPUTED. This rail stores each amount as the digit string the câmara wrote, renders it back unchanged, and neither derives the closing balance nor checks that it reconciles — that is the ledger consumer's work, against its own books. The instruction is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (PAG0114R1) arrives asynchronously and is read back with getPAG0114. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Read one card-route command
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-card-route-command

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/card-commands/{id}
One command Lerian SLC issued, the message it produced, and — for an answered position query — every entry the câmara returned, verbatim.



# Read one LDL0003 command and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-ldl0003-command-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/net-result-confirmations/{id}
The stored LDL0003 request projected verbatim, its dispatch state, and — once the câmara has acknowledged — the answer it sent. LDL0003R1 is an acknowledgement and carries no body beyond the header, so its details object is empty. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the LDL0003E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it).



# Read one LDL0026 command and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-ldl0026-command-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/net-position-queries/{id}
The stored LDL0026 request projected verbatim, its dispatch state, and — once the câmara has answered — its answer. The answer's details object carries TpInf, DtLiquid and Grupo_LDL0026R1_ResultLiqd, the per-non-settling-member results, ALWAYS as an array even when the câmara sent one repetition. Every value is projected exactly as written and never decoded: TpInf's values are published in BACEN's separate Dicionário de Domínios with their own activation and deactivation dates, so what one means is the ledger consumer's call.



# Read one LDL0032 command and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-ldl0032-command-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/camara-withdrawals/{id}
The stored LDL0032 request projected verbatim, its dispatch state, and — once the câmara has answered — its answer. The answer's details object carries NumCtrlLDL (the câmara's own control number for the movement), SitLancDev and, when present, VlrLanc. SitLancDev is projected VERBATIM and never decoded: its seventeen values are published separately in the Dicionário de Domínios, with activation and deactivation dates per value, so what a situação means about the money is the ledger consumer's call.



# Read one LDL1002 request and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-ldl1002-request-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/deposit-acceptance-requests/{id}
The stored LDL1002 request projected verbatim, its dispatch state, and — once the câmara has answered — its Número Controle LDL plus everything else the answer carried, also verbatim. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the LDL1002E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it). answer.details is projected VERBATIM and never decoded: the situação values the nine collateral answers carry enumerate nothing in the official types, so what one means about the collateral is the ledger consumer's call.



# Read one LDL1003 request and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-ldl1003-request-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/deposit-requests/{id}
The stored LDL1003 request projected verbatim, its dispatch state, and — once the câmara has answered — its Número Controle LDL plus everything else the answer carried, also verbatim. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the LDL1003E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it). answer.details is projected VERBATIM and never decoded: the situação values the nine collateral answers carry enumerate nothing in the official types, so what one means about the collateral is the ledger consumer's call.



# Read one LDL1006 request and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-ldl1006-request-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/withdrawal-acceptance-requests/{id}
The stored LDL1006 request projected verbatim, its dispatch state, and — once the câmara has answered — its Número Controle LDL plus everything else the answer carried, also verbatim. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the LDL1006E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it). answer.details is projected VERBATIM and never decoded: the situação values the nine collateral answers carry enumerate nothing in the official types, so what one means about the collateral is the ledger consumer's call.



# Read one LDL1010 request and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-ldl1010-request-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/guarantee-maturity-amendments/{id}
The stored LDL1010 request projected verbatim, its dispatch state, and — once the câmara has answered — its Número Controle LDL plus everything else the answer carried, also verbatim. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the LDL1010E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it). answer.details is projected VERBATIM and never decoded: the situação values the nine collateral answers carry enumerate nothing in the official types, so what one means about the collateral is the ledger consumer's call.



# Read one LDL1012 request and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-ldl1012-request-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/deposited-asset-queries/{id}
The stored LDL1012 request projected verbatim, its dispatch state, and — once the câmara has answered — its Número Controle LDL plus everything else the answer carried, also verbatim. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the LDL1012E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it). answer.details is projected VERBATIM and never decoded: the situação values the nine collateral answers carry enumerate nothing in the official types, so what one means about the collateral is the ledger consumer's call.



# Read one LDL1013 request and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-ldl1013-request-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/eligible-collateral-queries/{id}
The stored LDL1013 request projected verbatim, its dispatch state, and — once the câmara has answered — its Número Controle LDL plus everything else the answer carried, also verbatim. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the LDL1013E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it). answer.details is projected VERBATIM and never decoded: the situação values the nine collateral answers carry enumerate nothing in the official types, so what one means about the collateral is the ledger consumer's call.



# Read one LDL1015 request and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-ldl1015-request-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/price-history-queries/{id}
The stored LDL1015 request projected verbatim, its dispatch state, and — once the câmara has answered — its Número Controle LDL plus everything else the answer carried, also verbatim. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the LDL1015E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it). answer.details is projected VERBATIM and never decoded: the situação values the nine collateral answers carry enumerate nothing in the official types, so what one means about the collateral is the ledger consumer's call.



# Read one LDL1016 request and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-ldl1016-request-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/collateral-movements/{id}
The stored LDL1016 request projected verbatim, its dispatch state, and — once the câmara has answered — its Número Controle LDL plus everything else the answer carried, also verbatim. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the LDL1016E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it). answer.details is projected VERBATIM and never decoded: the situação values the nine collateral answers carry enumerate nothing in the official types, so what one means about the collateral is the ledger consumer's call.



# Read one LDL1017 request and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-ldl1017-request-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/same-holder-collateral-movements/{id}
The stored LDL1017 request projected verbatim, its dispatch state, and — once the câmara has answered — its Número Controle LDL plus everything else the answer carried, also verbatim. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the LDL1017E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it). answer.details is projected VERBATIM and never decoded: the situação values the nine collateral answers carry enumerate nothing in the official types, so what one means about the collateral is the ledger consumer's call.



# Read one LDL1019 command and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-ldl1019-command-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/guarantee-issuance-confirmations/{id}
The stored LDL1019 request projected verbatim and its dispatch state. There is no answer block on this code and there never will be: the Catálogo registers no LDL1019R1, and the official LDL1019.XSD declares none. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue — the terminal state for an accepted confirmation, because no reply is owed), REFUSED (the câmara returned the LDL1019E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it).



# Read one LTR0002 decision and its state
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-ltr0002-decision-and-its-state

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/ltr-result-decisions/{id}
The stored LTR0002 request, its dispatch state and, once ANSWERED, the câmara's LTR0002R1 body — all projected verbatim. An ANSWERED decision whose body this rail does not hold says so in answerAbsent; it never renders as an empty answer.



# Read one LTR0008 decision and its state
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-ltr0008-decision-and-its-state

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/ltr-nonliquidante-decisions/{id}
The stored LTR0008 request, its dispatch state and, once ANSWERED, the câmara's LTR0008R1 body — all projected verbatim. An ANSWERED decision whose body this rail does not hold says so in answerAbsent; it never renders as an empty answer.



# Read one LTR0009 query and its state
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-ltr0009-query-and-its-state

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/ltr-position-queries/{id}
The stored LTR0009 request, its dispatch state and, once ANSWERED, the câmara's LTR0009R1 body — all projected verbatim. An ANSWERED query whose body this rail does not hold says so in answerAbsent; it never renders as an empty answer.



# Read one outbound message, whatever its code
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-outbound-message-whatever-its-code

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/messages/{id}
The universal state of one issued message: its code, the control number the câmara echoes, its lifecycle status, how many queue puts have been attempted and why the last one failed. The stored request is not interpreted here.



# Read one PAG0107 instruction and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-pag0107-instruction-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/non-account-holder-transfers/{id}
The stored PAG0107 request projected verbatim, its dispatch state, and — once the câmara has answered — the Número Controle PAG and the Situação Lançamento PAG it assigned, also verbatim. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the PAG0107E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it). sitLancPAG is projected VERBATIM and never decoded: its values are published separately in the Dicionário de Domínios, with activation and deactivation dates per value, so what a situação means about the money is the ledger consumer's call.



# Read one PAG0108 instruction and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-pag0108-instruction-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/client-account-transfers/{id}
The stored PAG0108 request projected verbatim, its dispatch state, and — once the câmara has answered — the Número Controle PAG and the Situação Lançamento PAG it assigned, also verbatim. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the PAG0108E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it). sitLancPAG is projected VERBATIM and never decoded: its values are published separately in the Dicionário de Domínios, with activation and deactivation dates per value, so what a situação means about the money is the ledger consumer's call.



# Read one PAG0111 instruction and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-pag0111-instruction-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/undue-transfer-refunds/{id}
The stored PAG0111 request projected verbatim, its dispatch state, and — once the câmara has answered — the Número Controle PAG and the Situação Lançamento PAG it assigned, also verbatim. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the PAG0111E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it). sitLancPAG is projected VERBATIM and never decoded: its values are published separately in the Dicionário de Domínios, with activation and deactivation dates per value, so what a situação means about the money is the ledger consumer's call.



# Read one PAG0112 instruction and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-pag0112-instruction-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/pending-entry-cancellations/{id}
The stored PAG0112 request projected verbatim, its dispatch state, and — once the câmara has answered — what it replied, also verbatim. The answer carries the câmara's own control number for the cancellation it registered. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the PAG0112E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it).



# Read one PAG0113 instruction and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-pag0113-instruction-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/entry-queries/{id}
The stored PAG0113 request projected verbatim, its dispatch state, and — once the câmara has answered — what it replied, also verbatim. The answer carries up to 200 entries, in the order the câmara sent them, each with its amount as the decimal STRING the câmara wrote. `entries` is always present and is the empty list when the query matched nothing. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the PAG0113E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it).



# Read one PAG0114 instruction and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-pag0114-instruction-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/synthetic-statement-queries/{id}
The stored PAG0114 request projected verbatim, its dispatch state, and — once the câmara has answered — what it replied, also verbatim. The answer carries up to 200 period rows, in the order the câmara sent them. `periods` is always present and is the empty list when the câmara returned none. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the PAG0114E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it).



# Read one PAG0121 instruction and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-pag0121-instruction-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/judicial-deposit-transfers/{id}
The stored PAG0121 request projected verbatim, its dispatch state, and — once the câmara has answered — the Número Controle PAG and the Situação Lançamento PAG it assigned, also verbatim. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the PAG0121E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it). sitLancPAG is projected VERBATIM and never decoded: its values are published separately in the Dicionário de Domínios, with activation and deactivation dates per value, so what a situação means about the money is the ledger consumer's call.



# Read one PAG0122 instruction and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-pag0122-instruction-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/barcode-document-settlements/{id}
The stored PAG0122 request projected verbatim, its dispatch state, and — once the câmara has answered — the Número Controle PAG and the Situação Lançamento PAG it assigned, also verbatim. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the PAG0122E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it). sitLancPAG is projected VERBATIM and never decoded: its values are published separately in the Dicionário de Domínios, with activation and deactivation dates per value, so what a situação means about the money is the ledger consumer's call.



# Read one PAG0134 instruction and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-pag0134-instruction-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/non-reserve-institution-transfers/{id}
The stored PAG0134 request projected verbatim, its dispatch state, and — once the câmara has answered — the Número Controle PAG and the Situação Lançamento PAG it assigned, also verbatim. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the PAG0134E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it). sitLancPAG is projected VERBATIM and never decoded: its values are published separately in the Dicionário de Domínios, with activation and deactivation dates per value, so what a situação means about the money is the ledger consumer's call.



# Read one PAG0137 instruction and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-pag0137-instruction-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/salary-account-transfers/{id}
The stored PAG0137 request projected verbatim, its dispatch state, and — once the câmara has answered — the Número Controle PAG and the Situação Lançamento PAG it assigned, also verbatim. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the PAG0137E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it). sitLancPAG is projected VERBATIM and never decoded: its values are published separately in the Dicionário de Domínios, with activation and deactivation dates per value, so what a situação means about the money is the ledger consumer's call.



# Read one PAG0141 instruction and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-pag0141-instruction-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/payroll-loan-credit-transfers/{id}
The stored PAG0141 request projected verbatim, its dispatch state, and — once the câmara has answered — the Número Controle PAG and the Situação Lançamento PAG it assigned, also verbatim. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the PAG0141E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it). sitLancPAG is projected VERBATIM and never decoded: its values are published separately in the Dicionário de Domínios, with activation and deactivation dates per value, so what a situação means about the money is the ledger consumer's call.



# Read one PAG0142 instruction and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-pag0142-instruction-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/retail-client-to-institution-transfers/{id}
The stored PAG0142 request projected verbatim, its dispatch state, and — once the câmara has answered — the Número Controle PAG and the Situação Lançamento PAG it assigned, also verbatim. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the PAG0142E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it). sitLancPAG is projected VERBATIM and never decoded: its values are published separately in the Dicionário de Domínios, with activation and deactivation dates per value, so what a situação means about the money is the ledger consumer's call.



# Read one PAG0143 instruction and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-pag0143-instruction-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/retail-institution-to-client-transfers/{id}
The stored PAG0143 request projected verbatim, its dispatch state, and — once the câmara has answered — the Número Controle PAG and the Situação Lançamento PAG it assigned, also verbatim. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the PAG0143E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it). sitLancPAG is projected VERBATIM and never decoded: its values are published separately in the Dicionário de Domínios, with activation and deactivation dates per value, so what a situação means about the money is the ledger consumer's call.



# Read one PAG0151 instruction and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-pag0151-instruction-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/judicial-release-transfers/{id}
The stored PAG0151 request projected verbatim, its dispatch state, and — once the câmara has answered — the Número Controle PAG and the Situação Lançamento PAG it assigned, also verbatim. status is SUBMITTED (recorded; still queued, retried on a backoff), DISPATCHED (on the queue, awaiting the answer), ANSWERED, REFUSED (the câmara returned the PAG0151E twin; lastError carries its CodErro values) or FAILED (this rail could not deliver it). sitLancPAG is projected VERBATIM and never decoded: its values are published separately in the Dicionário de Domínios, with activation and deactivation dates per value, so what a situação means about the money is the ledger consumer's call.



# Read one schedule query and its answer
Source: https://docs.lerian.studio/en/reference/rails/siloc/read-one-schedule-query-and-its-answer

/en/openapi/v3-current/siloc.yaml get /api/v1/siloc/outbound/schedule-queries/{id}
The stored LDL0023 request, its dispatch state, and — once the câmara has answered — every grade de horário the LDL0023R1 returned, projected verbatim. status is SUBMITTED (recorded; still queued for delivery, and retried on a backoff for as long as the fault lasts), DISPATCHED (on the queue, awaiting the answer), ANSWERED, or FAILED (the official schema refused the document, which is terminal; lastError carries the diagnosis).



# Record a contingency schedule change
Source: https://docs.lerian.studio/en/reference/rails/siloc/record-schedule-change

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/schedule/changes
Records an out-of-band-received Núclea schedule announcement (OP002 §14 = telephone/e-mail) as an operator-entered operational fact, projected verbatim. The câmara's own wire grids (LDL0024, LDL0023R1) are read at listScheduleGrids; nothing here computes a schedule. The recorded change appends an audit row, raises the single active SCHEDULE_CHANGE alert (deadline_at = effectiveAt), and emits a schedule.change-recorded fact — all atomically.



# Request a collateral deposit the câmara already accepted
Source: https://docs.lerian.studio/en/reference/rails/siloc/request-collateral-deposit

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/deposit-requests
Issues a LDL1003 to the Câmara LDL on behalf of an Entidade Responsável (Catálogo de Serviços do SFN v5.13, Vol II). Requests the deposit itself, for assets the câmara already accepted through LDL1002; each asset names the original Número Controle Requisição IF and Número Controle Aceite LDL (Vol II, Evento LDL1003 Descrição). RLDL0008: one custody transfer that produces several allocations repeats its Selic or CETIP operation number once per Entidade Responsável 2. The request is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (LDL1003R1) arrives asynchronously and is read back with getLDL1003. Every amount and quantity is a decimal STRING carried to the wire exactly as written. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Return funds received in error
Source: https://docs.lerian.studio/en/reference/rails/siloc/return-funds-received-in-error

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/undue-transfer-refunds
Issues a PAG0111 "IF requisita Transferência de recursos para devolução de transferência indevida" to the Câmara PAG (Catálogo de Serviços do SFN v5.13, Vol II). Requests the return of funds transferred in error, or that the destination institution could not accept. It names the original Número Controle PAG and the official return reason. The instruction is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (PAG0111R1) arrives asynchronously and is read back with getPAG0111. Every amount is a decimal STRING carried to the wire exactly as written. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# SILOC error list
Source: https://docs.lerian.studio/en/reference/rails/siloc/siloc-error-list

Look up SILOC error codes, the HTTP status each one carries, and the action that resolves it.

**Error format**

SILOC returns errors as RFC 9457 problem details:

```json JSON theme={null}
{
  "type": "https://errors.lerian.studio/v1/SILOC-0007",
  "title": "Not Found",
  "status": 404,
  "detail": "participant not found",
  "code": "SILOC-0007"
}
```

**Field definitions**

* **`type`** – A URI that identifies the error in the Lerian error catalog, built as `https://errors.lerian.studio/v1/<code>`. This URI repeats `code`, so it does not separate two statuses that share one code.
* **`title`** – The HTTP status text (for example, `Not Found`).
* **`status`** – The HTTP status code.
* **`detail`** – A human-readable explanation for this occurrence. A `500`, a `SILOC-0023`, and a `SILOC-0024` replace the text with `internal error`, so the internal cause stays inside the rail. The text varies per occurrence, and a `403` can carry the message the authorization service reported. Do not branch on it.
* **`code`** – The stable, machine-readable code (`SILOC-NNNN`). Dispatch on the pair of `status` and `code`, not on `code` alone. One code can appear under more than one status, and each status needs a different action. For example, `SILOC-0001` is a 503 from the authorization gate and a 422 from a card operation. A request that fails schema validation carries `SILOC-0022`, and `errors` names the fields at fault.
* **`errors`** – An optional list of field-level details, each with the `location` it read, a `message`, and the `value` found there. A refusal from the authorization or idempotency gate carries an empty `violations` list instead.

The tables below list the codes SILOC returns, grouped by HTTP status.

## 400, 413, 415: Request body refused

***

| Status | `code` | Description | `detail` |
| - | - | - | - |
| 400 | SILOC-0022 | The request body is missing, or it is not valid JSON. Send a JSON body that matches the schema of the operation. | `request body is required`, `validation failed` |
| 413 | SILOC-0022 | The request body reached the 1 MiB limit. Send a smaller body. | `request body is too large limit=1048576 bytes` |
| 415 | SILOC-0022 | The request declares a `Content-Type` that is not JSON. Send the body as `application/json`. | `validation failed` |

## 401: Unidentified caller

***

| `code` | Description | `detail` |
| - | - | - |
| SILOC-0004 | The request arrived without a bearer token, or with a credential the authorization service does not accept. | `Missing Token`, or `Unauthorized` |
| SILOC-0003 | A state-changing request reached the idempotency gate without an identified caller to attribute the `X-Idempotency` to. | `authenticated principal unavailable` |
| SILOC-0401 | A certificate operation reached the rail without a caller identity to record. | `authorized actor identity is unavailable` |

## 403: Refused caller

***

| `code` | Description | `detail` |
| - | - | - |
| SILOC-0005 | The authorization service refused this caller for the resource and action the request targets. | `Forbidden`, or the message the authorization service reported |

## 404: Not found

***

| `code` | Description | `detail` |
| - | - | - |
| SILOC-0007 | The path or query named a resource the rail does not hold. Verify the identifier, or list the collection to find a valid one. | `participant not found`, `certificate not found`, `alert not found`, `relay failure not found`, `quarantined frame not found`, `cycle not found`, `settlement instruction not found`, `cycle reconciliation not found`, `no outbound instruction with that id`, `homologation scenario not found`, `business calendar year not covered` |
| SILOC-0004 | A card operation named a card message or card command the rail does not hold. | `no card message with that id`, `no card command with that id` |

## 409: Conflicts

***

| `code` | Description | `detail` |
| - | - | - |
| SILOC-0009 | The request collides with state the rail already holds, or with a command that already spent this `X-Idempotency`. Re-read the current state before you retry. | `a participant with this ISPB already exists`, `the active credential cannot be disabled; revocation was not recorded`, `alert is already inactive`, `notification config was modified concurrently; re-read and retry with the current version`, `a run is already in progress for this scenario; wait for it to finish`, `a request with this idempotency key is still being processed; retry once it completes`, `the idempotency key was already used with a different request` |

## 422: Validation errors

***

| `code` | Description | `detail` |
| - | - | - |
| SILOC-0022 | The request is well formed but breaks a domain rule, or carries a value the rail cannot read. Correct the field the response names and send the request again. | `validation failed`, `X-Idempotency header is required on a state-changing request`, `X-Idempotency must be at most 255 characters`, `invalid pagination cursor`, `participantId must be a valid uuid`, `certificateId must be a valid uuid`, `id must be a valid uuid`, `authorized actor identity is unavailable`, `from/to must be an RFC 3339 date-time`, `malformed semantic ROC payload`, `semantic ROC fiIspb is not the configured local FI`, `no OT cycle correlates the semantic ROC`, `ambiguous OT cycles correlate the semantic ROC`, `semantic ROC revision already ingested with a different content hash`, `semantic ROC revision supersession is invalid` |
| SILOC-0001 | A card operation carries a value the rail cannot accept. Correct the field the response names and send the request again. | `decidedAt must be an RFC 3339 timestamp`, `movementDate must be a date in YYYY-MM-DD form`, `id must be a uuid`, or the rule the command breaks |

## 500: Server errors

***

| `code` | Description | `detail` |
| - | - | - |
| SILOC-0500 | An unexpected server fault. The rail masks the cause and returns a fixed text. Retry the request, and quote the trace identifier of the response if the fault persists. | `internal error` |

## 503: Rail cannot answer

***

| `code` | Description | `detail` |
| - | - | - |
| SILOC-0001 | The rail could not reach a decision about this caller. The authorization service did not answer, or the deployment cannot authorize with its current configuration. | `Service Unavailable` |
| SILOC-0002 | The rail could not prove the command unique, so the outcome of the command is undetermined. | `the service could not prove this command unique; its outcome is undetermined — reconcile the original request before retrying, and never retry it with a new key` |
| SILOC-0023 | This deployment has no send leg to Núclea, so it cannot send the requested message. | `internal error` |
| SILOC-0024 | The send leg to Núclea is not running on this deployment. Retry once it recovers. | `internal error` |

> [!NOTE]
>
> A 503 that carries `SILOC-0002` does not tell you the command was rejected. The rail answers with it both before the command runs and after it commits, so the command may already have taken effect. Reconcile the original request first. When you do retry, send the same `X-Idempotency`, and never retry under a new one.


# Transfer funds between client accounts
Source: https://docs.lerian.studio/en/reference/rails/siloc/transfer-funds-between-client-accounts

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/client-account-transfers
Issues a PAG0108 "IF requisita Transferência de recursos entre contas de clientes" to the Câmara PAG (Catálogo de Serviços do SFN v5.13, Vol II). Requests a transfer of funds between natural or legal persons holding accounts at different financial institutions. The instruction is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (PAG0108R1) arrives asynchronously and is read back with getPAG0108. Every amount is a decimal STRING carried to the wire exactly as written. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Transfer funds for a judicial deposit
Source: https://docs.lerian.studio/en/reference/rails/siloc/transfer-funds-for-a-judicial-deposit

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/judicial-deposit-transfers
Issues a PAG0121 "IF requisita Transferência de recursos para depósito judicial" to the Câmara PAG (Catálogo de Serviços do SFN v5.13, Vol II). Requests a transfer of funds between financial institutions for a federal, state or labour judicial deposit, and for the judicial and extrajudicial deposits of Lei 9703/98 where the credited institution has pre-registered the depositor. The instruction is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (PAG0121R1) arrives asynchronously and is read back with getPAG0121. Every amount is a decimal STRING carried to the wire exactly as written. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Transfer funds for a judicial release
Source: https://docs.lerian.studio/en/reference/rails/siloc/transfer-funds-for-a-judicial-release

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/judicial-release-transfers
Issues a PAG0151 "IF requisita transferência de recursos para liberação de recursos judiciais" to the Câmara PAG (Catálogo de Serviços do SFN v5.13, Vol II). Requests a transfer of funds releasing judicial deposits, naming the court, the case number and the parties. The instruction is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (PAG0151R1) arrives asynchronously and is read back with getPAG0151. Every amount is a decimal STRING carried to the wire exactly as written. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Transfer funds for a payroll-loan credit
Source: https://docs.lerian.studio/en/reference/rails/siloc/transfer-funds-for-a-payroll-loan-credit

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/payroll-loan-credit-transfers
Issues a PAG0141 "IF requisita Transferência de recursos para crédito de consignação em IF detentora de relacionamento com aposentado" to the Câmara PAG (Catálogo de Serviços do SFN v5.13, Vol II). Requests a transfer of funds crediting a payroll loan where the pensioner receives the INSS benefit at another institution, by INSS card or account credit. It carries the benefit number, the loan contract, the INSS endorsement protocol and the fee the credited bank retains. The instruction is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (PAG0141R1) arrives asynchronously and is read back with getPAG0141. Every amount is a decimal STRING carried to the wire exactly as written. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Transfer funds on behalf of a non-account holder
Source: https://docs.lerian.studio/en/reference/rails/siloc/transfer-funds-on-behalf-of-a-non-account-holder

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/non-account-holder-transfers
Issues a PAG0107 "IF requisita Transferência de recursos por conta de não-correntistas" to the Câmara PAG (Catálogo de Serviços do SFN v5.13, Vol II). Requests a transfer of funds on behalf of a party that holds no account at this institution, for credit to a client or non-account-holder account at another one. The instruction is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (PAG0107R1) arrives asynchronously and is read back with getPAG0107. Every amount is a decimal STRING carried to the wire exactly as written. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Transfer funds out of a salary account
Source: https://docs.lerian.studio/en/reference/rails/siloc/transfer-funds-out-of-a-salary-account

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/salary-account-transfers
Issues a PAG0137 "IF requisita Transferência de recursos envolvendo conta-salário" to the Câmara PAG (Catálogo de Serviços do SFN v5.13, Vol II). Requests a transfer of funds debited from a conta-salário. The debited holder is identified by CPF, because a conta-salário belongs to a natural person. The instruction is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (PAG0137R1) arrives asynchronously and is read back with getPAG0137. Every amount is a decimal STRING carried to the wire exactly as written. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Transfer funds to settle a barcoded document
Source: https://docs.lerian.studio/en/reference/rails/siloc/transfer-funds-to-settle-a-barcoded-document

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/barcode-document-settlements
Issues a PAG0122 "IF requisita Transferência de recursos para liquidação de documentos com código de barras" to the Câmara PAG (Catálogo de Serviços do SFN v5.13, Vol II). Requests a transfer of funds to settle a document carrying a barcode, naming the drawee, the assignor, the payment channel and the amount breakdown the collection carried. The instruction is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (PAG0122R1) arrives asynchronously and is read back with getPAG0122. Every amount is a decimal STRING carried to the wire exactly as written. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Transfer funds from a client to an institution for a retail operation
Source: https://docs.lerian.studio/en/reference/rails/siloc/transfer-retail-client-to-institution

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/retail-client-to-institution-transfers
Issues a PAG0142 "IF requisita Transferência de recursos de cliente para IF por conta de operação de varejo" to the Câmara PAG (Catálogo de Serviços do SFN v5.13, Vol II). Requests a transfer of funds from a client to another financial institution on account of a retail operation. The instruction is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (PAG0142R1) arrives asynchronously and is read back with getPAG0142. Every amount is a decimal STRING carried to the wire exactly as written. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Transfer funds from an institution to a client for a retail operation
Source: https://docs.lerian.studio/en/reference/rails/siloc/transfer-retail-institution-to-client

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/retail-institution-to-client-transfers
Issues a PAG0143 "IF requisita Transferência de recursos de IF para cliente por conta de operação de varejo" to the Câmara PAG (Catálogo de Serviços do SFN v5.13, Vol II). Requests a transfer of funds to a client current account at another financial institution on account of a retail operation. The instruction is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (PAG0143R1) arrives asynchronously and is read back with getPAG0143. Every amount is a decimal STRING carried to the wire exactly as written. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Transfer funds for a client at a non-reserve-holding institution
Source: https://docs.lerian.studio/en/reference/rails/siloc/transfer-to-non-reserve-institution

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/non-reserve-institution-transfers
Issues a PAG0134 "IF requisita Transferência de recursos envolvendo conta de cliente em instituição não-detentora de conta Reservas Bancárias ou de liquidação" to the Câmara PAG (Catálogo de Serviços do SFN v5.13, Vol II). Requests a transfer of funds involving a client account at an institution that holds neither a Reservas Bancárias nor a settlement account, naming the investor the movement is on behalf of. The instruction is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (PAG0134R1) arrives asynchronously and is read back with getPAG0134. Every amount is a decimal STRING carried to the wire exactly as written. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Withdraw balance from the settlement account
Source: https://docs.lerian.studio/en/reference/rails/siloc/withdraw-balance-from-the-settlement-account

/en/openapi/v3-current/siloc.yaml post /api/v1/siloc/outbound/camara-withdrawals
Issues an LDL0032 "IF requisita saque parcial ou total na Câmara" to the Câmara LDL (Catálogo de Serviços do SFN v5.13, Vol II). It asks the câmara to return part or all of this institution's net balance from the Conta de Liquidação to its Reservas Bancárias or settlement account at the Bacen. TpDev chooses which amount: TOT (everything the participant may withdraw), LIM (at most VlrLimDev) or VAL (exactly VlrLimDev) — LIM and VAL require VlrLimDev, and a request carrying either without it is refused here rather than signed. The câmara determines the maximum it will return, so this rail neither computes nor bounds the amount. The request is minted, built, signed, encrypted and durably recorded BEFORE anything reaches the queue, so this returns 202 with the control number the câmara will echo; the answer (LDL0032R1) arrives asynchronously and is read back with getLDL0032. Every amount is a decimal STRING carried to the wire exactly as written. A deployment with no send leg configured answers 503 with SILOC-0023; one whose dispatcher is not running answers 503 with SILOC-0024.



# Revoke a credential (LOCAL-only soft-delete)
Source: https://docs.lerian.studio/en/reference/rails/sta/delete-credentials-id

/en/openapi/v3-current/sta.yaml delete /v1/credentials/{id}
Soft-deletes the credential by setting status=revoked. LOCAL only — BACEN is never contacted. The row is retained for audit but hidden from list/get; the freed institution code can be re-created. Emits credential.revoked via audit_outbox in one tx.



# Delete an inbound source config
Source: https://docs.lerian.studio/en/reference/rails/sta/delete-inbound-source-configs-id

/en/openapi/v3-current/sta.yaml delete /v1/inbound-source-configs/{id}
Soft-deletes the config, clearing its inbound-reserve contribution.



# List credentials
Source: https://docs.lerian.studio/en/reference/rails/sta/get-credentials

/en/openapi/v3-current/sta.yaml get /v1/credentials
Lists credentials for the authenticated tenant with page-based pagination. The encrypted password is never returned. Pagination defaults are clamped by the service.



# Read a credential
Source: https://docs.lerian.studio/en/reference/rails/sta/get-credentials-id

/en/openapi/v3-current/sta.yaml get /v1/credentials/{id}
Returns the credential metadata for the supplied id. The encrypted password is never returned. Emits credential.accessed via audit_outbox on every successful read.



# List inbound source configs
Source: https://docs.lerian.studio/en/reference/rails/sta/get-inbound-source-configs

/en/openapi/v3-current/sta.yaml get /v1/inbound-source-configs
Cursor-paginated listing for the authenticated tenant. The page size is clamped by the query service (default 20, max 100).



# Read an inbound source config
Source: https://docs.lerian.studio/en/reference/rails/sta/get-inbound-source-configs-id

/en/openapi/v3-current/sta.yaml get /v1/inbound-source-configs/{id}
Returns the inbound source config identified by {id} for the authenticated tenant.



# List transfers
Source: https://docs.lerian.studio/en/reference/rails/sta/get-transfers

/en/openapi/v3-current/sta.yaml get /v1/transfers
Lists transfers for the authenticated tenant with cursor-based pagination. Optional filters: state, direction, sourceProduct.



# Read a transfer
Source: https://docs.lerian.studio/en/reference/rails/sta/get-transfers-id

/en/openapi/v3-current/sta.yaml get /v1/transfers/{id}
Returns the transfer aggregate for the supplied id.



# Update a credential (LOCAL-only)
Source: https://docs.lerian.studio/en/reference/rails/sta/patch-credentials-id

/en/openapi/v3-current/sta.yaml patch /v1/credentials/{id}
Corrects operatorId and description only. A password change is NOT accepted here — use POST /v1/credentials/{id}/rotate. PATCH semantics: only present fields change. Emits credential.updated via audit_outbox in one tx.



# Update an inbound source config
Source: https://docs.lerian.studio/en/reference/rails/sta/patch-inbound-source-configs-id

/en/openapi/v3-current/sta.yaml patch /v1/inbound-source-configs/{id}
Partial update. Re-enabling a config, changing its intervalSeconds, or moving it to a different credential re-validates the configured inbound discovery reserve (422 on violation).



# Create a credential
Source: https://docs.lerian.studio/en/reference/rails/sta/post-credentials

/en/openapi/v3-current/sta.yaml post /v1/credentials
Provisions a new credential, encrypts the plaintext password with the current master key, and emits credential.created via audit_outbox in the same transaction.



# Rotate the password for a credential
Source: https://docs.lerian.studio/en/reference/rails/sta/post-credentials-id-rotate

/en/openapi/v3-current/sta.yaml post /v1/credentials/{id}/rotate
Accepts a client-chosen new password, encrypts it with the current master key, persists it as pending (Phase 0), calls BACEN's PUT /senhaws/senha on the senha-host (manual §9.1) (Phase 1), and promotes pending -> encrypted (Phase 2).



# Test BACEN STA connectivity for a credential
Source: https://docs.lerian.studio/en/reference/rails/sta/post-credentials-id-test

/en/openapi/v3-current/sta.yaml post /v1/credentials/{id}/test
Runs a BACEN STA connectivity probe for the credential and returns the outcome, latency, and diagnostic message.



# Create an inbound source config
Source: https://docs.lerian.studio/en/reference/rails/sta/post-inbound-source-configs

/en/openapi/v3-current/sta.yaml post /v1/inbound-source-configs
Provisions an inbound source config for the authenticated tenant. Every config is guarded against the configured inbound discovery reserve before persistence; a violation surfaces 422 POLLING_BUDGET_EXCEEDED.



# Trigger an inbound poll
Source: https://docs.lerian.studio/en/reference/rails/sta/post-inbound-source-configs-id-trigger-poll

/en/openapi/v3-current/sta.yaml post /v1/inbound-source-configs/{id}/trigger-poll
Dispatches a manual inbound poll for the inbound source config. Accepts an optional X-Idempotency header for 30s dedup; a within-window repeat replays the prior outcome without re-dispatching. Documented status is 202 Accepted; the runtime status is dynamic per outcome (200/409/503).



# Mark an inbound transfer for urgent processing
Source: https://docs.lerian.studio/en/reference/rails/sta/post-inbound-transfers-id-mark-urgent

/en/openapi/v3-current/sta.yaml post /v1/inbound/transfers/{id}/mark-urgent
Flags an inbound transfer that is AvailableForDownload for immediate download+processing instead of waiting for the next poll cycle.



# Create outbound transfer
Source: https://docs.lerian.studio/en/reference/rails/sta/post-transfers

/en/openapi/v3-current/sta.yaml post /v1/transfers
Creates a new outbound transfer. The worker streams the referenced object to BACEN STA asynchronously.



# Cancel a non-terminal transfer
Source: https://docs.lerian.studio/en/reference/rails/sta/post-transfers-id-cancel

/en/openapi/v3-current/sta.yaml post /v1/transfers/{id}/cancel
Flips the transfer to Canceled when its current state is in the cancelable set.



# Retry a stalled outbound transfer
Source: https://docs.lerian.studio/en/reference/rails/sta/post-transfers-id-retry

/en/openapi/v3-current/sta.yaml post /v1/transfers/{id}/retry
Re-enqueues a non-terminal outbound transfer subject to the attempt-budget and protocol-TTL guards.



# Archive mail
Source: https://docs.lerian.studio/en/reference/rails/bc-correios/archive-mail

/en/openapi/v3-current/bc-correios.yaml put /api/v1/correios/mails/{id}/archive
Moves a mail to the ARCHIVED folder. Local-only action; idempotent (returns 204).



# BC Correios error list
Source: https://docs.lerian.studio/en/reference/rails/bc-correios/bc-correios-error-list

Lerian BC Correios returns structured error responses. Look up each BC Correios error code, what it means, and the HTTP status it carries.

**Error format**

Lerian BC Correios operations return errors as RFC 9457 problem details with the `application/problem+json` media type:

```json JSON theme={null}
{
  "code": "BCC-0005",
  "correlationId": "req-7a3f9c2e",
  "detail": "Mail not found or access denied",
  "status": 404,
  "title": "Not Found",
  "type": "https://errors.lerian.studio/v1/BCC-0005"
}
```

**Field definitions**

* **`type`** – A URI that identifies the error in the Lerian error catalog, built as `https://errors.lerian.studio/v1/<code>`.
* **`title`** – The HTTP status text (for example, `Not Found`).
* **`status`** – The HTTP status code.
* **`detail`** – A human-readable explanation of this occurrence. For `5xx` responses, the detail reads `internal error`. Branch on `code` instead. The detail of `BCC-2009`, `BCC-2010`, and `BCC-2011` is in Portuguese.
* **`code`** – A stable identifier for the error. Branch on this field. The tables below list the `BCC-NNNN` codes and the named code `BANDWIDTH_LIMIT_EXCEEDED`. Two errors can share a status and still differ here. `BCC-0006` and `BCC-2010` both answer `409`. The `code` tells you which one you got.
* **`errors`** – Optional list of individual error details, each with a `location`, a `message`, and a `value`.
* **`correlationId`** – The request-scoped correlation identifier.

## Request errors

***

These errors apply to the request itself. They cover its fields, its headers, the resource it names, and the state of the service that received it.

| `code` | Description | Status |
| - | - | - |
| BCC-0001 | Invalid Input. A value in the request is not valid. A `POST`, `PUT`, or `PATCH` request with a `Content-Type` other than `application/json` answers `415`. An `X-Idempotency` key already used for a different request answers `422`. | 400, 415, 422 |
| BCC-0002 | Validation Failed. The request fails validation. A request-schema refusal answers `422`, and `errors` names the fields at fault. A field check answers `400`. A client-side refusal without a dedicated code also carries `BCC-0002`, with its own status. | 4xx |
| BCC-0003 | Invalid Cursor. The pagination cursor is not valid or has expired. | 400 |
| BCC-0005 | Not Found. The resource does not exist for the caller's tenant. On a send, the mail that `inReplyToMailId` names does not exist. | 404 |
| BCC-0006 | Settings Already Exist. The tenant already has settings. Update them instead of creating them again. | 409 |
| BCC-0007 | Rate Limit Exceeded. Too many requests arrived in the current window. Retry after the interval in the `Retry-After` header. | 429 |
| BCC-0008 | Internal Server Error. An unexpected failure. The `detail` reads `internal error`. | 500 |
| BCC-0009 | Service Unavailable. The service or a dependency it needs cannot complete the request. Try again later. | 503 |
| BCC-0010 | Checksum Mismatch. The stored attachment failed its integrity check on download. The `detail` reads `internal error`. | 500 |
| BCC-0012 | Duplicate Idempotency Key. A request with the same `X-Idempotency` key is still in process, and the response carries a `Retry-After` header. On a re-analysis, a key already used for a different mail answers `422`. | 409, 422 |
| BCC-0013 | Concurrent Modification. Another request changed the resource first. Read the current values and apply your change again. | 409 |
| BCC-0014 | Invalid State. The current state of the mail does not allow the action. A restore of a mail in the `CANCELLED` or `SENT` folder answers this code. | 409 |
| BANDWIDTH\_LIMIT\_EXCEEDED | The tenant used its attachment download budget for the current 60-second window. Retry after the interval in the `Retry-After` header. | 429 |

## Authentication errors

***

These errors apply to the token and to the permissions of the caller.

| `code` | Description | Status |
| - | - | - |
| BCC-1002 | Unauthorized. The request has no bearer token, or the service does not accept the token. | 401 |
| BCC-1003 | Forbidden. The caller does not have permission for this operation. In multi-tenant mode, a token without a tenant claim also answers this code. | 403 |

## BC Correio and send errors

***

These errors apply to messages that you send to BACEN through BC Correio.

| `code` | Description | Status |
| - | - | - |
| BCC-2001 | BCB Authentication Failed. The tenant has no settings or no stored BC Correio credentials, or the service cannot read them. Check the tenant settings. | 401 |
| BCC-2002 | BCB Service Unavailable. BC Correio refused the message, or the service did not send it. Send the message again with a new `X-Idempotency` key. | 503 |
| BCC-2009 | Transmission In Progress. Another send with the same `X-Idempotency` key is in progress. Wait a few seconds, then retry with the same key. | 409 |
| BCC-2010 | Transmission State Unknown. The service cannot tell whether BC Correio received the message. Do not send it again. Confirm non-delivery with BACEN through its manual channel before you use a new key. | 409 |
| BCC-2011 | Transmission Failed. An earlier send with the same key failed, and BC Correio does not hold the message. Send the message again with a new key. | 409 |
| BCC-4003 | Attachment Too Large For Transmission. The send request body is larger than 8 MB. | 413 |

## AI insight errors

***

These errors apply to a re-analysis of a mail by the AI provider that the tenant configured.

| `code` | Description | Status |
| - | - | - |
| BCC-3002 | AI Analysis Failed. The AI provider returned an error on a re-analysis. The `detail` reads `internal error`. | 502 |
| BCC-3004 | AI Not Configured. AI is not configured for the tenant. | 422 |
| BCC-3005 | AI No Content. The mail has no text to analyze. Its body is empty, and no text came from its attachments. | 422 |
| BCC-3006 | Attachment Extraction In Progress. The service is still extracting text from the attachments of the mail. Try again in a few seconds. | 409 |


# Count mails
Source: https://docs.lerian.studio/en/reference/rails/bc-correios/count-mails

/en/openapi/v3-current/bc-correios.yaml get /api/v1/correios/mails/count
Returns the total count of mails matching the given filters. May be cached for up to 60 seconds.



# Create tenant settings
Source: https://docs.lerian.studio/en/reference/rails/bc-correios/create-tenant-settings

/en/openapi/v3-current/bc-correios.yaml post /api/v1/correios/settings
Creates initial tenant settings. Returns 409 Conflict (BCC-0006) if settings already exist — use PATCH to update.



# Dashboard category breakdown
Source: https://docs.lerian.studio/en/reference/rails/bc-correios/dashboard-category-breakdown

/en/openapi/v3-current/bc-correios.yaml get /api/v1/correios/dashboard/categories
Returns per-category mail counts with a day or month timeline for the tenant.



# Dashboard summary
Source: https://docs.lerian.studio/en/reference/rails/bc-correios/dashboard-summary

/en/openapi/v3-current/bc-correios.yaml get /api/v1/correios/dashboard/summary
Returns aggregate metrics for the tenant: total received, unread, avg time to read, unread >3/7/15 days, and breakdown by sender. All counts are scoped to the given period (defaults to the last 30 days).



# Download attachment
Source: https://docs.lerian.studio/en/reference/rails/bc-correios/download-attachment

/en/openapi/v3-current/bc-correios.yaml get /api/v1/correios/mails/{id}/attachments/{attachmentId}
Streams an attachment file (application/octet-stream). Emits a DOWNLOAD_ATTACHMENT audit event.



# Export audit trail
Source: https://docs.lerian.studio/en/reference/rails/bc-correios/export-audit-trail

/en/openapi/v3-current/bc-correios.yaml get /api/v1/correios/audit/export
Generates an audit-trail report file for the given date range. The response is a file download (text/csv by default, or application/pdf when the Accept header requests it), not JSON.



# Get AI analysis status
Source: https://docs.lerian.studio/en/reference/rails/bc-correios/get-ai-analysis-status

/en/openapi/v3-current/bc-correios.yaml get /api/v1/correios/mails/{id}/ai-status
Returns the current AI analysis status, insight, and retry count for a mail.



# Get mail by ID
Source: https://docs.lerian.studio/en/reference/rails/bc-correios/get-mail-by-id

/en/openapi/v3-current/bc-correios.yaml get /api/v1/correios/mails/{id}
Retrieves the full content of a mail including body and attachment list. Emits a VIEW_MAIL audit event.



# Get tenant settings
Source: https://docs.lerian.studio/en/reference/rails/bc-correios/get-tenant-settings

/en/openapi/v3-current/bc-correios.yaml get /api/v1/correios/settings
Returns the current settings for the authenticated tenant. Sensitive credential fields are represented as boolean flags.



# List or search mails
Source: https://docs.lerian.studio/en/reference/rails/bc-correios/list-or-search-mails

/en/openapi/v3-current/bc-correios.yaml get /api/v1/correios/mails
Returns mails for a tenant. Pass 'folder' to browse a folder or 'query' to full-text search.



# Mark mail as read
Source: https://docs.lerian.studio/en/reference/rails/bc-correios/mark-mail-as-read

/en/openapi/v3-current/bc-correios.yaml put /api/v1/correios/mails/{id}/read
Idempotently marks a mail as read. If already read, returns 200 with current state.



# Query audit trail
Source: https://docs.lerian.studio/en/reference/rails/bc-correios/query-audit-trail

/en/openapi/v3-current/bc-correios.yaml get /api/v1/correios/audit
Returns paginated audit events for the tenant. Audit queries are not themselves logged.



# Restore mail
Source: https://docs.lerian.studio/en/reference/rails/bc-correios/restore-mail

/en/openapi/v3-current/bc-correios.yaml put /api/v1/correios/mails/{id}/restore
Moves a mail back to INBOX from ARCHIVED. Local-only; 409 BCC-0014 for CANCELLED or SENT mails.



# Send message to BCB
Source: https://docs.lerian.studio/en/reference/rails/bc-correios/send-message-to-bcb

/en/openapi/v3-current/bc-correios.yaml post /api/v1/correios/mails/send
Sends a message to BCB through BC Correio. Requires the X-Idempotency header for safe retries.



# Test AI provider connection
Source: https://docs.lerian.studio/en/reference/rails/bc-correios/test-ai-provider-connection

/en/openapi/v3-current/bc-correios.yaml post /api/v1/correios/settings/test-ai-connection
Issues a synchronous probe to the tenant's configured AI provider using the stored API key. 200 with status="ok" + latency on success; 200 with status="failed" + the redacted reason when the probe reaches the provider but is rejected. 400 when the provider is not configured, 404 when settings are absent, 500 on decrypt failure, 503 when AI is disabled.



# Test BCB connection
Source: https://docs.lerian.studio/en/reference/rails/bc-correios/test-bcb-connection

/en/openapi/v3-current/bc-correios.yaml post /api/v1/correios/settings/test-connection
Decrypts the stored BCB credentials and asks BC Correio for the authorized folders to verify connectivity. Returns the list of authorized folders on success.



# Trigger AI re-analysis
Source: https://docs.lerian.studio/en/reference/rails/bc-correios/trigger-ai-re-analysis

/en/openapi/v3-current/bc-correios.yaml post /api/v1/correios/mails/{id}/reanalyze
Executes a fresh AI analysis synchronously when the provider responds within 20s (200 with the insight); 202 pending when the provider exceeds the sync window. 422 BCC-3004 when the tenant has no AI configuration, 422 BCC-3005 when the mail has no content. Supports X-Idempotency for safe retries.



# Update retention policy
Source: https://docs.lerian.studio/en/reference/rails/bc-correios/update-retention-policy

/en/openapi/v3-current/bc-correios.yaml patch /api/v1/correios/settings/retention
Updates the mail retention period in days. Minimum 1825 (5 years), maximum 36500 (100 years).



# Update tenant settings
Source: https://docs.lerian.studio/en/reference/rails/bc-correios/update-tenant-settings

/en/openapi/v3-current/bc-correios.yaml patch /api/v1/correios/settings
Partially updates tenant settings. Only provided fields are updated; send an empty string to clear an encrypted credential field.



# Register a new originador
Source: https://docs.lerian.studio/en/reference/rails/consignado/create-consignado-originador

/en/openapi/v3-current/consignado.yaml post /v1/consignado/originadores
Registers a new originador under the tenant. The originador is a CHILD of this bancarizador, the same way a fund is: the same real originator registered under another tenant is a separate row.



# Deactivate an originador
Source: https://docs.lerian.studio/en/reference/rails/consignado/deactivate-consignado-originador

/en/openapi/v3-current/consignado.yaml delete /v1/consignado/originadores/{id}
Soft-disables the originador: it stops being allowed to act, but the row is never deleted, so what it already did stays legible. Idempotent: deactivating an already-deactivated originador succeeds.



# Fetch a worker's available consignable margin
Source: https://docs.lerian.studio/en/reference/rails/consignado/fetch-consignado-worker-margin

/en/openapi/v3-current/consignado.yaml post /v1/consignado/workers/margin
Opens or reuses the worker's authorization and reads available payroll margin — the rail's autorizar-consulta-dados-trabalhador (Manual 002 v1.15 §3.1) and consultar-dados-trabalhador (Manual 002 v1.15 §3.3) behind ONE operation, because the adapter performs them as one. POST, not GET: it opens a consent, and the consent evidence plus the CPF must travel in a body rather than in a path or query string. The worker's authorization token is NEVER returned. A consignado.margin.fetched fact is emitted on this path exactly as on the lender event path, so a client integrating by API keeps its other consumers fed.

CONSENT WINDOW (Manual 002 v1.15 §5.6). dataHoraAutorizacaoDigital starts two clocks, measured in calendar days from the worker's signature: the authorization may be CONSULTED for 30 days, and a request may be MADE against it for 45. Both boundaries are INCLUSIVE — the instant exactly 30 or 45 days after the signature is still inside its window, and only the next nanosecond is outside.

Outside either window the gateway refuses LOCALLY, before a byte reaches the rail: 422 with code CLT-0006 and a detail telling you to obtain a fresh worker authorization. THAT REFUSAL IS NOT RETRYABLE. Repeating the request performs the very read the lapsed authorization withdrew; only new authorization evidence makes it succeed. A dataHoraAutorizacaoDigital carrying a non-UTC offset, or dated ahead of the gateway's clock, is the same 422 with a different detail — correct the timestamp; the worker's consent is not in question.

Contrast the rail's OWN consent rejection (Dataprev EX/IV on a stale tokenAutorizacao): that is 503 and IS retryable, because the gateway drops the cached token and the next attempt opens a fresh consent from the same evidence.



# Get the Dataprev credential status
Source: https://docs.lerian.studio/en/reference/rails/consignado/get-credential-status

/en/openapi/v3-current/consignado.yaml get /v1/credentials/dataprev
Returns the non-secret status of the tenant's stored Dataprev credentials (cert presence + fingerprint + expiry, oauth presence) together with the two public values stored verbatim: the codigoSolicitante and the worker portal base URL. When nothing is stored it returns 200 with both presence flags false, NOT 404, and each verbatim value is absent rather than empty. NEVER returns secret material.



# List the credits this tenant bid on and where each bid stands
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-bid-submissions

/en/openapi/v3-current/consignado.yaml get /v1/consignado/bid-submissions
Walks the tenant's bid book, newest claim first: which credits this bancarizador claimed in the leilão, what the rail did with each bid, and whether a fund's cessão was ever registered against it.

'situation' is the row's own durable state, carried verbatim from the money path and never re-derived here. Five values: 'claimed' is the replay claim written before either proposal reached the rail; 'accepted' and 'refused' are the rail's answer; 'unknown' is an outcome that never arrived; and 'retry_in_flight' is a reconduction under way. Repeat 'situacao' to narrow the page to several at once (situacao=unknown&situacao=retry_in_flight). Omitting it means ALL FIVE, never none. A value outside the vocabulary is refused with 422 rather than matching nothing, because a page that matched nothing is indistinguishable from a tenant that never bid.

'payload_retained' is what separates a reconducible unknown from one with no way back. It is DERIVED on every read from whether the request payload is still stored, and the payload itself never leaves the database. An unresolved submission with the payload gone can no longer be replayed.

'retry_lease_expires_at' always carries an instant, including on a settled row where it is simply the last lease that was taken. An instant already in the PAST on a retry_in_flight row is a reconducible submission, and this read reports the book exactly as it stands: it never anticipates the reconduction the recovery sweep will perform.

'cedido', 'cedido_at' and 'fundo_ref' travel as one trio because the table's own pairing constraints keep the three mutually consistent, and half a cessão is not a state this ledger can hold. 'cedido' is actual OWNERSHIP and not mere attribution: 'fundo_ref' may name a fund on a credit nothing has ceded yet.

Filter with 'cedido=true' for the ceded half or 'cedido=false' for the credits no cessão was ever registered against. OMITTING the parameter is the whole book, and that is the default on purpose: an accepted credit nobody registered a cessão for is precisely the row this screen exists to surface, so it is never filtered out unasked.

'id_solicitacao' is null on a LOCAL REFUSAL recorded before the rail was ever reached, which is a real row of this book and not a missing value.

Four columns of the stored row never leave: the two proposal and response payloads, the refusal reason and the actor subject. The first three carry money terms and matrícula, and the last is a subject identity. The payload digest, the retry fence and the purge clocks stay behind with them, as the money path's own fence evidence.

Paging is keyset over the claim instant and the credit's business key, both frozen for the life of the row, which is what makes the position safe against a book the money path is still writing. Send the previous page's page.next_after as after. has_more is true exactly when another page exists, and next_after is null exactly when it is false, so a client loop may terminate on either. The cursor never expires; a cursor this service did not mint is refused with 422 rather than silently restarting the walk from the top.

It answers from a LOCAL table and never reaches the Dataprev rail, so it cannot answer 501 and it is served on a deployment with the rail off entirely. That deployment simply has an empty book. The tenant is derived from the validated identity and is never read from the request.



# Read the loans closed by employment-link termination
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-employment-terminations

/en/openapi/v3-current/consignado.yaml get /v1/consignado/employment-status/terminations
Reads one page of the rail's consultar-emprestimo-encerrado-termino-vinculo feed (Manual 006 v1.12 §2.1): the loans closed because the worker's employment link ended. Paginate with the opaque continuation token; omit it to start a fresh window. The read writes nothing — the poller's checkpoint advances only through its own compare-and-set persistence, so on-demand paging cannot make the job skip a page. When this deployment has no real termination-feed client plugged, the route answers 501 instead of returning fabricated records.



# List a worker's authorized employment bonds
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-fgts-autorizados

/en/openapi/v3-current/consignado.yaml post /v1/consignado/fgts/autorizados
Proxies listar-autorizados-trabalhador (Manual 002 §3.2): the worker's authorized employment bonds and, for an ineligible one, the rail's reason. POST, not GET, for the same reason as the balance read — the operation is consent-gated and the CPF belongs in the body. An empty vinculos list is the rail's answer, not an error, and is returned as 200.

CONSENT WINDOW (Manual 002 v1.15 §5.6). dataHoraAutorizacaoDigital starts two clocks, measured in calendar days from the worker's signature: the authorization may be CONSULTED for 30 days, and a request may be MADE against it for 45. Both boundaries are INCLUSIVE — the instant exactly 30 or 45 days after the signature is still inside its window, and only the next nanosecond is outside.

Outside either window the gateway refuses LOCALLY, before a byte reaches the rail: 422 with code CLT-0006 and a detail telling you to obtain a fresh worker authorization. THAT REFUSAL IS NOT RETRYABLE. Repeating the request performs the very read the lapsed authorization withdrew; only new authorization evidence makes it succeed. A dataHoraAutorizacaoDigital carrying a non-UTC offset, or dated ahead of the gateway's clock, is the same 422 with a different detail — correct the timestamp; the worker's consent is not in question.

Contrast the rail's OWN consent rejection (Dataprev EX/IV on a stale tokenAutorizacao): that is 503 and IS retryable, because the gateway drops the cached token and the next attempt opens a fresh consent from the same evidence.



# List the tenant's registered originadores
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-originadores

/en/openapi/v3-current/consignado.yaml get /v1/consignado/originadores
Returns every originador the tenant registered, active and deactivated alike. Tenant scope is derived from the validated identity; it is never taken from the request.



# Read one page of a portability's efetivação status
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-portabilidade-efetivacoes

/en/openapi/v3-current/consignado.yaml get /v1/consignado/portabilidade/efetivacoes
Reads one page of consultar-portabilidade-trabalhador (Manual 008 v1.10 §5.4), the proponent's published status view for a portability. classificadorSituacao is relayed without reinterpretation: 0 Aberto, 1 Encerrado por prazo, 2 Encerrado por averbação, or 3 Encerrado por alteração do Número Único. Code 1 means that the 20-calendar-day portability window has closed and the FGTS collateral blocks were removed.

codigoProponente is injected from the tenant's Dataprev credential and is never accepted from the caller. This read does not mutate gateway state.



# List the inbound portability requests open for the leilão
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-portabilidade-solicitacoes

/en/openapi/v3-current/consignado.yaml get /v1/consignado/leilao/portabilidade/solicitacoes
Reads one page of the rail's portability-auction listing (Manual 011 v1.6 §3.1.2/§3.1.3): the requests from another institution's client to port an existing payroll loan IN to this bancarizador, each carrying the worker's FREE consignable margin and the rail's own eligibility verdict.

The listing window is MANDATORY and carries no default. Both bounds are required by the rail, and "page N of the solicitações" has no defined answer until the window it pages over is named. Send the SAME window for every page of one walk: a window that slides between requests can let a solicitação cross a page boundary unread.

'data_hora_validade_solicitacao' is the AUTHORITATIVE clock of each row, not of the listing. It is the instant that specific auction closes, and a proposal submitted after it is refused by the rail. The 72 hours Manual 011 §2.1 publishes is only the rule that formed the instant, so never compute a deadline from the read time.

'elegivel_emprestimo' is the rail's own eligibility flag and is ABSENT when the rail published no verdict. Absence is a legal shape on this element, so it travels as absent rather than as a fabricated false.

'margem_disponivel' is the free margin the rail reports for this request, relayed as the decimal string it sent.

'descartadas' carries the elements the rail published on this page that could not be projected onto a solicitação: a malformed identity, or a worker CPF in a shape no padding repairs. It holds no worker data, only the rail identifier and nothing else. It is published rather than dropped because an inbound auction nobody was told about must not look identical to an auction that does not exist.

A window holding no open request answers an EMPTY page and not an error: the rail reports that condition as a refusal, and for a listing "nothing is open" is the answer, not a fault.

This is a window onto the RAIL and writes nothing. It does not advance the portability discovery job's state, so it can return a solicitação the job has already relayed as an offer, and reading it never suppresses one the job still owes. Use the event feed for what the gateway itself has processed. The tenant is derived from the validated identity and is never read from the request.



# List the worker loan requests open for the leilão
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-solicitacoes

/en/openapi/v3-current/consignado.yaml get /v1/consignado/leilao/solicitacoes
Reads one page of the rail's solicitações-trabalhador-paginado listing (Manual 001 v1.9 §3.2.1/§3.2.2): the worker loan requests open for a 24h leilão, each carrying the FREE consignable margin. The inclusion window is MANDATORY — the rail refuses a listing read without one — and the page is served over exactly that window. This is a window onto the RAIL and writes nothing: it does not advance the discovery job's state, so it can return a solicitação the job has already processed. Use the event feed for what the gateway itself has processed.



# Read workers with a new employment bond after a termination-closed contract
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-vinculos-novos

/en/openapi/v3-current/consignado.yaml get /v1/consignado/trabalhadores/vinculos-novos
Reads the rail's consultar-vinculos-novos-trabalhador (Manual 006 v1.12 §2.2): the support read for the §2.3 renegociação, listing workers who now hold a new employment bond after a contract closed by employment-link termination. The window is mandatory and capped at 30 days by the rail (code GR); this gateway refuses a wider window locally.



# Upload or rotate the Dataprev client certificate
Source: https://docs.lerian.studio/en/reference/rails/consignado/put-certificate

/en/openapi/v3-current/consignado.yaml put /v1/credentials/dataprev/certificate
Stores (or rotates) the tenant's ICP-Brasil A1 client certificate (PEM cert+key) for the Dataprev rail in the tenant secret store and upserts non-secret metadata. The certificate is validated before storage. The response NEVER carries secret material.



# Set the tenant's Dataprev codigoSolicitante
Source: https://docs.lerian.studio/en/reference/rails/consignado/put-codigo-solicitante

/en/openapi/v3-current/consignado.yaml put /v1/credentials/dataprev/codigo-solicitante
Stores (or corrects) the tenant's Dataprev codigoSolicitante — the institution's BACEN COMPE code, a 3-digit number (Numero 3 algarismos) in the range 001-999, required (Obrigatorio Sim) on nearly every rail operation. A COMPE code of 55 is published as 055; 000 is refused. It is PUBLIC, non-secret metadata held in Postgres beside the credential metadata; it is never written to the tenant secret store.



# Upload or rotate the Dataprev OAuth2 credentials
Source: https://docs.lerian.studio/en/reference/rails/consignado/put-oauth

/en/openapi/v3-current/consignado.yaml put /v1/credentials/dataprev/oauth
Stores (or rotates) the tenant's OAuth2 client_credentials secret for the Dataprev token endpoint in the tenant secret store and flips the oauth-present flag. The response NEVER echoes the client secret.



# Set the tenant worker portal base URL
Source: https://docs.lerian.studio/en/reference/rails/consignado/put-portal-base-url

/en/openapi/v3-current/consignado.yaml put /v1/credentials/dataprev/portal-base-url
Stores or updates the authenticated tenant's worker portal base URL. The URL must use HTTPS, contain no credentials or fragment, and be at most 255 characters. The response returns the stored configuration. Registering a portal is optional. When the tenant has one, the gateway injects it as the type 0 contact of every bid proposal that carries no portalBaseUrl of its own and names no originador with a registered portal. When no portal resolves for a bid, the bid travels with the client's own contacts alone and must carry at least one contact of type 1 through 4.



# Read a worker's consignable FGTS balance
Source: https://docs.lerian.studio/en/reference/rails/consignado/read-consignado-fgts-saldo

/en/openapi/v3-current/consignado.yaml post /v1/consignado/fgts/saldo
Proxies consultar-saldo-fgts (Manual 002 §3.4): the worker's consignable FGTS balance and rescission-penalty portion, the SOURCE of the collateral values an averbação or an auction bid carries. POST, not GET, because the read is consent-gated: the worker's grupo-1 authorization evidence is a nested object and the CPF must never appear in a path or query string. The consent token the gateway mints or reuses is never returned. Money is a decimal string, never a float.

CONSENT WINDOW (Manual 002 v1.15 §5.6). dataHoraAutorizacaoDigital starts two clocks, measured in calendar days from the worker's signature: the authorization may be CONSULTED for 30 days, and a request may be MADE against it for 45. Both boundaries are INCLUSIVE — the instant exactly 30 or 45 days after the signature is still inside its window, and only the next nanosecond is outside.

Outside either window the gateway refuses LOCALLY, before a byte reaches the rail: 422 with code CLT-0006 and a detail telling you to obtain a fresh worker authorization. THAT REFUSAL IS NOT RETRYABLE. Repeating the request performs the very read the lapsed authorization withdrew; only new authorization evidence makes it succeed. A dataHoraAutorizacaoDigital carrying a non-UTC offset, or dated ahead of the gateway's clock, is the same 422 with a different detail — correct the timestamp; the worker's consent is not in question.

Contrast the rail's OWN consent rejection (Dataprev EX/IV on a stale tokenAutorizacao): that is 503 and IS retryable, because the gateway drops the cached token and the next attempt opens a fresh consent from the same evidence.



# Respond to an inbound portability leilão solicitação
Source: https://docs.lerian.studio/en/reference/rails/consignado/respond-consignado-portability-auction

/en/openapi/v3-current/consignado.yaml post /v1/consignado/leilao/portabilidade/solicitacoes/{id_solicitacao_proposta}/propostas
Submits one proposal through inclusao-garantias (Manual 011 v1.6 §3.2) in response to a portability auction request that the client received on a consignado.portability_proposal.received fact. Unlike the M001 bid operation, this endpoint accepts one proposal per call: a request that permits a second proposal, with or without FGTS collateral, requires two separate calls rather than an array.

dataHoraValidadeSolicitacao is the same field that the initiating fact carried. It is response-side data from Manual 011 §3.1.3 and is not sent to Dataprev in this request. The client echoes it so the gateway can reject a response to an expired record before calling the rail. Expiration is evaluated per record without consulting a calendar.

Manual 011 uses two spellings for this operation's path: §2.2 omits an accent, while §3.2.3.1 includes one. Because M011 publishes no Swagger path to resolve the discrepancy, the configured path spelling must be validated during homologation. The request and response otherwise follow Manual 011 §3.2.1 and §3.2.2.

X-Idempotency is the mandatory transport replay key. A retry with the same key returns the stored response instead of resubmitting to the rail, as on the averbação and CCB attachment routes. This endpoint does not have durable PostgreSQL-backed replay storage, so the guarantee does not survive a Redis eviction or service restart.



# Revoke the Dataprev credentials
Source: https://docs.lerian.studio/en/reference/rails/consignado/revoke-credentials

/en/openapi/v3-current/consignado.yaml delete /v1/credentials/dataprev
Durably revokes the tenant's Dataprev certificate and OAuth credentials. Subsequent rail calls fail closed and never use static fallback credentials.



# Submit a one-or-two proposal set to the payroll rail
Source: https://docs.lerian.studio/en/reference/rails/consignado/submit-consignado-bid

/en/openapi/v3-current/consignado.yaml post /v1/consignado/leilao/solicitacoes/{id_solicitacao}/propostas
Submits the complete one-or-two proposal set through inclusao-garantias (Manual 001 v1.9 §3.1) synchronously. X-Idempotency is mandatory and durable.

| Case | Result | Rail call |
|---|---|---|
| Same key + same body, known outcome | 200 replay of the stored response | No |
| Same key + different body | 422 unprocessable entity | No |
| New key + same solicitação | 409 conflict | No |
| Unknown-outcome retry | Retry the unresolved submission with the same proposal IDs | May call the rail with the same proposal IDs |



# Create institution config and provision keys
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/executor/create-institution-config-and-provision-keys

/en/openapi/v3-current/sisbajud-executor.yaml post /v1/institutions
Creates a new institution configuration (create-only; 409 if one already exists for the id) and provisions its tokenization PRF + audit MAC keysets in the same flow. The institution id is supplied in the request body. Invalid input is refused with 400 SBJ-0001, including an empty or malformed institutionCode and a branchFormat/accountFormat that does not compile or is longer than 64 characters.



# Get institution config by id
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/executor/get-institution-config-by-id

/en/openapi/v3-current/sisbajud-executor.yaml get /v1/institutions/{institutionId}
Returns the institution's configuration as a safe metadata view (the credentials reference and any other secret material are omitted). The institution is addressed by the path id.



# List executor failed orders
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/executor/list-executor-failed-orders

/en/openapi/v3-current/sisbajud-executor.yaml get /v1/institutions/{institutionId}/executor/failed-orders
Returns the institution-scoped paginated list of order revisions the executor failed or abandoned, read from its execution journal. Each item names the journal row it was derived from and a closed-set reason; uncertain revisions are not listed.



# List executor human decisions
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/executor/list-executor-human-decisions

/en/openapi/v3-current/sisbajud-executor.yaml get /v1/institutions/{institutionId}/executor/human-decisions
Returns the institution-scoped paginated list of order revisions the executor stopped on a human decision, read from its execution journal. GAVE_UP items attempted no ledger write and carry the executionId and executionVersion of the given-up answer; HELD_MONEY_MOVED items attempted a write and carry neither. Another institution gets an empty page.



# Preflight the tenant's ledger routing configuration (admin)
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/executor/preflight-the-tenant-s-ledger-routing-configuration-admin

/en/openapi/v3-current/sisbajud-executor.yaml get /v1/admin/ledger-routing/preflight
Checks the caller tenant's ledger routing documents against the institution's ledger. For every organization with accounting routes enabled (routing.organizations): transaction and operation routes exist, the legs are members of the transaction route, their operation types, direct entries and account rules match, a ledger that validates account types has the block account type registered, and each flow of every configured ledger has a binding. An organization without routes is checked the same way, so it can be fixed before routes are turned on, but its lines are not_applicable unless its writes are refused without routes too (organization_routes_disabled). Every TRANSFER, with or without routes, needs a judicial deposit account: transfer.judicial_accounts for the legacy executor; in executor mode (the plugin) the institution's connector_metadata.executorLedger.judicialDepositAccountAlias, whose account must exist, unblocked, in the executor ledger. The executor-mode report reflects the STORED executorLedger; the running plugin keeps the one it loaded at boot until it restarts. The report never carries an account alias. The route is read-only: it never writes a document nor the ledger. Single-tenant (MULTI_TENANT_ENABLED=false) the institution is the required institutionId query parameter, with auth on or off, and the documents are the instance's single-tenant ones. Multi-tenant the tenant and institution are the validated token's tenantId, never the request; an institutionId that differs from it is refused with 403. Requires tenant_policy:read.



# Replace the institution's connector configuration
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/executor/replace-the-institution-s-connector-configuration

/en/openapi/v3-current/sisbajud-executor.yaml put /v1/institutions/{institutionId}/connector-config
Replaces the connector type and the non-secret connector configuration of an existing institution. The stored sealed credentials are preserved untouched; a body carrying credential material is refused with 400 before any write (credentials are written only by PUT /v1/institutions/{institutionId}/connector-credentials). The connector cache is invalidated on success. Returns 404 when the institution has no configuration.



# Rotate an institution's connector-credentials KEK
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/executor/rotate-an-institution-s-connector-credentials-kek

/en/openapi/v3-current/sisbajud-executor.yaml post /v1/institutions/{institutionId}/security/credential-kek:rotate
Rotates the key that wraps this institution's stored connector credentials — a DIFFERENT key from the institution-data KEK governing PII, whose rotation is owned by the Lerian SISBAJUD Mensageria. The Transit key advances and the stored credentials envelope is rebound to the new version; no credential is decrypted and no credential VALUE changes, so a leaked client_secret is NOT invalidated by this call (rotate the material itself with PUT /v1/institutions/{institutionId}/connector-credentials, and revoke it upstream). rewrapStatus reports whether the stored envelope was rebound or the row carried no sealed subtree to rebind. An institution that has never stored a connector credential has no credentials KEK and maps to 404, not to a rotation. A contended same-institution rotation maps to 409, and so does a concurrent change to this institution's connector configuration (the KEK version has already advanced; retry to rebind the envelope). An unknown institution maps to 404. A committed-but-unaudited rotation maps to 500 (non-retryable; escalate).



# Update institution config by id
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/executor/update-institution-config-by-id

/en/openapi/v3-current/sisbajud-executor.yaml patch /v1/institutions/{institutionId}
Applies a partial update (connectorType/institutionCode/retryPolicyConfig/connectorMetadata/branchFormat/accountFormat/enabled) to an existing institution configuration addressed by the path id. connectorMetadata, when present, replaces the entire bag wholesale. Invalid input is refused with 400 SBJ-0001, including a branchFormat/accountFormat that does not compile or is longer than 64 characters, and a merged configuration left without a valid institutionCode. Returns 404 when the institution has no configuration.



# Verify audit trail integrity (admin)
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/executor/verify-audit-trail-integrity-admin

/en/openapi/v3-current/sisbajud-executor.yaml get /v1/admin/audit/verify
Re-verifies a contiguous slice of the caller institution's append-only audit log by leaf index, without decrypting any payload. Returns a tamper / internal-deletion report. The institution is derived from the validated identity, never from the body or path.



# Write the institution's connector credentials
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/executor/write-the-institution-s-connector-credentials

/en/openapi/v3-current/sisbajud-executor.yaml put /v1/institutions/{institutionId}/connector-credentials
Writes (or rotates) the connector credentials of an existing institution: the credentials subtree of connector_metadata is replaced, sealed under a fresh data key, audited as a credential rotation, and never echoed; every other metadata key is kept as stored. This is the ONLY credential write path: PATCH /v1/institutions/{institutionId} refuses a credentials subtree with 400. Returns 404 when the institution has no configuration.



# Create an LGPD data-subject request
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/mensageria/create-an-lgpd-data-subject-request

/en/openapi/v3-current/sisbajud-mensageria.yaml post /v1/institutions/{institutionId}/lgpd/requests
Creates an LGPD access or portability request scoped to the path institution. The acting admin subject is derived from the validated identity; the CPF/CNPJ is tokenized server-side and never echoed. An institution with no tokenization keyset maps to 404.



# Create institution config and provision keys
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/mensageria/create-institution-config-and-provision-keys

/en/openapi/v3-current/sisbajud-mensageria.yaml post /v1/institutions
Creates a new institution configuration (create-only; 409 if one already exists for the id) and provisions its tokenization PRF + audit MAC keysets in the same flow. The institution id is supplied in the request body.



# Export a data subject's records
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/mensageria/export-a-data-subject-s-records

/en/openapi/v3-current/sisbajud-mensageria.yaml get /v1/institutions/{institutionId}/lgpd/subject-data
Tokenizes the query subject value across all active key versions, reunites the institution-scoped orders, decrypts each in full, and returns the subject export. The response body is the only place the decrypted subject data surfaces.



# Force a return-file generation
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/mensageria/force-a-return-file-generation

/en/openapi/v3-current/sisbajud-mensageria.yaml post /v1/institutions/{institutionId}/return-file/generate
Forces one return-file generation for the institution in the path and returns the generated file's summary. A malformed institutionId is 400; a caller without the role is 403; an institution not configured with an institution_code is 422; a missing reception flow fails closed with 503.



# Get file detail (admin)
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/mensageria/get-file-detail-admin

/en/openapi/v3-current/sisbajud-mensageria.yaml get /v1/institutions/{institutionId}/files/{id}
Returns the single-file metadata plus the decrypted file content (base64-encoded), elided per the request masking policy unless the caller is cleared for cleartext. Covers both remittance and return files.



# Get institution config by id
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/mensageria/get-institution-config-by-id

/en/openapi/v3-current/sisbajud-mensageria.yaml get /v1/institutions/{institutionId}
Returns the institution's configuration as a safe metadata view. The institution is addressed by the path id.



# Get order detail (admin)
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/mensageria/get-order-detail-admin

/en/openapi/v3-current/sisbajud-mensageria.yaml get /v1/institutions/{institutionId}/orders/{id}
Returns the fully decrypted single-order detail with sensitive fields masked per the request masking policy. A cleartext-authorized read reveals the fields and records the access in the audit trail.



# Get processing stats (admin)
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/mensageria/get-processing-stats-admin

/en/openapi/v3-current/sisbajud-mensageria.yaml get /v1/institutions/{institutionId}/stats
Returns the institution-scoped processing statistics: total order count plus breakdowns by status and tipo_ordem, optionally constrained to a created_at window.



# Get SLA status (admin)
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/mensageria/get-sla-status-admin

/en/openapi/v3-current/sisbajud-mensageria.yaml get /v1/institutions/{institutionId}/sla-status
Returns the institution-scoped SLA-risk view of active (non-terminal) orders: per-band counts plus per-order detail. No PII, no decryption.



# List failed orders (admin)
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/mensageria/list-failed-orders-admin

/en/openapi/v3-current/sisbajud-mensageria.yaml get /v1/institutions/{institutionId}/failed-orders
Returns the institution-scoped paginated list of orders in the FAILED terminal state, plus orders with an open executor give-up non-compliance log (e.g. a reiteration whose original gave up), each with its own SLA deadline and non-sensitive summary fields.



# List files (admin)
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/mensageria/list-files-admin

/en/openapi/v3-current/sisbajud-mensageria.yaml get /v1/institutions/{institutionId}/files
Returns the institution-scoped paginated list of remittance or return file metadata. No file content or encrypted bytes are exposed.



# List orders (admin)
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/mensageria/list-orders-admin

/en/openapi/v3-current/sisbajud-mensageria.yaml get /v1/institutions/{institutionId}/orders
Returns the institution-scoped paginated list of judicial orders with non-sensitive summary fields. The institution is addressed by the path id; filters (status, tipo_ordem, period, subject) are optional.



# List orders awaiting a human decision (admin)
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/mensageria/list-orders-awaiting-a-human-decision-admin

/en/openapi/v3-current/sisbajud-mensageria.yaml get /v1/institutions/{institutionId}/awaiting-decision-orders
Returns the institution-scoped paginated list of orders the return generator holds for a human decision and that are not resolved yet (no human decision recorded, never answered in a return file), with non-sensitive summary fields. An order leaves the list once decided or answered.



# Record the human treatment of a parked STA event
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/mensageria/record-the-human-treatment-of-a-parked-sta-event

/en/openapi/v3-current/sisbajud-mensageria.yaml post /v1/institutions/{institutionId}/sta-dlq/{eventId}/acknowledge
Writes the audit record that answers the three-day dead-letter window: which parked record, from which direction, under which parking token, and what the operator did about it (replayed, recorded, escalated). It does NOT remove anything: the dead-letter destination is the Kafka topic lerian.streaming.br-sisbajud.dlq, a LOG with its own retention, so a treated record stays exactly where it is and this acknowledgement — not the record's absence — is what says it was handled. Replaying means seeking the consumer group back to the source offset the record's headers name. Answers with a receipt id for the ticket. 422 when the parking token is not one the consumer emits, when the action is unknown, or when institutionId or eventId are missing — the refusal carries a code and a canned detail, so the valid tokens are published as this request's reason enum rather than named in the answer.



# Record the resolution of an LGPD request
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/mensageria/record-the-resolution-of-an-lgpd-request

/en/openapi/v3-current/sisbajud-mensageria.yaml post /v1/institutions/{institutionId}/lgpd/requests/{id}/resolve
Records the decision (fulfilled, refused, partial) for an existing LGPD request. A not-found request maps to 404; an already-resolved (terminal) request maps to 409.



# Register a justification on a non-compliance log
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/mensageria/register-a-justification-on-a-non-compliance-log

/en/openapi/v3-current/sisbajud-mensageria.yaml post /v1/institutions/{institutionId}/non-compliance-logs/{id}/justification
Registers an institution's justification on an SLA-breach non-compliance log. An empty or oversized justification maps to 400; an absent record to 404; an already-justified record to 409. The audit actor is derived from the validated identity (403 when absent).



# Release a failed return file's judicial orders
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/mensageria/release-a-failed-return-file-s-judicial-orders

/en/openapi/v3-current/sisbajud-mensageria.yaml post /v1/institutions/{institutionId}/return-file/{id}/reconsolidate
Releases the judicial orders held by a FAILED return file so a later generation can answer them. The file STAYS FAILED — it is the record that an attempt was made and did not arrive. Answers with how many orders were released and, when the file answers a remittance, the response deadline that the Mensageria computed. Refused with 409 while the Lerian STA transfer may still be live (a size mismatch whose cancel did not succeed): releasing then would put the same judicial answers in front of BACEN twice. 422 when the file is not FAILED or records no Lerian STA terminal; 404 when it does not exist.



# Resolve a stuck return-file transmission
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/mensageria/resolve-a-stuck-return-file-transmission

/en/openapi/v3-current/sisbajud-mensageria.yaml post /v1/institutions/{institutionId}/return-file/{id}/resolve-transmission
Applies one human remedy to a submission no automatic path can finish. probe_now asks Lerian STA whether a transfer for this file already exists and binds it if so; attach_transfer binds a transfer you located, but ONLY after Lerian STA confirms it belongs to this file; force_fail gives up on a stuck submission so the file becomes reconsolidable; cancel_now retries cancelling a size-mismatched transfer that is still live at Lerian STA. reason is required and MUST NOT contain personal data or monetary values — it is written verbatim into the audit trail. 422 names the door that IS open when the action does not apply to the file's state.



# Rotate an institution's KEK
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/mensageria/rotate-an-institution-s-kek

/en/openapi/v3-current/sisbajud-mensageria.yaml post /v1/institutions/{institutionId}/security/kek:rotate
Triggers a manual key-encryption-key rotation for the addressed institution. The KEK advances and the registry mirror syncs. A contended same-institution rotation maps to 409; a committed-but-unaudited rotation maps to 500 (non-retryable; escalate).



# Rotate an institution's tokenization keyset
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/mensageria/rotate-an-institution-s-tokenization-keyset

/en/openapi/v3-current/sisbajud-mensageria.yaml post /v1/institutions/{institutionId}/security/keyset:rotate
Triggers a manual tokenization-keyset rotation (adds a fresh primary PRF key) for the addressed institution. A contended same-institution rotation or a stale-version optimistic-concurrency conflict maps to 409; an institution with no active keyset maps to 422; a committed-but-unaudited rotation maps to 500 (non-retryable; escalate).



# Update institution config by id
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/mensageria/update-institution-config-by-id

/en/openapi/v3-current/sisbajud-mensageria.yaml patch /v1/institutions/{institutionId}
Applies a partial update (institutionCode/retryPolicyConfig/enabled) to an existing institution configuration addressed by the path id. Returns 404 when the institution has no configuration.



# Verify audit trail integrity (admin)
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/mensageria/verify-audit-trail-integrity-admin

/en/openapi/v3-current/sisbajud-mensageria.yaml get /v1/institutions/{institutionId}/audit/verify
Re-verifies a contiguous slice of the institution's append-only audit log by leaf index, without decrypting any payload. Returns a tamper / internal-deletion report. The institution comes from the path; a malformed institutionId is 400 and a caller without the role is 403.



# SISBAJUD error list
Source: https://docs.lerian.studio/en/reference/rails/sisbajud/sisbajud-error-list

Look up a Lerian SISBAJUD error code, the HTTP status it carries, and the action that resolves it. One list serves the Mensageria and the executor.

**Error format**

The Lerian SISBAJUD Mensageria and the Lerian SISBAJUD executor use the same error codes, `SBJ-0001` to `SBJ-0011`, with the same HTTP statuses. A license refusal answers 403 with an `LCS-` code. An operation error uses RFC 9457 problem details with the `application/problem+json` media type:

```json JSON theme={null}
{
  "type": "https://errors.lerian.studio/v1/SBJ-0001",
  "title": "Bad Request",
  "status": 400,
  "detail": "institutionId path parameter must be a valid non-nil UUID.",
  "code": "SBJ-0001"
}
```

**Field definitions**

* **`code`** – A stable identifier for the error, in the form `SBJ-NNNN`. Branch on this value.
* **`type`** – A URI that identifies the error in the Lerian error catalog. Built as `https://errors.lerian.studio/v1/<code>`.
* **`title`** – The HTTP status text (for example, `Bad Request`).
* **`status`** – The HTTP status code.
* **`detail`** – Guidance for this occurrence of the error. For `5xx` responses, the detail carries the static text `internal error`, so use `code` to branch.
* **`errors`** – Optional list of per-field validation details, each with a `message` and a `location`.

Some refusals happen before the request reaches an operation, for example an unsupported method or a rate limit. They answer the same `code` and `title` in a plain JSON body.

The execution API, which the executor calls on the Mensageria, is different: its `409` and `422` responses use a problem body without an `SBJ-` code.

## Client errors

***

| `code` | Description | Status |
| - | - | - |
| SBJ-0001 | The request has malformed syntax. Check the path identifiers, the timestamp format, and the field lengths. | 400 |
| SBJ-0003 | Authentication failed. Send a valid bearer token. | 401 |
| SBJ-0004 | The caller identity lacks permission for this resource. | 403 |
| SBJ-0005 | The resource does not exist. Check the identifier in the path. | 404 |
| SBJ-0007 | The request conflicts with the current state of the resource, such as a duplicate create or a request that already reached a terminal state. | 409 |
| SBJ-0010 | The request payload, or the file content the request asked for, is above the accepted size. | 413 |
| SBJ-0006 | The syntax is correct, but the service cannot process the request. A value falls outside the accepted set, or the resource is in the wrong state for the operation. | 422 |
| SBJ-0009 | The caller sent too many requests in the current window. Wait for the number of seconds in the `Retry-After` header, then send the request again. | 429 |
| SBJ-0011 | A client error outside the codes above, such as an unsupported HTTP method. The response keeps its original status, so read the HTTP status of the response. | Other `4xx` |

## Server errors

***

| `code` | Description | Status |
| - | - | - |
| SBJ-0002 | The service failed unexpectedly. A server error with no other code also answers `SBJ-0002`. Send the request again, and contact support if the failure continues. For a key rotation, read [Credentials and key rotation](/en/rails/sisbajud/sisbajud-operations#credentials-and-key-rotation) before you send it again. | 500 |
| SBJ-0008 | A dependency this endpoint needs is unavailable. Contact your platform team if the failure continues. | 503 |


# Acknowledge an invalid-dispatch case
Source: https://docs.lerian.studio/en/reference/rails/src/acknowledge-an-invalid-dispatch-case

/en/openapi/v3-current/src.yaml post /v1/src/operator/invalid-dispatches/{caseId}/closure
Acknowledges an open `invalid_outbound` operator case. Lerian SRC opens this case when it refuses to send a message that does not conform to BACEN's specification, and the consultation fails with code `SRC-OUTBOUND-INVALID`. Acknowledging the case repairs nothing and sends nothing. To consult again, create a new consultation.

The request carries a `reason`. Closing appends an `operator_case_closure` record to the evidence trail. A case that is not open returns `404` with code `SRC-0301`.



# Close a credential-operation case
Source: https://docs.lerian.studio/en/reference/rails/src/close-a-credential-operation-case

/en/openapi/v3-current/src.yaml post /v1/src/operator/credential-operations/{caseId}/closure
Closes an open `credential_operation` operator case. The request carries a `reason`. Closing records the closure on the case and appends an `operator_case_closure` record to the evidence trail. It does not change the credential operation.

A case that is not open returns `404` with code `SRC-0301`.



# Close an orphan-response case
Source: https://docs.lerian.studio/en/reference/rails/src/close-an-orphan-response-case

/en/openapi/v3-current/src.yaml post /v1/src/operator/orphan-responses/{caseId}/closure
Closes an open `orphan_response` operator case: an inbound message that matched no operation of this deployment. The request carries a `reason`. Closing records the closure on the case and appends an `operator_case_closure` record to the evidence trail.

A case that is not open returns `404` with code `SRC-0301`.



# Correct an evidence record
Source: https://docs.lerian.studio/en/reference/rails/src/correct-an-evidence-record

/en/openapi/v3-current/src.yaml post /v1/src/evidence/consultations/{id}/corrections
Appends a correction record to the evidence trail of a consultation. The correction points to the corrected record through `correctsSequence`, and the corrected record stays in the trail unchanged. The response returns the position of the new record.

A `409` with code `SRC-0104` means that a concurrent correction took the position. Nothing was written, and you can retry. This operation is not idempotent: a repeated request appends a second correction.



# Create a consultation
Source: https://docs.lerian.studio/en/reference/rails/src/create-a-consultation

/en/openapi/v3-current/src.yaml post /v1/src/consultations
Accepts a restriction consultation for one CPF or CNPJ and returns `202` with the consultation id. The consultation starts as `pending`, which is a normal state. Read the outcome with `GET /v1/src/consultations/{id}` or from the events.

Lerian SRC validates the request before it accepts it, and a refused request sends nothing to BACEN. `X-Idempotency` is required. [Idempotency](/en/rails/src/src-integration#idempotency) describes the replay rules and how long Lerian SRC keeps a key.



# List consultations
Source: https://docs.lerian.studio/en/reference/rails/src/list-consultations

/en/openapi/v3-current/src.yaml get /v1/src/consultations
Lists the consultations of this deployment, newest first, one page at a time. You can filter by `status`, `type`, `companyConsultationId`, `subjectRole`, `restrictionActive`, `from` and `to`. Use `companyConsultationId` to list the holder and representative consultations that link to a company consultation. To filter by document, use `POST /v1/src/consultations/search`.

For an exact page sequence, set `to` a few seconds in the past before you read the first page.



# List operator cases
Source: https://docs.lerian.studio/en/reference/rails/src/list-operator-cases

/en/openapi/v3-current/src.yaml get /v1/src/operator/cases
Lists operator cases, newest first, one page at a time. Without `status`, it lists the open cases. `status=closed` lists the closed cases, and `status=all` lists both. You can filter by `leg`: `budget_exhausted`, `orphan_response`, `invalid_outbound` or `credential_operation`.

No operation closes a `budget_exhausted` case.



# Register an institution record
Source: https://docs.lerian.studio/en/reference/rails/src/register-an-institution-record

/en/openapi/v3-current/src.yaml post /v1/src/consultations/{id}/institution-record
Registers the institution's record for a consultation that completed with an active restriction. Send `kind: exceptional_proceed` with a justification and a circumstance when the institution proceeds despite the restriction. Send `kind: refusal_explanation` with the explanation that the institution gave when it refused.

A consultation holds one record, and a second request returns `409` with code `SRC-0101`. A consultation that did not complete with an active restriction returns `409` with code `SRC-0102`.



# Retrieve a consultation
Source: https://docs.lerian.studio/en/reference/rails/src/retrieve-a-consultation

/en/openapi/v3-current/src.yaml get /v1/src/consultations/{id}
Returns the current state of one consultation. `pending` is a normal state. A `completed` consultation carries the verdict for each protection type and BACEN's control code. A `failed` consultation carries the rejection.

An unknown id returns `404` with code `SRC-0301`. A malformed id returns `400` with code `SRC-0001`.



# Retrieve a consultation's evidence trail
Source: https://docs.lerian.studio/en/reference/rails/src/retrieve-a-consultations-evidence-trail

/en/openapi/v3-current/src.yaml get /v1/src/evidence/consultations/{id}
Returns the evidence trail of one consultation: every record, in ascending `sequence` order. This order reconstructs the history of the consultation.

An unknown or malformed id returns `404` with code `SRC-0301`. A trail too large for one response returns `422` with code `SRC-0002`.



# Retrieve an operator case
Source: https://docs.lerian.studio/en/reference/rails/src/retrieve-an-operator-case

/en/openapi/v3-current/src.yaml get /v1/src/operator/cases/{leg}/{caseId}
Returns one operator case, open or closed. A case id is unique only within its leg, so the path names both.

An unknown or malformed case id returns `404` with code `SRC-0301`. An unknown leg returns `422` with code `SRC-0002`.



# Retrieve the consultation dashboard
Source: https://docs.lerian.studio/en/reference/rails/src/retrieve-the-consultation-dashboard

/en/openapi/v3-current/src.yaml get /v1/src/dashboard/consultations
Returns counts of the consultations accepted between `from` and `to`: the total, the breakdowns by outcome, document type and subject role, the restrictions by protection type, and the rejections by code. `byRegistration` counts the institution records registered in the period.

`pendingBeyondExpected` and `openOperatorCases` count the current backlog and do not depend on `from` and `to`.



# Retrieve the credential status
Source: https://docs.lerian.studio/en/reference/rails/src/retrieve-the-credential-status

/en/openapi/v3-current/src.yaml get /v1/src/credentials
Returns the status of the institution's regulatory credential.



# Search consultations
Source: https://docs.lerian.studio/en/reference/rails/src/search-consultations

/en/openapi/v3-current/src.yaml post /v1/src/consultations/search
Searches the consultations of this deployment, newest first, one page at a time. It takes its filters in the request body: `status`, `documentType`, `document`, `from` and `to`. For an exact page sequence, set `to` a few seconds in the past before you read the first page.



# Search evidence records
Source: https://docs.lerian.studio/en/reference/rails/src/search-evidence-records

/en/openapi/v3-current/src.yaml post /v1/src/evidence/records
Searches the evidence trail by document and returns the matching records, newest first by `occurredAt`. The results include requests that Lerian SRC refused before acceptance, which belong to no consultation. When `kind` is `operator_case_closure` or `credential_operation`, `document` is optional.

The response does not carry the record content. For a record that belongs to a consultation, `GET /v1/src/evidence/consultations/{id}` returns the content.



# Search the evidence trail
Source: https://docs.lerian.studio/en/reference/rails/src/search-the-evidence-trail

/en/openapi/v3-current/src.yaml post /v1/src/evidence
Searches the evidence trail by period, consultation id, BACEN control code or document. Each item is a consultation that has an evidence trail, most recently accepted first. To read the records of one consultation, use `GET /v1/src/evidence/consultations/{id}`.



# SRC error list
Source: https://docs.lerian.studio/en/reference/rails/src/src-error-list

Lerian SRC returns structured error responses. Look up each SRC error code, what it means, and the HTTP status it carries.

**Error format**

Lerian SRC operations return errors as RFC 9457 problem details with the `application/problem+json` media type:

```json JSON theme={null}
{
  "code": "SRC-0002",
  "correlationId": "req-7a3f9c2e",
  "detail": "consultation domain validation failed: document: check digits are invalid for the declared documentType",
  "instance": "/v1/src/consultations",
  "status": 422,
  "title": "Unprocessable Entity",
  "traceId": "a1b2c3d4",
  "type": "https://errors.lerian.studio/v1/SRC-0002",
  "violations": [
    {
      "code": "SRC-0002",
      "field": "document",
      "reason": "check digits are invalid for the declared documentType"
    }
  ]
}
```

**Field definitions**

* **`type`** – A URI that identifies the error in the Lerian error catalog, built as `https://errors.lerian.studio/v1/<code>`.
* **`title`** – The HTTP status text (for example, `Unprocessable Entity`).
* **`status`** – The HTTP status code.
* **`detail`** – A human-readable explanation of this occurrence. For `5xx` responses, the detail reads `internal error`. Branch on `code` instead.
* **`instance`** – The path of the request.
* **`traceId`** – The trace identifier of the request.
* **`correlationId`** – The request-scoped correlation identifier.
* **`code`** – A stable identifier for the error. Branch on this field. Two errors can share a status and still differ here. `SRC-0003` and `SRC-0101` both answer `409`.
* **`violations`** – A list of field-level validation errors, each with a `field`, a `reason`, and an optional `code`.
* **`details`** – Optional structured context about the error.

## Request errors

***

These errors apply to the request itself.

| `code` | Description | Status |
| - | - | - |
| SRC-0001 | Malformed request. A value in the request cannot be parsed, for example a date, a cursor, or a consultation id. A `POST /v1/src/consultations` request without the `X-Idempotency` header also answers this code. A request body over 1 MiB answers `413`, and a method that the path does not accept answers `405`. | 400, 405, 413 |
| SRC-0002 | Validation failed. `violations` names the fields at fault. For example, the CPF or CNPJ check digits are invalid, `documentType` does not match the document, a protection type is outside the catalog, or the motivation is missing. A refused consultation request sends nothing to BACEN. | 422 |
| SRC-0003 | Idempotency conflict. The `X-Idempotency` key was already used with a different request body. Use a new key, or send the original body again. The same key with the same body answers `202` with the original consultation id. | 409 |
| SRC-0004 | Invalid subject role. `subjectRole` is not `individual`, `company`, `holder`, or `representative`. Send one of these values, or omit the field so that Lerian SRC takes the role from `documentType`. | 422 |
| SRC-0005 | Subject role and document mismatch. `individual`, `holder`, and `representative` need a CPF, and `company` needs a CNPJ. | 422 |
| SRC-0006 | Company link required. `subjectRole` is `holder` or `representative`, and the request has no `companyConsultationId`. Send the id that the company consultation returned with its `202`. | 422 |
| SRC-0007 | Company link not allowed. The request sends `companyConsultationId` with `subjectRole` `individual` or `company`. Remove the field, or use `holder` or `representative`. | 422 |
| SRC-0008 | Company consultation not usable. `companyConsultationId` does not name a CNPJ consultation of this deployment. | 422 |
| SRC-0201 | A request without a valid token returns `401`. A token of another type returns `401` with code `SRC-0201`. | 401 |
| SRC-0202 | Each operation needs one permission on the `src` product. A token without that permission returns `403` with code `SRC-0202`. | 403 |
| SRC-0301 | Not found. The resource that the request names does not exist, for example a consultation or an operator case. A closure of an operator case that is not open, and a path that matches no route, also answer this code. | 404 |
| SRC-0401 | Rate limit exceeded. Too many requests arrived from your address in the current window. Retry after the interval in the `Retry-After` header. | 429 |

## Institution record and evidence errors

***

These errors apply to institution records and to corrections of the evidence trail.

| `code` | Description | Status |
| - | - | - |
| SRC-0101 | Institution record already registered. The consultation already has an institution record. A record cannot change, and a consultation holds one record of either kind. The `detail` can name the kind that is on record. | 409 |
| SRC-0102 | Institution record not applicable. The consultation did not complete with an active restriction, so it does not accept an institution record of either kind. | 409 |
| SRC-0104 | Trail position taken. A concurrent correction of the same evidence trail took the position. Nothing was written. Retry the correction. | 409 |

## Availability errors

***

These errors mean that Lerian SRC could not complete the request. When BACEN or the messaging channel is unavailable, Lerian SRC still accepts consultations, and they stay `pending`.

| `code` | Description | Status |
| - | - | - |
| SRC-1002 | Not ready. Lerian SRC cannot reach a dependency that it needs to serve the request. Retry later. | 503 |
| SRC-1003 | Lock contention. A database lock was not available within the time limit of Lerian SRC. Nothing was written, and the request was correct. Retry. | 504 |
| SRC-1004 | Request budget elapsed. The request did not complete within the 15-second time budget of Lerian SRC. Retry after the interval in the `Retry-After` header. Before you retry an evidence correction, read the evidence trail. | 503 |
| SRC-9000 | Internal error. An unexpected failure. The `detail` reads `internal error`. | 500 |


# List credential access logs
Source: https://docs.lerian.studio/en/reference/rails/sta/get-audit-credential-access-logs

/en/openapi/v3-current/sta.yaml get /v1/audit/credential-access-logs
Returns the tenant credential access-log entries in keyset order (performedAt DESC). Optional filters: credentialId, actorId, operation, and an inclusive from / exclusive to RFC3339 window. Hash-chain fields are never projected.



# Read a credential access log entry
Source: https://docs.lerian.studio/en/reference/rails/sta/get-audit-credential-access-logs-id

/en/openapi/v3-current/sta.yaml get /v1/audit/credential-access-logs/{id}
Returns the credential access-log entry identified by {id} for the authenticated tenant.



# List audit exports
Source: https://docs.lerian.studio/en/reference/rails/sta/get-audit-exports

/en/openapi/v3-current/sta.yaml get /v1/audit/exports
Returns the tenant audit-export journal in keyset order (requestedAt DESC). No download URL is embedded; fetch GET /v1/audit/exports/{id}/download to stream a READY export.



# Read an audit export
Source: https://docs.lerian.studio/en/reference/rails/sta/get-audit-exports-id

/en/openapi/v3-current/sta.yaml get /v1/audit/exports/{id}
Returns the audit export identified by {id}. A READY export whose underlying object has been removed is reported as EXPIRED.



# Download an audit export object
Source: https://docs.lerian.studio/en/reference/rails/sta/get-audit-exports-id-download

/en/openapi/v3-current/sta.yaml get /v1/audit/exports/{id}/download
Streams the READY export object as an attachment (Content-Disposition), proxied through the service so the download stays behind the audit auth chain and works when object storage is only reachable in-cluster. Returns 409 when the export is not READY and 503 when downloads are not configured.



# List transfer history
Source: https://docs.lerian.studio/en/reference/rails/sta/get-audit-transfer-history

/en/openapi/v3-current/sta.yaml get /v1/audit/transfer-history
Returns the tenant transfer state-transition history in keyset order (transitionedAt DESC). Optional filters: transferId, actorId, triggeredBy, and an inclusive from / exclusive to RFC3339 window. Hash-chain fields are never projected.



# Read a transfer history entry
Source: https://docs.lerian.studio/en/reference/rails/sta/get-audit-transfer-history-id

/en/openapi/v3-current/sta.yaml get /v1/audit/transfer-history/{id}
Returns the transfer state-transition entry identified by {id} for the authenticated tenant.



# Create an audit export
Source: https://docs.lerian.studio/en/reference/rails/sta/post-audit-exports

/en/openapi/v3-current/sta.yaml post /v1/audit/exports
Enqueues an asynchronous audit export (status GENERATING) for the given entity type, format, and RFC3339 window. The date range is capped at 365 days; a second concurrent export for the same entity type returns 409. The export generator worker materializes the object.



# STA error list
Source: https://docs.lerian.studio/en/reference/rails/sta/sta-error-list

Lerian STA returns structured error responses. Look up each STA error code, what it means, and the HTTP status it carries.

**Error format**

Lerian STA returns errors as RFC 9457 problem details with the `application/problem+json` media type:

```json JSON theme={null}
{
  "code": "STA-0016",
  "detail": "The requested route does not exist on this service.",
  "status": 404,
  "title": "Not Found",
  "type": "https://errors.lerian.studio/v1/STA-0016"
}
```

**Field definitions**

* **`type`** – A URI that identifies the error in the Lerian error catalog, built as `https://errors.lerian.studio/v1/<code>`. A response with no `code` carries the RFC default `about:blank`.
* **`title`** – The HTTP status text (for example, `Not Found`).
* **`status`** – The HTTP status code.
* **`detail`** – A human-readable explanation of this occurrence. For `5xx` responses, STA replaces the detail with `internal error`. An internal cause stays out of the response body. Branch on `code` instead.
* **`code`** – A stable identifier for the error (`STA-NNNN`). Branch on this field. A request that fails request-schema validation carries no `code`, and `errors` names the fields at fault. Two errors can share a `title` and a status and still differ here. `STA-0005` and `STA-0016` both answer `404` with the title `Not Found`. The `code` tells you which one you got.
* **`errors`** – Optional list of individual error details, each with a `location`, a `message`, and a `value`.

## Request and routing errors

***

These errors apply to the request itself. They cover its syntax, its fields, its route, and the state of the service that received it.

| `code` | Description | Status |
| - | - | - |
| STA-0001 | Bad Request. The service could not read the request syntax. | 400 |
| STA-0002 | Internal Server Error. An unexpected failure. The `detail` reads `internal error`. | 500 |
| STA-0003 | Unauthorized. The resource requires authentication. | 401 |
| STA-0004 | Forbidden. The caller does not have permission for this resource. | 403 |
| STA-0005 | Not Found. The route exists, and the requested resource does not. | 404 |
| STA-0006 | Unprocessable Entity. The service read the request and cannot process it in its current form. | 422 |
| STA-0007 | Conflict. The request conflicts with the current state of the resource. | 409 |
| STA-0008 | Service Unavailable. A dependency the request needs is unavailable. Try again later. | 503 |
| STA-0009 | Too Many Requests. Too many requests arrived in a given period. | 429 |
| STA-0010 | Request Entity Too Large. The request body, or the file a new transfer references, is larger than Lerian STA accepts. | 413 |
| STA-0011 | Bad Request. The fallback code for a client-side refusal without a dedicated entry. | 400 |
| STA-0012 | Missing Fields in Request. One or more required fields are empty. | 400 |
| STA-0014 | Invalid Request Fields. One or more supplied fields fail validation. | 400 |
| STA-0016 | Route Not Found. The request path does not match a mounted route. Correct the URL, because a retry gives the same result. | 404 |
| STA-0017 | Method Not Allowed. The path matches a mounted route, and the method does not. When the router refused the method, the response carries an `Allow` header that lists the methods the route accepts. | 405 |

## Credential and transfer errors

***

These errors apply to BACEN credentials, to inbound source configuration, and to the credential a transfer sends under.

| `code` | Description | Status |
| - | - | - |
| STA-0102 | Conflict. A rotation request targets a credential that is not active. | 409 |
| STA-0103 | Institution Code Conflict. A live credential already exists for the same institution code. | 409 |
| STA-0104 | Polling Budget Exceeded. The inbound source configuration would push the institution's inbound-discovery reserve past its queries-per-minute ceiling. | 422 |
| STA-0105 | Default Credential Not Resolvable. The request omits `credentialId`, and the tenant does not hold an eligible credential to resolve to. | 422 |
| STA-0106 | Default Credential Ambiguous. More than one eligible credential matches, so the service refuses instead of choosing one. Name the credential you want. | 422 |
| STA-0107 | Institution Credential Not Found. The supplied `institutionCode` does not match an eligible credential. | 422 |


# Consignado events
Source: https://docs.lerian.studio/en/reference/events/consignado

CloudEvents contract emitted by Lerian Consignado: routing headers, triggers, subjects, payload fields, and delivery semantics.

Lerian Consignado publishes its business facts as CloudEvents 1.0. Emitted facts enter the transactional outbox before publication.

> [!NOTE]
>
> The payload contracts below describe the CloudEvent `data` object. A property marked with `?` can be absent. `null` is valid only where a payload contract writes it explicitly.

## Application-stream contract

| Wire element | Value |
| - | - |
| Fact topic | `lerian.streaming.consignado-gw` |
| `ce-source` | `consignado-gw` |
| `ce-type` | `studio.lerian.consignado-gw.<resource>.<event>` |
| `ce-id` | UUIDv7 |
| Dispatch key | `<resource>.<event>` from `ce-resourcetype` and `ce-eventtype` |
| `ce-schemaversion` | `1.0.0` |
| Partition key | Tenant identifier |
| Delivery | At least once through the transactional outbox |

The topic identifies the producing application, not one event. Route by `ce-source`, `ce-resourcetype`, and `ce-eventtype`. Use `ce-type` as their source-qualified composite. Never infer an event from the topic name.

## Emitted-event catalog

| Definition key | `ce-type` | Resource / event | `ce-subject` | Emission trigger |
| - | - | - | - | - |
| `consignado.solicitacao.received` | `studio.lerian.consignado-gw.consignado_solicitacao.received` | `consignado_solicitacao` / `received` | `id_solicitacao` | The gateway discovers an open loan request in Dataprev. |
| `consignado.portability_proposal.received` | `studio.lerian.consignado-gw.consignado_portability_proposal.received` | `consignado_portability_proposal` / `received` | `id_solicitacao` | The gateway discovers a live M011 portability offer and records it with its outbox envelope. |
| `consignado.margin.fetched` | `studio.lerian.consignado-gw.consignado_margin.fetched` | `consignado_margin` / `fetched` | `request_ref` | The gateway reads worker margin from Dataprev. |
| `consignado.proposal.accepted` | `studio.lerian.consignado-gw.consignado_proposal.accepted` | `consignado_proposal` / `accepted` | `proposal_ref` | The gateway witnesses the accepted rail proposal against the durable client bid. |
| `consignado.averbacao.confirmed` | `studio.lerian.consignado-gw.consignado_averbacao.confirmed` | `consignado_averbacao` / `confirmed` | `contract_id` | Dataprev confirms averbação. |
| `consignado.averbacao.rejected` | `studio.lerian.consignado-gw.consignado_averbacao.rejected` | `consignado_averbacao` / `rejected` | `contract_id` | Dataprev rejects averbação. |
| `consignado.contract.registered` | `studio.lerian.consignado-gw.consignado_contract.registered` | `consignado_contract` / `registered` | `numero_contrato` | Contract booking reaches its immutable boundary. |
| `consignado.disbursement.confirmed` | `studio.lerian.consignado-gw.consignado_disbursement.confirmed` | `consignado_disbursement` / `confirmed` | `numero_contrato` | The client confirms that the worker received the funds. |
| `consignado.contract_correction.available` | `studio.lerian.consignado-gw.consignado_contract_correction.available` | `consignado_contract_correction` / `available` | `numero_contrato` | A client supersedes the signed CCB and exposes the corrected resource for authenticated retrieval. |
| `consignado.disbursement_correction.available` | `studio.lerian.consignado-gw.consignado_disbursement_correction.available` | `consignado_disbursement_correction` / `available` | `numero_contrato` | A client supersedes a payment confirmation and exposes the corrected resource for authenticated retrieval. |
| `consignado.portabilidade.efetivada` | `studio.lerian.consignado-gw.consignado_portabilidade.efetivada` | `consignado_portabilidade` / `efetivada` | `numero_contrato` | Dataprev accepts this gateway's origin-side portability exclusion and the contract leaves the institution. |
| `consignado.portabilidade.rejeitada` | `studio.lerian.consignado-gw.consignado_portabilidade.rejeitada` | `consignado_portabilidade` / `rejeitada` | `numero_contrato` | Dataprev rejects this gateway's origin-side portability exclusion. |
| `consignado.exclusao.confirmed` | `studio.lerian.consignado-gw.consignado_exclusao.confirmed` | `consignado_exclusao` / `confirmed` | `numero_contrato` | Contract exclusion reaches a successful terminal state. |
| `consignado.exclusao.rejected` | `studio.lerian.consignado-gw.consignado_exclusao.rejected` | `consignado_exclusao` / `rejected` | `numero_contrato` | Contract exclusion reaches a rejected terminal state. |
| `consignado.reconciliation.received` | `studio.lerian.consignado-gw.consignado_reconciliation.received` | `consignado_reconciliation` / `received` | `object_ref` | The gateway normalizes one bookkeeping, repasse, or portal CSV record. |
| `consignado.employment_status.reported` | `studio.lerian.consignado-gw.consignado_employment_status.reported` | `consignado_employment_status` / `reported` | `record_id` | The gateway reads an employment suspension or termination record. |
| `consignado.afastamento.reported` | `studio.lerian.consignado-gw.consignado_afastamento.reported` | `consignado_afastamento` / `reported` | `SHA-256(payload)` | A worker absence or termination alert is reported. |
| `consignado.throughput.changed` | `studio.lerian.consignado-gw.consignado_throughput.changed` | `consignado_throughput` / `changed` | `tenant_id` | A tenant’s effective Dataprev throughput changes. |
| `consignado.cessao.registered` | `studio.lerian.consignado-gw.consignado_cessao.registered` | `consignado_cessao` / `registered` | `idempotency_key` | A credit assignment is registered in the gateway domain. |
| `consignado.repasse.overdue` | `studio.lerian.consignado-gw.consignado_repasse.overdue` | `consignado_repasse` / `overdue` | `object_ref` | An expected repasse passes its deadline or has no computable deadline. |
| `consignado.repasse.resolved` | `studio.lerian.consignado-gw.consignado_repasse.resolved` | `consignado_repasse` / `resolved` | `object_ref` | A movement resolves an overdue repasse. |
| `consignado.repasse.unobserved` | `studio.lerian.consignado-gw.consignado_repasse.unobserved` | `consignado_repasse` / `unobserved` | `object_ref` | The gateway cannot establish a current rail observation for the expectations. |
| `consignado.calendar.published` | `studio.lerian.consignado-gw.consignado_calendar.published` | `consignado_calendar` / `published` | `competencia_consulta` | An operational deduction-calendar window is published. |
| `consignado.rail.paused` | `studio.lerian.consignado-gw.consignado_rail.paused` | `consignado_rail` / `paused` | `tenant/<tenant_id>` | A scheduled gateway job meets the Dataprev competência turnover refusal, and the gateway opens a pause for the tenant. |
| `consignado.rail.resumed` | `studio.lerian.consignado-gw.consignado_rail.resumed` | `consignado_rail` / `resumed` | `tenant/<tenant_id>` | The pause for the tenant ends. |

## Payload notation

The wire uses JSON with `snake_case` property names. These aliases describe the formats used by the schemas:

```typescript theme={null}
type Decimal = string
type RFC3339 = string
type DateOnly = string
type YearMonth = string
type UUID = string
type RailCodePair = {
  codigo: number
  descricao: string
}
```

`originador_ref` is the originador whose bid produced the contract. `fundo_ref` is the fund that received the contract in a cessão. On `consignado.contract.registered`, `fund_ref` is the fund that the averbação attributes the contract to.

## Payload contracts

> **consignado.solicitacao.received**
>
> The gateway discovers an open loan request in Dataprev.
>
> **Subject:** `id_solicitacao`
>
> ```typescript theme={null}
> type ConsignadoSolicitacaoReceivedV1 = {
> id_solicitacao: string
> codigo_solicitante: string
> cpf: string
> matricula: string
> nome_trabalhador: string
> data_nascimento: DateOnly | ""
> inscricao_empregador: RailCodePair | null
> numero_inscricao_empregador: string
> data_admissao: DateOnly | ""
> valor_liberado: Decimal
> nro_parcelas: number
> margem_disponivel: Decimal
> elegivel_emprestimo?: boolean
> data_hora_validade_solicitacao: RFC3339
> pessoa_exposta_politicamente?: RailCodePair
> garantias: {
>   tem_garantias: boolean
>   valor_saldo_disponivel_garantia_fgts?: Decimal
>   valor_multa_rescisoria_garantia_fgts?: Decimal
>   perc_verba_rescisoria_garantia?: Decimal
> }
> discovered_at: RFC3339
> }
> ```

> **consignado.portability\_proposal.received**
>
> The gateway discovers a live M011 portability offer and records it with its outbox envelope.
>
> **Subject:** `id_solicitacao`
>
> ```typescript theme={null}
> type ConsignadoPortabilityProposalReceivedV1 = {
> id_solicitacao: string
> cpf: string
> matricula: string
> nome_trabalhador: string
> numero_inscricao_empregador: string
> margem_disponivel: Decimal
> elegivel_emprestimo?: boolean
> data_hora_validade_solicitacao: RFC3339
> }
> ```

> **consignado.margin.fetched**
>
> The gateway reads worker margin from Dataprev.
>
> **Subject:** `request_ref`
>
> ```typescript theme={null}
> type ConsignadoMarginFetchedV1 = {
> request_ref: string
> cpf: string
> matricula: string
> available_margin: Decimal
> remuneracao_disponivel: Decimal
> valor_total_vencimentos?: Decimal
> elegivel?: boolean
> motivo_inelegibilidade?: RailCodePair
> tipo_bloqueio?: RailCodePair
> qtd_emprestimos_ativos_suspensos?: number
> data_desligamento?: DateOnly
> codigo_motivo_desligamento?: string
> percentual_verba_rescisoria_disponivel?: Decimal
> as_of: RFC3339
> }
> ```

> **consignado.proposal.accepted**
>
> The gateway witnesses the accepted rail proposal against the durable client bid.
>
> **Subject:** `proposal_ref`
>
> ```typescript theme={null}
> type ConsignadoProposalAcceptedV1 = {
> proposal_ref: string
> id_solicitacao: string
> numero_proposta: string
> numero_contrato: string
> cpf: string
> matricula: string
> numero_inscricao_empregador: string
> principal_amount: Decimal
> liberated_amount: Decimal
> installment_amount: Decimal
> installment_count: number
> monthly_rate: Decimal
> annual_rate: Decimal
> cet_monthly: Decimal
> cet_annual: Decimal
> iof_amount: Decimal
> situacao_emprestimo?: number
> situacao_descricao?: string
> garantia?: {
>   tem_garantias: boolean
>   valor_saldo_disponivel_garantia_fgts?: Decimal
>   valor_multa_rescisoria_garantia_fgts?: Decimal
>   perc_verba_rescisoria_garantia?: Decimal
> }
> accepted_at: RFC3339
> inscricao_empregador?: RailCodePair
> if_concessora?: RailCodePair
> origem_averbacao?: RailCodePair
> origem_exclusao?: RailCodePair
> motivo_exclusao?: RailCodePair
> situacao_bloqueio_garantia?: RailCodePair
> nome_trabalhador?: string
> nome_empregador?: string
> cnpj_operador?: string
> cnpj_empregador_completo?: boolean
> valor_troco?: Decimal
> competencia_inicio_desconto?: YearMonth
> competencia_fim_desconto?: YearMonth
> qtd_escrituracoes?: string
> qtd_pagamentos?: string
> portabilidade_codigo_origem?: string
> portabilidade_codigo_proponente?: string
> portabilidade_numero_unico_averbacao?: string
> portabilidade_numero_unico_exclusao?: string
> portabilidade_situacao?: RailCodePair
> portabilidade_valor_pago?: Decimal
> data_inicio_contrato?: RFC3339
> data_fim_contrato?: RFC3339
> data_primeiro_desconto?: RFC3339
> atualizado_em?: RFC3339
> excluido_em?: RFC3339
> info_contrato_enviada_em?: RFC3339
> originador_ref?: string
> fundo_ref?: string
> }
> ```

> **consignado.averbacao.confirmed**
>
> Dataprev confirms averbação.
>
> **Subject:** `contract_id`
>
> ```typescript theme={null}
> type ConsignadoAverbacaoConfirmedV1 = {
> contract_id: string
> numero_contrato: string
> dataprev_success_code: string
> averbado_at: RFC3339
> originador_ref?: string
> }
> ```

> **consignado.averbacao.rejected**
>
> Dataprev rejects averbação.
>
> **Subject:** `contract_id`
>
> ```typescript theme={null}
> type ConsignadoAverbacaoRejectedV1 = {
> contract_id: string
> numero_contrato: string
> error_code: string
> error_message: string
> originador_ref?: string
> }
> ```

> **consignado.contract.registered**
>
> Contract booking reaches its immutable boundary. `dados_cadastrais_digest_sha256` is the SHA-256 digest of the cadastro that the gateway stored at averbação.
>
> **Subject:** `numero_contrato`
>
> ```typescript theme={null}
> type ConsignadoContractRegisteredV1 = {
> contract_id: string
> numero_contrato: string
> numero_proposta?: string
> identity: {
>   cpf: string
>   matricula: string
>   codigo_inscricao_empregador: string
>   numero_inscricao_empregador: string
> }
> declared_terms: {
>   principal_amount: Decimal
>   liberated_amount: Decimal
>   installment_amount: Decimal
>   installment_count: number
>   monthly_interest_rate: Decimal
>   annual_interest_rate: Decimal
>   cet_monthly: Decimal
>   cet_annual: Decimal
>   iof_amount: Decimal
>   first_deduction_competencia: YearMonth
>   contract_start_date: DateOnly
>   contract_end_date: DateOnly
>   first_deduction_date: DateOnly
>   expected_disbursement_date: DateOnly
>   loan_product_version: string
>   formalization_deadline: RFC3339
>   guarantee: {
>     tem_garantias: boolean
>     valor_saldo_disponivel_garantia_fgts?: Decimal
>     valor_multa_rescisoria_garantia_fgts?: Decimal
>     perc_verba_rescisoria_garantia?: Decimal
>   }
> }
> rail_terms: {
>   principal_amount: Decimal
>   liberated_amount: Decimal
>   installment_amount: Decimal
>   installment_count: number
>   monthly_interest_rate: Decimal
>   annual_interest_rate: Decimal
>   cet_monthly: Decimal
>   cet_annual: Decimal
>   iof_amount: Decimal
>   accepted_at: RFC3339
>   guarantee?: {
>     tem_garantias: boolean
>     valor_saldo_disponivel_garantia_fgts?: Decimal
>     valor_multa_rescisoria_garantia_fgts?: Decimal
>     perc_verba_rescisoria_garantia?: Decimal
>   }
> }
> margin_snapshot: {
>   available_margin: Decimal
>   remuneracao_disponivel: Decimal
>   as_of: RFC3339
> }
> signature: {
>   binding_method: string
>   signed_at: RFC3339
>   provider_evidence_ref: string
>   ip: string
>   icp_brasil: boolean
>   analfabeto: boolean
> }
> artifacts: {
>   signed_ccb: {
>     digest_sha256: string
>     blob_ref: string
>   }
>   biometrics_documents_pack: {
>     digest_sha256: string
>     blob_ref: string
>   }
> }
> registration: {
>   averbado_at: RFC3339
>   response_code: string
>   attachment_hash_operacao: string
> }
> fund_ref?: string
> dados_cadastrais_digest_sha256?: string
> originador_ref?: string
> fundo_ref?: string
> }
> ```

> **consignado.disbursement.confirmed**
>
> The client confirms that the worker received the funds.
>
> **Subject:** `numero_contrato`
>
> ```typescript theme={null}
> type ConsignadoDisbursementConfirmedV1 = {
> confirmation_id: UUID
> numero_contrato: string
> amount: Decimal
> paid_at: RFC3339
> payment_reference: string
> confirmed_at: RFC3339
> originador_ref?: string
> fundo_ref?: string
> }
> ```

> **consignado.contract\_correction.available / consignado.disbursement\_correction.available**
>
> A client supersedes a signed CCB or an already-confirmed payment. The payload points to the corrected resource. Consumers retrieve it over authenticated M2M and verify its SHA-256 digest. The event `ce-resourcetype` distinguishes the correction kind.
>
> **Subject:** `numero_contrato`
>
> ```typescript theme={null}
> type ConsignadoCorrectionAvailableV1 = {
>   numero_contrato: string
>   source_authority: string
>   resource_uri: string
>   resource_digest_sha256: string
>   gateway_received_at: RFC3339
>   supersedes_event_id?: string
>   originador_ref?: string
>   fundo_ref?: string
> }
> ```

> **consignado.portabilidade.efetivada**
>
> Dataprev accepts this gateway's own origin-side portability exclusion. The contract leaves the institution, so downstream servicing can stop. This fact does not report the incoming-institution side and carries no settlement amount.
>
> **Subject:** `numero_contrato`
>
> ```typescript theme={null}
> type ConsignadoPortabilidadeEfetivadaV1 = {
>   fact_id: string
>   tenant_id: string
>   numero_contrato: string
>   status: "efetivada"
>   destination_institution: string
>   external_operation_ref: string
>   outcome_at: RFC3339
>   originador_ref?: string
>   fundo_ref?: string
> }
> ```

> **consignado.portabilidade.rejeitada**
>
> Dataprev rejects this gateway's own origin-side portability exclusion. The contract remains in place.
>
> **Subject:** `numero_contrato`
>
> ```typescript theme={null}
> type ConsignadoPortabilidadeRejeitadaV1 = {
>   fact_id: string
>   tenant_id: string
>   numero_contrato: string
>   status: "rejeitada"
>   reason_code: string
>   message: string
>   outcome_at: RFC3339
>   originador_ref?: string
>   fundo_ref?: string
> }
> ```

> **consignado.exclusao.confirmed**
>
> Contract exclusion reaches a successful terminal state.
>
> **Subject:** `numero_contrato`
>
> ```typescript theme={null}
> type ConsignadoExclusaoConfirmedV1 = {
> fact_id: UUID
> tenant_id: string
> request_ref: UUID
> numero_contrato: string
> motivo_exclusao: string
> status: "confirmed"
> provider_reference?: string
> outcome_at: RFC3339
> evidence_source: "exclude_response" | "m005_observation" | "operator_evidence"
> originador_ref?: string
> fundo_ref?: string
> }
> ```

> **consignado.exclusao.rejected**
>
> Contract exclusion reaches a rejected terminal state.
>
> **Subject:** `numero_contrato`
>
> ```typescript theme={null}
> type ConsignadoExclusaoRejectedV1 = {
> fact_id: UUID
> tenant_id: string
> request_ref: UUID
> numero_contrato: string
> motivo_exclusao: string
> status: "rejected"
> provider_reference?: string
> reason_code?: string
> message?: string
> outcome_at: RFC3339
> evidence_source: "exclude_response" | "operator_evidence"
> originador_ref?: string
> fundo_ref?: string
> }
> ```

> **consignado.reconciliation.received**
>
> The gateway normalizes one bookkeeping, repasse, or portal CSV record.
>
> **Subject:** `object_ref`
>
> ```typescript theme={null}
> type ConsignadoReconciliationReceivedV1 = {
>   competencia?: YearMonth
>   source_kind: "dataprev_escrituracao" | "dataprev_repasse" | "portal_csv"
>   object_ref: string
>   records?: RepasseRecord[] | EscrituracaoRecord[]
> }
>
> type RepasseRecord = {
>   id: string
>   numero_guia: string
>   numero_contrato: string
>   cpf?: string
>   matricula?: string
>   valor_parcela_paga: Decimal
>   codigo_trf: string
>   data_repasse_if: RFC3339
>   status_repasse: string
>   verbas_rescisorias: boolean
>   competencia?: YearMonth
>   data_hora_inclusao_dataprev?: RFC3339
>   valor_multa?: Decimal
>   valor_juros_de_mora?: Decimal
>   valor_atualizacao_monetaria?: Decimal
> }
>
> type EscrituracaoRecord = {
>   numero_contrato: string
>   cpf?: string
>   matricula?: string
>   valor_parcela: Decimal
>   analise: {
>     existe_trabalhador_escriturado: boolean
>     existe_numero_contrato_escriturado: boolean
>     vinculo_correto: boolean
>     instituicao_financeira_correta: boolean
>     valor_parcela_correta: boolean
>     dados_correspondentes: boolean
>   }
>   tipo_evento_esocial: {
>     codigo: number
>     descricao: string
>   }
> }
> ```

> **consignado.employment\_status.reported**
>
> The gateway reads an employment suspension or termination record.
>
> **Subject:** `record_id`
>
> ```typescript theme={null}
> type ConsignadoEmploymentStatusReportedV1 = {
> report_ref: string
> record_id: string
> numero_contrato: string
> status: "suspended" | "terminated"
> effective_at: RFC3339
> reason_code?: string
> originador_ref?: string
> fundo_ref?: string
> }
> ```

> **consignado.afastamento.reported**
>
> A worker absence or termination alert is reported.
>
> **Subject:** `SHA-256(payload)`
>
> ```typescript theme={null}
> type ConsignadoAfastamentoReportedV1 = {
> cpf: string
> matricula: string
> tipo_alerta_codigo: string
> codigo_motivo_afastamento?: string
> data_referencia: DateOnly
> data_afastamento?: DateOnly
> data_termino_afastamento?: DateOnly
> codigo_motivo_desligamento?: string
> data_desligamento?: DateOnly
> data_aviso_previo?: DateOnly
> data_fim_aviso_previo?: DateOnly
> }
> ```

> **consignado.throughput.changed**
>
> A tenant’s effective Dataprev throughput changes.
>
> **Subject:** `tenant_id`
>
> ```typescript theme={null}
> type ConsignadoThroughputChangedV1 = {
> tenant_id: string
> sequence: number
> requests_per_second: number
> previous_requests_per_second?: number
> changed_at: RFC3339
> changed_by: string
> }
> ```

> **consignado.cessao.registered**
>
> A credit assignment is registered in the gateway domain.
>
> **Subject:** `idempotency_key`
>
> ```typescript theme={null}
> type ConsignadoCessaoRegisteredV1 = {
> tenant_id: string
> idempotency_key: string
> fundo_ref: string
> cedido_at: RFC3339
> cedido_by: string
> originador_ref?: string
> }
> ```

> **consignado.repasse.overdue**
>
> An expected repasse passes its deadline or has no computable deadline.
>
> **Subject:** `object_ref`
>
> ```typescript theme={null}
> type ConsignadoRepasseOverdueV1 = {
> object_ref: string
> cnpj?: string
> numero_contrato: string
> competencia: YearMonth
> reason: "repasse_missing" | "deadline_uncomputable"
> due_at?: RFC3339
> observed_at: RFC3339
> originador_ref?: string
> fundo_ref?: string
> }
> ```

> **consignado.repasse.resolved**
>
> A movement resolves an overdue repasse.
>
> **Subject:** `object_ref`
>
> ```typescript theme={null}
> type ConsignadoRepasseResolvedV1 = {
> object_ref: string
> cnpj?: string
> numero_contrato: string
> competencia: YearMonth
> estimated_due_at?: RFC3339
> guia_paid_at?: RFC3339
> exact_due_at?: RFC3339
> repasse_paid_at?: RFC3339
> settled_at: RFC3339
> originador_ref?: string
> fundo_ref?: string
> }
> ```

> **consignado.repasse.unobserved**
>
> The gateway cannot establish a current rail observation for the expectations.
>
> **Subject:** `object_ref`
>
> ```typescript theme={null}
> type ConsignadoRepasseUnobservedV1 = {
> object_ref: string
> last_observed_at?: RFC3339
> }
> ```

> **consignado.calendar.published**
>
> An operational deduction-calendar window is published.
>
> **Subject:** `competencia_consulta`
>
> ```typescript theme={null}
> type ConsignadoCalendarPublishedV1 = {
> competencia_atual: YearMonth
> competencia_consulta: YearMonth
> data_inicio_competencia: DateOnly
> data_fim_competencia: DateOnly
> }
> ```

> **consignado.rail.paused**
>
> A scheduled gateway job meets the Dataprev competência turnover refusal, and the gateway opens a pause for the tenant. Only Lerian Cloud deployments emit this fact. `hold_until` is the end of the first wait, not the end of the turnover.
>
> **Subject:** `tenant/<tenant_id>`
>
> ```typescript theme={null}
> type ConsignadoRailPausedV1 = {
> tenant_id: string
> episode: number
> paused_at: RFC3339
> hold_until: RFC3339
> rail_codes: string
> armed_by_job: string
> }
> ```

> **consignado.rail.resumed**
>
> The pause for the tenant ends. Only Lerian Cloud deployments emit this fact. `episode` has the same value as in the pause fact that it closes.
>
> **Subject:** `tenant/<tenant_id>`
>
> ```typescript theme={null}
> type ConsignadoRailResumedV1 = {
> tenant_id: string
> episode: number
> paused_at: RFC3339
> resumed_at: RFC3339
> paused_for_seconds: number
> }
> ```

## Commands consumed from Lender

These are inbound commands, not events emitted by Consignado. They arrive on `lerian.streaming.lender.commands` with `ce-source: lender` and `ce-type: studio.lerian.lender.<resource>.<event>`.

Averbação is not a Lender command. Submit it through the authenticated HTTP operation.

| Definition key | `ce-type` | Runtime behavior |
| - | - | - |
| `consignado.margin.requested` | `studio.lerian.lender.consignado_margin.requested` | Performs the worker margin read against the rail. |
| `consignado.redirecionamento.requested` | `studio.lerian.lender.consignado_redirecionamento.requested` | The gateway returns a named refusal. |
| `consignado.exclusao.requested` | `studio.lerian.lender.consignado_exclusao.requested` | Executes through the same idempotent service as the authenticated HTTP operation when the exclusion runtime is enabled; otherwise it returns a named unavailable error. |

## Delivery and compatibility rules

* Deduplicate by `(ce-source, ce-id)` and make handlers idempotent.
* Read `ce-schemaversion` before decoding. The header carries schema `1.0.0`, and the topic never does.
* Money and rates are decimal strings. Timestamps are UTC, in RFC 3339 format. Date-only values use `YYYY-MM-DD`, and competências use `YYYYMM`.
* Unknown or unsupported inbound command keys land in the Consignado consumer DLQ.
* A missing required business identifier prevents publication or command execution. Consignado never synthesizes it.


# Acknowledge a Pix key claim
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/acknowledge-claim

/en/openapi/v3-current/pix-lerian-dict.yaml post /claims/{claim_id}/acknowledge
Acknowledges an OPEN donor-side Pix key claim when the automatic acknowledgement needs to be retried. The caller must be the donor participant. The operation has no request body.



# Acknowledge an infraction report
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/acknowledge-infraction-report

/en/openapi/v3-current/pix-lerian-dict.yaml post /dict/infraction-reports/{id}/acknowledge
Acknowledges an OPEN infraction report as the receiving counterparty and changes its status to ACKNOWLEDGED. Acknowledging an already-ACKNOWLEDGED report with a new X-Idempotency header is idempotent and returns its current state with HTTP 200. Reports in CLOSED or CANCELLED return 409. Reusing the original X-Idempotency header returns the first attempt response, which may not reflect the current report state; use a different key to evaluate the current state. The report must belong to the authenticated organization, otherwise 404 is returned.



# Close refund blocks after a manual devolution
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/blocks-close-refund

/en/openapi/v3-current/pix-lerian-dict.yaml post /dict/refunds/{id}/blocks/close
Closes the refund’s pending infraction blocks after the requesting participant completes the devolution outside the automatic flow. The operation requires the external payment End-to-End ID and verifies its amount before marking the blocks as settled. The refund remains OPEN until the infraction report is concluded.



# Cancel a Pix key claim
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/cancel-claim

/en/openapi/v3-current/pix-lerian-dict.yaml post /claims/{claim_id}/cancel
Cancels an in-progress claim at the request of either party: withdrawal by the claimant or refusal by the donor. The endpoint takes no request body and determines whether the account acts as CLAIMER or DONOR. Cancellation remains available while claim data is being reconciled.



# Cancel a fraud marker
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/cancel-fraud-marker

/en/openapi/v3-current/pix-lerian-dict.yaml post /dict/fraud-markers/{fraud_marker_id}/cancel
Cancels a DICT fraud marker by its directory resource ID within the scope of the participant determined by the authenticated tenant. The request has no body. Cancelling an already-CANCELLED marker is idempotent and returns 200 without changes. Returns 404 for an unknown resource ID, 403 when the participant is not authorized to cancel the marker, and 409 for another state conflict.



# Cancel a funds recovery
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/cancel-funds-recovery

/en/openapi/v3-current/pix-lerian-dict.yaml post /dict/funds-recoveries/{id}/cancel
Cancels a funds recovery within the authenticated participant scope, changing its status to CANCELLED from any non-terminal state from CREATED through REFUNDING. A recovery already in COMPLETED or CANCELLED returns 409. The request has no body and requires the X-Idempotency header. The response omits trackingGraph, trackingGraphParameters, and correlationId.



# Cancel an infraction report
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/cancel-infraction-report

/en/openapi/v3-current/pix-lerian-dict.yaml post /dict/infraction-reports/{id}/cancel
Cancels an infraction report on behalf of its original reporter and changes its status to CANCELLED. Cancellation attempts to release all PENDING balance blocks; failure to release an individual block does not fail the cancellation. Reports in OPEN, ACKNOWLEDGED, or CLOSED can be cancelled. Cancelling an already-CANCELLED report is idempotent. Returns 403 when the participant is not the original reporter, 422 when the report is linked to a funds recovery that must be cancelled through its own operation, and 404 when the report does not belong to the authenticated organization.



# Cancel a refund
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/cancel-refund

/en/openapi/v3-current/pix-lerian-dict.yaml post /dict/refunds/{id}/cancel
Cancels a refund opened by the authenticated tenant, changing its status from OPEN to CANCELLED. Only the requesting participant that opened the refund may cancel it; a tenant acting as the contested participant receives 403. Refunds in CLOSED or CANCELLED return 409. Reusing the original X-Idempotency header returns the first attempt response; using a different key evaluates the current state and returns 409 for a terminal refund.



# Close an infraction report
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/close-infraction-report

/en/openapi/v3-current/pix-lerian-dict.yaml post /dict/infraction-reports/{id}/close
Closes an ACKNOWLEDGED infraction report with the reporter verdict (AGREED or DISAGREED) and changes its status to CLOSED. DISAGREED attempts to release all PENDING balance blocks; failure to release an individual block does not fail the close. AGREED leaves the blocks unchanged. fraudType is required when analysisResult is AGREED, and analysisDetails is required when fraudType is OTHER. Any pre-state other than ACKNOWLEDGED returns 409. Reusing the original X-Idempotency header returns the first attempt response instead of re-evaluating the current state. The report must belong to the authenticated organization, otherwise 404 is returned.



# Close a refund with the analysis outcome (Phase 3)
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/close-refund

/en/openapi/v3-current/pix-lerian-dict.yaml post /dict/refunds/{id}/close
Closes a refund with the contested participant analysis outcome. TOTALLY_ACCEPTED or PARTIALLY_ACCEPTED requires every linked infraction block to be SETTLED. REJECTED requires refundRejectionReason and every linked block to be PENDING; the refund changes to CLOSED and release is attempted for each block. A release failure does not change the HTTP 200 outcome: the refund remains CLOSED and any unreleased block is returned with blocks[].status=PENDING, indicating that its hold remains outstanding. Retrying this endpoint cannot release that block: the original X-Idempotency header returns the first response, while a different key returns 409 because the refund is CLOSED. The affected block can be released with DELETE /v1/dict/infraction-reports/{id}/balance-blocks/{blockId}, using blocks[].lockId as {blockId}, not blocks[].spiBlockId. effectiveRefundedAmount and refundTransactionId must not be sent and return 400 when present. Only the contested participant tenant may close the refund.



# Complete a Pix key claim
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/complete-claim

/en/openapi/v3-current/pix-lerian-dict.yaml post /claims/{claim_id}/complete
Completes the claim after directory confirmation and finalizes the Pix key binding to the claimant. This operation is available only to the claimant, takes no request body, and does not use X-Reason.



# Confirm a Pix key claim
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/confirm-claim

/en/openapi/v3-current/pix-lerian-dict.yaml post /claims/{claim_id}/confirm
Confirms an in-progress claim on behalf of the donor. The endpoint takes no request body; the reason is supplied in the X-Reason header. The account must be the claim donor. Claims outside the account scope return the same not-found response as unknown claims.



# Confirm the aggregated settlement (liquidation — Phase 2)
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/confirm-settle-refund

/en/openapi/v3-current/pix-lerian-dict.yaml post /dict/refunds/{id}/settle/confirm
Reports or checks the network outcome of the aggregated devolution. When result=SUCCESS, the group blocks change to SETTLED and the response includes the aggregated settlement facts: effective refunded amount, aggregated end-to-end ID, already-settled and surplus amounts, and settlement type and reason. When result=FAILED, the blocks return to PENDING and those facts remain null. Omitting result checks the current group state without changing it. The refund remains OPEN until it is closed separately. result, when provided, must be SUCCESS or FAILED; endToEndId is required for SUCCESS. Only the requesting participant tenant may confirm its own refund.



# Open a Pix key claim
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/create-claim

/en/openapi/v3-current/pix-lerian-dict.yaml post /claims
Opens a Pix key claim of type PORTABILITY or OWNERSHIP on behalf of the claimant account identified by X-Account-Id. The request body contains only the key and claim type; keyType is derived from the key format.



# Create a fraud marker
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/create-fraud-marker

/en/openapi/v3-current/pix-lerian-dict.yaml post /dict/fraud-markers
Registers a DICT fraud marker for the taxpayer identified by taxIdNumber, optionally linked to a Pix key. requestId is the caller-provided idempotency key. Repeating a requestId with the same payload returns the same marker; repeating it with a different payload is rejected. The participant is determined by the authenticated tenant.



# Create a funds recovery
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/create-funds-recovery

/en/openapi/v3-current/pix-lerian-dict.yaml post /dict/funds-recoveries
Opens a MED 2.0 funds recovery synchronously. A successful creation returns HTTP 201 with status CREATED. Reusing an X-Idempotency header returns the original response with HTTP 200. A duplicate recovery is rejected with 409 / PIX-0113. If the timestamp in rootTransactionId is outside the applicable MED contestation window, the request is rejected with 422 / PIX-0117. The window is determined by the funds recovery creation time: pacs.008 uses 80 calendar days; pacs.004 uses 30 calendar days before 2026-09-01T00:00:00Z and 80 calendar days from that instant onward. This timestamp validation does not confirm that the referenced transaction exists. The participant is determined by the authenticated tenant. participantId, reporterParticipant, rootTransactionType, and idempotencyKey are rejected when included in the body.



# Create a refund
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/create-refund

/en/openapi/v3-current/pix-lerian-dict.yaml post /dict/refunds
Opens a MED 2.0 refund for a contested transaction. If an OPEN refund already exists for the same transaction, organization, and requesting participant, a sequential retry returns the existing refund with HTTP 200. The X-Idempotency header is required and deduplicates retries, including concurrent requests. The transaction amount is validated against the SPI; a successful creation returns HTTP 201 with status OPEN. The requesting participant is determined by the authenticated tenant. participant, requestingParticipant, contestedParticipant, and organizationId are rejected when included in the body.



# Get a Pix key claim
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/get-claim

/en/openapi/v3-current/pix-lerian-dict.yaml get /claims/{claim_id}
Retrieves a Pix claim by its identifier, including events[] in ascending createdAt order. The claim must belong to the account identified by X-Account-Id. A claim outside that scope returns the same not-found response as an unknown claim.



# Get a fraud marker
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/get-fraud-marker

/en/openapi/v3-current/pix-lerian-dict.yaml get /dict/fraud-markers/{fraud_marker_id}
Retrieves a DICT fraud marker by its directory resource ID. This operation is not restricted to markers owned by the requesting participant. Under the Central Bank of Brazil contract, the documented outcomes are 200 and 404; 404 is returned when the resource ID is unknown.



# Get a funds recovery
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/get-funds-recovery

/en/openapi/v3-current/pix-lerian-dict.yaml get /dict/funds-recoveries/{id}
Retrieves a funds recovery by its resource ID (UUID v7), within the scope of the participant determined by the authenticated tenant. Returns 404 when no active recovery with that ID belongs to the participant. A recovery owned by another participant produces the same response as an unknown ID.



# Get a funds recovery tracking graph
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/get-funds-recovery-tracking-graph

/en/openapi/v3-current/pix-lerian-dict.yaml get /dict/funds-recoveries/{id}/tracking-graph
Returns the DICT tracking graph for a funds recovery identified by the resource ID returned at creation, within the authenticated participant scope. The response includes correlationId for support. trackingGraph is null when the graph is not yet available.



# Get an infraction report
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/get-infraction-report

/en/openapi/v3-current/pix-lerian-dict.yaml get /dict/infraction-reports/{id}
Retrieves an infraction report by its resource ID (UUID v7), including its tracked balance blocks, within the authenticated organization scope. Returns 404 when no report with that ID belongs to the organization. A report owned by another organization produces the same response as an unknown ID.



# Get a refund
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/get-refund

/en/openapi/v3-current/pix-lerian-dict.yaml get /dict/refunds/{id}
Retrieves a MED 2.0 refund by its resource ID (UUID), within the authenticated tenant organization scope. The response includes the Phase 2 settlement fields, which are null until settlement. Returns 404 when no active refund with that ID belongs to the tenant. A refund owned by another tenant produces the same response as an unknown ID.



# List Pix key claims
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/list-claims

/en/openapi/v3-current/pix-lerian-dict.yaml get /claims
Returns a paginated list of Pix claims for the tenant. X-Account-Id is optional: when provided the listing is scoped to that account (as claimer or donor); when omitted it spans the tenant's full organization-scoped claim set. The role/status/type/key_type filters are repeatable and case-insensitive (OR within a filter, AND across filters). List items omit the per-claim events[]; use get-by-id for the full event history.



# List fraud markers
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/list-fraud-markers

/en/openapi/v3-current/pix-lerian-dict.yaml get /dict/fraud-markers
Returns the fraud markers registered for the required tax_id_number within the participant scope determined by the authenticated tenant. Optional filters are key, status (REGISTERED or CANCELLED), modified_after and modified_before (RFC3339), and limit (1 to 200). limit has no default and is applied only when provided.



# List funds recoveries
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/list-funds-recoveries

/en/openapi/v3-current/pix-lerian-dict.yaml get /dict/funds-recoveries
Returns a paginated list of funds recoveries owned by the requesting participant, newest first by default. The listing is always scoped to the participant (ISPB) resolved from the authenticated tenant context; account_id is an optional accessory filter, not a tenant boundary. modified_after / modified_before are RFC3339 timestamps filtering updatedAt exclusively; start_date / end_date are YYYY-MM-DD dates filtering createdAt inclusively. status and sort_order are case-insensitive. The response echoes the filtered total, the applied page/limit, and hasMore.



# List infraction reports for a funds recovery
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/list-funds-recovery-infraction-reports

/en/openapi/v3-current/pix-lerian-dict.yaml get /dict/funds-recoveries/{id}/infraction-reports
Returns the infraction reports associated with a funds recovery within the scope of the participant determined by the authenticated tenant. {id} is the funds recovery resource ID. An unknown ID or a recovery owned by another participant returns 404. The BCB does not paginate this list, so the response contains only items and total.



# List refunds linked to a funds recovery
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/list-funds-recovery-refunds

/en/openapi/v3-current/pix-lerian-dict.yaml get /dict/funds-recoveries/{id}/refunds
Lists the refunds associated with a funds recovery within the scope of the participant determined by the authenticated tenant. {id} is the funds recovery resource ID. The recovery must belong to the requesting participant.



# List balance blocks for an infraction report
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/list-infraction-report-balance-blocks

/en/openapi/v3-current/pix-lerian-dict.yaml get /dict/infraction-reports/{id}/balance-blocks
Returns the balance blocks associated with an infraction report and the aggregate totals: infractionAmount from the parent report and totalBlocked, the effective amount retained across active blocks in PENDING, SETTLING, or SETTLED. The report must belong to the authenticated organization, otherwise 404 is returned.



# List infraction reports
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/list-infraction-reports

/en/openapi/v3-current/pix-lerian-dict.yaml get /dict/infraction-reports
Returns a page of infraction reports for the authenticated organization, newest-updated first by default. Every filter is optional and validated only when present; any invalid value returns 400 PIX-0003. modified_after / modified_before are ISO 8601 UTC timestamps filtering updated_at; when both are present, modified_after must not be after modified_before.



# List refunds
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/list-refunds

/en/openapi/v3-current/pix-lerian-dict.yaml get /dict/refunds
Returns a paginated list of MED 2.0 Refunds (devoluções) owned by the requesting tenant's organization, newest first by default. Filtering is always scoped to the tenant organization resolved from the authenticated context. requesting_participant / contested_participant are optional accessory filters, not tenant boundaries. status, refund_reason, and sort_order are case-insensitive.



# Update a funds recovery
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/patch-funds-recovery

/en/openapi/v3-current/pix-lerian-dict.yaml patch /dict/funds-recoveries/{id}
Applies a JSON merge-patch (Content-Type: application/merge-patch+json) to the mutable fields (contact information and report details) of a funds recovery owned by the authenticated participant. Only the fields present in the body are changed; any other field (metadata, status, participantId, ...) is rejected with 422. Returns 404 when no active recovery with that ID belongs to the participant and 409 when the recovery's current status no longer allows information changes.



# Initiate a refund for a funds recovery
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/refund-funds-recovery

/en/openapi/v3-current/pix-lerian-dict.yaml post /dict/funds-recoveries/{id}/refund
Initiates a refund for a funds recovery in the ANALYSED state, within the scope of the participant determined by the authenticated tenant. The recovery changes to REFUNDING, and the updated recovery is returned with HTTP 200. Returns 404 when no active recovery with that ID belongs to the participant and 409 when its current state does not allow a refund. The response is a concise funds recovery representation.



# Settle a refund with an aggregated block devolution (Phase 1)
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/settle-refund

/en/openapi/v3-current/pix-lerian-dict.yaml post /dict/refunds/{id}/settle
Initiates exactly one aggregated devolution for all PENDING blocks linked to the refund infraction report and changes those blocks together to SETTLING. Processing is selected automatically from the infraction operation type and contested transaction format. The refund remains OPEN during this phase. The request has no body. A successful SPI response reports SETTLING, or SETTLED for an idempotent replay; rejected or unexpected outcomes return an error. Only the requesting participant tenant may settle its own refund.



# Alter the mutable terms of an averbado contract
Source: https://docs.lerian.studio/en/reference/rails/consignado/alter-consignado-contract-terms

/en/openapi/v3-current/consignado.yaml patch /v1/consignado/contracts/{numero_contrato}/terms
Proxies alterar-consignado-trabalhador (Manual 003 §3.2): instalment count, instalment amount, worker name, and optionally the first deduction competência. Same tenant-ownership proof and idempotency requirement as suspend. Money is a decimal string, never a float.



# Attach the signed CCB for an already-averbado contract
Source: https://docs.lerian.studio/en/reference/rails/consignado/attach-consignado-ccb

/en/openapi/v3-current/consignado.yaml post /v1/consignado/contracts/{numero_contrato}/ccb-attachment
Submits incluir-informacoes-contrato-trabalhador (Manual 004 v1.6 §2.1) for a contract whose averbação the rail already accepted, and records the rail's hashOperacao durably so a replay is answered from the record instead of re-attaching. It drives the SAME command as the averbação route: the durable state machine decides which provider mutation is still owed, so this route resumes an operation rather than starting a second one. It therefore takes the SAME body — the payload digest is the replay authority, and a different payload is a different operation, refused rather than silently served the first answer.

THIS CAN COMMIT MONEY, which is why it is marked x-money-path: true. Because the state machine resumes at whichever mutation is still owed, calling this route for a contract that has NO prior operation performs the AVERBAÇÃO — it does not merely attach a document. Treat it as the averbação's equal, not as a follow-up.

This intake accepts a bancarizador credential, a fundo credential for its own fund, or an originador credential for a contract whose proposal came from its own bid (a fund it names is validated against the tenant's fund register first, and a contract outside its own bids is refused 403), and most other rail operations accept a bancarizador credential only — so do not assume the credential that reaches this route reaches the rest of the rail.



# Averbar a signed consignado contract on the payroll rail
Source: https://docs.lerian.studio/en/reference/rails/consignado/averbar-consignado-contract

/en/openapi/v3-current/consignado.yaml post /v1/consignado/contracts/{numero_contrato}/averbacao
Submits averbar-consignado-trabalhador (Manual 003 v1.19 §3.1) and, when the rail accepts it, continues straight into the signed-CCB attachment — one durable operation with two separately fenced provider mutations. THIS COMMITS MONEY: the averbação creates the payroll-deduction mandate the worker starts paying, and the exclusion that would undo it is not on this surface — so the operation is marked x-money-path: true in this document. The signed CCB is validated BEFORE anything is claimed and before the rail is called: absent, non-base64, non-PDF, or implausibly small is refused, because averbating a real contract against a non-existent document is the one ordering the rail punishes. X-Idempotency is required; the transport middleware supplies best-effort response replay while the durable PostgreSQL operation record remains the semantic authority, keyed by tenant and contract and bound to the request payload's digest. The numero_contrato in the body MUST equal the one in the path. The conditional signature-evidence fields are mutually exclusive §2.1.1 branches, so send the branch your signing flow used rather than the union of the per-field examples: indicador_analfabetismo, indicador_assinatura_cert_digital_icp_brasil or nsu_contrato makes the flow biometrics-exempt.

This intake accepts a bancarizador credential, a fundo credential for its own fund, or an originador credential for a contract whose proposal came from its own bid (a fund it names is validated against the tenant's fund register first, and a contract outside its own bids is refused 403), and most other rail operations accept a bancarizador credential only — so do not assume the credential that reaches this route reaches the rest of the rail.



# Averbate a portability
Source: https://docs.lerian.studio/en/reference/rails/consignado/averbar-consignado-portabilidade

/en/openapi/v3-current/consignado.yaml post /v1/consignado/portabilidade/{numero_unico}/averbacao
Performs averbar-portabilidade-trabalhador (Manual 008 v1.10 §5.3): the proponent institution's averbação of a portability. The origin-side exclusion is a separate command, POST /v1/consignado/contracts/{numero_contrato}/portabilidade/exclusao. It may occur before or after this averbação under Manual 008 §4, which explicitly defines the before-exclusion case and treats the reserved value as zero.

dataExclusaoOrigem is optional and is not sent to Dataprev. When supplied, it is the origin exclusion date tracked by the client. The gateway echoes it so it can refuse an averbação whose 20-calendar-day window (Manual 008 §4) has already elapsed before calling the rail. No business calendar is consulted because the window is in calendar days. When absent, the gateway submits the averbação as occurring before the origin exclusion. The gateway has no initiating fact to fall back on, so the client is the only source of the exclusion date when one exists.

X-Idempotency is the mandatory transport replay key. A retry with the same key is answered from the stored response instead of being resubmitted to the rail, as on the averbação and CCB-attachment routes. This route does not have durable Postgres-backed replay storage, so, unlike the bid route, that guarantee does not survive a Redis eviction or restart.



# Confirm a disbursement already paid to the worker
Source: https://docs.lerian.studio/en/reference/rails/consignado/confirm-consignado-disbursement

/en/openapi/v3-current/consignado.yaml post /v1/consignado/contracts/{numero_contrato}/disbursement-confirmation
Records the gateway's own durable fact that a client bank ALREADY paid a worker. This is NOT a Dataprev operation: no rail credential is used, no government boundary is crossed, and Dataprev publishes no disbursement-confirmation operation to proxy. The gateway records what the client asserted; it asks no downstream product whether the payment is plausible.

It accepts ORPHAN confirmations — money for a contract this deployment never registered locally — and a contract may be disbursed in MORE THAN ONE payment. The identity of a confirmation is (tenant, numero_contrato, payment_reference), so a second payment under a different reference on the same contract is a first acceptance with its own fact, never a conflict.

X-Idempotency is mandatory, opaque, 1..128 bytes, and never defaulted. Two keys differing in one byte are two keys, and there is no X-Idempotency-Key alias.

| Case | Status | X-Idempotency-Replayed |
|---|---|---|
| First acceptance | 202 | absent |
| Same key, same request, served from the transport cache | 202, the identical bytes | true |
| Same key, same request, served from the durable authority | 202, the identical bytes | absent |
| Same key, divergent request | 422 — never the earlier body | whatever the shared middleware wrote |
| New key, same payment | 202, the same body | absent |
| New key, same payment reference, different money | 409 | whatever the shared middleware wrote |

PostgreSQL is the authority on every row. The transport idempotency cache is a best-effort accelerator over it, in BOTH directions: whether that cache fails before the request is decided or after the confirmation is already committed, the answer is the durable one and the only difference on the wire is that the replay header is absent. A cache failure never turns a recorded payment into a 503. That is a different failure from a shared Redis outage, which the tenant rate limiter refuses first.



# Consignado error list
Source: https://docs.lerian.studio/en/reference/rails/consignado/consignado-error-list

Lerian Consignado returns structured error responses. Look up each CLT error code, what it means, and which reason codes come straight from Dataprev.

**Error format**

Lerian Consignado returns errors as RFC 9457 problem details with the `application/problem+json` media type:

```json JSON theme={null}
{
  "code": "CLT-0006",
  "detail": "The worker's authorization is outside its validity window, so their payroll data can no longer be read under it. Obtain a fresh worker authorization and send its evidence; repeating this request cannot succeed.",
  "status": 422,
  "title": "Unprocessable Entity",
  "type": "https://errors.lerian.studio/v1/CLT-0006"
}
```

**Field definitions**

* **`type`** – A URI that identifies the error in the Lerian error catalog. Built as `https://errors.lerian.studio/v1/<code>`.
* **`title`** – The HTTP status text (for example, `Unprocessable Entity`).
* **`status`** – The HTTP status code.
* **`detail`** – A human-readable explanation of this occurrence. On a `5xx` response Consignado sanitizes the detail to `internal error`, so an internal cause stays out of the body. Branch on `code` and on the status instead.
* **`code`** – A stable identifier for the error. The tables below list the `CLT-NNNN` codes. Some operations answer a named code of their own, such as `CURSOR_EXPIRED` on the registration inventory sweep. A request that fails schema validation carries no `code`: it answers `422` with the detail `validation failed`, or `400` when the body cannot be parsed, and the `errors` list names each field.
* **`errors`** – Optional list of individual error details, each with a `location`, a `message`, and a `value`.
* **`upstream`** – Dataprev's own error, when the gateway relays one. It holds Dataprev's `code` and `message`, and it survives the `5xx` sanitization that clears `detail`. See [Dataprev reason codes](#dataprev-reason-codes).
* **`refusal`** – On a bid refusal: the reason the gateway recorded for the bid, with its `source`, `field`, `rule`, and `detail`. A refusal from Dataprev also carries Dataprev's `code`.

## 400: Bad request

***

| `code` | Description | `detail` |
| - | - | - |
| CLT-0001 | Invalid request. For example, a credentials request carries a requester code that is not three digits, or a certificate and key that are not a valid PEM pair. A request with an `X-Idempotency` key longer than the operation accepts also gets this code. A disbursement confirmation answers a key that is too long with `422`. A request that fails schema validation carries no code. | — |
| CLT-0011 | Request failed. The fallback code for a client-side refusal with no entry of its own. | Names the refusal. |

## 401: Unauthorized

***

| `code` | Description | `detail` |
| - | - | - |
| CLT-0003 | Unauthorized. The request carried no valid bearer token, or the gateway could not resolve a tenant from it. | `Unauthorized`, or `Authentication is required to access this resource.` |

## 403: Forbidden

***

| `code` | Description | `detail` |
| - | - | - |
| CLT-0004 | Forbidden. The authenticated caller does not hold permission for this operation. | `Forbidden` |

## 404: Not found

***

| `code` | Description | `detail` |
| - | - | - |
| CLT-0005 | Not found. The record the request named does not exist for this tenant. A retained artifact owned by another tenant answers the same way. | `Not Found`, or `The requested resource was not found.` |

## 409: Conflict

***

| `code` | Description | `detail` |
| - | - | - |
| CLT-0007 | Conflict. The request conflicts with the current state of the record. | `Conflict`, or the sentence for the conflict, such as `an identical request is already in flight`. |

`CLT-0007` with the detail `an identical request is already in flight` marks a request the gateway has not finished. Retry that request under the same idempotency key.

Command conflicts answer a named code in place of `CLT-0007`, so a client can tell them apart. Read `code` and `detail` together before you retry. These code spellings are part of the wire contract and do not change.

| `code` | Description | `detail` |
| - | - | - |
| FGTS\_EXECUTION\_PAYLOAD\_MISMATCH | This idempotency key already holds a different FGTS guarantee execution. | This idempotency key already holds a different FGTS guarantee execution. Resend the original request under this key to replay it, or use a new key for a different execution. |
| FGTS\_EXECUTION\_OUTCOME\_UNRESOLVED | The execution held under this idempotency key has no known outcome yet, so it cannot be replayed. | The FGTS guarantee execution held under this idempotency key has no known outcome yet, so it cannot be replayed. Executing the same contract under a new key risks moving the money twice. |
| FGTS\_EXECUTION\_ALREADY\_REFUSED | The execution held under this idempotency key was refused, so a corrected request needs a new key. | The FGTS guarantee execution held under this idempotency key was refused. This key can only ever return that refusal, so a corrected request needs a new key. |
| FGTS\_EXECUTION\_CONTRACT\_TAKEN | This contract's FGTS guarantee already ran under another idempotency key. This request did not execute. | This contract's FGTS guarantee was already executed under another idempotency key, and a guarantee is executed once. This request was not executed. |
| BID\_SOLICITACAO\_TAKEN | The solicitação already carries a bid from this institution. | This solicitação already carries a bid from this institution, and a solicitação takes one. Read the bid book for the outcome of the bid that holds it. |
| BID\_PROPOSAL\_SLOT\_TAKEN | An earlier submission holds the proposal position, so this bid was not recorded. | A proposal position in this bid is already held by an earlier submission, so this bid was not recorded. Read the bid book for the outcome of the submission that holds it. |
| AVERBACAO\_CLAIM\_CONFLICT | This contract's averbação is already claimed under another idempotency key. | This contract's averbação is already claimed under another idempotency key. Follow the claim that exists instead of opening a second one. |
| AVERBACAO\_ARTIFACT\_CONFLICT | A different document is already retained for this contract's averbação. This request did not apply. | A different document is already retained for this contract's averbação, and a retained document is never replaced. This request was not applied. |
| EXCLUSION\_AUTHORITY\_QUARANTINED | This contract holds an exclusion record the gateway cannot report, so it does not answer absence. | This contract holds an exclusion record the gateway cannot report. It is deliberately not answered as absent, because the contract may well be excluded. |
| EXCLUSION\_AUTHORITY\_CONFLICT | This contract's exclusion is already recorded under another authority. This request did not apply. | This contract's exclusion is already recorded under another authority, and an exclusion has no undo. This request was not applied. |
| RAIL\_COMMAND\_CLAIM\_CONFLICT | This command is already claimed for this contract under another idempotency key. | This command is already claimed for this contract under another idempotency key. Follow the claim that exists instead of opening a second one. |
| RAIL\_COMMAND\_ANSWER\_NOT\_RETAINED | This command already committed for this contract, and its original answer was not kept. | This command already committed for this contract, but its original answer was not kept, so there is nothing to replay. Read the contract's current state rather than sending it again. |
| REVERSAO\_WINDOW\_EXPIRED | The window for reversing this refinancing has closed, so no correction reopens it. | The window for reversing this refinancing has closed, so the reversal can no longer be requested. No correction to this request can reopen it. |
| CONTRACT\_ALREADY\_REGISTERED | The contract import names a contract this tenant already holds. | This contract is already registered in this tenant's saldo devedor book, and a contract is imported once. Read the obligation that exists instead of importing a second one. |
| DATAPREV\_CREDENTIAL\_REQUIRED | The tenant has no Dataprev credential in custody, so no rail operation can run for it. | This tenant has no Dataprev credential in custody, so the gateway cannot act for it on the rail. Provision the credential first; no correction to this request can succeed until then. |

After `DATAPREV_CREDENTIAL_REQUIRED`, upload the tenant's Dataprev certificate, OAuth credentials, and requester code, then send the request again.

## 410: Gone

***

The paginated registration inventory sweep issues a cursor with a limited retry window.

| `code` | Description | `detail` |
| - | - | - |
| CURSOR\_EXPIRED | Gone. The cursor's retry window has passed, so the sweep it belonged to cannot continue. Start a new sweep instead. | The cursor retry window has expired. |

## 413: Request entity too large

***

| `code` | Description | `detail` |
| - | - | - |
| CLT-0010 | Request entity too large. The request payload is larger than the endpoint accepts. | `The request payload is too large.` |

## 422: Unprocessable entity

***

| `code` | Description | `detail` |
| - | - | - |
| CLT-0006 | Unprocessable entity. The gateway read the request and refuses it in its current form. A deterministic Dataprev rejection answers here too, and carries `upstream`. | The reason to act on, such as obtaining a fresh worker authorization. |

A command sent again under an idempotency key that an earlier request already spent can answer one of four named codes. The earlier request can already have reached Dataprev. Do not send the command again, under this key or a new one. Read the current state of the record the command changes.

| `code` | Description | `detail` |
| - | - | - |
| IDEMPOTENCY\_STATE\_UNRECOGNISED | The record held under this key was written by a newer version of the service. | An earlier request spent this idempotency key with a record written by a newer version of this service; reconcile the original request and do not retry under a new key. |
| IDEMPOTENCY\_RECORD\_UNREADABLE | The record held under this key cannot be read. | An earlier request spent this idempotency key with a record this service cannot read; reconcile the original request and do not retry under a new key. |
| IDEMPOTENCY\_OUTCOME\_UNRECORDED | The earlier request under this key has no recorded outcome. | An earlier request spent this idempotency key and its outcome was not recorded; reconcile the original request and do not retry under a new key. |
| IDEMPOTENCY\_REPLAY\_UNAVAILABLE | The earlier request under this key completed, and its answer cannot be replayed. | An earlier request with this idempotency key completed and its response was delivered once, but it cannot be replayed; do not resend, reconcile the resource the command mutates, and do not retry under a new key. |

## 429: Too many requests

***

| `code` | Description | `detail` |
| - | - | - |
| CLT-0009 | Too many requests. The caller exceeded its request budget. | `Too many requests were sent in a given amount of time.` |

Wait for the time the `Retry-After` header gives, then send the request again.

## 500: Internal server error

***

| `code` | Description | `detail` |
| - | - | - |
| CLT-0002 | Internal server error. An unexpected failure inside the gateway. | `internal error` |

## 501: Not implemented

***

A `501` answers an operation your deployment has not enabled. The routes stay mounted, so the answer arrives per request rather than as a missing path. Contract artifact downloads, contract corrections, disbursement confirmation, cessão registration, bid submission, and operations that reach Dataprev answer `501` until your deployment enables them.

The `detail` reads `internal error`, because Consignado sanitizes the detail on a `5xx` response. Branch on the status.

## 503: Service unavailable

***

| `code` | Description | `detail` |
| - | - | - |
| CLT-0008 | Service unavailable. A dependency the request needs is unavailable, or Dataprev answered with a retry-later fault. Send the same request again shortly. | `internal error` |

When Dataprev produced the fault, the response also carries `upstream` with Dataprev's own code and message.

## Dataprev reason codes

***

Consignado relays Dataprev's reason codes rather than mapping them onto codes of its own. That keeps a refusal readable against what Dataprev said. Read each reason code against Dataprev's specification, not against this page. Dataprev can publish a code this page does not list, and the gateway still delivers it to you.

They reach you in two places.

**On a refusal.** The `upstream` member carries Dataprev's own `code` and `message`. A refusal with several codes lists them comma-separated. The member holds Dataprev's codes and sentences, bounded in length, rather than a response body. A `422` carries it for a deterministic rejection, and a `503` carries it for a retry-later fault.

**On contract and margin responses.** Several response fields pair a Dataprev reason code with Dataprev's own label for it. A margin read publishes `blockType` and `ineligibilityReason`, which spell the pair `code` and `description`. A contract read publishes `motivo_exclusao`, `origem_averbacao`, `origem_exclusao`, `portabilidade_situacao`, and `situacao_bloqueio_garantia`, which spell it `codigo` and `descricao`. Each field holds a numeric code and the text Dataprev returned beside it.

Treat the set as open. Map the reason codes your integration acts on, and pass the rest through with their labels, so a code you have not mapped yet stays readable to an operator.


# Register a new fund
Source: https://docs.lerian.studio/en/reference/rails/consignado/create-consignado-fundo

/en/openapi/v3-current/consignado.yaml post /v1/consignado/fundos
Registers a new fund under the authenticated tenant. The same real-world fund registered under another tenant is represented by a separate tenant-scoped record.



# Create a hub subscription
Source: https://docs.lerian.studio/en/reference/rails/consignado/create-subscription

/en/openapi/v3-current/consignado.yaml post /v1/subscriptions
Creates a streaming-hub subscription for the tenant and returns the once-shown signing secret. The secret is shown exactly once and is never re-fetchable; the console never stores it.



# Deactivate a fund
Source: https://docs.lerian.studio/en/reference/rails/consignado/deactivate-consignado-fundo

/en/openapi/v3-current/consignado.yaml delete /v1/consignado/fundos/{id}
Soft-disables the fund: it stops accepting new credit, but the row is never deleted, so credit already attributed to it stays legible. Idempotent: deactivating an already-deactivated fund succeeds.



# Withdraw a competência's early-payment suspension
Source: https://docs.lerian.studio/en/reference/rails/consignado/excluir-consignado-antecipacao-parcela

/en/openapi/v3-current/consignado.yaml put /v1/consignado/contracts/{numero_contrato}/antecipacao/{competencia}
Proxies excluir-antecipar-parcela (Manual 013 v1.3 §2.2), returning the contract to its normal discount schedule for the named competência. Same tenant-ownership proof and idempotency requirement as incluir.



# Remove an averbado contract from the payroll registry
Source: https://docs.lerian.studio/en/reference/rails/consignado/excluir-consignado-contract

/en/openapi/v3-current/consignado.yaml post /v1/consignado/contracts/{numero_contrato}/exclusion
Removes one averbado contract from the Dataprev registry through excluir-consignado-trabalhador (Manual 003 v1.19 §3.3). THERE IS NO UNDO, which is why the operation is marked x-money-path: true.

The body carries exactly ONE key. codigoSolicitante, cpfTrabalhador, matricula, codigoInscricaoEmpregador and numeroInscricaoEmpregador are never accepted from the caller: they identify the worker and the employer and come from the immutable local booking snapshot, so a client cannot address an exclusion at a worker its own booking never covered.

The answer distinguishes the three outcomes a caller must be able to tell apart:

| Status | Meaning |
|---|---|
| 201 | This call created the attempt and it reached a terminal state — confirmed (the contract came off the payroll) or rejected (the registry refused, and its own code and message are in the body) |
| 200 | A replay of an attempt that is ALREADY terminal: the outcome in the body is the earlier attempt's, and this call invoked nothing |
| 202 | The gateway holds the request and the effect at the registry is not known yet; M005 reconciliation converges it. A replay of an attempt that is not terminal yet is also a 202 — X-Idempotency-Replayed, not the status code, is what says whether this call invoked anything |

A rejected attempt is a BUSINESS answer, not a transport error: the registry published a refusal the client must read.



# Remove a previously registered legado loan
Source: https://docs.lerian.studio/en/reference/rails/consignado/excluir-consignado-emprestimo-legado

/en/openapi/v3-current/consignado.yaml put /v1/consignado/legacy-contracts/{numero_contrato}
Proxies excluir-emprestimo-legado-trabalhador (Manual 007 v1.4 §3.2, PUT — never DELETE), restoring the worker's eligibility for new contracting on this rail. motivoExclusao is a closed, non-contiguous set (1,2,3,7,8,9 — the manual's own apêndice §4.1 has no 4, 5 or 6). X-Idempotency is required. A retried request that lands on the rail's own HY ("empréstimo inexistente") answers success rather than a refusal.



# Exclude a contract from this institution because the worker ported it out
Source: https://docs.lerian.studio/en/reference/rails/consignado/excluir-consignado-portabilidade

/en/openapi/v3-current/consignado.yaml post /v1/consignado/contracts/{numero_contrato}/portabilidade/exclusao
Proxies excluir-portabilidade-trabalhador (Manual 008 v1.10 §4.1), the ORIGIN institution's write: the contract named in the path stops being consigned here because the worker moved it to the institution named by codigoProponente. codigoOrigem is never accepted from the caller — it is the authenticated tenant's own COMPE/CBC. The contract must be an averbação of the authenticated tenant that the rail acknowledged; anything else is 404 before the rail is called. The call is claimed durably before it departs and closed durably after the answer lands, so a retry under the same X-Idempotency key is answered from the retained rail answer instead of excluding a second time, and a call whose outcome nobody established is reconciled against the registry rather than lost. Success publishes consignado.portabilidade.efetivada and a published refusal publishes consignado.portabilidade.rejeitada. A portability the client performs OUTSIDE this gateway publishes nothing: Manual 008 §5.4's consulta is proponente-only, so the origin institution has no discovery path. X-Idempotency is required.



# Execute the FGTS guarantee for a contract
Source: https://docs.lerian.studio/en/reference/rails/consignado/execute-consignado-fgts-guarantee

/en/openapi/v3-current/consignado.yaml post /v1/consignado/fgts/garantias/execucao
Proxies execucao-garantias-fgts (Manual 017 §3.1). THIS MOVES CASH AND CANNOT BE UNDONE — it is marked x-money-path: true in this document. The guarantee executes AT MOST ONCE per (tenant, contract). X-Idempotency is required and is never defaulted; the gateway records the request durably BEFORE calling the rail.

The four conflict cases, all 409:
1. Same key, same body — the recorded outcome is REPLAYED (replayed: true) without touching the rail. This is the only non-conflict repeat.
2. Same key, DIFFERENT body — refused, never served the earlier answer.
3. A BRAND-NEW key for a contract that ALREADY has an execution record — REFUSED, not replayed. The stored outcome belongs to the other key, and a fresh key must not buy a second cash movement. This is a refusal, not a fault: nothing was claimed and the rail was not called.
4. The first attempt's outcome could not be established — the key is terminally unresolved. Retrying could execute the guarantee twice, and Manual 017 publishes no operation that asks the rail whether it already did, so reconciliation is an OPERATOR action, deliberately not an automatic one.

The two collateral values are Obrigatório=Não at the rail: OMIT them for a contract with no FGTS collateral. Sending 0 is refused locally with 422 — the rail reads 0 as an invalid guarantee value, and refusing early keeps the mistake from burning your idempotency key.



# Read the rail's operational-calendar competência window
Source: https://docs.lerian.studio/en/reference/rails/consignado/get-consignado-calendar

/en/openapi/v3-current/consignado.yaml get /v1/consignado/calendar
Proxies consultar-calendario-trabalhador (Manual 005 v1.13 §3.1): the start/end dates of one payroll competência plus the rail's own notion of the CURRENT competência. It answers a competência WINDOW ONLY — Manual 005 §3.1 has zero occurrences of "feriado" and publishes no business-day field, so this route never claims a date is or is not a business day. Cached for up to one hour per (tenant, competência), because the read spends the rail's own request quota on every call; a cache hit answers with no rail round trip at all.



# Report which operation families this deployment reaches
Source: https://docs.lerian.studio/en/reference/rails/consignado/get-consignado-capabilities

/en/openapi/v3-current/consignado.yaml get /v1/consignado/capabilities
Reports which operation families THIS deployment reaches.

The console reads it once and uses it to disable, rather than hide, a control that would otherwise answer 501. Nothing here is tenant data: the answer is a property of the running deployment and is identical for every tenant it serves. The tenant is still derived from the validated identity, as on every other operation, and is never read from the request.

'name' is the operation family, never the name of the deployment flag behind it: a flag name is operator material.

'reason' is a closed vocabulary of four values, one per mechanism. 'enabled' is the only one that appears beside available true. 'flag_off' means a boot flag made the composition skip building the family. 'portal_store_absent' means this deployment mounted no portal store. 'rail_client_absent' means no Dataprev client was wired, which takes the whole rail family with it.

A family reported unavailable will answer 501 on every one of its operations. A family reported available may still answer 501 in the instant between this read and the call, so a client keeps its own 501 branch: this read tells a client what to offer, it does not replace the refusal.



# Download a retained consignado contract artifact
Source: https://docs.lerian.studio/en/reference/rails/consignado/get-consignado-contract-artifact

/en/openapi/v3-current/consignado.yaml get /v1/consignado/contracts/{numero_contrato}/artifacts/{artifact_type}
Returns the verified artifact bytes owned by the authenticated tenant. Missing and non-owned artifacts share the same 404 response. The response contains no storage coordinates or direct-storage URL.



# Get one contract's averbação operation
Source: https://docs.lerian.studio/en/reference/rails/consignado/get-consignado-contract-averbacao-operation

/en/openapi/v3-current/consignado.yaml get /v1/consignado/contracts/{numero_contrato}/averbacao
Returns ONE contract's averbação operation, by the rail contract number.

It answers from a LOCAL table and never reaches the Dataprev rail. The tenant is derived from the validated identity: a contract that does not exist and a contract belonging to another tenant are the SAME answer, 404, so this read cannot be used to probe another tenant's book.

The body is the operation object itself, with no envelope, the same shape as one element of GET /v1/consignado/averbacao-operations. Every conditional instant is present and null until the step it names has happened.

This is the READ half of the address whose POST creates the payroll-deduction mandate. It creates nothing and changes nothing.



# Download the corrected resource a correction fact names
Source: https://docs.lerian.studio/en/reference/rails/consignado/get-consignado-contract-correction

/en/openapi/v3-current/consignado.yaml get /v1/consignado/contracts/{numero_contrato}/corrections/{correction_id}
Returns the corrected resource bytes a correction fact points at, verified against the digest that fact published.

This is the endpoint the consumer's M2M artifact reader calls. It answers bytes or an error and never a redirect, a byte range or a content-coded body: each of those turns a valid correction into a terminal failure on the consumer side.

An unknown correction and one belonging to another tenant share the same 404. The tenant is part of the chain's primary key, so the distinction is not made rather than merely hidden.



# Read the exclusion this gateway holds for a contract
Source: https://docs.lerian.studio/en/reference/rails/consignado/get-consignado-contract-exclusion

/en/openapi/v3-current/consignado.yaml get /v1/consignado/contracts/{numero_contrato}/exclusion
Reads the exclusion this gateway durably holds for one contract — the outcome of excluir-consignado-trabalhador (Manual 003 v1.19 §3.3). It is a LOCAL read: it never calls Dataprev and never starts a reconciliation pass, because the gateway's own row already answers and an M003 operation with no undo does not justify spending the rail's rate budget on the question.

404 means the gateway holds nothing for this contract. 409 means the contract holds a legacy authority row that cannot be reported — deliberately NOT a 404, because silence would read as "this contract was never excluded".



# Read the FGTS guarantee execution this gateway holds for a contract
Source: https://docs.lerian.studio/en/reference/rails/consignado/get-consignado-contract-fgts-guarantee-execution

/en/openapi/v3-current/consignado.yaml get /v1/consignado/contracts/{numero_contrato}/fgts-garantia/execucao
Reads the FGTS-guarantee execution this gateway durably holds for one contract (Manual 017 §3.1).

It is a LOCAL read: it never calls Dataprev, opens no worker consent and spends none of the rail's rate budget. There is nothing out there to call — Manual 017 publishes consultar-saldo, listar-autorizados and the execution itself, and NO operation that asks the registry whether it already executed. The gateway's own row is the whole answer, which is why an unestablished outcome is reconciled by an operator rather than retried.

This exists because the execution is the one irreversible cash movement whose outcome used to be readable in exactly one place: the response to the POST that performed it. A closed tab or a dropped connection left an operator unable to tell whether the money moved.

The four statuses, and what each one means for the caller:

| Status | Meaning |
|---|---|
| executed | The rail confirmed. protocolo is the receipt and dtPrevRepasse the forecast repasse date |
| refused | The rail PROVED it executed nothing. Terminal for that idempotency key, but the contract is released: a corrected request under a NEW key may execute |
| claimed | The gateway recorded the request and the rail has not answered yet |
| unknown | The outcome could not be established. Terminal for the key, and the contract stays fenced until an operator reconciles — retrying could execute the guarantee twice |

404 means the gateway holds no execution record for this contract. It is never answered as an empty record: on a movement with no undo, "we hold nothing" and "we hold a claim nobody settled" are the two answers that must never be confused.

The idempotency key and the payload digest are not published. They are internal replay mechanics, and the digest fingerprints a body carrying the worker's CPF.



# Download the rail's document for a contract
Source: https://docs.lerian.studio/en/reference/rails/consignado/get-consignado-contract-rail-document

/en/openapi/v3-current/consignado.yaml get /v1/consignado/contracts/{numero_contrato}/rail-document
Proxies consultar-informacoes-contrato-trabalhador (Manual 004 §2.2): the document the payroll rail holds for a contract, selected by tipoArquivo (2..5). The response is the document itself, streamed in the content type the rail declared — not a JSON envelope with base64. tipoArquivo is required and validated locally, so an out-of-domain value never spends rail quota. Nothing is cached: the value of this operation is being the rail's current truth. The route accepts no CPF, because the rail operation has no such parameter.



# Get current consignado contract registration evidence
Source: https://docs.lerian.studio/en/reference/rails/consignado/get-consignado-contract-registration

/en/openapi/v3-current/consignado.yaml get /v1/consignado/contract-registrations/{numero_contrato}
Returns one current, tenant-scoped observation without moving an inventory cursor.



# Get one contract's saldo devedor and its amortization book
Source: https://docs.lerian.studio/en/reference/rails/consignado/get-consignado-contract-saldo-devedor

/en/openapi/v3-current/consignado.yaml get /v1/consignado/contracts/{numero_contrato}/saldo-devedor
Returns ONE contract's saldo devedor obligation together with its whole amortization book, by the rail contract number.

'obrigacao' is the SAME shape as one element of GET /v1/consignado/saldo-devedor, so a console needs one renderer for both. 'amortizacoes' is the per-competência record of what has already amortized, ordered by competência, which is the amortization table's own key order.

'origem' on each amortization is the provenance a reversal acts against: E1 is an amortização prevista, which nothing withdraws, and E5 is an antecipação, which its own exclusion can withdraw. That distinction is why the two are published rather than collapsed into a count.

An obligation with NO amortization at all answers an empty list and never a 404. The obligation is real and has simply never amortized, which is the ordinary state of a contract in its first month.

It answers from a LOCAL table and never reaches the Dataprev rail. The tenant is derived from the validated identity: a contract that does not exist and a contract belonging to another tenant are the SAME answer, 404, so this read cannot be used to probe another tenant's book.



# Census this tenant's outbox event delivery by status
Source: https://docs.lerian.studio/en/reference/rails/consignado/get-consignado-event-delivery

/en/openapi/v3-current/consignado.yaml get /v1/consignado/event-delivery
Censuses this tenant's transactional outbox by status: five buckets, always five, one per value of the database enum.

It answers whether the facts this gateway WROTE actually left it, which no other surface reports. A fact recorded in a local table and never published is invisible to every read beside this one: the operation books show what the gateway did, and this shows whether the world was told.

ALL FIVE BUCKETS ARE ALWAYS PRESENT, at count zero included. A bucket that vanished when it emptied would make "nothing is stuck" and "nothing was ever written" render identically.

'oldest_created_at' is the number to act on, and it is null exactly when the bucket is at zero. A PENDING bucket whose oldest row is hours old is a dispatcher that stopped; a PENDING bucket of the same count whose oldest row is seconds old is a healthy queue.

The status labels are the Postgres enum's own, verbatim and UPPERCASE. This is the one read here that does not use lowercase vocabulary, deliberately: inventing a lowercase alias would give one fact two spellings, and an operator would read one on the screen and the other in every query they run against the database while acting on it.

INVALID is terminal. Those facts will never be published, and switching a relay on afterwards recovers nothing. GET /v1/consignado/event-delivery/invalid is the row-by-row read of that bucket.

It answers from a LOCAL table and never reaches the Dataprev rail, so it cannot answer 501. It takes no parameter of any kind, neither filter nor page: the whole answer is five numbers, and there is nothing for a caller to narrow. The tenant is derived from the validated identity and is never read from the request.



# Get one exclusion operation's audit trail
Source: https://docs.lerian.studio/en/reference/rails/consignado/get-consignado-exclusion-operation-audit

/en/openapi/v3-current/consignado.yaml get /v1/consignado/exclusion-operations/{request_ref}/audit
Returns ONE exclusion operation's append-only transition trail, oldest first.

The trail is keyed by the operation's own request_ref rather than by contract number, because the trail belongs to the OPERATION: a contract excluded more than once has more than one trail, and keying by contract would need a resolution step free to answer with the wrong one.

The tenant is derived from the validated identity: an operation that does not exist and an operation belonging to another tenant are the SAME answer, 404, so this read cannot be used to probe another tenant's book.

evidence is handed back as the JSON document the writer stored, byte for byte, and its shape varies by event_type. It is deliberately not re-encoded: a trail exists to hold proof, and a server that rewrites proof cannot settle the argument the trail was kept for.

The trail is not paginated. It is capped at 200 entries and the cut is STATED through truncated rather than swallowed, because a silent cut reads as a complete history. A quarantined operation's trail is served like any other: it is exactly the evidence an operator has about a row nothing will converge.



# Read one averbado contract's loan status on the rail
Source: https://docs.lerian.studio/en/reference/rails/consignado/get-consignado-rail-loan

/en/openapi/v3-current/consignado.yaml get /v1/consignado/contracts/{numero_contrato}/rail-loan
Reads the rail's consultar-emprestimo-trabalhador (Manual 005 v1.13 §3.2.1) for one averbado contract: situação do empréstimo, the proposta that owns it, the money terms and the FGTS collateral block. It REPORTS status only — it creates or resolves no durable proposal witness and emits no handoff fact.



# Get this tenant's outbound Dataprev rail throughput
Source: https://docs.lerian.studio/en/reference/rails/consignado/get-consignado-throughput

/en/openapi/v3-current/consignado.yaml get /v1/consignado/throughput
Returns the tenant's own outbound Dataprev rail rate in requests per second, together with the rail's code-locked ceiling and the starter floor, so no consumer restates either number from its own bundle. A tenant that has never chosen a rate is reported at the starter floor with configured=false; the read never opens a chain. A rate of zero is a deliberate self-service pause, never an absent value.



# Get consignado gateway usage for a competência
Source: https://docs.lerian.studio/en/reference/rails/consignado/get-consignado-usage

/en/openapi/v3-current/consignado.yaml get /v1/consignado/usage
Returns the tenant's gateway-scoped, priced usage aggregation for a billing competência: R$15 per confirmed averbação and R$2 per active deduction competência, priced SEPARATELY from single-source flat fees (independent of the loan principal). Omit competencia for the current UTC month. A period with no usage returns 200 with zero counts, NOT 404. Money is a decimal string, never a float.



# Get a hub subscription
Source: https://docs.lerian.studio/en/reference/rails/consignado/get-subscription

/en/openapi/v3-current/consignado.yaml get /v1/subscriptions/{id}
Returns a single tenant subscription. NEVER returns the signing secret (only create/rotate reveal it, once).



# Get a subscription's delivery health
Source: https://docs.lerian.studio/en/reference/rails/consignado/get-subscription-health

/en/openapi/v3-current/consignado.yaml get /v1/subscriptions/{id}/health
Rolls one subscription's delivery record into a single non-secret view: outcome counts over the hub's window and over the last 24 hours, dead-lettered and poison-event counts, the auto-disable verdict, the success rate and the consumer lag.

It answers the question none of the other subscription reads can: whether the events this tenant subscribed to are ACTUALLY ARRIVING. Listing a subscription proves it is registered and enabled; only this shows whether the endpoint behind it has been accepting deliveries.

'auto_disabled' and 'success_rate' are NULLABLE and null is not the zero value of either. A null 'auto_disabled' means the hub holds no endpoint-health row yet, which is not the same fact as false ("checked, and healthy"). A null 'success_rate' means no delivery attempt has reached a terminal outcome yet, which is not the same fact as 0.0 ("every attempt failed"). A client that reads either null as its zero value reports a healthy endpoint as broken, or a broken one as fine.

'disabled_reason', 'last_success_at' and 'last_failure_at' are null when there is nothing to report, and the key is always present.

'status' and 'verification_state' are FREE strings carried through from the hub, not a closed vocabulary this gateway pins. The hub may add a value, and a client should render an unrecognized one by its identifier rather than refuse the response.

This is a FORWARD, not a local read: the gateway owns no subscription storage. The hub answers an unknown subscription and another tenant's subscription with the SAME 404, publishing no existence oracle, and that 404 reaches the caller unchanged. This gateway does not reinterpret it, because splitting it into "no such subscription" and "not yours" would state something the hub deliberately refused to state.

The tenant is derived from the validated identity and is never read from the request.



# Import a contract already averbado outside this gateway
Source: https://docs.lerian.studio/en/reference/rails/consignado/import-consignado-contract

/en/openapi/v3-current/consignado.yaml post /v1/consignado/contracts/{numero_contrato}/import
Adopts a contract that is ALREADY averbado on the payroll rail — registered on the Dataprev portal by hand, by a previous provider, or carried in from a book you are migrating — so its recurring saldo devedor obligation (Manual 015 §2.2) exists here and its first M015 report is scheduled.

It does NOT averbate anything and it moves no money: the only call it makes to Dataprev is consultar-emprestimo-trabalhador (Manual 005 v1.13 §3.2.1), a read, under your own credential. Everything the obligation needs — the worker's CPF and matrícula, the employer inscription, the instalment count, the instalment amount, the first discount competência, the monthly rate and the first deduction date — is taken from that read. You send the contract number and, optionally, how many competências have already amortized; you never send worker or employer identifiers, and none come back.

Only a LIVE contract can be imported: situação 0 (Ativo), 7 (Contrato suspenso), 8 (Suspenso banco) or 17 (Contrato suspenso por antecipação de parcela). A suspension is not a closure — the deduction is still attached to the worker and the debt is still reportable. Situação 2, 3, 15 and 16 are closed and refused 422 whose detail names the código the registry published (`situacaoEmprestimo 3 não é vigente`) and nothing else — Dataprev's own descrição is never relayed into the body. Importing one would make this gateway file recurring reports about a debt the registry already ended. A read that carries no situação at all, no competência de início de desconto, no monthly rate (valorTaxaMensal) or first deduction date (dataPrimeiroDesconto), or one that answers about a different contract number, is refused 422 the same way rather than guessed at.

The import is not idempotent in the ordinary sense: a contract this tenant already holds an obligation for is answered 409 CONTRACT_ALREADY_REGISTERED, with nothing changed and the parcelas_pagas you sent NOT applied. X-Idempotency is still required, and the transport middleware replays the answer of a duplicate request under the same key.



# Suspend one or more competências by early payment
Source: https://docs.lerian.studio/en/reference/rails/consignado/incluir-consignado-antecipacao-parcela

/en/openapi/v3-current/consignado.yaml post /v1/consignado/contracts/{numero_contrato}/antecipacao
Proxies antecipar-parcela (Manual 013 v1.3 §2.1). The contract assumes "Suspenso por Antecipação de Parcelas" for every competência informed: it drops off the employer's loan listing for those competências, and the competências count toward parcelas pagas. The transition back to Ativo happens automatically at the competência's own virada — excluir-antecipar-parcela is the operation that undoes it early. The contract must be an averbação of the authenticated tenant that the rail acknowledged; anything else is 404 before the rail is called. X-Idempotency is required.



# Register a pre-existing (legado) loan
Source: https://docs.lerian.studio/en/reference/rails/consignado/incluir-consignado-emprestimo-legado

/en/openapi/v3-current/consignado.yaml post /v1/consignado/legacy-contracts
Proxies incluir-emprestimo-legado-trabalhador (Manual 007 v1.4 §3.1): registers a contract the tenant made BEFORE this rail's model existed. The worker becomes ineligible for new contracting on this rail until the legado contract is excluded or renegotiated. Dataprev performs no documental validation of legado contracts (§2.2.1.3) — the veracity of what is sent is the institution's own responsibility. When codigoTipoContrato is 2 (folha), codigoInscricaoEmpregador, numeroInscricaoEmpregador and matricula become required; this gateway proves that conditional before the rail is called, since neither the rail nor the official Swagger enforces it. X-Idempotency is required. A retried request that lands on the rail's own HX ("empréstimo já cadastrado") answers success rather than a refusal.



# List the tenant's averbação operations
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-averbacao-operations

/en/openapi/v3-current/consignado.yaml get /v1/consignado/averbacao-operations
Walks the tenant's own averbação operation book, oldest claim first.

It answers from a LOCAL table and never reaches the Dataprev rail, so it cannot answer 501 and it is served even on a deployment where averbação itself is switched off. That deployment simply has an empty book. Distinguishing "nothing is stuck" from "the convergence loop is off" is what GET /v1/consignado/capabilities is for: read the averbacao_recovery family there, not the status of this response.

The tenant is derived from the validated identity and is never read from the request. There is no tenant parameter on this operation.

Paging is keyset over the operation's own claim instant, which the table holds immutable by trigger, so a row's position never moves and a page can neither skip nor repeat. Send the previous page's page.next_after as after. has_more is true exactly when another page exists, and next_after is null exactly when it is false, so a client loop may terminate on either. The cursor never expires; a cursor this service did not mint is refused with 422 rather than silently restarting the scan from the top.

status may be repeated to narrow the page to several situations at once (status=averbacao_unknown&status=attachment_unknown). Omitting it means ALL eight situations, never none.



# List one contract's correction chain
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-contract-corrections

/en/openapi/v3-current/consignado.yaml get /v1/consignado/contracts/{numero_contrato}/corrections
Lists every correction one contract carries, so an operator can prove WHAT was superseded, in which order, and which correction is current.

A contract nobody has had to correct answers 200 with an empty list, never 404. Having never been corrected is a normal state of a registered contract, and a miss there would read as "no such contract".

One contract can carry SEVERAL independent chains: one for its CCB and one per corrected payment. They are laid end to end rather than interleaved, each ordered root first and head last, because there is no order BETWEEN chains and publishing one would invent a fact. Each item names its own `correction_type` and `payment_reference`, which is what tells the chains apart.

`is_head` is declared by the server and answers "which correction is current". The head is the one correction nothing supersedes, which is a TOPOLOGICAL property: deriving it from a timestamp can name an already-superseded row, so it is derived here once instead of once per client.

`supersedes_event_id` is null on a first CCB correction, and that null MEANS the original contract-registration fact. It travels as null rather than being omitted, so a reader never has to tell "no such field" apart from "supersedes the original".

There is NO paging and no cursor. The chain's order is topological, and a keyset needs a position that survives the next append, which supersession links are not. The answer is bounded at 200 items instead, and reaching the bound is REPORTED through `truncated` rather than swallowed: a cut nobody is told about reads as a complete audit trail on the one surface whose purpose is proving what was corrected. `truncated` is also true when a chain link points at a correction this answer does not carry, which means the same thing to the reader.

Three columns of the stored row never leave: the client's own transport key, and the gateway's object key and version id. The published `resource_uri` is the only address a caller is given, and it is the same path the correction fact names.

It answers from a LOCAL table and never reaches the Dataprev rail. It answers 501 on a deployment that composed no correction family, which is a deployment posture rather than a wrong URL. The tenant is derived from the validated identity and is never read from the request.



# List confirmed consignado contract registrations
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-contract-registrations

/en/openapi/v3-current/consignado.yaml get /v1/consignado/contract-registrations
Returns one tenant-scoped, commit-fenced page of confirmed Dataprev registration evidence.



# List the disbursement confirmations recorded for this tenant
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-disbursement-confirmations

/en/openapi/v3-current/consignado.yaml get /v1/consignado/disbursement-confirmations
Walks the confirmations client banks recorded against this tenant, most recently confirmed first: money the client says it ALREADY paid a worker.

'orphan' is the field to read first. It is true when this deployment holds NO averbado contract under the confirmation's contract number, which means a client reported paying against a contract that is not here. It is DERIVED on every read from the same predicate the antecipação gate uses, never stored: storing it would create a second owner of the truth about whether a contract exists, and the two would disagree the moment an averbação landed after its confirmation.

Filter with 'orphan=true' to see only those, or 'orphan=false' for the matched ones. OMITTING the parameter is the whole book, which is what an operator arriving with no filter is asking for.

'amount' is the canonical BRL decimal STRING the client asserted, byte for byte as it was recorded, and it is never re-rendered: 'payload_digest' is taken over exactly those bytes, so a reformatted number would stop re-deriving the digest a client checks its own receipt against.

'confirmed_at' is when THIS GATEWAY stamped the confirmation and it is what orders the book. 'paid_at' is when the CLIENT says the money left, which is declared rather than observed, so it never orders anything: a client may declare any instant it likes, and a late confirmation ordered by it would insert itself in the middle of a page an operator had already walked past.

There is deliberately NO time window. A confirmation is immutable and is never purged, and a window would hide exactly the old orphan nobody ever reconciled.

Paging is keyset over the gateway's stamp and the confirmation id. Send the previous page's page.next_after as after. has_more is true exactly when another page exists, and next_after is null exactly when it is false, so a client loop may terminate on either. The cursor never expires; a cursor this service did not mint is refused with 422 rather than silently restarting the walk from the top.

It answers from a LOCAL table and crosses no government boundary. It answers 501 on a deployment that composed no disbursement family, the same posture the confirmation intake answers there: a deployment that can never record a confirmation has none to report, and an empty page would say the opposite. The tenant is derived from the validated identity and is never read from the request.



# Read the payroll escrituração records included in a window
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-escrituracoes

/en/openapi/v3-current/consignado.yaml get /v1/consignado/reconciliation/escrituracoes
Reads the rail's consultar-escrituracoes-remuneracoes (Manual 005 v1.13 §3.3): every escrituração record included in the inclusion window, each carrying its OWN competência and Dataprev's pre-computed analise verdict, relayed verbatim. The window is mandatory and capped at 30 days by the rail (code GR); this gateway refuses a wider window locally. The read writes nothing: the reconciliation job's per-record done-keys are untouched, so a record read here is still delivered as a fact by the job.



# List the tenant's exclusion operations
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-exclusion-operations

/en/openapi/v3-current/consignado.yaml get /v1/consignado/exclusion-operations
Walks the tenant's own exclusion operation book, oldest claim first.

Exclusion is the product's IRREVERSIBLE operation: once the registry removes the payroll deduction there is no undo, so this queue is the surface an operator watches. The situation that matters most is outcome_unknown: the command was sent and the registry has not yet been observed answering it, which the exclusion recovery loop is still driving.

It answers from a LOCAL table and never reaches the Dataprev rail, so it cannot answer 501 and it is served even on a deployment where exclusion itself is switched off. That deployment simply has an empty book. Distinguishing "the queue is clear" from "the command was never composed" is what GET /v1/consignado/capabilities is for: read the exclusao family there, not the status of this response.

The tenant is derived from the validated identity and is never read from the request. There is no tenant parameter on this operation.

Paging is keyset over the operation's own claim instant and reference, the pair the table holds immutable, so a row's position never moves and a page can neither skip nor repeat. Send the previous page's page.next_after as after. has_more is true exactly when another page exists, and next_after is null exactly when it is false. The cursor never expires; a cursor this service did not mint is refused with 422 rather than silently restarting the scan from the top.

status may be repeated to narrow the page to several situations at once (status=claimed&status=invoking). Omitting it means ALL five situations, never none.

A quarantined row, a legacy operation whose authority could not be hydrated and which no worker converges, is present and MARKED, never filtered out. Hiding it would make an exclusion that happened indistinguishable from one that never did.



# List the credits ceded to the caller's own fund
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-fundo-creditos-cedidos

/en/openapi/v3-current/consignado.yaml get /v1/consignado/fundo/creditos
Returns the credits this fund actually OWNS.

Ownership is keyed on the cessão registration and on nothing else: a credit merely ATTRIBUTED to the fund — allocated to it, but with no cessão registered — is INVISIBLE here.

The fund is taken from the authenticated credential and is never read from the request: there is no fund parameter on this operation, and naming another fund anywhere in the request changes nothing. The tenant is derived from the validated identity the same way.

A bancarizador reading a fund it administers uses GET /v1/consignado/fundos/{id}/creditos instead, where the fund is named in the path and resolved against that bancarizador's own tenant.



# List the credits ceded to one fund the caller administers
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-fundo-creditos-cedidos-as-bancarizador

/en/openapi/v3-current/consignado.yaml get /v1/consignado/fundos/{id}/creditos
Returns the credits a fund you administer actually OWNS.

Ownership is keyed on the cessão registration and on nothing else: a credit merely ATTRIBUTED to the fund (allocated to it, but with no cessão registered) is INVISIBLE here, exactly as it is on the fund's own route.

This operation is for the BANCARIZADOR, which administers many funds and carries none on its credential, so it names the fund it means. The fence is the tenant plus that fund: the tenant is derived from the validated identity and is never read from the request, and the path id must resolve to a fund registered under THAT tenant. An id belonging to another tenant answers 404, identically to one that never existed. The reference the credit query runs on is the resolved fund row's own, so nothing else in the request narrows or widens it.

A fund reading its own credits uses GET /v1/consignado/fundo/creditos instead, where the fund comes from the credential and there is no fund parameter at all.



# List the tenant's registered funds
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-fundos

/en/openapi/v3-current/consignado.yaml get /v1/consignado/fundos
Returns every fund the tenant registered, active and deactivated alike. Tenant scope is derived from the validated identity; it is never taken from the request.



# List the outbox facts this gateway destroyed
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-invalid-events

/en/openapi/v3-current/consignado.yaml get /v1/consignado/event-delivery/invalid
Walks the terminal INVALID rows of this tenant's outbox, oldest first: the money facts this gateway DESTROYED.

A row here will never be published. Nothing retries it, and switching a relay on afterwards recovers nothing, so this page is a record rather than a queue. Nothing on this operation can move a fact: it is a read, and a screen that could retry a row would be a second publisher racing the dispatcher.

The event PAYLOAD never leaves the store. It is the whole envelope of the fact, business data and CPF included, and an operator deciding what to do about a destroyed fact does not need its body. The recorded failure text does not leave either: it travels as 'last_error_class', a MECHANISM, because a publish error can carry a tenant identifier, a contract number or a rail payload. 'unclassified' covers both a message no rule recognises and a row with no message at all, which are the same thing to an operator.

'event_type' is the stable relay type the dispatcher routed on, not the business fact's name: the concrete fact rides inside the envelope this read never opens. 'id' is what an operator quotes when asking for a fact to be replayed by hand.

There is deliberately NO status filter and NO time window. INVALID is the only status a cursor is correct over, because it is the only one nothing moves a row out of, and a window would hide exactly the old destroyed fact nobody ever noticed, which is what this surface exists to show.

Paging is keyset over the row's creation instant and its id. Send the previous page's page.next_after as after. has_more is true exactly when another page exists, and next_after is null exactly when it is false, so a client loop may terminate on either. The cursor never expires; a cursor this service did not mint is refused with 422 rather than silently restarting the scan from the top.

It answers from a LOCAL table and never reaches the Dataprev rail, so it cannot answer 501. The tenant is derived from the validated identity and is never read from the request.



# List the tenant's rail commands and the operations that leave no record
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-rail-commands

/en/openapi/v3-current/consignado.yaml get /v1/consignado/rail-commands
Walks the tenant's rail-command book, newest invocation first: what this gateway told the payroll rail to do, and what the rail answered.

It records TWELVE commands: refinanciamento, its reversal, renegociação, the origin-side portability exclusion, both antecipação de parcela operations, all three empréstimo legado operations, and the three contract-management ones (suspensão, reativação, alteração de termos). Each row carries the situation it is durably parked in, reported exactly as it stands: an invoking row whose deadline has passed is the row the recovery sweep will convert, and this read never anticipates that conversion.

'unlogged_operations' is a FIXED list rather than anything derived from the rows, and it names TWO operations, both on the portability path: averbarConsignadoPortabilidade and respondConsignadoPortabilityAuction. Their command services hold no durable store of any kind, so nothing on this side can report what the rail was told or what it answered, and an empty book is NOT evidence that no call departed — which matters because portability moves a consignado contract between institutions. The field is published even when empty, so a client can tell "no operation is unlogged" from "this gateway stopped reporting it"; a rail operation added later with no durable record of its own appears here too.

Not every command is CONVERGIBLE. A Manual 005 contract read decides the outcome of refinanciamento, its reversal, renegociação and the portability exclusion, so an ambiguous row of those four leaves outcome_unknown once the recovery pass reads the registry. The other eight have no such decisive read. A legado contract number, for instance, may be registered by an earlier attempt, another channel or the institution itself, so its presence proves the number is taken and not that this command committed. One of their rows that reaches outcome_unknown STAYS there. That is the truth about the call, not a queue nobody drains, and the situation filter is how you find them.

'unknown_at' SURVIVES on a closed row. An outcome that passed through ambiguity keeps that evidence, which is what lets a screen tell a clean acceptance from a recovered one. 'response_code' and 'response_message' are null on an invoking row, which the ledger's own constraint demands, and they are the refusal reason an operator came to this screen to read.

Three columns of the stored row never leave: the rail's raw answer, the request digest and the idempotency key. The first can carry fields no screen was meant to publish; the other two are the money fence's own transport evidence.

'command' and 'status' may each be repeated to narrow the page to several values at once (status=invoking&status=outcome_unknown). Omitting a filter means ALL of its values, never none. A value outside either vocabulary is refused with 422 rather than matching nothing, because a page that matched nothing is indistinguishable from a tenant that never called the rail.

Paging is keyset over the invocation instant and the row id, both frozen for the life of the row by the ledger's own trigger, which is what makes the position safe against a book the money path is still writing. Send the previous page's page.next_after as after. has_more is true exactly when another page exists, and next_after is null exactly when it is false, so a client loop may terminate on either. The cursor never expires; a cursor this service did not mint is refused with 422 rather than silently restarting the walk from the top.

It answers from a LOCAL table and never reaches the Dataprev rail, so it cannot answer 501 and it is served on a deployment with the rail off entirely. That deployment simply has an empty book. The tenant is derived from the validated identity and is never read from the request.



# List the repasse transfers the rail still owes this tenant
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-repasse-expectations

/en/openapi/v3-current/consignado.yaml get /v1/consignado/reconciliation/repasse-expectations
Walks the tenant's own repasse expectation book: the escriturated instalments whose transfer the rail still owes, oldest deadline first, undated promises last.

READ THE FRESHNESS STAMP BEFORE THE ROWS. An empty list under a state other than fresh DOES NOT MEAN nothing is missing. When the reconciliation pass cannot seed the tenant database it returns before the D+2 detector runs, publishing neither an alarm nor the "I do not know" fact, so that outage class is indistinguishable from health unless the stamp is read. state is fresh, stale or never. never covers a deployment that never composed reconciliation, a deployment whose rail credentials never worked, and every tenant that is not the pass's one canonical tenant. stale additionally covers a stamp this deployment could not read at all: that is not a claim that reconciliation never ran, and last_clean_read_at is then null under a stale state rather than under never.

The clean-read instant is DURABLE and shared by every replica whenever the stamp was recorded and can be read, so a restarted process answers for a pass it did not run and two reads of the same tenant agree. Two reads that DISAGREE therefore name a problem with the shared stamp and never two processes holding different clocks: a replica that cannot read the stamp answers stale with a null last_clean_read_at, while a replica whose own pass read the rail cleanly still answers from what it knows when the stamp was never recorded at all. freshness.observed_replica is the opaque tag of the ONE PROCESS that answered this request, kept because the rows and the census are still read through one process's connections. It is never a hostname and never a pod name.

It answers from the LOCAL BOOK and never reaches the Dataprev rail, so it cannot answer 501 and it is served on a deployment with no reconciliation composed at all - that deployment answers 200 with an empty book, an empty scope census and state never.

scopes censuses the OPEN promises by employer scope. A scope with in_scope false is an ORPHAN: promises written under an employer scope this deployment no longer reconciles, whose repasse now arrives under a different key and closes nothing, so they alarm forever for money already in the bank. An empty cnpj is a legal scope and is the rail-wide read's own name, never a missing value.

scopes IS ANSWERED ON THE FIRST PAGE ONLY and is null on every page requested with a non-blank after. A blank or whitespace-only after is a first-page request and is censused like an omitted one. The census is unfiltered and unpaged by design, so it describes the whole book rather than the page and is asked once per scan. Read it from the first page. null means it was not asked on this page; an empty list is the different, stated fact that no employer scope holds an open promise. freshness, by contrast, travels on every page.

There is deliberately NO time window. The rail's own reads carry one because the rail demands it; imposing one here would hide exactly the old promise nobody ever closed, which is what this board exists to show.

Paging is keyset over (due_at nulls last, competencia, numero_contrato, cnpj), EXACTLY the order the D+2 alarm walks, so the board and the alarm can never disagree about which deadline is next. Send the previous page's page.next_after as after. has_more is true exactly when another page exists, and next_after is null exactly when it is false. The cursor never expires; a cursor this service did not mint is refused with 422 rather than silently restarting the scan from the top.

situation may be repeated to narrow the page to several situations at once (situation=open&situation=overdue). Omitting it means ALL FOUR, never none. undated is a promise whose deadline was not computable, which is a durable STATE and not missing data: nothing ever back-fills it, so it can never become overdue.



# Read the CEF D+2 repasse transfers included in a window
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-repasses

/en/openapi/v3-current/consignado.yaml get /v1/consignado/reconciliation/repasses
Reads the rail's consultar-repasse-pagamentos (Manual 005 v1.13 §3.4): the per-registro CEF D+2 transfers included in the inclusion window, each with its own competência, guia and transfer instant. The existence of a registro IS the liquidation — the rail publishes no status field. Same mandatory 30-day-capped window as escriturações, and the same no-write discipline: the job's done-keys are untouched.



# List what each averbado contract of this tenant still owes
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-saldo-devedor-obrigacoes

/en/openapi/v3-current/consignado.yaml get /v1/consignado/saldo-devedor
Walks the tenant's saldo devedor obligation book, lowest contract number first: what each averbado contract still owes, as this gateway itself reports it to the payroll rail under M015.

'valor_saldo_devedor' is DERIVED on every read and never stored: the present value, at today's Brasília date, of every instalment still ahead whose competência has not amortized (an antecipação need not be the next one), discounted at the contract's own monthly rate as valor_parcela / (1 + taxa_mensal)^(days/30) and assuming on-time payment. It is published BESIDE 'valor_parcela', 'numero_parcelas', 'parcelas_pagas', 'taxa_mensal' and 'data_primeiro_desconto' precisely so a client can redo the discounting and see the same figure the rail is given on a send that day. 'valor_parcela' is republished byte for byte as the schedule stores it and is never re-scaled, because a reformatted number would make the screen and the rail report two spellings of one amount.

'quitado' is likewise derived, as parcelas_pagas >= numero_parcelas, the same predicate the M015 clock's own scan filters on. It is not a stored flag, because two owners of that fact would disagree.

Filter with 'quitado=true' for the settled obligations or 'quitado=false' for the ones still paying. OMITTING the parameter is the whole book, which is what an operator arriving with no filter is asking for, and it is the only way to see a settled obligation at all: the table's own index deliberately excludes them, and they are exactly the rows a client reconciling a finished contract comes to check.

'proximo_marco' is always null. 'ultimo_envio_at' is null until this gateway has reported the obligation at least once, and it travels as null rather than as the zero instant.

The worker's CPF is deliberately absent from every row. It is on the table only because M015 resends it on each report, and this screen answers its question without it.

Paging is keyset over the contract number, which is half the table's own primary key, so the page costs an index walk and no sort. Send the previous page's page.next_after as after. has_more is true exactly when another page exists, and next_after is null exactly when it is false, so a client loop may terminate on either. The cursor never expires; a cursor this service did not mint is refused with 422 rather than silently restarting the walk from the top.

It answers from a LOCAL table and never reaches the Dataprev rail, so it cannot answer 501 and it is served on a deployment with the rail off entirely. The tenant is derived from the validated identity and is never read from the request.



# Report this process's scheduled Consignado loops
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-scheduled-jobs

/en/openapi/v3-current/consignado.yaml get /v1/consignado/jobs
Reports every scheduled Consignado loop this process knows about, whether or not it is running.

THE ANSWER IS PROCESS MEMORY. One request is served by ONE replica and reports that replica alone, so two reads of this operation may disagree, by design rather than by fault. 'observed_replica' is what makes the disagreement legible: it is an opaque, stable per-process tag, never a hostname and never a pod name. Counters and stamps reset when a process restarts.

The row set is fixed and complete: every loop in the inventory appears, including one this deployment did not compose. That is the point of the surface. Three conditions read differently, and conflating them is what leaves an operator acting on the wrong thing:

started true is a loop this process put on the scheduler. 'passes' and 'failures' count what it has done since the process came up.

started true is always accompanied by a 'reason' of enabled, whatever its family reports: a loop can be gated by its own boot flag rather than by its family's, and a running loop is running.

started false with a 'reason' of flag_off, portal_store_absent or rail_client_absent is a loop this deployment never composed. The loop never reached the scheduler at all, so it has no counters and no stamps. 'family' names the operation family, and GET /v1/consignado/capabilities carries the same vocabulary for the family as a whole. The deployment flag behind the decision is deliberately not named: a flag name is operator material.

started false with a 'reason' of enabled, or with no reason at all, plus a 'last_error_class' of scheduler_refused, is the third condition: the registration reached the scheduler and the scheduler REFUSED it, so no worker was started. It is a wiring fault rather than a posture, and it is the one an operator has to escalate.

No loop runs a pass at process start. Every loop's first pass is delayed and staggered per replica, so 'last_pass_started_at' is null for some time after a deploy on a healthy process.

'last_error_class' is the class of the MOST RECENT error, not the outcome of the last pass. It is not cleared by a later success, deliberately: a one-second loop would otherwise erase its own failure before anyone could read it. 'failures' beside it is what says whether the loop is still failing. The class names a mechanism and never carries the error message, because a pass error can carry a tenant identifier, a contract number or a rail payload.

'overruns' and 'max_in_flight' are populated only for the one fixed-rate loop and are null everywhere else, where null means 'does not apply' rather than 'measured none'.

Nothing here is tenant data: the answer is identical for every tenant this process serves. The tenant is still derived from the validated identity, as on every other operation, and is never read from the request.



# List this tenant's outbound Dataprev rail throughput transitions
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-consignado-throughput-history

/en/openapi/v3-current/consignado.yaml get /v1/consignado/throughput/history
Walks this tenant's append-only outbound-rail throughput chain, newest transition first: every rate the tenant has held, when it changed, and who changed it.

It is the SIBLING of GET /v1/consignado/throughput and never a replacement for it: that read answers what the tenant is paced at right now, and this one answers how it got there.

'sequence' is the chain's own authority on order and is the ONLY column this read sorts by. 'changed_at' is reported and never ordered by, because a wall clock stamped by whichever replica served the change would let two links swap places under clock skew.

'previous_requests_per_second' is null on sequence 1 and on no other link. A stored ZERO is a real predecessor and means the tenant was coming off a pause, so absent and zero never share a spelling here.

'requests_per_second' of zero is a deliberate self-service pause, not an absent value. 'changed_by' names the actor: the gateway's own reserved system actor marks the automatic first grant, which is how a rate somebody chose is told apart from the floor the gateway opened the chain at.

The rows are reported AS STORED, and this read asserts nothing about the sequence advancing by exactly one. The plus-one step lives in the write path under an advisory lock and the table enforces only uniqueness and the first-link rule, so a reader that refused a jump would be claiming a guarantee nothing makes. A consumer that cares about continuity verifies what it received.

A tenant that never changed its rate reads as an EMPTY page and never as a not-found: never having changed the rate is an ordinary state.

There is deliberately no time window. A window would hide exactly the old transition an operator is looking for when they ask why a client is paced the way it is.

Paging is keyset over the sequence. Send the previous page's page.next_after as after. has_more is true exactly when another page exists, and next_after is null exactly when it is false, so a client loop may terminate on either. The cursor never expires; a cursor this service did not mint is refused with 422 rather than silently restarting the walk from the head.

It answers from a LOCAL table and never reaches the Dataprev rail, so it cannot answer 501. The tenant is derived from the validated identity and is never read from the request.



# List the tenant's hub subscriptions
Source: https://docs.lerian.studio/en/reference/rails/consignado/list-subscriptions

/en/openapi/v3-current/consignado.yaml get /v1/subscriptions
Returns the tenant's streaming-hub subscriptions (keyset-paginated). Tenant scope is derived from the validated identity; it is never taken from the request.



# Set this tenant's outbound Dataprev rail throughput
Source: https://docs.lerian.studio/en/reference/rails/consignado/put-consignado-throughput

/en/openapi/v3-current/consignado.yaml put /v1/consignado/throughput
Sets the tenant's own outbound Dataprev rail rate, within the rail's 0..25 contract. A value outside that range is refused naming the rejected value; zero is accepted and pauses this tenant's outbound rail. Setting the value the tenant already holds succeeds without recording a transition. The change is durable and published as one fact; the serving replica applies it on its very next exchange, and every other replica converges within the pace cache TTL.



# Reactivate a suspended contract
Source: https://docs.lerian.studio/en/reference/rails/consignado/reactivate-consignado-contract

/en/openapi/v3-current/consignado.yaml post /v1/consignado/contracts/{numero_contrato}/reactivate
Proxies reativar-consignado-trabalhador (Manual 003 §3.5). Same tenant-ownership proof and idempotency requirement as suspend.



# Read the cadastro stored with a consignado averbação
Source: https://docs.lerian.studio/en/reference/rails/consignado/read-the-cadastro-stored-with-a-consignado-averbacao

/en/openapi/v3-current/consignado.yaml get /v1/consignado/contracts/{numero_contrato}/dados-cadastrais
Returns the cadastro the client sent with the averbação — `dados_cadastrais` plus `nome_trabalhador` — as the exact bytes stored at averbação time. Their SHA-256 is the `dados_cadastrais_digest_sha256` that consignado.contract.registered published, so the consumer verifies the body against the fact and never parses before verifying.

A contract with no cadastro, a missing contract and another tenant's contract share the same 404. The tenant comes from the validated identity; a fund credential reads only contracts of its own fund.



# Refinance one or more active contracts into a new one
Source: https://docs.lerian.studio/en/reference/rails/consignado/realizar-consignado-refinanciamento

/en/openapi/v3-current/consignado.yaml post /v1/consignado/contracts/{numero_contrato}/refinanciamento
Proxies realizar-refinanciamento-trabalhador (Manual 008 v1.10 §3.1): quits every contract named in listaContratosQuitadosTrabalhador and averbates the new contract that replaces them, reserving margin until the refinanciamento closes. Every quitado contract must be an averbação of the authenticated tenant that the rail acknowledged; anything else is 404 before the rail is called — whether that contract is currently ACTIVE on the government registry is left to the rail's own judgment. With garantia (temGarantias=true), the refinanciamento may only relate 1:1 (regra FR, at most one quitado contract) and must inform at least one of the three garantia values (regra FI). X-Idempotency is required.



# Record a correction to a registered contract
Source: https://docs.lerian.studio/en/reference/rails/consignado/record-consignado-contract-correction

/en/openapi/v3-current/consignado.yaml post /v1/consignado/contracts/{numero_contrato}/corrections
Records a correction to something the client already asserted about a registered contract, and publishes the fact that names it.

This is NOT a Dataprev operation: no rail credential is used and no government boundary is crossed. Manual 005 revision 1.13 states the rail's retification fields are no longer used and always return null, so the client is the only authority a correction can have — `source_authority` is always `client`.

NOTHING IS MUTATED. A correction is an append that names what it supersedes, and the record it corrects stays immutable in the database exactly as it was. Correcting the same thing twice appends a second correction that supersedes the first.

The gateway takes custody of the corrected resource and computes its SHA-256 itself; a client-declared digest is never accepted. The published fact carries a same-origin path back to this gateway plus that digest, and the consumer fetches and verifies it over authenticated M2M.

| correction_type | payment_reference | supersedes |
|---|---|---|
| `ccb` | must be empty | the previous CCB correction, or nothing on the first |
| `disbursement` | required | the confirmed payment it repairs, then the previous correction of that payment |

A disbursement correction naming a payment this deployment holds no confirmation for is refused with 404: a supersession pointing at nothing is worse than no correction.

X-Idempotency is mandatory, opaque, 1..128 bytes, and never defaulted. PostgreSQL is the authority: the same key replays the identical 202 body and publishes no second fact, and the same key carrying a different correction answers 422 without ever returning the earlier body.



# Register a credit's cessão to its attributed fund
Source: https://docs.lerian.studio/en/reference/rails/consignado/register-consignado-cessao

/en/openapi/v3-current/consignado.yaml put /v1/consignado/leilao/bid-submissions/cessao
Registers one credit's cessão and establishes the fund's ownership boundary. A prior fund attribution alone does not open fund-scoped reads.

The bancarizador identifies the credit with the idempotency_key used for the bid and the fund that signed the endosso. The credit must already be attributed to that exact fund; a credit without an attribution or attributed to another fund is rejected.

The operation is idempotent. Registering the same credit and fund again returns the durable state instead of creating a second row or feed fact. cedido starts false and becomes true only through this registration.



# Renegotiate a contract closed by employment-link termination
Source: https://docs.lerian.studio/en/reference/rails/consignado/renegociar-consignado-contract

/en/openapi/v3-current/consignado.yaml post /v1/consignado/contracts/{numero_contrato}/renegociacao
Proxies renegociar-consignado-trabalhador (Manual 006 v1.12 §2.3): renegotiates a contract closed in situação 15 ("Encerrado por término de vínculo") into a new one against the worker's new employment bond. numeroContratoEncerrado must be an averbação of the authenticated tenant that the rail acknowledged, and must differ from the new contract number in the path; that is checked here, before the rail is called. Whether the closed contract actually sits in situação 15, whether the new bond is elegível or inelegível only by motivo 8, and whether valorParcela stays within the closed contract's own instalment (regra BL) are live registry facts this gateway holds no local copy of and defers to the rail's own judgment. valorIOF is required, following the manual rather than the mirrored Swagger's required list. X-Idempotency is required.



# Renegotiate one or more legado loans into a new contract
Source: https://docs.lerian.studio/en/reference/rails/consignado/renegociar-consignado-emprestimo-legado

/en/openapi/v3-current/consignado.yaml post /v1/consignado/legacy-contracts/renegociacao
Proxies renegociar-emprestimo-legado-trabalhador (Manual 007 v1.4 §3.3): folds every contract named in contratosLegados into a single new Plataforma contract. codigoTipoRenegociacao selects Padrão (1) or Portabilidade (2); this gateway proves the structural half of the Portabilidade rules before the rail is called — numeroUnico populated only under Portabilidade, at least one item carrying it, and no two items sharing the same one — while whether the requester actually holds each legado contract, whether an existing folha (tipoContrato=2) contract was included, and whether the new rate undercuts the original are left to the rail's own judgment (Dataprev performs no documental validation of legado contracts, §2.2.1.3). On Portabilidade (§2.2.1.3): the ported contract itself is NOT excluded automatically — exclusion is the origin bank's own responsibility; every contract of the REQUESTER that carries no numeroUnico is excluded automatically once the operation completes; and any troco (change) is only permitted when every contract INVOLVED in the operation — including the ported one itself — is fully settled (§2.2.1.3). A SUCCESSFUL round trip is codigo SUCESSO with a non-empty numeroContrato: read codigo and errosContratosPortados in the response body — the rail can report per-legado-contract failures inside that same 200 while the new contract still averbates; any other codigo means no new contract was minted and surfaces as a 422 naming the rail's own code. X-Idempotency is required; this operation names no idempotency pair of its own, so a retry is refused by the rail on its own terms.



# Reveal a subscription's full destination (admin only)
Source: https://docs.lerian.studio/en/reference/rails/consignado/reveal-subscription-endpoint

/en/openapi/v3-current/consignado.yaml get /v1/subscriptions/{id}/endpoint
Returns one subscription's FULL delivery destination, unmasked: the webhook URL with its path and query, the queue URL with its account id, the exchange/routing-key pair, the bus name, or the synthesized pull:// URL.

ADMIN ONLY. Every other read on this surface answers with 'endpoint_display', the show-safe rendering of the destination. This route is the one that does not, and the reason it is fenced is that a destination is a CAPABILITY, not a description of one: a webhook path routinely carries a per-subscription callback token, and anyone holding the full value can be delivered to. The operator and viewer roles are refused here by this gateway's own authorization chain, before the request reaches the hub.

The body carries EXACTLY ONE key. No secret, no credential status, no other column of the row: this route answers a single question, and a body that grew the row's other fields would put them behind the admin action as a side effect of nobody deciding to.

The 200 carries 'Cache-Control: private, no-store'. The body is a live delivery capability rather than a view of one, so it must not reach a browser's disk cache, a synced profile or a forward proxy, where it would outlive the session entitled to it.

This is a FORWARD, not a local read: the gateway owns no subscription storage. The hub answers an unknown subscription, a soft-deleted one and another tenant's with the SAME 404, publishing no existence oracle, and that 404 reaches the caller unchanged. That uniformity matters more here than anywhere else on the surface: this route is reached with a strictly stronger grant, so a refusal that read differently would let an administrator of one tenant confirm that an id belongs to another.

The tenant is derived from the validated identity and is never read from the request.



# Reverse a refinancing within its 7 business day window
Source: https://docs.lerian.studio/en/reference/rails/consignado/reverter-consignado-refinanciamento

/en/openapi/v3-current/consignado.yaml post /v1/consignado/contracts/{numero_contrato}/refinanciamento/reversao
Proxies reverter-refinanciamento-trabalhador (Manual 008 v1.10 §3.2): the new contract is excluded and every contract it quitou returns to ativo. motivoReversao is a closed set (1 Desistência, 2 Óbito, 3 Fraude). ONLY a refinanciamento this gateway itself registered can be reversed here: the contract must be backed by an accepted refinanciamento of the authenticated tenant that no accepted reversal has already excluded, and anything else is 404 before the rail is called — a refinanciamento made outside this gateway (through the Dataprev Portal, say) has to be reversed there too. The 7-business-day window is judged against the gateway's OWN record of when that refinanciamento committed, never against a date in the request, and it refuses locally only once the window has unambiguously passed; the rail remains the final judge. X-Idempotency is required.



# Revoke a hub subscription
Source: https://docs.lerian.studio/en/reference/rails/consignado/revoke-subscription

/en/openapi/v3-current/consignado.yaml delete /v1/subscriptions/{id}
Soft-deletes the tenant's subscription. Idempotent: revoking an already-revoked subscription succeeds.



# Rotate a subscription signing secret
Source: https://docs.lerian.studio/en/reference/rails/consignado/rotate-subscription-secret

/en/openapi/v3-current/consignado.yaml post /v1/subscriptions/{id}/rotate
Rotates the subscription's signing secret and returns the new once-shown secret plus the overlap window during which the previous secret still verifies. The console never stores the secret.



# Suspend payroll deduction for an averbado contract
Source: https://docs.lerian.studio/en/reference/rails/consignado/suspend-consignado-contract

/en/openapi/v3-current/consignado.yaml post /v1/consignado/contracts/{numero_contrato}/suspend
Proxies suspender-consignado-trabalhador (Manual 003 §3.4). The contract must be an averbação of the authenticated tenant that the rail acknowledged; anything else is 404 before the rail is called. X-Idempotency is required. Competência is calculated by the rail and is never sent. Reversible by the reactivate operation.



# Send a synchronous test delivery
Source: https://docs.lerian.studio/en/reference/rails/consignado/test-subscription-delivery

/en/openapi/v3-current/consignado.yaml post /v1/subscriptions/{id}/test-delivery
Sends a synchronous signed test delivery to the subscription's endpoint via the hub's production delivery path and returns the outcome and sink status.



# Cancel a PIX Automatico authorization
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/cancel-a-pix-automatico-authorization

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/authorizations/{idRecorrencia}/cancel
Cancels a recurring-payment authorization (JDPI 4.3.5), transitioning it to Cancelled and soft-deleting the local row. Returns the cancellation id (idCancelamento). Optional ispb names the direct participant this write acts for: named, the recurrence row has to be booked in that participant's books, or the answer is 404 PIX-0147 before JDPI is asked; an ISPB this deployment does not act as is 422 PIX-0128, before the row is read.



# Cancel a PIX key claim
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/cancel-claim

/en/openapi/v3-current/pix.yaml delete /v1/claims/{claimId}
Abandons a claim. Either side may call it - the claimer giving up, or the holder refusing to hand the key over (§8.2.11). claimId is in the path; the body carries key and accountId. The claim must resolve to a local row for the pair (claimId, your account), else 404 PIX-0020.

What reaches DICT depends on how far the claim got, and the counterparty can tell the difference. A row at status 5, 6 or 7 is live at DICT and is cancelled there. Anything else - notably status 4, recognised as claimable but never opened at DICT - is cancelled locally with NO DICT call, which is the fail-closed direction, because a spurious DICT cancel is the step that has no undo. The reason follows the §8.2.11 matrix for the side and the claim type: a claimer (status 5 or 7) sends 0 = user request; a DONOR (status 6) sends 0 for a portability claim but 4 = fraud for a possession claim, because 4 is the only value the Posse-Doador column accepts - so a possession refusal is recorded at Bacen as fraud rather than as a preference.

Either way the key row ends CANCELLED (-1) and soft-deleted. CANCELLED is terminal - the state machine has no edge out of it - so the claim cannot be revived; start over with POST /v1/entries followed by POST /v1/claims.

Which of this deployment's direct participants writes to the national directory is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo.



# Change a PIX key entry
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/change-a-pix-key-entry

/en/openapi/v3-current/pix.yaml put /v1/entries/{entryId}
Re-points an existing PIX key to a new transactional account and/or a new owner name inside the SAME participant (§8.2.02 Alterar Chave de Endereçamento). entryId is the key VALUE, URL-encoded, and it never changes - no operation in this API edits a key's value.

Only the destination travels in the body: newBranch, newAccountType, newAccount, accountOpeningDate, newName and newTradeName, all optional per the spec. The owner identity (ISPB, CPF/CNPJ, person type) is derived server-side from accountId and is never read from the payload. reason is required and is DICT's reason code: 0=Customer Request, 2=Branch Transfer, 6=Reconciliation, 8=Receita Federal Validation; an EVP (RANDOM) key must not use 0.

When the change moves the key to another account (newAccount or newAccountType differs from accountId's own), the plugin clears the account link on the holder's local rows of the key, so every account of the holder lists it until it is deleted; a change that keeps the key on its account leaves the rows alone. DICT may open a possession or portability claim as a consequence of the change; when it does, the response carries claimOpenedAt. Failures are DICT's, translated into the PIX-1xxx family - an unknown key is 404 PIX-1011.

Which of this deployment's direct participants writes to the national directory is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo.



# Conclude a PIX key claim
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/complete-claim

/en/openapi/v3-current/pix.yaml post /v1/claims/{claimId}/conclusion
Finishes a claim you opened once the holder has accepted it. You are the CLAIMER, and this is where DICT binds the key to your account (§8.2.12). claimId is in the path; the body carries key and accountId. It is the point of no return - §8.2.12 offers no undo.

Everything checkable is checked first. The claim must still appear in DICT's in-flight listing (§8.2.08, walked across pages so a claim past page one is still found); a local row must exist for the pair (claimId, your account); that row is projected to status 7, the holder gave it away; and a row that cannot legally reach FINALIZED is refused with 422 PIX-0073 before DICT is touched. A claim missing from the listing, or one with no local row, is 404 PIX-0020.

On success your key row becomes FINALIZED (0) and the key is yours. The donor's own row is soft-deleted when it belongs to a different account: it keeps its DONATED status and simply stops appearing in that account's listing. Note that POST /v1/entries/{entryId}/confirmation also concludes a confirmed claim on the same key, so a transfer can be completed through either route.

Which of this deployment's direct participants writes to the national directory is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo.



# Confirm a PIX Automatico authorization
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/confirm-a-pix-automatico-authorization

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/authorizations/{idRecorrencia}/confirm
Confirms, as the payer's PSP, a recurring-payment authorization read from a QR (JDPI 4.3.3, journeys 2-4). An existing payer-side authorization moves to Active; with none, the confirmation creates it, Active, once the payer agency/account is proved to belong to the payer document and to be bound to a ledger account; contractNumber, payer.cpfCnpj and payer.account are required on every confirmation. createdDateTime and authorizedAt are required on every confirmation, so a retry sends JD the same body. When the payer row already exists here, payer.ispb has to name the participant it is booked under, or the answer is 404 PIX-0147 before JDPI is asked — a replay included; an ISPB this deployment does not act as is 422 PIX-0128, before the row is read.



# Confirm a PIX key claim
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/confirm-claim

/en/openapi/v3-current/pix.yaml post /v1/claims/{claimId}/confirmation
Accepts a claim someone opened on YOUR key: you are the DONOR - the Cliente Doador - agreeing to hand it over (§8.2.10). claimId is in the path; the body carries key and accountId.

Every check is local and runs BEFORE DICT, because the DICT confirmation has no undo and a refusal afterwards would leave the claim confirmed at Bacen while the caller was told the call failed. A claim row with that id must exist; your account must OWN the key named in the body, else 404 PIX-0069; and that key must be the one the claim targets, else 404 PIX-0020. The row must also stand at status 6 - I hold this key and must decide - and any other status, including a CLAIMER's own row at status 5, is 422 PIX-0073 before DICT is called.

DICT is sent reason 0 (user request), the only value §8.2.10 accepts in both donor columns. On success your key row becomes DONATED (3), which is terminal on your side: the state machine has no edge out of it, the key stops being yours, and only the claimer can finish the transfer with POST /v1/claims/{claimId}/conclusion.

Which of this deployment's direct participants writes to the national directory is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo.



# Confirm PIX key ownership
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/confirm-key

/en/openapi/v3-current/pix.yaml post /v1/entries/{entryId}/confirmation
Confirms ownership of an EMAIL or PHONE key with the 6-digit code POST /v1/entries delivered. entryId is the key VALUE, URL-encoded; the body carries token and accountId. On success the key is registered at DICT and the local row becomes FINALIZED (0); if that registration comes back claim-pending instead, the response carries THAT status and no key was bound.

The route is dual-purpose, and the second purpose runs FIRST and ignores the code entirely: if DICT reports a CONFIRMED claim on this key - the holder has already agreed to give it away - the service concludes that claim at DICT (§8.2.12), soft-deletes the local pending row, and answers 200 with an EMPTY CreateEntryResponse - the JSON object {}, because every field is omitempty - and NOT an absent body. A generated client deserializes it normally; what it reads is every field unset, which is the signal that this branch ran and no key was bound here. That conclusion is irreversible, so a caller expecting a rejected code can find the transfer completed instead.

Otherwise the code decides. It is matched by hash, so a code that fits no pending row of this account is 401 PIX-0059 - the same answer as a missing code, with nothing in the response distinguishing the two. A row that is not awaiting confirmation is 422 PIX-0073.

Which of this deployment's direct participants writes to the national directory is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo.



# Consult a PIX Automatico authorization cancellation
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/consult-a-pix-automatico-authorization-cancellation

/en/openapi/v3-current/pix.yaml get /v1/pix-automatico/authorizations/{idRecorrencia}/cancel/{idCancelamento}
Consults the live JDPI situation of an authorization cancellation (JDPI 4.3.6), keyed by (idRecorrencia, idCancelamento).



# Consult a PIX Automatico authorization situation
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/consult-a-pix-automatico-authorization-situation

/en/openapi/v3-current/pix.yaml get /v1/pix-automatico/authorizations/{idRecorrencia}
Consults the live JDPI situation of a recurring-payment authorization (JDPI 4.3.4), projecting the JDPI situation axes onto the local authorization status.



# Create a CobV (due-date) composite PIX Automatico QR code
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/create-a-cobv-due-date-composite-pix-automatico-qr-code

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/composite/cobv
Generates a composite PIX QR code embedding due-date dynamic-QR data (due-date charge) and a recurring-payment authorization (PIX Automatico). The recipient name and city are CRM-sourced from the account. 422 PIX-0139 when the account's record names a different institution than the one minting the QR code; nothing is sent to JDPI.



# Create a recurrence-only composite PIX Automatico QR code
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/create-a-recurrence-only-composite-pix-automatico-qr-code

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/composite/recurrence
Generates a composite PIX QR code carrying ONLY a recurring-payment authorization (PIX Automatico), with no static or dynamic QR data. The recipient city is CRM-sourced from the account. 422 PIX-0139 when the account's record names a different institution than the one minting the QR code; nothing is sent to JDPI.



# Create an immediate dynamic composite PIX Automatico QR code
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/create-an-immediate-dynamic-composite-pix-automatico-qr-code

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/composite/dynamic
Generates a composite PIX QR code embedding immediate-dynamic-QR data and a recurring-payment authorization (PIX Automatico). The recipient name and city are CRM-sourced from the account. 422 PIX-0139 when the account's record names a different institution than the one minting the QR code; nothing is sent to JDPI.



# Open a PIX key claim
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/create-claim

/en/openapi/v3-current/pix.yaml post /v1/claims
Opens a DICT claim on a PIX key that another participant currently holds. You are the CLAIMER - the Cliente Reivindicador of §8.2.07 - and the body carries only key and accountId, because the claim TYPE is not yours to choose: the service decides it, portability when the key's holder document at DICT equals your account document and possession otherwise, which is the rule §8.2.07 states.

The precondition the body does not show is the one that fails most often. The key must ALREADY sit on this account as a claim-pending row (status 4), and the only thing that creates one is POST /v1/entries answering that DICT recognised the key as claimable. Claiming a key you never tried to register is 422 PIX-0073. For a CPF or CNPJ key your account document must equal the key value, else 422 PIX-0086. The call is idempotent: a row already carrying a claim id returns that claim instead of opening a second one.

On success the row moves to status 5 - waiting for the holder to hand the key over. §8.2.07 gives the holder a deadline to read the claim and then a further deadline to accept or refuse it; this service neither enforces nor exposes those windows, so track the outcome with GET /v1/claims?status=processing or GET /v1/entries. Per §8.2.07 an EVP (RANDOM) key cannot be claimed at all - mint a new one instead.

Which of this deployment's direct participants writes to the national directory is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo.



# Create an immediate dynamic PIX QR code
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/create-dynamic-qr-code

/en/openapi/v3-current/pix.yaml post /v1/qrcodes/dynamic
Generates an immediate dynamic PIX QR code and persists its conciliation metadata. The plugin sends the JWS host URLs (urlPayloadJson / urlJwk) to JDPI and self-hosts the signed JWS, so the returned QR is end-to-end resolvable; the response carries the resolvable payload URL the EMV embeds. cobv (due-date) and saque/troco variants are not supported.

WHAT indirectId DECIDES HERE IS WHO SERVES THE QR, and it is a decision about hosting rather than about whose charge it is. This participant may serve INDIRECT participants — institutions registered with POST /v1/indirects. Most of them need nothing here: by default a QR raised for one of them is signed with THIS participant's certificate and its payload is hosted on THIS participant's domain, which is the ordinary arrangement and the one nearly every institution wants. An institution that has opted into holding its OWN certificate is the exception, and only for it does indirectId change anything: JDPI then signs with that institution's certificate, the payload URL is built on that institution's own domain, and the signed document comes back to you to host there. Certificate and domain are ONE decision, never two — the payer's app validates the signature against the certificate published at the domain that answered, so signing with one party's certificate while hosting on another's does not validate.

⚠️ indirectId IS REFUSED 422 PIX-0111 WHILE THIS TENANT'S INDIRECT-PARTICIPANTS FEATURE IS SWITCHED OFF, and the refusal names the setting an operator has to turn on. It is never dropped: a QR minted as if you had sent none would be signed with THIS participant's certificate and published on THIS participant's domain, so you would have asked for one institution's QR and silently received another's. Send no indirectId and the QR is generated exactly as it always was.

Refusals specific to indirectId — all decided before JDPI is called, so a refused QR is never generated: 422 PIX-0111 when this tenant's indirect-participants feature is off (the value is refused rather than parsed, so none of the others can be reached); 404 PIX-0095 for an id that addresses no institution registered in this tenant (a malformed UUID lands here too — it can address none); 422 PIX-0100 when the institution it names is not ACTIVE; 422 PIX-0113 when that institution's registered public base URL names a host a payer's app cannot resolve; 422 PIX-0112 when the composed payload URL exceeds the 77 characters BACEN allows — the path this participant is configured with spends most of that budget, so an institution's hostname must be chosen against the remaining allowance BEFORE it is registered, not after.

When indirectId names an indirect that hosts its OWN certificate, the signed JWS comes back in payloadJws and the plugin does NOT store it — the indirect hosts it at payloadUrl on its own infrastructure, so THIS RESPONSE IS THE ONLY DELIVERY OF IT. If the response never reaches you (client timeout, connection reset, proxy error) the charge nevertheless exists at JDPI, and re-sending the same recipientConciliationId is refused as a duplicate (PIX-0065). Recover it, do not re-create it: call GET /v1/qrcodes/list with qrCodeType 12 over the registration window, match your own recipientConciliationId to read its documentId, then call PUT /v1/qrcodes/dynamic/{documentId} with the SAME indirectId — the update re-signs the charge and returns a fresh payloadJws (JDPI §8.3.5 returns payloadJws on every update). The update mints a NEW payloadUrl and a regenerated EMV payload, so it REPLACES the lost QR rather than reproducing it; host the new payloadJws at the new payloadUrl and distribute the new qrCode.

Hosting the payload is not the whole obligation: an institution serving its own domain must ALSO publish, at that domain, the key set the payer's app validates the signature against. It cannot produce that key set itself — JDPI holds the certificate and does the signing — so read it with GET /v1/indirects/{indirectId}/jwks and serve those bytes verbatim, re-reading whenever the certificate is rotated. A payload served without a matching key set fails validation at the payer, silently: the QR scans, the app fetches the document, and the payment does not go through.

Which of this deployment's direct participants acts is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own customers and its own JDPI credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. For an indirect participant: 422 PIX-0141 when the account is not in the ledger the indirect is mounted on, and 409 PIX-0140 when the indirect is mounted on books that are no longer configured for Pix (an operator setting). The published payloadUrl and its JWKS location carry THAT participant's ISPB, so a QR minted as the wrong participant sends every payer's PSP to a key set that cannot validate its signature — and by then the QR is already in the wild. An indirect's QR is minted, signed and published by the participant recorded at that indirect's registration - the one direct participant it mounts on, which is NOT necessarily this deployment's default one - so supplying indirectId together with any other ispb, the default one included, is 422 PIX-0102; leaving ispb blank on an indirect request resolves to that same recorded participant rather than to the default.



# Register a PIX key entry
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/create-key

/en/openapi/v3-current/pix.yaml post /v1/entries
Registers a PIX key for the account named by accountId, and is also the only entry point to the claim flow. keyType must agree with the value in key (0=CPF, 1=CNPJ, 2=EMAIL, 3=PHONE, 4=RANDOM) or the call is 422 PIX-0010 naming the expected and detected types; omit key for RANDOM and DICT mints the EVP value (§8.2.01). isValidated is accepted but ignored - the service always restarts validation.

An unvalidated EMAIL or PHONE key never reaches DICT on this call: the service stores it locally as awaiting ownership confirmation (status 2), sends a 6-digit code to that address, and answers with status 2. Finish it with POST /v1/entries/{entryId}/confirmation. Calling this route again for the same key re-arms the row with a NEW code and the previous one stops working. A key of those two types that the account already holds at DICT is 409 PIX-0071. CPF, CNPJ and RANDOM keys go straight to DICT.

If DICT answers that the key is already registered elsewhere, the call still SUCCEEDS: the service records a claim-pending row (status 4) carrying the claim type DICT implied - portability when the current holder's document matches yours, possession otherwise (§8.2.07) - and no claim is opened yet. Opening it is POST /v1/claims, which works only on a row this call created. The whole operation is idempotent on (accountId, key): an existing live row is returned with its current status rather than registered a second time.

The service records the registration as pending (status 8) BEFORE it asks DICT. If DICT does not answer in time the call is 504 PIX-1051, and if DICT cannot be reached it is 503 PIX-1054 - never 500 - and the pending record stays: DICT may still have registered the key. Retrying the same CPF, CNPJ, EMAIL or PHONE key re-sends the same request, which DICT deduplicates. For RANDOM, whose value only DICT knows, the next RANDOM request for the account first reads the account's DICT keys: when DICT lists exactly ONE EVP that this deployment never recorded, it is adopted and returned as ACTIVE instead of minting another; when it lists none, or several unrecorded EVPs (there is then no telling which one was this account's), a new RANDOM request is 409 PIX-0007 for up to 10 minutes after the unanswered one, after which the pending record is released and a new EVP is registered.

Which of this deployment's direct participants writes to the national directory is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo.



# Create a PIX refund
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/create-refund

/en/openapi/v3-current/pix.yaml post /v1/refunds
Creates a PIX refund against an executed transaction. Bacen makes the refund the RECIPIENT's operation, so the caller must be the party that RECEIVED the original payment: the requesting accountId's document has to equal the original payee's document. The original payer cannot refund a payment it sent — that is the MED/fraud path, not this one.

Identify the original with BOTH transactionId (the local UUID) and endToEndId, and it must still be EXECUTED. Partial refunds are allowed and they ACCUMULATE: the amount is checked against the original amount minus everything already refunded, under a row lock on the original, so two concurrent refunds cannot together exceed it. An on-us original is refunded as a synchronous ledger reversal from the refunder to the original payer; a payment received from another institution is returned over SPI: the amount is first reserved on the refunding account, then the refund is submitted to JDPI, and it answers PENDING with the money held until SPI settles it (EXECUTED, the reserve committed) or refuses it (ERROR, the reserve released) — poll GET /v1/transactions. A Pix received from an account that banks at this participant but is held in other books is returned to those books, never over SPI: the amount is held on the refunding account and the refund relayed, answering EXECUTED once those books credited the original payer, PENDING while their answer is unknown (the reconcile worker completes it — poll GET /v1/transactions), 422 PIX-0145 when they refused it and 503 PIX-0146 when they could not be reached; both release the hold, so nothing moved; 409 PIX-0149 when any fee in the package priced on the cross-core return route (this refund to the other core of the same participant, priced like a refund sent to another bank) is configured to deduct from the amount instead of being charged on top (an operator setting) — the applied package is known only once the hold is posted, so this refusal comes after the hold and before anything is relayed: the hold is released, by the reconcile worker when the ledger does not confirm the release at once, and nothing moved. The refund's own end-to-end id (endToEndRefundId) is filled when JD supplies it and may be empty while the refund is PENDING; an empty value is not a failure, the outcome arrives as transaction.refunded or transaction.failed. An on-us original that itself moved between two ledgers of this institution is returned the same way it was paid — a reserve in the ledger that received it, a credit in the ledger that paid, then a commit — so that one branch reports EXECUTED only after both legs landed; a refund whose credit that ledger has not yet confirmed delivered is ACCEPTED and still settling, reported PENDING with the money held, and the reconcile worker completes it — poll GET /v1/transactions rather than retrying it as a fresh refund. The exception is the same one the payment route carries: once the credit has landed, a settlement outcome the ledger leaves unknown while CLOSING the reserve still answers 5xx and still leaves the transaction PENDING, so a 5xx here never means nothing happened — poll it rather than sending a new refund under a new key. code is the return reason and is accepted only as BE08, FR01, MD06 or SL02.

Idempotency: the X-Idempotency header is REQUIRED, and it is what makes a resend safe on every branch, on-us included: once a refund is recorded under a key, a resend under that key is refused 409 PIX-0029 and moves no money — read its outcome with GET /v1/transactions. Keys are scoped to the payer (the organization, plus the indirect participant on an indirect refund); a new refund needs a new key.

A Pix received on an indirect participant's PIX position is returned by that indirect: send its indirectId, and the refund debits that indirect's position. A Pix received on a direct account is returned without one.

payerIspb optionally names the direct participant paying the refund back. Named, the original has to be booked in that participant's books, checked before the idempotency key is read and before anything is held or sent; a token confined to one participant has to name it.

Refusals: 422 PIX-0036 when no EXECUTED payment matches that (endToEndId, transactionId) pair, which is also the answer when the pair names a refund (a refund is never the original of another); 404 PIX-0147 when payerIspb names a participant, or indirectId an indirect, that does not hold the original (checked before eligibility, so it never tells the caller whether another participant's original exists or which way it went); 422 PIX-0128 for a payerIspb this deployment does not act as; 400 PIX-0087 when the original is a payment sent to another institution, or to an account held in other books of this one, and the caller is its sender; 400 PIX-0089 when it is such a payment and the caller is anyone else (only the receiving institution can return what it received); 400 PIX-0088 when the original is any other payment and the caller is not its payee; 422 PIX-0135 when indirectId is absent on a Pix received on an indirect's position; 422 PIX-0111 when the indirect-participants feature is off, 404 PIX-0095 when the indirect is not registered and 422 PIX-0100 when it is not ACTIVE, as on a payment order; 409 PIX-0075 when this amount plus the prior refunds would exceed the original; 409 PIX-0076 when the available balance of the account the refund debits (the indirect's position, for a Pix it received) is below the amount of a refund sent over SPI or to other books (nothing is reserved or sent); 409 PIX-0029 when this X-Idempotency key already names a refund of the payer, and while another refund of the same payment sent over SPI or to other books is still PENDING, or when JD answers with an earlier refund of it; 422 PIX-0030 on a non-positive amount; 409 PIX-0105 when a ledger the refund has to post in does not declare the reversal accounting routes (nothing is posted and no refund is recorded); 409 PIX-0142 when the ledger the original was booked in — or, for an on-us payment between two ledgers, the ledger it was credited in — is no longer configured for Pix on this deployment (nothing is posted and no refund is recorded; an operator has to restore that ledger to the Pix setup); 400 PIX-0061 when the X-Idempotency header is absent, blank or over 255 bytes, accountId or endToEndId is empty, transactionId is not a UUID, or code is outside the four accepted values.



# Create a static PIX QR code
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/create-static-qr-code

/en/openapi/v3-current/pix.yaml post /v1/qrcodes/static
Generates a static PIX QR code into the recipient's key. The recipient name and city are sourced from the CRM alias, never the request body. An amount of 0 produces an any-amount static QR.

Which of this deployment's direct participants acts is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own customers and its own JDPI credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution.



# Create a PIX transaction
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/create-transaction

/en/openapi/v3-current/pix.yaml post /v1/transactions
Creates an outbound PIX payment. What happens next depends on where the payee is, and the two branches answer with different statuses and different bodies — a client has to handle both.

An on-us payee (payee.ispb equal to this participant's own ISPB, on a direct order) settles SYNCHRONOUSLY as an INTRA_PSP ledger transfer and answers 201 with the transaction already EXECUTED. The account credited is the one payee.branch, payee.accountNumber and payee.accountDigit name, and it must belong to payee.document (422 PIX-0134). On a payment by key (payee.key) those coordinates are first checked against DICT (§8.2.14, asked as the payer; JDPI answers a key of this institution from its own base): a field the order states differently from the account DICT binds the key to is refused 422 PIX-0033 naming that field (the branch is compared by value, so "1" and "0001" name the same branch, here and in the paying participant's records), a key DICT does not hold is 404 PIX-1011, and JDPI unavailable is 503 PIX-1050 — all before anything is held. Send the payee object GET /v1/entries/{entryId}/lookup answered and it matches. Any other payee settles over SPI in TWO PHASES: the amount is first HELD on the paying position as a pending ledger debit, and only then is the order submitted to JDPI (§8.4.1), which is asynchronous by design — nothing has settled when the call returns. A direct order answers 201 with the transaction PENDING; an order routed through a registered indirect (indirectId in the body) answers 202 carrying JD's own §8.4.1 acknowledgement byte-for-byte when JDPI returns one, whose idReqJdPi is the handle the outcome is read with, and 201 PENDING with this plugin's body when JDPI's answer proves nothing. Either way, poll GET /v1/transactions/{transactionId}: a background reconciler consults JDPI §8.4.2 and then commits or cancels the hold, and the money is not settled until the status says so.

WHAT indirectId ACTUALLY MOVES, because it is more than a label. This participant may serve INDIRECT participants — other institutions registered here with POST /v1/indirects that reach SPI through this participant's ISPB. Naming one on an order changes THREE things at once: the amount is held on that institution's `@pi_{ispb}` settlement position instead of on the payer's own, the persisted order is stamped with that institution so it appears in GET /v1/indirects/{indirectId}/transactions, and the response shape changes from 201-plus-plugin-body to 202-plus-JD-body whenever JDPI acknowledges the order. The identifier is ROUTING DATA, not a credential: this participant authenticates you, and guaranteeing that the order really belongs to that institution is your responsibility, not this API's.

⚠️ indirectId IS REFUSED 422 PIX-0111 WHILE THIS TENANT'S INDIRECT-PARTICIPANTS FEATURE IS SWITCHED OFF, and the refusal names the setting an operator has to turn on. The order is never quietly executed as a DIRECT one: that would hold the amount on the payer's own position instead of the institution's `@pi_{ispb}`, so the money would leave an account you never named, behind a 201. The refusal is decided before the payer is read, so nothing is held and no order is persisted. An order carrying NO indirectId is unaffected.

When the order reaches its outcome, an indirect order may ALSO push a NOTICE to the endpoint that registration carries (delivery.endpointUrl), queued by the background reconciler once JD's terminal outcome is known — an HTTPS POST forwarding JD's own result body verbatim, carrying X-Lerian-Signature ('sha256=' followed by the hex HMAC-SHA256 of the exact body bytes under the registration's shared secret) and X-Lerian-Timestamp. **Do not build on the notice arriving.** No notice is queued at all when this deployment has no outbound queue configured, and none is queued when the outcome carries no JD result body to forward — an order cancelled locally, without a JD answer, is exactly that case. Delivery of a notice that WAS queued is AT-LEAST-ONCE and can still fail permanently while the payment stands. So the institution must dedup on the end-to-end id and treat GET /v1/indirects/{indirectId}/transactions, not the notice, as the record of truth: it is the only place an outcome whose notice was never queued becomes visible. A direct order pushes no notice at all.

End-to-end ids: send endToEndId only when you already hold one (from a key lookup or a QR decode), and then payee.key is mandatory with it. Omit it on a manually typed order and SPI mints one — the response carries the minted value. Idempotency: the X-Idempotency header is REQUIRED, and it is what makes a retry safe on every branch, on-us included: once an order is recorded under a key, a resend under that key is refused 409 PIX-0029 and moves no money. Keys are scoped to the payer (the organization, plus the indirect participant on an indirect order); a new order needs a new key. Amounts are integer centavos.

Every refusal below is decided before the hold is taken, so it moves ZERO money, except the cross-core answers PIX-0145, PIX-0146 and PIX-0149, which come after the hold and release it; when JDPI refuses the order after the hold exists, the call answers the refusal, the hold is released and the order stays in GET /v1/transactions with status ERROR — or PENDING, when the ledger does not confirm the release, until the background reconciler resolves it; when JDPI's answer does not prove a refusal (a timeout, a 5xx, a 408, 409 or 422 — except JD's payment-signature refusals JDPISPI017 and JDPISPI018, which prove one whatever status carries them and are never re-sent), the hold is kept and the order answers 201 PENDING with this plugin's body, an indirect order included, its final status coming later. The same release follows 409 PIX-0136, refused before JDPI is called when the paying participant's payment-order signing settings are written but cannot sign (a setting missing, an algorithm this plugin does not sign with, a key that does not fit it, or a certificate that is not the key's own); the message names the setting, and nothing reaches JDPI unsigned. Refusals: 409 PIX-0029 when this endToEndId or X-Idempotency key was already used by an order that may have moved money, and 409 PIX-0133 when that order was refused and moved none (send a new order under a new key); 409 PIX-0076 when the paying position lacks the amount; 409 PIX-0078 on a transfer to the same account; 409 PIX-0075 when the account's period limit is exceeded; 422 PIX-0030 on a non-positive amount; 422 PIX-0037 when endToEndId arrives without payee.key; 422 PIX-0108 when the payer — or, on an indirect order, the indirect's `@pi` — resolves in the CRM but is not bound to a ledger account; 422 PIX-0111 when an indirectId is supplied while this deployment's indirect-participants feature is off (naming the setting to enable — the order is refused, never quietly paid from the payer's own account), 404 PIX-0095 for an unknown or malformed indirectId and 422 PIX-0100 when the indirect it names is not ACTIVE; 422 PIX-0127 when this deployment acts as SEVERAL direct participants and the order names none of them in payerIspb, and 422 PIX-0128 when the one it names is not among them; when the payee banks at the PAYING participant — the order would normally settle internally, never touching SPI — and that participant has declared its ISPB shared with another core, the ownership map says which books hold the account the order names (payee.branch, payee.accountNumber and payee.accountDigit; a payment account, accountType 3, by its account alone), asked before the payee is looked up. When the OTHER core holds it, the order is a cross-core transfer, never sent over SPI: the amount is held on the payer's account and the order is relayed to that core, answering 201 EXECUTED once it credited the payee, 201 PENDING while its answer is unknown (the hold stays and the background worker resends and settles it; poll GET /v1/transactions), 422 PIX-0145 when it refused the credit and 503 PIX-0146 when the order never reached it — both release the hold, so nothing was debited, and the order stays in GET /v1/transactions with status ERROR (send it again under a new X-Idempotency key); and 409 PIX-0149 when any fee in the package priced on the cross-core route (this leg to the other core of the same participant, priced like a Pix sent to another bank) is configured to deduct from the amount instead of being charged on top (an operator setting) — the applied package is known only once the hold is posted, so this refusal comes after the hold and before anything is relayed: the hold is released and the order stays ERROR, or PENDING until the background worker finishes a release the ledger did not confirm; nothing was debited. Otherwise: 422 PIX-0129 when the map holds that account nowhere, 422 PIX-0132 when the order's account cannot be used to ask (a blank account, a blank branch on anything but a payment account, or one the map refuses as malformed — a retry changes nothing), 503 PIX-0130 when it could not answer (safe to retry: nothing was created) and 502 PIX-0131 when it answered in a form that cannot be acted on; each of these four is refused before anything is held and is NOT rerouted over SPI; an on-us payment WITHOUT payee.key is a payment by bank details, and it is credited on the account payee.branch, payee.accountNumber and payee.accountDigit name — number and digit together, exactly the account an interbank Pix carries — which must belong to payee.document, as the receiving institution checks on an interbank Pix: 404 PIX-2016 when the paying participant holds no such account, 422 PIX-0134 when it belongs to someone else, 422 PIX-0033 when no account is typed, 422 PIX-0108 when it is not bound to a ledger account (a payment account, accountType 3, is looked up by its account alone); an on-us payment WITH payee.key is credited on the account payee.branch, payee.accountNumber and payee.accountDigit name once DICT has confirmed them, checked exactly as a payment by bank details (404 PIX-2016, 422 PIX-0134), while an order naming no account is 422 PIX-0033; 422 PIX-0108 when that payee is not bound to a ledger account; 422 PIX-0102 when payerIspb is supplied on an indirect order and is not the participant recorded at that indirect's registration; 409 PIX-0105 when the ledger the money leaves from declares no accounting route for the direction; when the payer or the on-us payee cannot be used as the order addresses it, nothing is reserved and the answer names what refused: 422 PIX-0137 when the account is held in a ledger that is not configured for Pix on the paying participant (pay from or to an account on a configured ledger, or have the operator add that ledger to the Pix setup), 422 PIX-0138 when the account's record does not say which ledger holds it, 422 PIX-0139 when the payer's record names a different institution than the one paying, 422 PIX-0141 when, on an indirect order, the payer account is not in the ledger the indirect is mounted on, and 409 PIX-0140 when the indirect is mounted on books no longer configured for Pix (an operator setting); a refusal of the payer names the payer account (accountId) in its message, while a refusal of the on-us payee — PIX-0137 or PIX-0138 — names no account, because on a payment by key the payee's account is one you never saw, so read it as the payee the order addressed; 400 PIX-0061 when the X-Idempotency header is missing, blank or over 255 bytes, when accountId is empty or when an accountType is outside the PIX domain 0..4. Called with a partner credential, the order is also decided by that partner's own rules for the ledger and the CRM this plugin calls to serve it: 403 PIX-4019 when Midaz refuses the partner and 403 PIX-2025 when the CRM does, the message naming the reason (other_tenant, suspended, no_longer_valid or not_allowed) — grant the partner the missing permission on that service; a partner holding no grant for those services is decided by its Pix grant alone. On an indirect order a JD refusal is passed back with JD's own status and body instead of a problem+json. An on-us payee who banks at the paying participant but in a DIFFERENT ledger of it is served rather than refused: the amount is reserved on the payer's ledger, credited on the payee's ledger, and the reserve is then committed — so the order answers EXECUTED only once both legs landed. Both on-us shapes persist their transaction before the first posting, so their failures are not invisible: an order the ledger refuses answers an error AND leaves a transaction you will find in GET /v1/transactions with status ERROR (it does not count against the account's period limit: only a hold that reached the ledger does); a same-ledger order whose posting the ledger leaves unknown answers 5xx and stays PENDING until the reconcile worker finds the posting and settles it EXECUTED — a posting the ledger does not show yet never fails the order, because the ledger may record a posting after answering for it; and a cross-ledger order whose credit the payee's ledger has not yet confirmed delivered is ACCEPTED and still settling: it answers 201 with status PENDING, the money stays held, and the reconcile worker completes it — poll GET /v1/transactions rather than retrying it as a fresh payment. NOT every failure on that branch became a 201, and the exception matters because the money has already moved: when the credit HAS landed and the ledger then leaves the outcome of CLOSING the hold unknown — the settle failed, or a release could not be proved — the order still answers 5xx AND still leaves the transaction PENDING. So a 5xx here never means nothing happened. Poll GET /v1/transactions; if you retry, retry with the SAME X-Idempotency key, because a fresh key is a second payment.



# Decode a composite PIX Automatico QR code from its URL
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/decode-a-composite-pix-automatico-qr-code-from-its-url

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/composite/decode
Decodes a composite PIX QR code from its embedded recurrence URL (urlPayloadJsonRec), returning the recurring-payment authorization configuration. Optional ispb makes the decode AS that direct participant.

Call it on the paying side, after the payer scans a composite QR and before the authorization is requested; it reads and changes nothing. JDPI fetches the URL from the server of the institution receiving the payment, so the answer depends on that server as well as on JDPI.

Refusals: 400 PIX-0061 when recurrencePayloadUrl is blank; 422 PIX-1065 when JDPI answered that the payload could not be fetched from the URL's host — the detail names the host and carries JDPI's reason, and the failure is that host's, not JDPI's, so retrying only helps once the receiving institution serves it; 404 PIX-1005 when JDPI found no payload at the URL; 422 PIX-1047 when JDPI refused the URL; 400 PIX-1001 when what the URL served is not a valid recurrence payload; 503 PIX-1050 when JDPI is unavailable, 503 PIX-1054 when it cannot be reached, and 504 PIX-1051 when it does not answer in time.



# Decode a PIX QR code via its payload URL
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/decode-a-pix-qr-code-via-its-payload-url

/en/openapi/v3-current/pix.yaml post /v1/qrcodes/decode/url
Decodes a dynamic PIX QR code by the payee-published JWS payload URL (JDPI §8.3.10), normalizing static / immediate-dynamic / cobv sub-types into one null-safe response. Unlike the scan decode it takes a urlPayloadJson the JDPI fetches; the payer document is sourced from the CRM alias for the JDPI decode header.

Which of this deployment's direct participants acts is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own customers and its own JDPI credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. It selects the JDPI credential the decode goes out on and nothing else.



# Decode a scanned PIX QR code
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/decode-qr-code

/en/openapi/v3-current/pix.yaml post /v1/qrcodes/decode
Decodes a scanned PIX QR-code payload, normalizing static / immediate-dynamic / cobv sub-types into one null-safe response. The payer document is sourced from the CRM alias for the JDPI decode header.

Which of this deployment's direct participants acts is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own customers and its own JDPI credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. It selects the JDPI credential the decode goes out on and nothing else.



# Delete a PIX key entry
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/delete-key

/en/openapi/v3-current/pix.yaml delete /v1/entries/{entryId}
Removes a PIX key from the DICT directory and hides every live local row of the key in this participant, whichever account of the holder it names, except another holder's pending ownership confirmation. entryId is the key VALUE, URL-encoded; the body carries accountId.

Two ownership gates run before anything is deleted, and both fail closed. The key must appear in the account's own §8.2.06 directory listing, and §8.2.14 must report it held by this ISPB and account number - a key held by anyone else is 403 PIX-0018, and an ownership check that could not complete refuses with the upstream cause rather than claiming the key is not yours. If DICT reports the key does not exist at all, no delete is sent: stale local rows are hidden so the listing stops advertising the key, and with no local row on this account either the call is 403 PIX-0018. A key whose registration never got an answer (a pending record at status 8) that the account's directory listing does not show was never registered: once that registration is older than its own time limit (about one minute), the pending record is released, this account's other local rows of the key are hidden as stale (a claim in progress is left to the claim flow), and the call succeeds; before that the registration may still land, and the call is 409 PIX-0007 - retry it a minute later.

Order matters for recovery. DICT is deleted FIRST, then the local rows are soft-deleted (deleted_at is set and the status column is left alone, so nothing marks the row as cancelled). A failure between the two steps leaves the key gone upstream while a local row keeps surfacing in GET /v1/entries with its stale status; re-issuing the DELETE through the same account finishes that account's cleanup: §8.2.14 reports the key gone, so the account's stale rows are hidden (a claim in progress is left to the claim flow) and the call succeeds. Another account's stale row of the key is cleaned by a DELETE through that account. A row still pending registration follows its own rule: once its time limit passes, the retry releases it and succeeds, as described above. The DICT deletion itself cannot be undone through this API - register the key again with POST /v1/entries.

Which of this deployment's direct participants writes to the national directory is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo.



# List PIX key claims
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/list-claims

/en/openapi/v3-current/pix.yaml get /v1/claims
Two different listings behind one route, selected by the status query parameter.

With no status (the default) it returns DICT's §8.2.13 claim listing for the PARTICIPANT, not for the account: account_id only resolves the caller's ISPB, and the request body carries that ISPB and nothing else, so every claim DICT associates with the institution comes back - including claims that belong to OTHER accounts under the same ISPB. There is no filter, no paging and no local sort. Two consequences follow from the omitted fields: §8.2.13 declares that an omitted stReivindicacao defaults to situation 1 (awaiting resolution), so claims in other situations may not appear; and each row is only key, ispb and claimId, with no state, because DICT's situation value cannot be projected onto this API's status enum without losing cases.

With status=processing it answers something else entirely - the in-flight claims of §8.2.08, filtered to the caller's own account number, projected onto the key-entry shape and returned under data instead of claims. The projected status is 5 (you are waiting for the holder), 6 (you hold the key and must decide) or 7 (the holder gave it away; conclude it). Cancelled and completed claims are dropped, and only the FIRST §8.2.08 page (100 rows) is read. Any other status value falls through to the default branch. An account the CRM cannot resolve is 404 PIX-2016.

Which participant's DICT mailbox is read is decided by ispb, by exactly the rule an order's payerIspb follows - and here it decides WHOSE claims come back, not merely which credential signs the call, because §8.2.13 and §8.2.15 answer for a PARTICIPANT. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. Sending it empty (ispb=) reads the same as omitting it.



# List PIX key entries
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/list-keys

/en/openapi/v3-current/pix.yaml get /v1/entries
Lists the PIX keys of the account named by account_id. The response is not a table read: it is rebuilt on every call by merging three sources - the live DICT directory listing for the account (§8.2.06, every key reported as ACTIVE), the plugin's own local key rows (whose status is only a hint), and the account's in-flight DICT claims (§8.2.08), all projected onto the same eKeyStatus enum. Rows are keyed by the key VALUE: a directory key wins over a local row for the same value, and a live claim overrides both, because claim state is authoritative at DICT.

Nothing is written back, so the three sources never reconcile. A local row for a key DICT no longer holds keeps appearing with its stale status until the directory or a claim overrides it, and a key that exists only at DICT appears with no claimId and no local history. There is no filter and no pagination, and the claims source reads only the FIRST §8.2.08 page (100 rows), so an account with more in-flight claims than that is silently short. If any one of the three sources fails the whole request fails - the listing is never partial. account_id is required (omitting it is refused by schema validation; a blank value is 400 PIX-0061), and an account the CRM cannot resolve is 404 PIX-2016.

Which of this deployment's direct participants answers is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own customers and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. Sending it empty (ispb=) reads the same as omitting it. Read the participant that holds the keys: another one's directory answers for its own customers, not yours.



# List PIX Automatico authorizations
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/list-pix-automatico-authorizations

/en/openapi/v3-current/pix.yaml get /v1/pix-automatico/authorizations
Lists live JDPI recurring-payment authorizations (JDPI 4.3.7), scoped by flow + update window, projecting each onto the local authorization status. Optional ispb makes the listing AS that direct participant: JDPI answers only for what it holds.



# List PIX participant bank ids
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/list-pix-participant-bank-ids

/en/openapi/v3-current/pix.yaml get /v1/banks
Returns the SPI participating-PSP catalog reduced to what a payment form needs: ispb plus the participant's legal name, per §8.6.1. It takes no parameters - §8.6.1 declares none and the plugin adds no filter, page or sort - so the entire catalog arrives in one response, in the order JDPI returns it.

It is a live passthrough on every call with nothing cached, so this route's latency and availability are JDPI's. Keep ispb a STRING: it is 8 characters and its leading zeros are significant (00000208), so parsing it as a number corrupts it. An empty catalog is 200 with an empty data array, not an error. JDPI faulting is 503 PIX-1050, JDPI unreachable is 503 PIX-1054, and a timeout is 504 PIX-1051.

GET /v1/banks/participants reads the SAME §8.6.1 call and returns the full record; use it when you need cnpj, participation type, modality or status.



# List PIX refund reasons
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/list-refund-reasons

/en/openapi/v3-current/pix.yaml get /v1/refunds/reasons
Returns the PIX refund reason catalog from JDPI, as code + description pairs. Fetch it before offering a refund choice to a user, rather than hard-coding a list: the catalog is JD's, not this plugin's, and it can change with no release here.

Read-only, unfiltered, unpaginated, and not persisted or cached — every call reaches JDPI, so load it once per session rather than once per refund. It changes nothing.

⚠️ The catalog is JD's full list, but createRefund accepts only BE08, FR01, MD06 and SL02: a code from this response outside those four is refused with 400 PIX-0061 before the refund is attempted. There are no request-attributable refusals here (there is no request to get wrong); a failure is JDPI's and is reported as such — 503 PIX-1050 when JDPI is unavailable.



# List SPI participants
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/list-spi-participants

/en/openapi/v3-current/pix.yaml get /v1/banks/participants
Returns the full SPI participant directory from §8.6.1 - the same JDPI call GET /v1/banks makes, with every field instead of the ispb-and-name pair: ispb, cnpj, legalName, shortName, participantType (1=direct, 2=indirect), modality (1=transactional-account provider, 2=government entity, 3=special settler, 4=user institution), startedAt, endedAt and status (1=active, 2=inactive, 3=awaiting BACEN activation, 4=activation failed).

Only ispb, shortName, participantType and status are mandatory in §8.6.1; the rest are omitted from a row when JDPI does not send them, so treat them as optional instead of assuming a fixed shape. status and endedAt are what say whether a participant can receive a payment today - a row can be present and inactive.

The route takes no parameters and applies no filter, page or sort, and nothing is cached: the whole directory is fetched live from JDPI on every call, in JDPI's own order. JDPI faulting is 503 PIX-1050, JDPI unreachable is 503 PIX-1054, and a timeout is 504 PIX-1051.

participantType=2 here means SPI's own classification of an institution as indirect at BACEN, and it says NOTHING about whether that institution is an indirect participant registered with THIS participant. The two are unrelated lists: this one is the national directory, and the institutions this deployment serves are read with GET /v1/indirects. A row being participantType=2 is not a reason to send its ISPB an order or a credit, and an institution registered here does not have to appear as 2 in this directory.



# List the PSP's PIX QR codes
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/list-the-psp-s-pix-qr-codes

/en/openapi/v3-current/pix.yaml get /v1/qrcodes/list
Lists the PIX QR codes this participant created at JD (JDPI §8.3.12) whose registration falls inside a date window. Call it to reconcile or audit the charges you generated; it only reads, and changes nothing.

The response always carries all four blocks: staticQrCodes, dynamicQrCodes (immediate), cobvQrCodes (dynamic with due date) and recurrenceQrCodes. A block with no match is an empty array, and a window with no QR code is a 200, never a 404. qrCodeType filters by JD type: 11 static, 12 immediate dynamic, 13 dynamic with due date, 14 QRCode Composto, and 15-17 QRCode Composto carrying static, immediate-dynamic or due-date data. Omit it to list every type: the plugin asks JD once per type and merges the answers, so page and pageSize apply to each type's answer.

startDateTime and endDateTime are required. Send any RFC 3339 date-time, with or without milliseconds and with any offset (2026-01-01T00:00:00Z, 2026-01-01T00:00:00-03:00); the plugin converts both to UTC in JD's format. The window may span at most 90 days, counted to the millisecond. pageSize is 1-100 (default 50); page defaults to 1.

JD lists every charge of the DIRECT participant whose credential signs the call, and the indirect participants riding it share that listing. indirectId narrows it to ONE indirect: only the immediate dynamic charges created for that indirect come back - never another indirect's and never the direct participant's own - and the static, due-date and recurrence blocks come back empty, because none of them is created for an indirect. A charge created before this deployment recorded which indirect a charge belongs to is not returned to a listing that names an indirect. The narrowing is applied to each page JD answers, so a page may hold fewer entries than pageSize. A token confined to one indirect has to name it.

What goes wrong. Every refusal below except the JD answers is decided before JD is called:
- 400 PIX-0061, errors[] naming the field: startDateTime or endDateTime missing or not an RFC 3339 date-time; startDateTime later than endDateTime (startDateTime); a window over 90 days (endDateTime); pageSize outside 1-100 (pageSize).
- 400 PIX-0061: indirectId is not a valid UUID.
- 422 PIX-0127 / PIX-0128: the participant rule for ispb, below.
- 400 PIX-1001: JD refused the filters; detail carries JD's reason when JD gave one. 400 PIX-1000 when JD named the fields, with errors[] per field.
- 404 PIX-1005: JD answered not found. 429 PIX-1008: JD's rate limit; retry later.
- 503 PIX-1050 / 504 PIX-1051: JD unavailable or timing out; retry. 409 PIX-0092: the participant's JD credential is not provisioned, an operator setting.

Which of this deployment's direct participants answers is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own customers and its own JDPI credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. Sending it empty (ispb=) reads the same as omitting it. §8.3.12 answers for the participant whose credential signs the call, so reading as another one lists that institution's charges, not yours.



# List PIX transactions
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/list-transactions

/en/openapi/v3-current/pix.yaml get /v1/transactions
Lists the transactions this plugin has persisted, most recent first. Use it to reconcile your own records against the plugin's, or to find the local transaction id of an order you know only by its end-to-end id.

Read-only. Every filter is optional and they combine with AND: account_id (the Midaz alias the row carries: the payer's ledger account on a payment, the credited one on a cash-in, the debited one on a refund), end_to_end_id, status (the eTransactionStatus NAME, e.g. EXECUTED), and is_refund. is_refund is tri-state and parsed leniently — only "true" and "false" filter, and ANY other value (including "1" or "yes") leaves the filter unset rather than erroring, so a typo there silently widens the result set. There is no pagination and no page size: the response is the whole matching set in one array, so filter narrowly on a busy account. Amounts are integer centavos.

An unknown account_id or end_to_end_id is not an error — it matches nothing and returns an empty array, so absence here means "nothing persisted under that value", never "the value is wrong". The only refusal is 400 PIX-0061 for a status that is not a known eTransactionStatus name.

THIS FEED INCLUDES MOVEMENTS THAT BELONG TO INDIRECT PARTICIPANTS, and nothing here separates them. When this participant serves indirect participants (institutions registered with POST /v1/indirects), their credits and payments are persisted as ordinary transactions and come back mixed in with the direct participant's own. Name the institution to separate them: `indirectId` lists only one indirect's transactions, and `ispb` only one direct participant's books (its indirects included). GET /v1/indirects/{indirectId}/transactions remains the purpose-built feed for reconciling an indirect (it is windowed, cursor-paged and ordered for reconciliation, which this one is not).

A token confined to one participant or one indirect has to name it in `ispb` or `indirectId`; the listing then holds only what that one holds, and naming another is refused before anything is read. Naming neither lists every participant's transactions, exactly as before. Refusals: 422 PIX-0128 for an `ispb` this deployment does not act as; 400 for an `indirectId` that is not a UUID or an `ispb` that is not 8 digits.



# Look up a PIX key before paying it
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/look-up-a-pix-key-before-paying-it

/en/openapi/v3-current/pix.yaml get /v1/entries/{entryId}/lookup
Resolves a PIX key you are about to PAY - anyone's key, at any institution - into the recipient a payment needs (§8.2.14 Consultar Chave de Endereçamento). entryId is the key value, URL-encoded; account_id is YOUR account, the one the payment will leave from. Call it right before POST /v1/transactions: copy payee into that body as it stands and send endToEndId with it. payee.key plus endToEndId is what makes the payment one initiated by key (JDPI tpIniciacao=1); a payment by key without the endToEndId goes out as a manually typed one. The endToEndId belongs to this lookup: one lookup, one payment, and a new lookup before every payment.

The answer is what DICT holds now: the holder's document, name and person type, the institution (ispb), branch, account and account type. DICT returns the account as ONE string and does not say where a check digit is, so it is never split: payee.accountNumber carries it whole and payee.accountDigit is empty, and the payment hands JD the same string. Unlike GET /v1/entries/{entryId}/details, the holder is NOT compared against you: resolving someone else's key is the purpose of this route.

Nothing is written here, but the call is not free. DICT counts every lookup against the payer (PI-PayerId, your account holder's CPF/CNPJ) and against this institution, and a lookup that is not followed by a payment still spends that budget (§8.2.14, §8.2.31). This deployment therefore limits lookups per payer account before DICT is asked, always, whether or not its general request limits are switched on: by default 100 lookups per payer account per 60 seconds, which the operator tunes apart from every other limit. Past it the call is 429 PIX-0009 with Retry-After, and DICT itself refusing is 429 PIX-1008. Look a key up when the payer is about to pay it, never to browse or to validate a list - POST /v1/entries/verification is the batch existence check.

Refusals: 400 PIX-0061 when account_id is missing or blank, or ispb is not 8 digits; 404 PIX-2016 when account_id does not resolve to an account; 404 PIX-1011 when DICT holds no such key; 429 PIX-0009 (this deployment's per-payer limit) or PIX-1008 (DICT's); 503 PIX-1050 when JDPI is unavailable and 503 PIX-1054 when it cannot be reached; 504 PIX-1051 when JDPI does not answer in time.

Which of this deployment's direct participants asks DICT is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own customers and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. Send the participant the payment will be paid by: the endToEndId carries the ISPB of the participant that asked.

Paying through an INDIRECT participant: send indirectId, the same one the payment order will carry. The lookup then asks DICT on that indirect's behalf, so the endToEndId names the indirect - the institution the payment originates from - rather than the direct participant it rides (JDPI §8.2.14 PI-RequestingParticipant). Without it the endToEndId names the direct participant and does not match the order's payer. indirectId is validated before DICT is asked, by the rules the order applies: 404 PIX-0095 unknown to this tenant, 422 PIX-0100 not ACTIVE, 422 PIX-0111 while the indirect-participants feature is off. The lookup acts as the direct participant that indirect is mounted on: omit ispb, or send that participant's ISPB; any other is 422 PIX-0102.



# Register a holder-ownership removal
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/register-a-holder-ownership-removal

/en/openapi/v3-current/pix.yaml post /v1/holder-removals
Severs ONE holder's ownership of a transactional account at the DICT (JDPI §8.2.05 Excluir Titular) and, as a consequence, has the DICT DELETE EVERY PIX key bound to that holder ON that account. The account itself stays open and the keys of its OTHER holders are untouched — that is the whole difference from POST /v1/account-closures, which closes the account and deletes every key on it regardless of holder.

Call it when a joint holder leaves, or when a holder's link to the account ends for any other reason, after that holder has stopped transacting. Deletion at the DICT is not reversible: each key is gone from the national directory and has to be registered again to come back, which restarts its ownership and can open a claim if another institution claimed the key in the meantime.

The target holder is named by personType + document and is deliberately NOT inferred from accountId: the holder being removed is frequently not the one whose credentials made the call. The ISPB is resolved server-side from accountId and never read from the body.

⚠️ A 200 does NOT mean every deletion succeeded. The response carries one outcome row per key the DICT attempted; read result on each (1 = deleted, 0 = not deleted, with resultDescription giving the reason), because only the successes are mirrored into this plugin's key projection. These rows are narrower than the account-closure ones — document and name are not populated here.

Refusals: 400 PIX-0061 when accountId or account is empty, or accountType is outside 0..4; 404 PIX-2016 when accountId does not resolve; 400 PIX-1000 when the DICT rejects a field, naming it; 404 PIX-1011 when the DICT knows no such holder-and-account binding or no keys under it; 422 PIX-1007 when the DICT refuses the removal in the current state; 503 PIX-1050 when the DICT is unreachable.

Which of this deployment's direct participants writes to the national directory is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo.



# Register a PIX Automatico authorization validation
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/register-a-pix-automatico-authorization-validation

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/authorizations/{idRecorrencia}/validation
Registers the deferred async validation reply for a recurring-payment authorization (JDPI 4.3.10), the outbound reply to an inbound 5.2.1 that returned 202-async.



# Register a transactional account closure
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/register-a-transactional-account-closure

/en/openapi/v3-current/pix.yaml post /v1/account-closures
Registers the closure of a transactional account at the DICT (JDPI §8.2.04 Encerrar Conta) and, as a consequence, has the DICT DELETE EVERY PIX key bound to that account in one operation. It is a bulk key deletion addressed by ACCOUNT COORDINATES, not by key: you do not name the keys and you cannot select a subset of them.

Call it when the account itself is being closed and has stopped transacting — not to tidy up keys. Deletion at the DICT is not reversible: each key is gone from the national directory, and getting one back means registering it again, which restarts its ownership and can open a claim if another institution took the key meanwhile. To remove ONE key use the entry-deletion route; to sever one holder's ownership while the account stays open use POST /v1/holder-removals.

⚠️ A 200 does NOT mean every deletion succeeded. The response carries one outcome row per key the DICT attempted, and each row's result is the verdict: 1 = deleted, 0 = not deleted with resultDescription giving the reason. Only the successes are mirrored into this plugin's own key projection, so a row with result 0 is still live at the DICT and still needs attention — iterate the rows, do not read the status code alone. The ISPB is resolved server-side from accountId and is never taken from the body; branch, accountType and account identify the account being closed, and a wrong coordinate resolves nothing rather than closing something else.

Refusals: 400 PIX-0061 when accountId or account is empty, or accountType is outside 0..4; 404 PIX-2016 when accountId does not resolve to an account; 400 PIX-1000 when the DICT rejects a field, with the offending fields named in the response; 404 PIX-1011 when the DICT knows no such account or keys; 422 PIX-1007 when the DICT refuses the closure in the account's current state; 503 PIX-1050 when the DICT is unreachable.

Which of this deployment's direct participants writes to the national directory is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo.



# Register an inbound PIX Automatico authorization on the PSP Recebedor
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/register-an-inbound-pix-automatico-authorization-on-the-psp-recebedor

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/authorizations/inbound/recipient/register
Registers the payer's authorization result delivered by JDPI to the PSP Recebedor (section 5.2.4, the plugin is the server). It loads the existing recebedor-side authorization row and transitions it to Accepted or Rejected per resultadoAutorizacao, returning the local SGCT id.



# Register an inbound PIX Automatico cancellation
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/register-an-inbound-pix-automatico-cancellation

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/authorizations/inbound/cancellation/register
Registers a recurring-payment cancellation outcome delivered by JDPI (section 5.2.5, the plugin is the server). An accepted cancellation (stCancelamento=0) transitions the authorization to Cancelled and soft-deletes the row; a rejected cancellation (stCancelamento=1) is acknowledged with no state change. Returns the local SGCT id.



# Register an inbound PIX Automatico solicitation on the PSP Pagador
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/register-an-inbound-pix-automatico-solicitation-on-the-psp-pagador

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/authorizations/inbound/payer/register
Registers an inbound recurring-payment solicitation delivered by JDPI to the PSP Pagador (section 5.2.3, the plugin is the server). This is payer-side genesis: it creates the payer-side authorization row in the Requested state and returns the local SGCT id. A re-delivered solicitation resolves to a 409 conflict.



# Request a PIX Automatico authorization
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/request-a-pix-automatico-authorization

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/authorizations
Requests a recurring-payment authorization as the recipient's PSP (JDPI 4.3.1). Persists the authorization in the Requested state and returns the JDPI request id. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. The recipient is resolved by the document, or by branch and account: 422 PIX-0143 when they match more than one account, and 422 PIX-0144 when the branch and account belong to a different holder than the document.



# Respond to a PIX Automatico authorization
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/respond-to-a-pix-automatico-authorization

/en/openapi/v3-current/pix.yaml put /v1/pix-automatico/authorizations/{idRecorrencia}/respond
Accepts or rejects a recurring-payment authorization as the payer's PSP (JDPI 4.3.2). An acceptance transitions the authorization to Accepted; a rejection to Rejected. Accepting a payer-side authorization first resolves the payer account its recurring debits will draw on, and an account that cannot be resolved refuses the acceptance before anything is sent to JDPI. Optional ispb names the direct participant this write acts for: named, the recurrence row has to be booked in that participant's books, or the answer is 404 PIX-0147 before JDPI is asked; an ISPB this deployment does not act as is 422 PIX-0128, before the row is read.



# Get available PIX limits
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/retrieve-available-limits

/en/openapi/v3-current/pix.yaml get /v1/limits/available
Computes what is left of each limit for the account: availableAmount = totalLimit - usedAmount, floored at zero, in exact int64 centavos with no rounding. currentPeriod names the period that is active right now.

The windows are the part that surprises callers, and they are UTC calendar-day bands. DAILY is the half-open [init, end) hour range taken from the tenant's systemplane knobs transaction_limits.daily_period_init and transaction_limits.daily_period_end (6 and 20 when unset). NIGHTLY is the WHOLE complement of that band summed across the day - both [00:00, init) and [end, 24:00), not only the band the request falls in. MONTHLY is summed over a single UTC day, NOT a month, so a MONTHLY row's usedAmount reports today's usage only.

usedAmount is the sum of the account's live outbound rows of the same transaction type - CASH_OUT plus on-us INTRA_PSP - created inside the window, with NO status filter, so a pending or failed payment still counts against you; outbound refunds are included too, matching what the enforcement check counts. An account with no limit rows at all is 404 PIX-0063 (see GET /v1/limits for why that is a normal state rather than a fault), an account_id the CRM cannot resolve is 404 PIX-2016, and one the ledger holds no account for (unbound, or absent from the ledger) is 422 PIX-0108, one held in a ledger that is not configured for Pix on that participant is 422 PIX-0137, one whose record does not say which ledger holds it is 422 PIX-0138, and one whose record names a different institution is 422 PIX-0139.

Whose limits these are is decided by payer_ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, the account id is an alias that is unique only inside one of them, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. Read the headroom of the SAME participant you pay as.



# Get a PIX key claim
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/retrieve-claim

/en/openapi/v3-current/pix.yaml get /v1/claims/{claimId}
Reads one claim live from DICT (§8.2.15 Consultar Reivindicação). Nothing local is consulted: account_id exists only to validate the caller and to produce the ISPB §8.2.15 requires, and the plugin's own key row is deliberately ignored because it is absent for a claim this plugin never opened and gone once the row is soft-deleted.

So this route serves the same universe as the default GET /v1/claims: any claim DICT associates with the caller's ISPB, including one opened by another account of the same institution. Note what the response does NOT carry - only claimId, key and ispb are serialized. DICT's situation and which side of the claim you are on are read and then dropped, so this route cannot tell you whether a claim is open, confirmed or cancelled; read state from GET /v1/claims?status=processing or GET /v1/entries instead. A claimId DICT does not know is 404 PIX-0020, and DICT being unavailable is 503 PIX-1050.

Which participant's DICT mailbox is read is decided by ispb, by exactly the rule an order's payerIspb follows - and here it decides WHOSE claims come back, not merely which credential signs the call, because §8.2.13 and §8.2.15 answer for a PARTICIPANT. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. Sending it empty (ispb=) reads the same as omitting it.



# Get PIX key entry details
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/retrieve-key

/en/openapi/v3-current/pix.yaml get /v1/entries/{entryId}/details
Resolves what DICT holds behind a PIX key - the payee document and name, the key type, the holder ISPB and an end-to-end id (§8.2.14 Consultar Chave de Endereçamento). entryId is the key VALUE, URL-encoded; account_id is the caller's CRM account.

It is a SELF-lookup, not a directory search, and the shape does not show it: after the DICT read the service compares the payee document DICT returned against the caller's own account document and refuses the response with 422 PIX-0086 when they differ. A CPF or CNPJ key that is not the caller's own document is refused the same way BEFORE DICT is called. The only key this route will describe is therefore one whose holder document equals yours - it cannot be used to resolve a counterparty ahead of a payment. An account_id the CRM cannot resolve is 404 PIX-0063 here (not the PIX-2016 the sibling key routes answer), and a key DICT does not hold is 404 PIX-1011.

Which of this deployment's direct participants answers is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own customers and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. Sending it empty (ispb=) reads the same as omitting it. Read the participant that holds the keys: another one's directory answers for its own customers, not yours.



# List PIX transaction limits
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/retrieve-transaction-limits

/en/openapi/v3-current/pix.yaml get /v1/limits
Lists the PIX limit rows that exist for the account named by account_id. Each row is a (transactionType, periodType, limitType) tuple plus an amount in centavos: periodType is DAILY, NIGHTLY or MONTHLY; limitType is TRANSACTION, the cap on a single payment, or PERIOD, the cap on everything inside the window; transactionType is always PIX.

No endpoint in this API creates a limit row. Four of them - PERIOD and TRANSACTION for DAILY and NIGHTLY, at a deployment-configured default of 30000 reais - are seeded lazily the first time POST /v1/transactions runs the limit check for the account, and a MONTHLY row is never created by the service at all. Until that first payment attempt this route answers 200 with an empty data array rather than a 404, and PATCH /v1/limits has no row to change. An account_id the CRM cannot resolve is 404 PIX-2016, and one the ledger holds no account for (unbound, or absent from the ledger) is 422 PIX-0108, one held in a ledger that is not configured for Pix on that participant is 422 PIX-0137, one whose record does not say which ledger holds it is 422 PIX-0138, and one whose record names a different institution is 422 PIX-0139.

Whose limits these are is decided by payer_ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, the account id is an alias that is unique only inside one of them, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. Read the headroom of the SAME participant you pay as.



# Get a PIX transaction status
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/retrieve-transaction-status

/en/openapi/v3-current/pix.yaml get /v1/transactions/{transactionId}
Resolves one transaction's status. This is the operation that closes the loop after a payment: an outbound SPI order answers 201 or 202 with nothing settled, and the verdict arrives here.

The path id is resolved in three steps, in order: by JDPI request id (idReqJdPi), then — only when the value parses as a UUID — by local transaction id, and finally, when neither matched, by a LIVE lookup at JDPI (§8.4.2). Those branches do not answer the same thing. A local hit returns the status the reconciler last persisted; a live hit is a projection of JD's own processing status, is the only branch that populates jdpiStatus, and projects JD status 9 to EXECUTED. So a transaction this plugin never persisted can still answer 200 here, and a status read live is not evidence that a local row exists.

Read-only: it neither commits nor releases the held amount — the background reconciler does that on its own tick, so a PENDING answer means "not decided yet", not "stuck". Optional `ispb` and `indirectId` name who the transaction is read as: named, it has to be held by that direct participant or indirect, or the answer is 404 PIX-0147 and nothing about it is returned — a token confined to one participant or indirect has to name it. Refusals: 400 PIX-0061 when transactionId is empty; 404 PIX-0147 when the transaction is held by another participant or indirect than the one named; 422 PIX-0128 for an `ispb` this deployment does not act as; and on the live branch, JDPI's own outcome — 404 PIX-1027 when JD does not know the id either, 503 PIX-1050 when JDPI is unreachable — so a failure here names the dependency instead of hiding behind a generic error.



# Update a CobV (due-date) composite PIX Automatico QR code
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/update-a-cobv-due-date-composite-pix-automatico-qr-code

/en/openapi/v3-current/pix.yaml put /v1/pix-automatico/composite/cobv/{id}
Updates a previously generated CobV (due-date charge) composite PIX QR code, keyed by its document id (idDocumento). The response carries the JDPI-computed revision (revisao).



# Update a PIX Automatico authorization max value
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/update-a-pix-automatico-authorization-max-value

/en/openapi/v3-current/pix.yaml put /v1/pix-automatico/authorizations/{idRecorrencia}/max-value
Updates the payer max-value cap of an Active recurring-payment authorization (JDPI 4.3.9). This is not a status transition; an omitted/zero value removes the cap. Optional ispb names the direct participant this write acts for: named, the recurrence row has to be booked in that participant's books, or the answer is 404 PIX-0147 before JDPI is asked; an ISPB this deployment does not act as is 422 PIX-0128, before the row is read.



# Update a recurrence-only composite PIX Automatico QR code
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/update-a-recurrence-only-composite-pix-automatico-qr-code

/en/openapi/v3-current/pix.yaml put /v1/pix-automatico/composite/recurrence/{id}
Updates a previously generated recurrence-only composite PIX QR code, keyed by its document id (idDocumento), carrying the recurrence status transition (stRecorrencia).



# Update an immediate dynamic composite PIX Automatico QR code
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/update-an-immediate-dynamic-composite-pix-automatico-qr-code

/en/openapi/v3-current/pix.yaml put /v1/pix-automatico/composite/dynamic/{id}
Updates a previously generated immediate-dynamic composite PIX QR code, keyed by its document id (idDocumento). The response carries the JDPI-computed revision (revisao).



# Update an immediate dynamic PIX QR code
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/update-an-immediate-dynamic-pix-qr-code

/en/openapi/v3-current/pix.yaml put /v1/qrcodes/dynamic/{documentId}
Updates an existing immediate dynamic PIX QR code (JDPI §8.3.5): the charge amount, conciliation, expiration, optional payer, and the charge status (0=Active, 1=Concluded, 2=Removed by recipient, 3=Removed by PSP). The recipient name + city are CRM-sourced (never the body). The plugin re-hosts the updated signed JWS so the QR stays end-to-end resolvable; the response carries the JDPI revision and the resolvable payload URL.

It is also the RECOVERY path for an indirect-hosted payloadJws whose create response never reached the caller: the update re-signs the charge under whichever certificate the request names and returns the fresh payloadJws, so supply the SAME indirectId the charge was created with (omitting it re-signs under the DIRECT participant and moves the location onto the direct FQDN). Every update — recovery or not — mints a new payloadUrl and a regenerated EMV payload, so the previously advertised location is superseded.

A CHARGE STAYS WITH THE INDIRECT IT WAS CREATED FOR. Every charge created records which indirect it was created for (none, for the direct participant's own), and an update naming a different one is refused 404 PIX-0147 — after the indirectId checks below and before JDPI is called, so the charge, its revision and its hosted payload are not changed. That covers naming indirect A on a charge created for indirect B, and naming any indirect on a charge created for the direct participant. A charge created before this record existed is not checked, and neither is an update that names no indirect. The record decides only WHO MAY update; this request's indirectId — not the create's — still decides who signs and where the location points, on every update. Omitting it on a charge created for an institution that hosts its own certificate is not a no-op: it MOVES the charge onto the direct participant's certificate and domain, and the institution's own domain stops serving the current location. The same rules as on create apply here, and they apply in this order: while this tenant's indirect-participants feature is off the value is refused 422 PIX-0111 naming the setting, so none of the refusals below can be reached and nothing is re-signed — an update that silently reverted to the direct participant would move a LIVE charge onto another certificate and domain, and its refreshed QR would stop validating at the payer's app. With the feature on, the value is validated and refused with 404 PIX-0095 (unknown or malformed id), 422 PIX-0100 (not ACTIVE), 422 PIX-0113 (registered host a payer's app cannot resolve) or 422 PIX-0112 (composed payload URL over the 77-character BACEN cap) — all before JDPI is called, so a refused update changes nothing.

Which of this deployment's direct participants acts is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own customers and its own JDPI credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. For an indirect participant: 422 PIX-0141 when the account is not in the ledger the indirect is mounted on, and 409 PIX-0140 when the indirect is mounted on books that are no longer configured for Pix (an operator setting). The published payloadUrl and its JWKS location carry THAT participant's ISPB, so a QR minted as the wrong participant sends every payer's PSP to a key set that cannot validate its signature — and by then the QR is already in the wild. An indirect's QR is minted, signed and published by the participant recorded at that indirect's registration - the one direct participant it mounts on, which is NOT necessarily this deployment's default one - so supplying indirectId together with any other ispb, the default one included, is 422 PIX-0102; leaving ispb blank on an indirect request resolves to that same recorded participant rather than to the default.



# Change a PIX transaction limit
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/update-transaction-limit

/en/openapi/v3-current/pix.yaml patch /v1/limits
Changes the amount of ONE existing limit row. The row is addressed by its natural key rather than by an id: accountId, plus periodType (DAILY, NIGHTLY or MONTHLY, case-insensitive) and limitType (TRANSACTION or PERIOD, case-insensitive); transactionType is always PIX. amount is the new cap in centavos and must be greater than zero.

It is update-only. It never creates a row, and no other endpoint does either - the four default rows appear only after POST /v1/transactions first runs the limit check for the account (see GET /v1/limits). A MONTHLY row, which the service never seeds, therefore cannot be changed here.

The refusals are worth knowing before you debug one: an unknown periodType, an unknown limitType, and a well-formed tuple with no matching row ALL answer 422 PIX-0036, carrying the message about a transaction status transition not being permitted, and nothing in the response tells the three apart. A non-positive amount is the one distinct case, 422 PIX-0030 naming the amount. An accountId the CRM cannot resolve is 404 PIX-2016, and one the ledger holds no account for (unbound, or absent from the ledger) is 422 PIX-0108, one held in a ledger that is not configured for Pix on that participant is 422 PIX-0137, one whose record does not say which ledger holds it is 422 PIX-0138, and one whose record names a different institution is 422 PIX-0139. A new cap applies from the next POST /v1/transactions; there is no scheduling and no approval window.

Which participant's row is changed is decided by payerIspb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, the accountId is an alias that is unique only inside one of them, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. A row of a participant you did not name is not reachable here.



# Validate an inbound PIX Automatico authorization
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/validate-an-inbound-pix-automatico-authorization

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/authorizations/inbound/validate
Validates an inbound recurring-payment authorization request pushed by JDPI (section 5.2.1, the plugin is the server). A synchronous validation returns the result inline (200); a Jornada-3 authorization returns 202-async with the eventual result delivered via the outbound 4.3.10 validation reply.



# Validate an inbound PIX Automatico cancellation
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/validate-an-inbound-pix-automatico-cancellation

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/authorizations/inbound/cancellation/validate
Validates an inbound recurring-payment cancellation request pushed by JDPI (section 5.2.2, the plugin is the server). The cancellation is valid iff a live authorization exists and the FSM permits a transition to Cancelled from its current status; the result is returned inline (200).



# Verify PIX key existence
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/verify-pix-key-existence

/en/openapi/v3-current/pix.yaml post /v1/entries/verification
Bulk-checks whether each supplied PIX key exists in the DICT directory (§8.2.23 Verificar Existência de Chaves). accountId resolves the caller's ISPB only - it does not scope the answer - and keys carries 1 to 200 values; a batch outside those bounds is refused before any DICT call, with 400 PIX-0061 naming keys.

What comes back is existence and nothing else: each row is a key plus an exists flag. It does not say who holds a key, whether YOU hold it, or whether it can be claimed, so it is not the pre-check for a claim - POST /v1/entries is, because that is what turns a key DICT already knows into the claim-pending row POST /v1/claims requires. Use this to sift a list of keys, for example before a batch payout. The response also echoes DICT's own jdpiReturnedAt and correlationId, which are the values support asks for.

Which of this deployment's direct participants writes to the national directory is decided by ispb, by exactly the rule an order's payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo.



# Cancel a due-date collection
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/cob/cancel-due-date-collection

/en/openapi/v3-current/pix-lerian-cob.yaml delete /collections/duedate/{id}
Cancels a due-date collection synchronously and changes its status to `CANCELLED`. The operation is idempotent: cancelling a collection that is already `CANCELLED` returns the same `200` response.



# Cancel an immediate collection
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/cob/cancel-immediate-collection

/en/openapi/v3-current/pix-lerian-cob.yaml delete /collections/immediate/{id}
Cancels an immediate collection synchronously and changes its status to `CANCELLED`. The operation is idempotent.



# Create a due-date Pix collection (cobv)
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/cob/create-due-date-collection

/en/openapi/v3-current/pix-lerian-cob.yaml post /collections/duedate
Registers a dynamic due-date Pix collection using the due-date calendar defined by the BCB and optional value modifiers (fine, interest, abatement, and discount). The Pix key is validated before creation. The collection includes its EMV payload, location URL, and expiration time.

**Replay:** retrying the same request with the same `txId` within the same organization, account, and merchant-document scope returns the original `201` response unchanged and does not create another collection. Using an existing `txId` with a different request body returns `PIX-0012` with status `409`.



# Create an immediate Pix collection (cob)
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/cob/create-immediate-collection

/en/openapi/v3-current/pix-lerian-cob.yaml post /collections/immediate
Registers an immediate dynamic Pix collection. The Pix key is validated before creation. The collection includes its EMV payload, location URL, and expiration time.



# Create a static BR Code
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/cob/create-static-brcode

/en/openapi/v3-current/pix-lerian-cob.yaml post /brcodes/static
Creates a reusable static Pix BR Code and returns its EMV payload. The requested Pix key must belong to the account identified by `X-Account-Id` and is validated before the code is generated.



# Decode a Pix EMV payload
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/cob/decode-qrcode

/en/openapi/v3-current/pix-lerian-cob.yaml post /brcodes/decode
Parses a Pix EMV payload and returns the structured payment details. Third-party payloads are accepted, so decoding is more permissive than BR Code creation: a payload without a Point of Initiation method is decoded as `STATIC`. `keyType` is inferred from the key value and omitted when no key type defined by the BCB both matches the value and passes validation. See the response schema for the rules that apply to each field.



# Get a due-date collection by ID
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/cob/get-due-date-collection

/en/openapi/v3-current/pix-lerian-cob.yaml get /collections/duedate/{id}
Retrieves a due-date collection by its collection ID. A paid collection includes the payment block; a cancelled collection includes the cancellation details.



# Poll the provider's current view of a due-date collection
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/cob/get-due-date-provider-status

/en/openapi/v3-current/pix-lerian-cob.yaml get /collections/duedate/provider-status
Reads the configured provider's current view of a due-date collection identified by its BACEN `tx_id` query parameter, alongside the Hub's persisted view, and reports whether they diverge. This operation is read-only and does not update the local collection. Authorization may be required when the deployment enables access management.



# Get an immediate collection by ID
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/cob/get-immediate-collection

/en/openapi/v3-current/pix-lerian-cob.yaml get /collections/immediate/{id}
Retrieves an immediate collection by its collection ID. A paid collection includes the payment block; a cancelled collection includes the cancellation details.



# Get a static BR Code by ID
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/cob/get-static-brcode

/en/openapi/v3-current/pix-lerian-cob.yaml get /brcodes/static/{id}
Returns a single static BR Code scoped to the calling tenant.



# List due-date collections or retrieve one by txId
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/cob/list-due-date-collections

/en/openapi/v3-current/pix-lerian-cob.yaml get /collections/duedate
Returns a page-based list envelope of due-date collections, optionally filtered by a dueDateFrom/dueDateTo range. When a `txId` query parameter is supplied the endpoint switches to a by-txId lookup and returns a single bare collection entity instead — the two 200 shapes are documented as a oneOf.



# List immediate collections or retrieve one by txId
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/cob/list-immediate-collections

/en/openapi/v3-current/pix-lerian-cob.yaml get /collections/immediate
Returns a page-based list envelope of immediate collections. When a `txId` query parameter is supplied the endpoint switches to a by-txId lookup and returns a single bare collection entity instead — the two 200 shapes are documented as a oneOf.



# List static BR Codes
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/cob/list-static-brcodes

/en/openapi/v3-current/pix-lerian-cob.yaml get /brcodes/static
Returns a page-based list of static BR Codes with optional key/status filters.



# Revise a due-date collection's value modifiers
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/cob/revise-due-date-collection

/en/openapi/v3-current/pix-lerian-cob.yaml patch /collections/duedate/{id}
Revises the four BACEN value modifiers (fine, interest, abatement, discount) of an ACTIVE due-date collection. Each modifier is an independent RFC 7386 JSON Merge Patch slot: an object present in the body REPLACES that modifier outright, an explicit `null` REMOVES it, and an absent field leaves the currently-stored modifier unchanged. At least one modifier field is required. No other field (calendar, debtor, key, receiver) is revisable through this endpoint.

**Replay:** retrying the same request with the same `X-Idempotency` returns the ORIGINAL 200 response unchanged rather than re-applying the modifiers a second time; retrying the same key with a divergent body is PIX-0031 @ 412. Unlike the other gated mutations, this route is FAIL-CLOSED: if the replay cache cannot serve the request it refuses with PIX-0032 @ 503 instead of re-applying the modifiers without replay protection.



# Check whether Pix keys exist
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/check-keys-existence

/en/openapi/v3-current/pix-lerian-dict.yaml post /keys/check
Verifies whether the provided Pix keys exist in the DICT system. Supports batch verification of multiple keys in a single request.



# Create a Pix key entry
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/create-entry

/en/openapi/v3-current/pix-lerian-dict.yaml post /entries
Registers a new Pix key entry in the DICT directory. Assumes Receita Federal validation and MFA ownership authentication were completed by the client before the request.



# Delete a Pix key entry
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/delete-entry

/en/openapi/v3-current/pix-lerian-dict.yaml delete /entries/{entry_id}
Marks a Pix key entry as DELETED. The entry is no longer active after the operation.



# Get a Pix key entry
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/get-entry

/en/openapi/v3-current/pix-lerian-dict.yaml get /entries/{entry_id}
Retrieves a Pix entry by its unique identifier, scoped to the calling account.



# List Pix key entries for an account
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/list-entries

/en/openapi/v3-current/pix-lerian-dict.yaml get /entries
Returns a page-based list of Pix entries owned by the account in X-Account-Id. Account-scoped to prevent cross-account PII exposure; key_type and sort_order are case-insensitive.



# Retrieve a Pix key
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/lookup-key

/en/openapi/v3-current/pix-lerian-dict.yaml get /keys/{key}
Queries the DICT system for Pix key details for payment preparation. The key type is inferred server-side from the value's shape.



# Update a Pix key entry
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/dict/update-entry

/en/openapi/v3-current/pix-lerian-dict.yaml patch /entries/{entry_id}
Updates an existing Pix entry (RFC 7386 JSON Merge Patch). Only account information, name, and trade name can be changed.



# Cancel an authorization at the payer's request
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/pix-automatico/cancel-authorization

/en/openapi/v3-current/pix-lerian-pixauto.yaml post /payer/authorizations/{authorization_id}/cancel
Revokes the mandate at the payer's request. The revocation is IMMEDIATE and CASCADES over every debit scheduled under it, retries after the due date included — except those due for settlement on the day the revocation happens, which are preserved by rule (Guia v1.2 §3.7.1).

The termination and the scheduled-debit cascade commit together or not at all, so a mandate cannot be revoked while cancellable debits remain active.

A non-zero preservedScheduledPayments is CORRECT behaviour, not a partial failure. Those debits will still settle today, and the payer is shown the count so they know it.

The body's reason is a free-text note for the payer's own audit trail. It is NOT the value sent to the counterparty: the receiving PSP is told motivoCancelamento = SLDB, the pain.011 code for a cancellation the paying user asked for, which the response echoes as counterpartyReason.

A revocation over a mandate that has upcoming debits reports non-zero values on either counter, so a caller must read them rather than assume zero.



# Cancel a single scheduled debit at the payer's request
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/pix-automatico/cancel-scheduled-payment

/en/openapi/v3-current/pix-lerian-pixauto.yaml post /payer/scheduled-payments/{scheduled_payment_id}/cancel
Cancels ONE scheduled debit at the payer's request (Guia v1.2 §4.1).

The AUTHORIZATION IS NOT AFFECTED. This stops a single charge; the mandate keeps billing and future cycles are still scheduled. To end the mandate itself — which cascades over every debit scheduled under it — use POST /v1/payer/authorizations/{authorization_id}/cancel instead. The two are told apart on the wire by the camt.055 reason: SLBD here, CCLD there.

THE WINDOW CLOSES AT MIDNIGHT of the settlement date, in America/Sao_Paulo: the payer may cancel up to 23:59:59 of the day before, and a request at or after 00:00 is refused with PIX-0825. That boundary is where the 00:00-08:00 settlement window opens, so a cancellation admitted past it would race the debit it is trying to stop.

A DEBIT ARISING FROM A POST-DUE RETRY (purpose NTAG) CANNOT BE CANCELLED HERE, at any hour, and is refused with PIX-0826 (Guia v1.2 §5.1): the retry is a collection the payer already authorized, and ending the mandate is the payer's remedy. The receiving side may still cancel that same charge.

The cancellation is communicated to the receiving PSP by camt.055, raised asynchronously from an obligation written in the same transaction as the cancellation. The payer is notified of the cancellation unconditionally, including when scheduling notifications are disabled.



# Load a recurrence from a scanned QR Code
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/pix-automatico/create-authorization-request-from-qr-code

/en/openapi/v3-current/pix-lerian-pixauto.yaml post /payer/authorization-requests/from-qr
Entry point for authorization journeys 2, 3 and 4 (Manual de Padrões §4.4). The app decodes the composed QR Code, detects the journey from its content and reads the recurrence payload over HTTPS directly from the receiving PSP (Manual §2.5.2).

Journey 3 carries an immediate first payment which is an ordinary Pix on the existing rail, NOT commanded by this service. Guia v1.2 §3.4 requires its settlement flow to have completed before the authorization flow proceeds, so `immediatePayment.result` must be SETTLED on that journey; anything else aborts the whole journey and creates nothing. A payment that DID settle is never reverted because the authorization then failed — the payer paid what they owed.

Journey 4 reads the same field under a different rule. Guia v1.2 §3.5 relaxes the ordering — the payer may have SCHEDULED the charge instead of paying it, and the authorization must still be offered — but forbids the offer after an error: a `result` of FAILED aborts the journey and creates nothing, while SCHEDULED and SETTLED proceed. Omitting the object on journey 4 is admitted and asserts nothing about a payment.

Failure to read the payload is absence of data, not rejection of the recurrence: the journey stops with an error and no recurrence state is created. The request this returns is pending — the payer answers it through the decision operation.

The response carries lifecycle identifiers and the decision deadline; it does not echo the fetched counterparty or recurrence terms. The channel must obtain the terms it displays to the payer from its provider/messaging integration.



# Accept or reject an authorization request
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/pix-automatico/decide-authorization-request

/en/openapi/v3-current/pix-lerian-pixauto.yaml post /payer/authorization-requests/{authorization_request_id}/decide
Records the payer's decision. Confirmation and the granting of the authorization and the permission are a single command — there is no second confirmation step.

On acceptance the caller may set the payer parameters in the same call; omitted parameters take the normative defaults of Guia v1.2 §6 (notifications enabled, credit line enabled, no maximum amount).

On rejection, rejectionReason is mandatory and limited to the two motives the Guia admits. A rejection is NOT answered by the receiving PSP — the flow closes without a response (Guia v1.2 §3.2), so no acknowledgement should be awaited.



# Get one authorization
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/pix-automatico/get-authorization

/en/openapi/v3-current/pix-lerian-pixauto.yaml get /payer/authorizations/{authorization_id}
Returns one mandate, in ANY lifecycle state Authorizations itself lists: AWAITING_CONCLUSION, APPROVED, REJECTED, EXPIRED or CANCELLED. The representation is the SAME AuthorizationItem the listing already publishes.

A mandate belonging to a different account than X-Account-Id names is answered 404, exactly as one that does not exist: the account is a predicate on the lookup, so this end never learns the mandate exists elsewhere and cannot confirm it.

This operation does not include history: an integrator reads the append-only audit through the /history route.



# Get one authorization request
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/pix-automatico/get-authorization-request

/en/openapi/v3-current/pix-lerian-pixauto.yaml get /payer/authorization-requests/{authorization_request_id}
Returns one authorization request, in ANY state: pending, accepted, rejected, cancelled by the receiving PSP or expired. It is the companion of the pending-request listing above, which a request LEAVES the moment it is decided (Guia v1.2 §3.2) — this operation is what an integrator calls afterwards to learn the outcome.

A request belonging to a different account than X-Account-Id names is answered 404, exactly as one that does not exist: the account is a predicate on the lookup, so this end never learns the request exists elsewhere and cannot confirm it.



# List the state transitions of an authorization
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/pix-automatico/list-authorization-history

/en/openapi/v3-current/pix-lerian-pixauto.yaml get /payer/authorizations/{authorization_id}/history
Returns the append-only audit of one mandate: previous state, new state, instant, actor, correlation, and the operation identifier when the transition came from an external invocation. The projection is never updated and never deleted from.

Ordering is by the instant the transition HAPPENED (occurredAt), which is also what the cursor resumes on — not the write instant.

A mandate belonging to another payer account is answered 404, exactly as one that does not exist: the account in X-Account-Id is a predicate on the lookup, so this end never learns the mandate exists elsewhere and cannot confirm it.

Paging is by cursor. On the last page next_cursor is null, never an empty string.



# List authorization requests pending the payer's decision
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/pix-automatico/list-authorization-requests

/en/openapi/v3-current/pix-lerian-pixauto.yaml get /payer/authorization-requests
Returns the requests still awaiting the payer's decision, newest first — the "consulta e gerenciamento de autorizações pendentes" of Guia v1.2 §6.4.

A request LEAVES this list when it is accepted, rejected, cancelled by the receiving PSP (pain.011) or expires: §3.2 requires the payer PSP to remove it in the last two cases. There is deliberately no status parameter to widen the surface with.

This page is a lifecycle projection: it carries identifiers, journey, status and deadlines, but not the counterparty or recurrence terms. The channel must obtain the terms it displays to the payer from its provider/messaging integration.

Paging is by cursor. On the last page next_cursor is null, never an empty string.



# List the payer's authorizations
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/pix-automatico/list-authorizations

/en/openapi/v3-current/pix-lerian-pixauto.yaml get /payer/authorizations
Returns the payer's mandates. Without include_terminated it answers the ones that have NOT ENDED — the APPROVED mandates and those still AWAITING_CONCLUSION — which is the "consulta e gerenciamento de autorizações ativas" surface of Guia v1.2 §6.4; with include_terminated=true it answers that same section's "histórico de autorizações", the REJECTED, EXPIRED and CANCELLED mandates included.

WARNING: THE DEFAULT PAGE IS NOT THE SET OF ACTIVE MANDATES. A mandate stays AWAITING_CONCLUSION until the receiving PSP answers this end's concession with its conclusive pain.012, and until that message arrives it is NOT active at BACEN: nothing may be debited under it (Manual de Tempos do Pix v7.0 §3.2). It is listed by default because the payer was told to wait for precisely that flow and would look for it here. Filter on status=APPROVED to read only the mandates that are in force.

The maximum amount is returned here because this is the PAYER's own authenticated channel. Guia v1.2 §6.1 bars sharing it with the RECEIVING user and their PSP, which this surface is not.

This page does not repeat the counterparty or complete recurrence terms. It is the lifecycle and payer-parameter projection; the channel must join any richer display data from its provider/messaging integration.

Paging is by cursor. On the last page next_cursor is null, never an empty string.



# List scheduled debits
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/pix-automatico/list-scheduled-payments

/en/openapi/v3-current/pix-lerian-pixauto.yaml get /payer/scheduled-payments
Returns the payer's scheduled-debit lifecycle for the account — the "consulta e gerenciamento de pagamentos agendados" of Guia v1.2 §6.4.

It is NOT a forward-only view: a debit stays listed after it leaves SCHEDULED, so SETTLED and CANCELLED entries appear beside the ones still to come. A payer asking why a charge did not happen needs the cancelled row, and the cancellation route needs the id only this listing returns.

An empty page means that the account named in X-Account-Id has no scheduled debit.

This is the ONLY operation that returns a scheduled debit's id, and POST /v1/payer/scheduled-payments/{scheduled_payment_id}/cancel needs that id. Integrate the two together: list, then cancel by the id an item carries.

Each item carries maximumAmountSnapshot — the ceiling in force when the debit was SCHEDULED, written once and never updated — so a payer who has since changed the ceiling can see why an existing debit still reflects the old one. Returning it here is the payer's own authenticated channel; Guia v1.2 §6.1 bars sharing it with the RECEIVING user and their PSP, which this surface is not.

Ordering is by scheduledDate and then by id, which is also what the cursor resumes on — not the write instant, unlike the three sibling listings. authorizationId is absent on a debit scheduled without a mandate (purpose RIFL), and maximumAmountSnapshot is absent when no ceiling was in force; neither absence is an error.

Paging is by cursor. On the last page next_cursor is null, never an empty string.



# Update the payer-configurable parameters of an authorization
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/pix-automatico/update-authorization-parameters

/en/openapi/v3-current/pix-lerian-pixauto.yaml patch /payer/authorizations/{authorization_id}
RFC 7386 JSON Merge Patch over the three payer-configurable parameters of Guia v1.2 §6. Setting a property to null resets it to its NORMATIVE default; omitting it leaves it unchanged. The two toggles default to enabled, so a reset is not an opt-out.

A change never reaches debits already scheduled. The maximum amount in force at scheduling time is snapshotted on the debit and prevails (Guia v1.2 §6.1); the new value applies to future scheduling only.

The maximum amount never leaves this PSP: it is not shared with the receiving user or their PSP (Guia v1.2 §6.1).



# Pix Lerian error list
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/pix-lerian-error-list

Pix Lerian returns structured error responses. Look up a PIX-NNNN code to find what it means and the text the response carries.

**Error format**

This catalog covers the Pix Lerian application plugin. In v1.0.0, it applies to the delivered integration and testing lane with the mock provider adapter. It does not document an available native SPI messaging connector. See the [SPI error list](/en/reference/rails/spi/spi-error-list) only for that separate native-rail contract.

Pix Lerian answers an error in one of two shapes. The media type on the response tells you which shape you received. A response with the `application/json` media type carries the `code`, `title`, and `message` envelope. A response with the `application/problem+json` media type carries an RFC 9457 problem detail. Both shapes carry the `code` field, so you can branch on the `PIX-NNNN` value.

A refusal raised inside a handler uses the `application/problem+json` shape. A refusal raised before the handler runs uses the `application/json` shape. An unmatched path, a disallowed method, a timeout, a disconnect and the idempotency replay check all refuse before the handler runs.

```json application/json theme={null}
{
  "code": "PIX-0030",
  "title": "Idempotency Key Required",
  "message": "The X-Idempotency header is required for this operation and must be within the accepted length."
}
```

```json application/problem+json theme={null}
{
  "type": "https://errors.lerian.studio/v1/PIX-0240",
  "title": "Not Found",
  "status": 404,
  "detail": "No collection found for the given identifiers.",
  "code": "PIX-0240"
}
```

**Field definitions**

The `application/json` envelope carries three fields:

* **`code`** – A stable, unique identifier for the error (`PIX-NNNN`). Useful for programmatic handling and support requests.
* **`title`** – A short, human-readable summary of the issue.
* **`message`** – Detailed guidance to help you resolve the error.

The `application/problem+json` envelope follows RFC 9457:

* **`type`** – A URI that identifies the error in the Lerian error catalog. Built as `https://errors.lerian.studio/v1/<code>`.
* **`title`** – The HTTP status text (for example, `Not Found`).
* **`status`** – The HTTP status code.
* **`detail`** – A human-readable explanation for this occurrence of the problem. Use `code` to branch programmatically.
* **`code`** – The same `PIX-NNNN` identifier that the `application/json` envelope carries.
* **`errors`** – Optional list of per-field validation details, each with a `message` and a `location`.
* **`instance`** – Optional URI reference that identifies this specific occurrence.

The tables below list the codes by domain. The `Status` column shows the HTTP status for the code. The `detail` column shows the text that the `application/problem+json` shape carries. At status 500 and above that shape carries the fixed text `internal error`, and the tables show it on those rows.

`PIX-0010` and `PIX-0000` are generic fall-through codes. On a refusal raised before the handler runs, either one can carry a status other than the one in the table.

## Common errors

***

DICT, collections, and payments share these codes. They run from `PIX-0000` to `PIX-0061`.

| `code` | Description | Status | `detail` |
| - | - | - | - |
| PIX-0000 | Internal Server Error | 500 | `internal error` |
| PIX-0001 | Missing Headers in Request | 400 | Your request is missing one or more required header params. |
| PIX-0002 | Missing Fields in Request | 400 | Your request is missing one or more required fields. |
| PIX-0003 | Invalid Field Values in Request | 400 | Your request contains one or more fields with an invalid data type. |
| PIX-0004 | Unauthorized | 401 | Invalid or expired authentication credentials. |
| PIX-0005 | Forbidden | 403 | You do not have permission to perform this operation. |
| PIX-0006 | Too Many Requests | 429 | Rate limit exceeded. Please wait before making additional requests. |
| PIX-0008 | Route Not Found | 404 | The requested resource path does not exist. |
| PIX-0009 | Method Not Allowed | 405 | The HTTP method is not allowed for this resource. |
| PIX-0010 | Client Error | 400 | The request could not be processed due to a client-side error. |
| PIX-0011 | Entity Not Found | 404 | No entity was found for the given ID. Please make sure to use the correct ID. |
| PIX-0012 | Entity Conflict | 409 | The entity already exists or conflicts with an existing resource. |
| PIX-0013 | Unprocessable Operation | 422 | The operation could not be processed due to a business rule violation. |
| PIX-0014 | Action Not Permitted | 403 | The action you are attempting is not allowed in the current environment. |
| PIX-0015 | Invalid Path Parameter | 400 | One or more path parameters are invalid. |
| PIX-0016 | Unsupported Media Type | 415 | The request body must be sent with Content-Type: application/json. |
| PIX-0017 | Invalid Headers in Request | 400 | Your request contains one or more headers with an invalid format. |
| PIX-0018 | Tenant Context Missing | 400 | The request could not be associated with a tenant. Ensure tenant resolution ran for this route. |
| PIX-0020 | Invalid Query Parameter | 400 | One or more query parameters are in an incorrect format. |
| PIX-0021 | Invalid Date Format | 400 | The date fields are in the incorrect format. Please use the 'yyyy-mm-dd' format. |
| PIX-0022 | Invalid Date Range | 400 | Both 'start\_date' and 'end\_date' fields are required and must be in the 'yyyy-mm-dd' format. |
| PIX-0023 | Date Range Exceeds Limit | 400 | The range between 'start\_date' and 'end\_date' exceeds the permitted limit. |
| PIX-0024 | Pagination Limit Exceeded | 400 | The pagination limit exceeds the maximum allowed items per page. |
| PIX-0025 | Invalid Sort Order | 400 | The 'sort\_order' field must be 'asc' or 'desc'. |
| PIX-0026 | Metadata Key Length Exceeded | 400 | A metadata key exceeds the maximum allowed length. |
| PIX-0027 | Metadata Value Length Exceeded | 400 | A metadata value exceeds the maximum allowed length. |
| PIX-0028 | Invalid Metadata Nesting | 400 | The metadata object cannot contain nested values. |
| PIX-0030 | Idempotency Key Required | 400 | The X-Idempotency header is required for this operation and must be within the accepted length. |
| PIX-0031 | Idempotency Key Conflict | 412 | The X-Idempotency header was already used with a different request. |
| PIX-0032 | Idempotency Unavailable | 503 | `internal error` |
| PIX-0033 | Idempotency Effect Unknown | 409 | A previous attempt under this idempotency key already executed at the provider. The operation must be reconciled before it is retried. |
| PIX-0034 | Payload Too Large | 413 | The request body exceeds the maximum size allowed for this operation. |
| PIX-0050 | Invalid Transaction ID Format | 400 | The transaction ID does not match the required format. |
| PIX-0054 | Gateway Timeout | 504 | `internal error` |
| PIX-0055 | Client Disconnected | 499 | The client disconnected before the request completed. |
| PIX-0061 | Invalid Amount Format | 400 | The amount must be in decimal format with 2 decimal places. |

## DICT and Pix key errors

***

These codes come from Pix key entries, key lookup, claims, fraud markers, funds recoveries, and key synchronization. They run from `PIX-0100` to `PIX-0174`.

| `code` | Description | Status | `detail` |
| - | - | - | - |
| PIX-0100 | Invalid Input | 422 | Missing or malformed required fields. |
| PIX-0101 | Invalid Key Format | 400 | Key value does not match expected format for the key type. |
| PIX-0102 | Key Already Exists | 409 | Key value is already registered. |
| PIX-0103 | Key Limit Exceeded | 400 | Account has reached the maximum number of keys for this key type. |
| PIX-0104 | Account Ownership Failed | 400 | Account ownership could not be verified via CRM. |
| PIX-0105 | Entry Not Found | 404 | Key entry does not exist. |
| PIX-0106 | Entry Not Active | 422 | Key entry is not in ACTIVE status. |
| PIX-0107 | No Fields to Update | 400 | No updateable fields provided. |
| PIX-0108 | Deletion Reason Required | 400 | Deletion reason was not provided. |
| PIX-0109 | Invalid Filter | 400 | Invalid filter parameter value. |
| PIX-0110 | Funds Recovery Not Found | 404 | No funds recovery exists with the provided ID for this participant. |
| PIX-0111 | Idempotency Key Required | 400 | The X-Idempotency header is required for this operation. |
| PIX-0112 | Idempotency Key Conflict | 412 | The X-Idempotency header was already used with a different request body. |
| PIX-0113 | Funds Recovery Already Exists | 409 | A funds recovery already exists for this root transaction. |
| PIX-0114 | Invalid Funds Recovery State Transition | 409 | The requested operation is not allowed from the current funds recovery status. |
| PIX-0115 | Person Statistics Not Found | 404 | No statistics projection exists for the provided tax id. |
| PIX-0116 | Account Not Found | 422 | Account or holder not found for the provided key or account. |
| PIX-0117 | Funds Recovery Contestation Deadline Expired | 422 | The regulatory contestation deadline for this transaction has already expired. |
| PIX-0118 | Funds Recovery Outcome Pending | 409 | The provider accepted the operation but BACEN's outcome is not yet resolved; poll the operation before retrying. |
| PIX-0120 | Key Not Found | 404 | Key does not exist in the DICT directory. |
| PIX-0121 | Empty Key List | 400 | At least one key must be provided for the check operation. |
| PIX-0122 | Key List Exceeds Limit | 400 | The number of keys exceeds the maximum allowed (200). |
| PIX-0124 | Key In Custody | 409 | The requested key is already in the custody of the requesting account. |
| PIX-0130 | Fraud Marker Not Found | 404 | The requested fraud marker was not found at the provider. |
| PIX-0131 | Fraud Marker Conflict | 409 | The fraud marker operation conflicts with its current state at the provider. |
| PIX-0132 | Request ID Already Used | 400 | This requestId was already used with different parameters. |
| PIX-0133 | Fraud Marker Forbidden | 403 | The caller is not authorized to perform this fraud marker operation. |
| PIX-0134 | Fraud Marker Rate Limited | 429 | The provider rate-limited this fraud marker operation. |
| PIX-0140 | CRM Unavailable | 502 | `internal error` |
| PIX-0141 | Adapter Failure | 502 | `internal error` |
| PIX-0142 | Missing Required Field | 400 | A required field or header is missing from the claim request. |
| PIX-0143 | Invalid Field Value | 400 | One or more claim fields or headers have an invalid value. |
| PIX-0144 | Request Id Replay Mismatch | 409 | The X-Request-Id was already seen with a different request body. |
| PIX-0145 | Claim Not Found | 404 | No claim was found for the given identifier and account. |
| PIX-0146 | Unsupported Claim Configuration | 422 | The requested claim type and key type combination is not supported. |
| PIX-0147 | Invalid Claim Transition | 422 | The requested claim state transition is not permitted. |
| PIX-0148 | Claim Rate Limit Exceeded | 429 | The rate limit for this claim operation has been exceeded. |
| PIX-0149 | Claim Already Active For Key | 422 | An active claim already exists for this key. |
| PIX-0150 | Daily Budget Exhausted | 429 | Daily request budget is exhausted for createCidSetFile. |
| PIX-0151 | VSync State Not Found | 404 | No VSync state exists for the requested scope. |
| PIX-0152 | Reconciliation Job Not Found | 404 | Reconciliation job does not exist. |
| PIX-0153 | Discrepancy Not Found | 404 | Discrepancy record does not exist. |
| PIX-0154 | Discrepancy Already Resolved | 409 | Discrepancy has already been resolved. |
| PIX-0155 | Job Not Retryable | 409 | Reconciliation job is not in a retryable state. |
| PIX-0156 | Active Job Exists | 409 | An active reconciliation job already exists for this scope. |
| PIX-0157 | Invalid Scope | 400 | Unknown ISPB or key type in the requested scope. |
| PIX-0158 | Verification Budget Exhausted | 429 | Request budget is exhausted for sync verifications. |
| PIX-0159 | Scope Not Escalation Blocked | 409 | The requested scope is not in ESCALATION\_BLOCKED status. |
| PIX-0160 | Reconciliation Log Not Found | 404 | Reconciliation log entry does not exist. |
| PIX-0161 | Webhook Job Not Found | 404 | No reconciliation job found for the given scope. |
| PIX-0162 | Invalid Webhook Payload | 400 | The webhook payload is invalid or contains inconsistent data. |
| PIX-0163 | Claim Blocked By Fraud | 422 | The claim was rejected because the key is marked for fraud. |
| PIX-0164 | Claim Adapter Unavailable | 503 | `internal error` |
| PIX-0165 | Claim Not Acknowledgeable | 422 | The acknowledge preconditions are not met for this claim. |
| PIX-0166 | Same Participant | 422 | The donor and claimer participants must differ. |
| PIX-0167 | Resolution Period Missing | 422 | The resolution period is required for this claim transition. |
| PIX-0168 | Terminal State | 422 | The claim is in a terminal state and cannot be mutated. |
| PIX-0169 | Claim Mutations Temporarily Blocked | 503 | `internal error` |
| PIX-0171 | Key Does Not Exist | 422 | The key is not registered in the directory; there is nothing to claim. |
| PIX-0172 | Invalid Opening Date | 422 | The account opening date returned by CRM could not be parsed. |
| PIX-0173 | Key Already Belongs To Holder | 422 | The key already belongs to the requesting holder. |
| PIX-0174 | Invalid Verify-Sync Scope | 422 | Unknown ISPB or key type in the requested verify-sync scope. |

## Collections and BR Code errors

***

These codes come from BR Codes, immediate collections, and due-date collections. They run from `PIX-0200` to `PIX-0267`.

| `code` | Description | Status | `detail` |
| - | - | - | - |
| PIX-0200 | Invalid Input | 400 | Missing or malformed required fields. |
| PIX-0201 | Key Not Found | 422 | Pix key does not exist or is not active. |
| PIX-0202 | Merchant Name Too Long | 400 | Merchant name exceeds the 25-character EMV limit. |
| PIX-0203 | Merchant City Too Long | 400 | Merchant city exceeds the 15-character EMV limit. |
| PIX-0204 | EMV Generation Failed | 500 | `internal error` |
| PIX-0205 | BR Code Not Found | 404 | BR Code does not exist for this organization. |
| PIX-0206 | Invalid Filter | 400 | Invalid filter parameter value. |
| PIX-0207 | BR Code Field Too Long To Encode | 422 | keyValue and description together exceed the length the BR Code merchant template can encode. Shorten the description, or use a shorter Pix key. |
| PIX-0220 | Malformed EMV Payload | 400 | EMV payload is malformed or not a valid Pix QR code. |
| PIX-0221 | QR Decode Failed | 400 | QR code could not be parsed. |
| PIX-0222 | Dynamic QR Resolution Failed | 502 | `internal error` |
| PIX-0223 | Adapter Unreachable | 502 | `internal error` |
| PIX-0224 | Provider Rejected Collection | 400 | The provider rejected the collection request. |
| PIX-0225 | Provider Resource Not Found | 404 | The requested collection resource was not found at the provider. |
| PIX-0226 | Provider State Conflict | 409 | The collection is in a conflicting state at the provider. |
| PIX-0240 | Collection Not Found | 404 | No collection found for the given identifiers. |
| PIX-0241 | Collection In Terminal State | 422 | Collection is in a terminal state (already CANCELLED or COMPLETED) and cannot transition. |
| PIX-0242 | Collection Already Paid | 409 | Collection has already been marked as paid. |
| PIX-0260 | Due Date Required | 400 | The due-date calendar (dueDate/validityAfterDue) is required for a due-date collection. |
| PIX-0261 | Validity After Due Invalid | 400 | validityAfterDue must be zero or a positive number of calendar days. |
| PIX-0262 | Debtor Required | 400 | The debtor block is required for a due-date collection. |
| PIX-0263 | Fine Terms Invalid | 400 | The fine (multa) modality or value is invalid. |
| PIX-0264 | Interest Terms Invalid | 400 | The interest (juros) modality or value is invalid. |
| PIX-0265 | Abatement Terms Invalid | 400 | The abatement (abatimento) modality or value is invalid. |
| PIX-0266 | Discount Terms Invalid | 400 | The discount (desconto) modality, value, or fixed dates are invalid. |
| PIX-0267 | Due Date Invalid | 400 | dueDate must not be earlier than today. |

## Payments and refund errors

***

These codes come from Pix transfers, refunds, and their settlement. They run from `PIX-0300` to `PIX-0706`.

| `code` | Description | Status | `detail` |
| - | - | - | - |
| PIX-0300 | Missing or Malformed Fields | 400 | Missing or malformed required fields for transfer initiation. |
| PIX-0301 | Initiation Type Mismatch | 400 | initiationType does not match provided destination fields. |
| PIX-0302 | Source Account Invalid | 400 | Source account not found or inactive in CRM. |
| PIX-0303 | DICT Key Not Found | 422 | DICT key lookup returned no results. |
| PIX-0304 | QR Code Decode Failed | 422 | QR code could not be decoded. |
| PIX-0320 | Initiation Not Found | 404 | Initiation ID does not exist. |
| PIX-0321 | Initiation Expired | 422 | Initiation has expired. |
| PIX-0322 | Initiation Already Confirmed | 409 | Initiation was already confirmed. |
| PIX-0323 | Midaz Debit Failed | 422 | Midaz debit failed due to insufficient balance. |
| PIX-0324 | Midaz Transaction Failed | 502 | `internal error` |
| PIX-0325 | Provider Call Failed After Debit | 502 | `internal error` |
| PIX-0326 | Initiation Cancelled | 409 | Initiation has been cancelled and cannot be processed. |
| PIX-0327 | Transfer Conflict | 409 | The transfer changed during this request. Retry the operation. |
| PIX-0328 | Ledger Account Blocked | 422 | The ledger account is blocked and cannot be used for the requested operation. |
| PIX-0329 | Ledger Balance Not Found | 422 | No balance record exists for the account and asset. |
| PIX-0340 | Transfer Not Found | 404 | Transfer ID does not exist for this organization. |
| PIX-0341 | Invalid Filter Parameter | 400 | Invalid filter parameter value. |
| PIX-0342 | Date Range Exceeds Limit | 400 | Date range exceeds 90 days. |
| PIX-0400 | Original Transfer Not Found | 404 | Original transfer does not exist. |
| PIX-0401 | Transfer Not Completed | 422 | Original transfer is not in COMPLETED status. |
| PIX-0402 | Refund Amount Exceeds Remaining | 422 | Refund amount exceeds remaining refundable amount. |
| PIX-0403 | Missing or Malformed Fields | 400 | Missing or malformed required fields for refund. |
| PIX-0404 | Provider Call Failed | 502 | `internal error` |
| PIX-0405 | Midaz Transaction Failed | 502 | `internal error` |
| PIX-0406 | Refund Conflict | 409 | The refund changed during this request. Retry the operation. |
| PIX-0420 | Refund Not Found | 404 | Refund ID does not exist for this organization. |
| PIX-0421 | Invalid Filter Parameter | 400 | Invalid filter parameter value. |
| PIX-0422 | Date Range Exceeds Limit | 400 | Date range exceeds 90 days. |
| PIX-0450 | Destination Account Not Found | 422 | Destination account does not exist. |
| PIX-0451 | Destination Account Not Active | 422 | Destination account is not active. |
| PIX-0453 | CRM Unavailable | 502 | `internal error` |
| PIX-0454 | Midaz Unavailable | 502 | `internal error` |
| PIX-0470 | Payment Not Found | 404 | No approved payment for this endToEndId. |
| PIX-0472 | Midaz Credit Failed | 502 | `internal error` |
| PIX-0500 | Original Transfer Not Found | 404 | Original transfer not found for this endToEndId. |
| PIX-0501 | Refund Exceeds Remaining | 422 | Refund exceeds remaining refundable amount. |
| PIX-0502 | Missing or Malformed Fields | 400 | Missing or malformed required fields. |
| PIX-0520 | Refund Not Found | 404 | No approved refund for this endToEndId. |
| PIX-0521 | Already Settled | 409 | Refund was already settled. |
| PIX-0522 | Midaz Credit Failed | 502 | `internal error` |
| PIX-0550 | Entity Not Found | 404 | No PROCESSING entity found for this endToEndId. |
| PIX-0551 | Unexpected State | 409 | Callback received for entity not in PROCESSING state. |
| PIX-0552 | Invalid Status | 400 | Status is not a valid terminal state. |
| PIX-0553 | Midaz Revert Failed | 502 | `internal error` |
| PIX-0554 | Entity Already Terminal | 409 | The entity has already reached a terminal state; there is nothing to unblock. |
| PIX-0555 | Insufficient Processing Age | 409 | The entity has not been in PROCESSING long enough to be unblocked; wait and retry. |
| PIX-0556 | Provider Has No Terminal Outcome Yet | 409 | The provider has not reached a terminal outcome for this entity yet; wait and retry. |
| PIX-0557 | Provider Unreachable | 502 | `internal error` |
| PIX-0650 | Blocking Account Not Configured | 422 | The blocking account is not configured for this participant. |
| PIX-0652 | Ledger Failure | 502 | `internal error` |
| PIX-0653 | Settle In Progress | 409 | The block is settling and cannot be cancelled or restarted; confirm or close it instead. |
| PIX-0654 | Nothing To Settle | 422 | There is nothing left to settle for this block. |
| PIX-0655 | Account Alias Unresolvable | 422 | An account required for this operation has no resolvable alias in the ledger. |
| PIX-0700 | DICT Hub Unavailable | 502 | `internal error` |
| PIX-0701 | COB Hub Unavailable | 502 | `internal error` |
| PIX-0702 | CRM Unavailable | 502 | `internal error` |
| PIX-0703 | Resource Not Found | 404 | The requested SPI resource was not found. |
| PIX-0704 | State Conflict | 409 | The resource is in a conflicting state for the requested operation. |
| PIX-0705 | Upstream Service Unavailable | 502 | `internal error` |
| PIX-0706 | Bad Request | 400 | The request is invalid. |


# Cancel a scheduled Pix payment
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/cancel-scheduled-payment

/en/openapi/v3-current/pix-lerian-spi.yaml post /scheduled-payments/{schedule_id}/cancel
Cancels a schedule at the payer's request, accepted right up to the cancellation cut-off recorded on it and refused AT that instant. The deadline compared against is the one photographed when the schedule was created, not whatever the configuration derives today: the deadline the payer was told is the deadline they get. Because the cut-off is strictly before the first settlement window, cancelling and executing can never both be in time. Nothing is released -- nothing was held.



# Create an outbound Pix refund (MED)
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/create-refund

/en/openapi/v3-current/pix-lerian-spi.yaml post /transfers/{id}/refunds
Issues a refund against a previously completed CASHIN transfer with a structured pacs.004 reasonCode.



# Register a scheduled Pix payment
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/create-scheduled-payment

/en/openapi/v3-current/pix-lerian-spi.yaml post /scheduled-payments
Registers a Pix payment for a future civil date, evaluated in America/Sao_Paulo. The available balance is NOT touched here (RF-07, REG-Art.9 caput): nothing moves until the scheduled date, when the order is sent inside the settlement window IN 513 art. 12 fixes. Non-business days are accepted, because Pix settles every day. Pix Saque (OTHR) and Pix Troco (GSCB) are refused at creation rather than on the scheduled date: REG-Art.11-P prohibits scheduling them, and the rule is knowable now. The payee is photographed at creation AND resolved again on the scheduled date, which is what REG-Art.9§5 requires -- a key can be reassigned in between.



# Get a Pix refund by ID
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/get-refund

/en/openapi/v3-current/pix-lerian-spi.yaml get /refunds/{id}
Returns a single refund scoped to the calling account.



# Read one scheduled Pix payment
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/get-scheduled-payment

/en/openapi/v3-current/pix-lerian-spi.yaml get /scheduled-payments/{schedule_id}
Returns the schedule together with every attempt of its scheduled day, oldest first. The list is empty and never null before that date. A schedule belonging to another organization answers 404 rather than 403: the read is scoped by organization, so the row is never seen, and answering 'forbidden' would confirm the identifier exists.



# Schedules a proposed limit would make unviable
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/get-scheduled-payment-limit-impact

/en/openapi/v3-current/pix-lerian-spi.yaml get /scheduled-payment-limit-impact
The totals route seen from the other side: given a proposed limit, returns the future schedules that would exceed it, so the institution can see the consequence BEFORE concluding a reduction. This route reads -- it does not apply the reduction and does not judge it. Each item carries its date's total, so a caller can see why a small schedule is affected rather than only that it is. Nothing affected is an empty page, never null.



# Read a scheduled payment's receipt
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/get-scheduled-payment-receipt

/en/openapi/v3-current/pix-lerian-spi.yaml get /scheduled-payments/{schedule_id}/receipt
Returns the proof of what was agreed: the amount, the settlement date, both parties as photographed at creation, and the cancellation deadline the payer was told. It carries no status and no attempt history on purpose -- a receipt answers what was committed to, and putting the lifecycle in it would make a document people save go stale the moment the schedule moves.



# Total scheduled for an account on a date
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/get-scheduled-payment-totals

/en/openapi/v3-current/pix-lerian-spi.yaml get /scheduled-payment-totals
THIS ROUTE AND ITS SIBLING ARE THE WHOLE OF WHAT THE SWITCH DOES ABOUT DAILY PIX LIMITS. The policy belongs to the client institution, which holds the ISPB and answers to BACEN for it; the Switch does not accumulate, project or decide. It returns the figure the decision needs. The total sums every NON-TERMINAL schedule for that account on that date -- cancelled and failed ones are excluded, because neither will move money. Supplying night_period_start adds the IN 512 art. 7 §7 slice, which is a DIFFERENT rule from the general night period of art. 3: created inside the window, settling the next day, to a natural person distinct from the payer. Omit the parameter and the slice is omitted rather than defaulted.



# Get a Pix transfer by ID
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/get-transfer

/en/openapi/v3-current/pix-lerian-spi.yaml get /transfers/{id}
Returns a single transfer scoped to the calling account.



# Initiate a Pix transfer (step 1)
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/initiate-transfer

/en/openapi/v3-current/pix-lerian-spi.yaml post /transfers/cashout/initiate
Creates a transfer initiation in PENDING state and validates the source account. The amount is supplied at process time.



# List Pix refunds for an account
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/list-refunds

/en/openapi/v3-current/pix-lerian-spi.yaml get /refunds
Returns a cursor-paginated page of refunds for the calling account.



# List scheduled Pix payments
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/list-scheduled-payments

/en/openapi/v3-current/pix-lerian-spi.yaml get /scheduled-payments
Returns a page of the organization's scheduled payments, newest settlement date first. Paging is by opaque cursor rather than offset: a schedule registered between two pages would shift every later row under an offset and silently skip one. Echo the cursor verbatim. The page carries no attempt history -- that is per-schedule data a list view does not show, and it is on the single-schedule route instead.



# List Pix transfers for an account
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/list-transfers

/en/openapi/v3-current/pix-lerian-spi.yaml get /transfers
Returns a cursor-paginated page of transfers for the calling account.



# Process and confirm a Pix transfer (step 2)
Source: https://docs.lerian.studio/en/reference/interfaces/pix-lerian/spi/process-transfer

/en/openapi/v3-current/pix-lerian-spi.yaml post /transfers/cashout/process
Confirms a previously initiated transfer, debits the source account, and submits the Pix payment for processing.



# Pix Direct via JD events
Source: https://docs.lerian.studio/en/reference/events/pix-direct-jd

CloudEvents emitted by the Pix Direct via JD integration for transaction, DICT key, and Pix Automático lifecycles.

The Pix Direct via JD integration emits 21 JSON business facts as CloudEvents 1.0 in binary content mode over Kafka. Streaming is optional. When enabled, the integration writes the business state and event envelope to the PostgreSQL outbox in the same transaction. The outbox relay is the only broker publisher.

## Transport contract

| Field | Value |
| - | - |
| `ce-source` | `plugin-br-pix-jd` |
| Topic | `lerian.streaming.plugin-br-pix-jd` |
| Schema version | `1.0.0` for every event |
| Content type | `application/json` |
| Delivery | At least once through the transactional outbox |
| Command topic | None |
| Runtime manifest | Not exposed |

Set `STREAMING_ENABLED=true` and `OUTBOX_ENABLED=true` together. If you set `STREAMING_CLOUDEVENTS_SOURCE`, its value must be exactly `plugin-br-pix-jd`. When streaming is off, the integration does not write lifecycle events to the streaming outbox.

> [!WARNING]
>
> This integration does not expose a streaming manifest endpoint yet. Its bootstrap catalog contains only the structural `transaction.created` definition, while the production emit paths below publish all 21 facts. Use this page as the current event inventory, not the incomplete runtime catalog.

Deduplicate on `(ce-source, ce-id)` and keep consumers idempotent. The integration provisions no command topic.

## Event catalog

Every `ce-type` uses `studio.lerian.plugin-br-pix-jd.<event-key>`.

### Transactions

| Event key | Fires when |
| - | - |
| `transaction.created` | An external cash-out is persisted as pending, its pending Midaz posting exists, and the JDPI submission succeeds. |
| `transaction.executed` | An internal transfer completes synchronously, a cash-in is applied, or reconciliation settles an external cash-out. |
| `transaction.refunded` | A refund transaction is persisted and linked to the original transaction. |
| `transaction.failed` | Reconciliation moves a pending external cash-out to its terminal error state and cancels the pending posting. |

### DICT keys and claims

| Event key | Fires when |
| - | - |
| `key.registered` | A key is registered in DICT and persisted as active. |
| `key.validation-requested` | The integration stores and dispatches an ownership-validation challenge. |
| `key.confirmed` | The submitted challenge is verified and the key leaves the waiting-for-confirmation state. |
| `key.deleted` | A key is deleted in DICT and soft-deleted locally. |
| `key.claimed` | A claim is opened in DICT and its identifier is persisted. |
| `key.claim-confirmed` | The donor confirms the claim. |
| `key.claim-concluded` | The claimer concludes the claim. |
| `key.claim-cancelled` | The claim is cancelled. |

### Pix Automático authorizations

| Event key | Fires when |
| - | - |
| `authorization.requested` | The receiving PSP requests an authorization and the integration persists it as requested. |
| `authorization.accepted` | The payer accepts the authorization. |
| `authorization.rejected` | The authorization transitions to rejected. |
| `authorization.activated` | The authorization is confirmed successfully and transitions to active. |
| `authorization.cancelled` | The authorization is cancelled and soft-deleted. |

### Pix Automático schedules

| Event key | Fires when |
| - | - |
| `schedule.requested` | The receiving PSP requests a payment schedule and the integration persists it as requested. |
| `schedule.accepted` | The schedule transitions to accepted. |
| `schedule.rejected` | The schedule transitions to rejected. |
| `schedule.cancelled` | The schedule is cancelled and soft-deleted. |

## Payload contracts

All timestamps are UTC RFC 3339 strings. Transaction and Pix Automático monetary values are integer centavos, not decimal strings or floating-point numbers. Fields marked with `?` are optional.

> [!WARNING]
>
> The wire contract encodes `amount`, `value`, and `payerMaxValue` as JSON `int64` number tokens. JavaScript consumers that accept the full `int64` range must use lossless, BigInt-aware JSON parsing or reject values above `Number.MAX_SAFE_INTEGER`. Standard `JSON.parse` can round larger integers.

```typescript theme={null}
interface TransactionEventData {
  id: string
  jdpiRequestId?: string
  indirectId?: string
  endToEndId?: string
  status: string
  flow: number
  type: number
  amount: number // int64 centavos
  accountId: string
  isRefund: boolean
  isInternal: boolean
  refundType?: number
  refundAccountId?: string
  refundEndToEndId?: string
  refundCode?: string
  createdAt: string
  updatedAt: string
}

interface KeyEventData {
  id: string
  key: string
  accountId: string
  status: number
  keyType: number
  claimId?: string
  claimType?: number
  createdAt: string
  updatedAt: string
}

interface AuthorizationEventData {
  id: string
  idRecorrencia: string
  idReqJdPi?: string
  idCancelamento?: string
  tenantId?: string
  status: number
  frequency: number
  value?: number // int64 centavos
  payerMaxValue?: number // int64 centavos
  recipientIspb?: string
  recipientCnpj?: string
  payerCpfCnpj?: string
  contractNumber?: string
  createdAt: string
  updatedAt: string
}

interface ScheduleEventData {
  id: string
  endToEndId: string
  idRecorrencia: string
  idConciliacaoRecebedor?: string
  idCancelamento?: string
  tenantId?: string
  status: number
  finalidadeAgendamento: number
  dtVencimento?: string
  value?: number // int64 centavos
  recipientIspb?: string
  recipientCnpj?: string
  payerCpfCnpj?: string
  createdAt: string
  updatedAt: string
}
```


# Activate a rail for the caller's tenant
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/activate-a-rail-for-the-caller-s-tenant

/en/openapi/v3-current/jd-courier.yaml put /v1/channels/{channelId}/activation
Until a rail is active for a tenant, the Pix ingress resolves no tenant and the SPB drain reads nothing from the vendor. Activating spb starts the drain of the vendor queue, whose read is destructive: from then on the Courier, not the engines, consumes it. The tenant is the caller's, from the validated identity, and is returned as tenantId — the identifier an engine's credential path names. The first activation records the operator as registeredBy. Activating a suspended rail resumes it; an active one is returned unchanged. A single-tenant Courier carries one tenant per rail: activating a rail another tenant holds active is refused 409 JDC-0117. Needs the admin grant (channels activation:write); channels write is not enough.



# Assign a key to an engine
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/assign-a-key-to-an-engine

/en/openapi/v3-current/jd-courier.yaml post /v1/ownership/assignments
A double owner is inexpressible: a key owned by a different engine is refused 409 JDC-0102, which points at the move operation. Re-assigning to the current owner is a no-op answered 200, with no new audit entry.



# Claim a Pix Automático recurrence for the calling engine
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/claim-a-pix-automatico-recurrence-for-the-calling-engine

/en/openapi/v3-current/jd-courier.yaml put /v1/ownership/recurrences/{recurrenceId}
The engine that authorizes a recurrence claims it, and the Courier then routes the recurrence's messages to it. 201: the recurrence is now the caller's. 204: it already was. 409 JDC-0102: another engine holds it; stop and report it to an operator, because only an operator moves a recurrence. 422 JDC-0104: the recurrenceId is not usable. 503: nothing was recorded; send the same claim again, it is idempotent. The owner is always the caller: an engine claims for itself and can write nothing else to the map.



# Close a reconciliation finding
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/close-a-reconciliation-finding

/en/openapi/v3-current/jd-courier.yaml post /v1/assurance/findings/{findingId}/close
An operator who investigated and settled a finding closes it with a mandatory note and the finding's updatedAt as read. The Courier records who closed it, when and the note; the finding stays in history. A cycle that re-raised the finding after it was read answers 409 JDC-0008: re-read it, so no window is closed unread. A finding already closed answers 200 with its first closure, never overwritten. A later cycle that sees a new divergence opens a new finding. Idempotent per X-Idempotency: the same key with another body is 409 JDC-0003.



# Close an indeterminate send by hand
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/close-an-indeterminate-send-by-hand

/en/openapi/v3-current/jd-courier.yaml post /v1/send-journal/{controlId}/resolve
Records an operator's finding on an INDETERMINATE send — the engine's settle or revert, JD support's written answer — with the evidence and a note, and changes nothing else. It is a record, never a routing decision: the outcome stays INDETERMINATE, a second send of the same control id is still refused, and the engine's ConsultaNumCtrlIF is still forwarded to JD, whose answer may still resolve the row. It never resends and calls no vendor. The Courier offers no by-hand NOT_SENT: an operator wrong about "never sent" would release the control id for a second send, and two TEDs would reach BACEN. What the close changes is the alert: a closed send stops aging. 409 JDC-0303 when the send is not INDETERMINATE or was already closed; 404 JDC-0302 when the journal does not hold it. A body missing a field, carrying a non-string or an unexpected property is 400 JDC-0001; a present field whose value breaks a rule (blank evidence, a note outside 10-500 characters after trimming) is 422 JDC-0002.



# Declare an earlier leg of a Pix Automático payment the calling engine holds
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/declare-an-earlier-leg-of-a-pix-automatico-payment-the-calling-engine-holds

/en/openapi/v3-current/jd-courier.yaml put /v1/ownership/payments/{endToEndId}/legs/{leg}
Before the Courier takes over Pix, each engine declares the payments in flight whose earlier leg it already answered yes: the debit block (block) of every payment whose debit or reversal is still to come, and the schedule (schedule) of every schedule whose cancellation status is still to come. Those later legs then reach the caller. A later leg that arrived first is retained and is released by the Courier's re-check once its leg is declared. A leg the Courier itself dispatched outranks any declaration unless its engine answered other than yes. 201: the leg now follows the caller. 204: it already did. 409 JDC-0116: the Courier's record gives the leg to another engine, or holds the caller's answer to the block that was not a yes; stop and report it to an operator. 422 JDC-0104: the leg or the endToEndId is not usable. 503: nothing may have been recorded; send the same declaration again, it is idempotent. The holder is always the caller.



# Declare that an engine is in bypass on this rail
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/declare-that-an-engine-is-in-bypass-on-this-rail

/en/openapi/v3-current/jd-courier.yaml put /v1/channels/{channelId}/bypass
Records that an engine was reconnected directly to the vendor. Activating the bypass itself is a configuration change in the engine; this operation declares the fact to the Courier so it suspends its guarantees explicitly instead of reporting green while blind. With one engine in bypass, declaring a second on the same (tenant, channel) returns 409 JDC-0301 — the database's partial unique index decides it. Declaring the same engine again keeps the one active row: its declaredAt becomes the earlier of the two (the interval only ever lengthens) and its reason the new one. A backdated declaration overlapping another engine's cleared bypass is accepted, and the Courier logs a WARN naming both engines and the overlap interval. A rail that declares no bypass refuses with 422 JDC-0501. While a bypass is active the Courier's own SPB consumer takes nothing for that (tenant, channel).



# Declare the delivery mode for one message code
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/declare-the-delivery-mode-for-one-message-code

/en/openapi/v3-current/jd-courier.yaml put /v1/channels/{channelId}/delivery-modes/{messageCode}
Declares that a code takes every engine or is refused instead of the single-owner default. The reason is mandatory. Two refusals, both on the write and neither at delivery: 422 JDC-0110 when the rail lists the code among its financial families, and 422 JDC-0112 when the rail does not declare the mode. Deliveries stay one row per (message, engine); the expectation is frozen onto each message at routing. Idempotent per (channelId, messageCode, mode, reason).



# Declare the end of a bypass on this rail
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/declare-the-end-of-a-bypass-on-this-rail

/en/openapi/v3-current/jd-courier.yaml delete /v1/channels/{channelId}/bypass
Idempotent. Restores the coexistence guarantees for that engine.



# Enable, disable or rename an engine
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/enable-disable-or-rename-an-engine

/en/openapi/v3-current/jd-courier.yaml patch /v1/engines/{engineId}
There is no delete. A disabled engine receives no new deliveries, cannot receive new ownership assignments, and keeps every row it already owns. A disable requires a reason.



# Issue the engine's SOAP channel credential
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/issue-the-engine-s-soap-channel-credential

/en/openapi/v3-current/jd-courier.yaml post /v1/engines/{engineId}/channel-credential
Mints the three TAutenticacao values the engine presents to the Courier's /soap. The secret is returned once. Minting while a credential is live is the rotation: the older credentials keep working for the configured overlap window, then stop. The credential is stored only in the tenant's own database: on a send, the tenant manager lists the tenants and the tenant database that holds the legacy code authenticates; there is no shared index.



# JD Courier error list
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/jd-courier-error-list

JD Courier returns RFC 9457 problem details on its operator API and its engine API. Look up a JDC-NNNN code to find what it means.

**Error format**

The operator API and the engine API of JD Courier answer an error with an RFC 9457 problem detail, with the `application/problem+json` media type. Each error carries a `JDC-NNNN` code in the `code` field. Match on the code, not on the text.

The SOAP interface and the Pix address do not carry `JDC-NNNN` codes. On those surfaces, JD and the engines receive the answers that [How routing works](/en/interfaces/jd-courier/jd-courier-routing) describes.

```json application/problem+json theme={null}
{
  "type": "https://errors.lerian.studio/v1/JDC-0102",
  "title": "Conflict",
  "status": 409,
  "detail": "<error_detail>",
  "code": "JDC-0102"
}
```

**Field definitions**

* **`type`** – A URI that identifies the error code.
* **`title`** – The text of the HTTP status.
* **`status`** – The HTTP status code.
* **`detail`** – The explanation for this occurrence of the error.
* **`code`** – A stable identifier for the error (`JDC-NNNN`). Use it for programmatic handling and support requests.
* **`errors`** – Optional. A list of field errors, each with a `location` and a `message`.
* **`instance`** – Optional. The identifier of this occurrence.

## JD Courier errors

***

### 400

| `code` | Meaning |
| - | - |
| JDC-0001 | The request is not valid: a malformed body, a field outside its range, or a missing or too long `X-Idempotency` header. |

### 401

| `code` | Meaning |
| - | - |
| JDC-0401 | Authentication is required to access this resource. |

### 403

| `code` | Meaning |
| - | - |
| JDC-0405 | You do not have permission to access this resource. |
| JDC-0406 | The tenant of the caller is suspended or purged. |

### 404

| `code` | Meaning |
| - | - |
| JDC-0004 | The resource was not found: for example, the rail, the reconciliation cycle, the reconciliation finding, the channel halt, or the SPB message. |
| JDC-0103 | The ownership assignment was not found. |
| JDC-0109 | The engine, or its SOAP channel credential, was not found. |
| JDC-0201 | The retained message was not found. |
| JDC-0302 | The send journal does not hold this control number. |

### 409

| `code` | Meaning |
| - | - |
| JDC-0003 | The `X-Idempotency` key was used before with a different body. |
| JDC-0008 | The request conflicts with the current state: for example, the channel is not halted, a cycle found the reconciliation finding again after you read it, or a request with the same `X-Idempotency` key is still in progress. |
| JDC-0102 | Another engine owns the key. To change the owner, move the key. |
| JDC-0107 | An engine with this ID is already registered. |
| JDC-0114 | Another engine already uses this credential subject. |
| JDC-0116 | The record of the Courier gives this Pix Automático leg to another engine. Stop and report it to an operator. |
| JDC-0117 | Another tenant holds the rail active. |
| JDC-0202 | The message is no longer retained. |
| JDC-0301 | Another engine is already in bypass on this rail. |
| JDC-0303 | The send is not an open indeterminate send: it has a verdict, or an operator already closed it. |
| JDC-0601 | A reconciliation cycle already runs on this rail. |

### 413

| `code` | Meaning |
| - | - |
| JDC-0006 | The request body is larger than the limit. |

### 422

| `code` | Meaning |
| - | - |
| JDC-0002 | A field breaks a rule: for example, a blank value or a note outside its length. |
| JDC-0101 | The target engine is not registered. |
| JDC-0104 | The key is not usable: it is blank, too long, or malformed for its kind. |
| JDC-0105 | The target engine is disabled. |
| JDC-0106 | The engine ID does not match `^[a-z0-9-]{1,32}$`. |
| JDC-0108 | A disable request has no reason. |
| JDC-0110 | The message code is a money code of the rail. It cannot have a delivery mode. |
| JDC-0112 | The rail does not accept this delivery mode. |
| JDC-0113 | The message was not routed to this engine, so it cannot be served to it again. |
| JDC-0115 | The target engine already owns the key. |
| JDC-0204 | The retention reason is about the message itself, so a new routing decision cannot release it. |
| JDC-0304 | You cannot suspend the rail. JD sends the messages of this rail. Stop the rail at JD. |
| JDC-0501 | The rail has no bypass. |

### 500

| `code` | Meaning |
| - | - |
| JDC-9000 | An unexpected error occurred. |

### 503

| `code` | Meaning |
| - | - |
| JDC-0902 | The license is revoked. The process answers its probes and refuses the other requests until the license is valid again. |
| JDC-9001 | A dependency of the Courier is unavailable. Retry later. On the ownership lookup, fail the payment. |

### Other 4xx

| `code` | Meaning |
| - | - |
| JDC-0007 | The request failed with a 4xx status that has no specific code. The `status` field carries the status. |

## Boot refusal

***

This code does not appear in an HTTP answer. The process writes it to its log and stops at boot.

| `code` | Meaning |
| - | - |
| JDC-0314 | The `spb-consumer` role shares a process with another role. Run `spb-consumer` alone. |


# Lift a durable channel halt
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/lift-a-durable-channel-halt

/en/openapi/v3-current/jd-courier.yaml post /v1/channels/{channelId}/lease/resume
The SPB drain halts its channel, on the lease row, when a destructive read may have removed a message the Courier never received. Nothing is taken from the vendor until an operator lifts it here; a restart never does. The note is mandatory and, with the operator and the halt it cleared, is kept on the lease row and written to the audit log. Idempotent per X-Idempotency.



# List ownership assignments
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/list-ownership-assignments

/en/openapi/v3-current/jd-courier.yaml get /v1/ownership/assignments
Offset pagination: the set is bounded by the client's account base, not by time. Filter by keyKind + keyValue to resolve an exact key.



# List retained messages
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/list-retained-messages

/en/openapi/v3-current/jd-courier.yaml get /v1/retained
Every message the Courier holds because no engine could receive it, every rail, oldest retention first. Read-only, and it never carries the message's content. A releasable message leaves by itself on the first re-check after its cause lifts — its account enters the ownership map, its owner is enabled again. An UNRECOGNIZED_TYPE of a non-financial code releases once a delivery mode is declared for its code and is not re-checked before that; one of a financial code releases on the re-check after a Courier release reads its destination. Each is re-checked at most once a minute, and within that minute while the tenant holds up to about 6,000 due retentions and its queue is empty, or about 600 while messages keep arriving (re-checks then take at most a tenth of the consumer's time; measured at 10 ms a re-check); above that, less often in proportion. Re-evaluate one to have it re-checked first: within a second while messages arrive, within 10 seconds otherwise. A Pix retention is re-checked at most once a minute. A re-evaluation has it re-checked within about 10 seconds while the engines answer; Pix tenants are re-checked one after another, and a tenant's pass that meets an engine that does not answer takes up to about 75 seconds, which every tenant after it waits out. Its release is a delivery the Courier starts with no vendor waiting: the engine's answer is stored and answers the vendor's next resend.



# List SPB sends
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/list-spb-sends

/en/openapi/v3-current/jd-courier.yaml get /v1/send-journal
Answers "is there a send in unknown state?". Every send enters the journal before it leaves, so a send whose answer never came back is here as INDETERMINATE rather than missing. Newest first. SPB rail only.



# List the per-code delivery-mode declarations on a rail
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/list-the-per-code-delivery-mode-declarations-on-a-rail

/en/openapi/v3-current/jd-courier.yaml get /v1/channels/{channelId}/delivery-modes
Only the exceptions to single-owner delivery live here; a code with no declaration is delivered to the engine that owns its destination. A financial family can never appear: the rail's own financialFamilies is the authority. Revoked declarations stay readable with includeRevoked=true, newest first.



# List the registered engines
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/list-the-registered-engines

/en/openapi/v3-current/jd-courier.yaml get /v1/engines
Every per-engine behavior iterates this list. Not paginated: an engine registry that needs pagination is an incident, not a scale requirement.



# List the registered rails, their declared properties and their state
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/list-the-registered-rails-their-declared-properties-and-their-state

/en/openapi/v3-current/jd-courier.yaml get /v1/channels
The rail contract, made visible. Reading this before attempting a bypass is how a client discovers that a rail declares hasBypass: false rather than discovering it from a 422. Listing requires an identified operator holding channels:read, because the listing returns declaredBy, an operator identity.



# Move a key to another engine
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/move-a-key-to-another-engine

/en/openapi/v3-current/jd-courier.yaml post /v1/ownership/assignments/{assignmentId}/move
The migration-wave operation. Records the previous owner and the reason. Once the move commits, the next lookup answers the new owner. On the SPB rail an operation already in flight resolves to the engine that originated it. On the Pix rail a message decided after the move reaches the new owner, and one an earlier attempt already sent to the previous owner is retained for a person, never sent to the new one. A Pix Automático debit, its reversal and a schedule's cancellation status stay with the engine that holds the payment's block or schedule, whoever owns the account after the move.



# One SPB send and its query history
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/one-spb-send-and-its-query-history

/en/openapi/v3-current/jd-courier.yaml get /v1/send-journal/{controlId}
The latest send of the control identifier in the caller tenant's journal. 404 JDC-0302 when the journal does not hold it.



# Ownership history for one key
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/ownership-history-for-one-key

/en/openapi/v3-current/jd-courier.yaml get /v1/ownership/assignments/{assignmentId}/audit
Insert-only, most recent first, with author, time, previous and new value. Audit is data, not a log line.



# Ownership history for one key, addressed by the key
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/ownership-history-for-one-key-addressed-by-the-key

/en/openapi/v3-current/jd-courier.yaml post /v1/ownership/audit/lookup
The same history as the by-assignment route, addressed by the key sent as held, normalized exactly as the lookup normalizes it. It needs no live assignment, so the history of a removed key — the removal included — stays readable. Most recent first. A read: it changes nothing and takes no X-Idempotency. The key travels in the body because it is personal data; a malformed key is refused 422 JDC-0104 with a fixed sentence that never repeats it.



# Read one ownership assignment
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/read-one-ownership-assignment

/en/openapi/v3-current/jd-courier.yaml get /v1/ownership/assignments/{assignmentId}



# Reconciliation report for a rail
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/reconciliation-report-for-a-rail

/en/openapi/v3-current/jd-courier.yaml get /v1/channels/{channelId}/reconciliation
Answers "did we lose a message?" by evaluating E(m) = C(m) + T(m) + R(m) per rail over a declared window. What pages: a non-zero divergence, and a send with no captured return leg past the return-leg window. What does not: a hole in the vendor's sequence, which is counted and listed here.



# Register an engine
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/register-an-engine

/en/openapi/v3-current/jd-courier.yaml post /v1/engines
Adding an engine is a configuration operation, not a software delivery. credentialSubject is globally unique.



# Reopen the delivery of a message to an engine
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/reopen-the-delivery-of-a-message-to-an-engine

/en/openapi/v3-current/jd-courier.yaml post /v1/messages/{messageId}/redeliver
Serves a message again without asking the vendor: the delivery goes to REDELIVER_REQUESTED and the engine's next RecebeMensagem hands it the stored bytes, the vendor's NumCabSeq unchanged, so the engine's sequence index absorbs the repeat. The engine must be one the message was resolved to (JDC-0113 otherwise). The operator and the reason are kept on the delivery row, the most recent request overwriting the one before. SPB rail only. Idempotent per X-Idempotency.



# Resolve which engine owns a key
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/resolve-which-engine-owns-a-key

/en/openapi/v3-current/jd-courier.yaml post /v1/ownership/lookup
Authoritative, never advisory. 200 resolved:true names the owning engine; 200 resolved:false is a decided negative — nobody's key, or another tenant's, indistinguishably; 503 means the Courier cannot answer and the caller fails the payment closed. This operation never answers 404. A POST that reads: the key is personal data and travels in the body, never in a URL. An engine treats ANY status other than 200 and 422 as fail-closed — 404, 405, 429 and every 5xx included — and keys on the code (JDC-9001), never on the detail sentence. The 503 sentence names what could not answer — the ownership map, or the engine credential (registry or tenant database) — and both tell the engine to fail closed.



# Revoke a code's declaration and restore the single-owner default
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/revoke-a-code-s-declaration-and-restore-the-single-owner-default

/en/openapi/v3-current/jd-courier.yaml delete /v1/channels/{channelId}/delivery-modes/{messageCode}
Idempotent. Revocation is not deletion: the row stays readable, and messages already routed under it keep the expected outcome count they were frozen with.



# Revoke one of the engine's SOAP channel credentials
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/revoke-one-of-the-engine-s-soap-channel-credentials

/en/openapi/v3-current/jd-courier.yaml post /v1/engines/{engineId}/channel-credential/{credentialId}/revoke
Ends the credential now, inside an overlap window or not. Who revoked it is recorded on the credential.



# Run a retained message's routing decision again
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/run-a-retained-message-s-routing-decision-again

/en/openapi/v3-current/jd-courier.yaml post /v1/retained/{messageId}/reevaluate
Records who asked, when and why, and the rail runs the same routing decision a new message gets — send journal, ownership map, declared rules — on its next pass. Engines named release the message to them; a declared refusal refuses it, citing the rule; otherwise it stays retained, under the cause the decision found. The operator never chooses the engine. Only a releasable retention can be re-evaluated (JDC-0204 otherwise), and only while it is still retained (JDC-0202). Idempotent per X-Idempotency.



# Suspend a rail for the caller's tenant
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/suspend-a-rail-for-the-caller-s-tenant

/en/openapi/v3-current/jd-courier.yaml delete /v1/channels/{channelId}/activation
Stops a rail drained from a vendor queue (spb) for the tenant: the drain stops reading the queue, which keeps its messages until the rail is activated again. History and retained messages stay. A rail whose vendor pushes keeps nothing while stopped, so suspending it is refused 422 JDC-0304: a Pix stop is a vendor-side repoint, never this operation. Idempotent: a rail never activated or already suspended answers 204 and keeps its first reason. Needs the admin grant (channels activation:write).



# Trigger a reconciliation cycle for a rail
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/trigger-a-reconciliation-cycle-for-a-rail

/en/openapi/v3-current/jd-courier.yaml post /v1/channels/{channelId}/reconciliation/tick
Runs one cycle now and answers once it is recorded. A cycle already running on this (tenant, channel) answers 409 JDC-0601 rather than starting a second; a cycle on one rail never blocks the other.



# Unassign a key
Source: https://docs.lerian.studio/en/reference/interfaces/jd-courier/unassign-a-key

/en/openapi/v3-current/jd-courier.yaml delete /v1/ownership/assignments/{assignmentId}
Idempotent: an absent assignment answers 204 too. Afterwards, messages arriving for that key are retained — never credited, never returned to BACEN. The audit records the removal with the previous owner; read it by the key at POST /v1/ownership/audit/lookup, since this assignment id answers 404 from now on.



# Check Pix Keys Existence
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/check-keys-existence

/en/openapi/v3-current/indirect-pix.yaml post /v1/dict/keys/check
Use this endpoint to verify if the provided Pix keys exist in the DICT system.



# Create a Pix Entry
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/create-entry

/en/openapi/v3-current/indirect-pix.yaml post /v1/dict/entries
Use this endpoint to create a new Pix entry associated with an account and its data.



# Delete a Pix Entry
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/delete-an-entry

/en/openapi/v3-current/indirect-pix.yaml delete /v1/dict/entries/{entry_id}
Use this endpoint to delete (inactivate) an existing Pix entry associated with an account.



# List All Pix Entries
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-entries

/en/openapi/v3-current/indirect-pix.yaml get /v1/dict/entries
Use this endpoint to list all Pix entries for an account with optional filters. Returns empty array [] if no entries match the criteria.



# Retrieve a Pix Key
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/retrieve-a-key

/en/openapi/v3-current/indirect-pix.yaml get /v1/dict/keys/{key}
Use this endpoint to retrieve Pix key details for payment purposes.



# Get a Pix Entry
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/retrieve-an-entry

/en/openapi/v3-current/indirect-pix.yaml get /v1/dict/entries/{entry_id}
Use this endpoint to retrieve a Pix entry by its unique identifier.



# Amend a MED value recovery
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/amend-a-med-value-recovery

/en/openapi/v3-current/pix.yaml put /v1/med/recoveries/{idRecValores}/amend
Records a field-only update to a value recovery (JDPI recuperacao-valores/{id} PUT, contract 2.23 — Alterar). It NEVER changes status. The contract 2.23 invariants are validated before any JDPI call. An unknown id returns a coded 404. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the value recovery has to be over a root payment this deployment recorded for that indirect — the rule GET /v1/med/recoveries/awaiting-return?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061.



# Analyze a MED infraction
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/analyze-a-med-infraction

/en/openapi/v3-current/pix.yaml post /v1/med/infractions/{idRelatoInfracao}/analyze
Records the counterparty PSP's analysis result (JDPI relato-infracao/analisar, contract §2.4). The §2.4 invariants (analysisResult {0=Aceita,1=Rejeitada}, tpFraude {0..4} required when Aceita) are validated before any JDPI call. Persists the JDPI response entity (the advanced watermark + minted idMarcacaoFraude) and returns it. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the infraction has to be over a payment this deployment recorded for that indirect — the rule GET /v1/med/infractions?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061.



# Analyze a MED refund request
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/analyze-a-med-refund-request

/en/openapi/v3-current/pix.yaml post /v1/med/refunds/{idSolDevolucao}/analyze
Records the contested PSP's analysis result (JDPI devolucao/analisar, contract 2.12). The contract 2.12 conditional-required invariants are validated before any JDPI call. Persists the JDPI response entity (the advanced watermark) and returns it. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the refund request has to be over a payment this deployment recorded for that indirect — the rule GET /v1/med/refunds?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061.



# Cancel a MED fraud marker
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/cancel-a-med-fraud-marker

/en/openapi/v3-current/pix.yaml post /v1/med/fraud-markers/{idMarcacaoFraude}/cancel
Cancels a fraud marker as the creator PSP (JDPI marcacao-fraude/{id}/cancelar, contract 2.17). An unknown id returns a coded 404.



# Cancel a MED infraction
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/cancel-a-med-infraction

/en/openapi/v3-current/pix.yaml post /v1/med/infractions/{idRelatoInfracao}/cancel
Cancels an infraction as the creator PSP (JDPI relato-infracao/cancelar, contract §2.3). Cancel is allowed at any time, even after Analisado. An unknown id returns a coded 404. Persists the JDPI response entity and returns it. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the infraction has to be over a payment this deployment recorded for that indirect — the rule GET /v1/med/infractions?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061.



# Cancel a MED refund request
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/cancel-a-med-refund-request

/en/openapi/v3-current/pix.yaml post /v1/med/refunds/{idSolDevolucao}/cancel
Cancels a not-yet-analyzed refund request as the requesting PSP (JDPI devolucao/cancelar, contract 2.11). An unknown id returns a coded 404. Persists the JDPI response entity and returns it. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the refund request has to be over a payment this deployment recorded for that indirect — the rule GET /v1/med/refunds?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061.



# Cancel a PIX Automatico schedule
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/cancel-a-pix-automatico-schedule

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/schedules/{endToEndId}/cancel
Cancels a scheduled payment instruction (JDPI 4.4.3), transitioning it to Cancelled and soft-deleting the local row. Returns the cancellation id (idCancelamento). requesterIspb has to name the participant the schedule row is booked under, or the answer is 404 PIX-0147 before JDPI is asked; an ISPB this deployment does not act as is 422 PIX-0128, before the row is read.



# Consult a PIX Automatico schedule cancellation
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/consult-a-pix-automatico-schedule-cancellation

/en/openapi/v3-current/pix.yaml get /v1/pix-automatico/schedules/{endToEndId}/cancel/{idCancelamento}
Consults the live JDPI situation of a schedule cancellation (JDPI 4.4.4), keyed by (endToEndId, idCancelamento).



# Consult a PIX Automatico schedule situation
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/consult-a-pix-automatico-schedule-situation

/en/openapi/v3-current/pix.yaml get /v1/pix-automatico/schedules/{endToEndId}
Consults the live JDPI situation of a scheduled payment instruction (JDPI 4.4.2), projecting the JDPI situation axes onto the local schedule status.



# Create a MED value recovery
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/create-a-med-value-recovery

/en/openapi/v3-current/pix.yaml post /v1/med/recoveries
Opens a value recovery as the creator PSP (JDPI recuperacao-valores/incluir, contract 2.20). The creator ISPB is derived from configuration. grafoRastreamento.vlrMinTransacao is a graph-traversal FILTER threshold, never a posting amount.



# Create a static composite PIX Automatico QR code
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/create-a-static-composite-pix-automatico-qr-code

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/composite/static
Generates a composite PIX QR code embedding static-QR data and a recurring-payment authorization (PIX Automatico). The recipient name and city are CRM-sourced from the account, never the request body. 422 PIX-0139 when the account's record names a different institution than the one minting the QR code; nothing is sent to JDPI.



# Effect an inbound PIX Automatico settlement debit
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/effect-an-inbound-pix-automatico-settlement-debit

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/settlements/inbound/debit
Posts the real double-entry settlement debit on the payer's local ledger for a scheduled PIX Automatico payment (section 5.4.2, the plugin is the SGCT server). JDPI calls this after it confirms SPI settlement. The amount was established at schedule/block time, so the body carries no value. Returns the SGCT debit-operation id (idOperacaoSgct). A re-delivery resolves to a clean 200 with the prior confirmation, never a double post.



# Effectuate a MED refund debit (THIRD RAIL — moves money)
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/effectuate-a-med-refund-debit

/en/openapi/v3-current/pix.yaml post /v1/med/refunds/{idSolDevolucao}/effectuate
Effectuates the refund DEBIT at SPI for an accepted refund (JDPI POST /od, contract §2.24): posts a balanced PENDING Midaz double-entry (contested-side debit, clearing credit) and generates the pacs.004. The debit commits on the settlement reconcile poll. The precondition (accepted AND not-yet-effectuated) is checked before any ledger touch: a non-accepted request returns a coded 422, and an already-effectuated one echoes its recorded ids with no second post. A failed request is not safe to retry blindly: its reserve may have landed, and the ledger deduplicates a retry only within 300 seconds, so past that window an operator reconciles the request before it is sent again. An unknown id returns a coded 404. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the refund request has to be over a payment this deployment recorded for that indirect — the rule GET /v1/med/refunds?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061.



# Get a MED fraud marker
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/get-a-med-fraud-marker

/en/openapi/v3-current/pix.yaml get /v1/med/fraud-markers/{idMarcacaoFraude}
Returns a single fraud marker by its idMarcacaoFraude GUID, read live from JDPI (contract 2.16). An unknown id returns a coded 404.



# Get a MED infraction
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/get-a-med-infraction

/en/openapi/v3-current/pix.yaml get /v1/med/infractions/{idRelatoInfracao}
Returns a single detected infraction by its idRelatoInfracao GUID from the local projection. An unknown id returns a coded 404. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the infraction has to be over a payment this deployment recorded for that indirect — the rule GET /v1/med/infractions?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061.



# Get a MED infraction from the JDPI base
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/get-a-med-infraction-from-jdpi

/en/openapi/v3-current/pix.yaml get /v1/med/infractions/{idRelatoInfracao}/jdpi
Returns a single infraction by its idRelatoInfracao GUID read live from the JDPI base (JDPI relato-infracao/consultar, §8.2.18) — NOT from the local projection the sibling route serves, and NOT from the DICT-direct §8.2.38 query. The requesting ISPB is derived from the tenant binding. An unknown id returns a coded 404. Moves no money and persists nothing. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the infraction has to be over a payment this deployment recorded for that indirect — the rule GET /v1/med/infractions?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061.



# Get the credit status of a MED refund order
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/get-a-med-refund-credit-status

/en/openapi/v3-current/pix.yaml get /v1/med/refunds/credits/{endToEndIdDevolucao}
Returns the CREDIT-side situation of a refund order by its pacs.004 endToEndIdDevolucao, read live from JDPI (JDPI credito-devolucao/{endToEndId}, §8.5.4). stJdPiProc here is the CREDIT domain, DISTINCT from the debit poll's despite the shared field name (§4.5). Moves no money and persists nothing — the credit itself is settled by the inbound §9.3.3 webhook, never by this read. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the refund credit has to be booked against a payment this deployment recorded for that indirect, or the answer is 404 PIX-0147 before anything is read from JDPI; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061.



# Get a MED refund request
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/get-a-med-refund-request

/en/openapi/v3-current/pix.yaml get /v1/med/refunds/{idSolDevolucao}
Returns a single detected refund request by its idSolDevolucao GUID from the local projection. An unknown id returns a coded 404. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the refund request has to be over a payment this deployment recorded for that indirect — the rule GET /v1/med/refunds?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061.



# Get a MED refund request from the JDPI base
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/get-a-med-refund-request-from-jdpi

/en/openapi/v3-current/pix.yaml get /v1/med/refunds/{idSolDevolucao}/jdpi
Returns a single refund request by its idSolDevolucao GUID read live from the JDPI base (JDPI devolucao/consultar, §8.2.26) — NOT from the local projection the sibling route serves, and NOT from the DICT-direct §8.2.39 query. It is the only refund read that carries registeredAt: §8.2.25 (the listar the pollers run) does not return that field. The requesting ISPB is derived from the tenant binding. An unknown id returns a coded 404. Moves no money and persists nothing. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the refund request has to be over a payment this deployment recorded for that indirect — the rule GET /v1/med/refunds?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061.



# Get a MED value recovery
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/get-a-med-value-recovery

/en/openapi/v3-current/pix.yaml get /v1/med/recoveries/{idRecValores}
Returns a single value recovery by its idRecValores GUID, read live from JDPI (contract 2.21). An unknown id returns a coded 404. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the value recovery has to be over a root payment this deployment recorded for that indirect — the rule GET /v1/med/recoveries/awaiting-return?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061.



# Get an indirect participant
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/get-an-indirect-participant

/en/openapi/v3-current/pix.yaml get /v1/indirects/{indirectId}
Returns one indirect participant by id with its full registry record: lifecycle status, the derived `@pi_{ispb}` settlement-account alias its money moves through, the delivery configuration, and the own-QR-certificate configuration. Call it to read back the `@pi` alias, and to see the CURRENT lifecycle status after a suspend, a reactivate or a close.

Read-only, and uncached: it always reads the registry row, unlike the cached slim projection the money paths resolve against — so this is the operation that tells you the CURRENT state, while a suspend may take up to the resolution-cache TTL to be seen by every replica. delivery.secret always comes back as "***": the stored credential is write-only and no operation returns it, so a lost secret is replaced with a PATCH rather than recovered.

The `provisioning` object is always present, and its `failedStep` is LEGACY: it is null for anything registered by this service, because registration is atomic and a failure leaves no row to describe. A row that does carry a failedStep, and sits in PENDING_PROVISIONING, was written before that change — it is not routable and its ispb is still held.

Optional directIspb names the direct participant the indirect is read as; a token confined to one direct participant has to name it. Refusals: 404 PIX-0095 when no indirect with that id exists in this tenant — an id belonging to another tenant is deliberately indistinguishable from an unknown one; 422 PIX-0128 when directIspb names a direct participant this deployment does not act as, before the indirect is read; 404 PIX-0147 when directIspb names a direct participant the indirect is not mounted on; 422 PIX-0098 when indirectId is not a valid UUID.



# Get an indirect participant's JWK Set
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/get-an-indirect-participant-jwk-set

/en/openapi/v3-current/pix.yaml get /v1/indirects/{indirectId}/jwks
Returns the JWK Set JDPI signs THIS indirect's dynamic-QR JWS with, as an application/jwk-set+json document, so the indirect can publish it on its own host for payer PSPs to validate signatures against. The indirect cannot produce this itself — JDPI holds the certificate and does the signing — which is why the convenience lives on the direct participant's API.

Call it once when onboarding an indirect onto its own QR certificate (after qrCertificate.ownCertificate is set), and again whenever that certificate is rotated; then serve the bytes verbatim at the JWKS location under the indirect's own base URL. It is read-only and changes nothing here. It is ONLY for an indirect that hosts its own certificate: one that falls back to the direct participant has no key set of its own and is refused 422 PIX-0114, which names the direct participant's own JWKS route to publish instead. Lifecycle status is deliberately NOT a condition — a SUSPENDED or CLOSED indirect still has live QR codes in the wild, and withholding the key would break their validation.

Every answer carries X-JWK-Set-Freshness: 'fresh' when the key set came from inside the cache TTL, or 'stale' when the TTL had expired, JDPI could not be reached, and a cached key set was served instead — a 200 alone does not assert freshness, since a cached document and a fresh one are the same bytes. Optional directIspb names the direct participant the indirect is read as; a token confined to one direct participant has to name it. Refusals: 422 PIX-0128 when directIspb names a direct participant this deployment does not act as, before the indirect is read; 404 PIX-0147 when directIspb names a direct participant the indirect is not mounted on; 422 PIX-0111 when this tenant's indirect-participants feature is not enabled (no QR is signed with any indirect certificate while it is off, so the key set would validate nothing); 404 PIX-0095 for an unknown id; 422 PIX-0114 for the fallback case above; 422 PIX-0098 when the indirect carries no ispb, which is the key §8.3.11 is looked up by; 503 PIX-1050 when JDPI is unreachable and nothing is cached — attributed to JDPI, never presented as a configuration error.



# Indirect participants
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/indirect-participants

How a smaller institution reaches Pix through your direct participation: the settlement position registering one creates, how its money arrives, how it learns about a movement, how it returns a Pix, and what registering one costs permanently.

Your institution is a **direct participant**. It has its own presence at the national Pix settlement system (SPI), and this plugin is its way there. An **indirect participant** is a smaller institution without a connection of its own. It reaches SPI through yours. It is a client of your institution, not a client of the rail.

That relationship exists in your tenant's registry, not at BACEN. You create it with `POST /v1/indirects`. [The direct and indirect model](/en/interfaces/pix-jd/direct-and-indirect-model) explains where an indirect participant's money lives: the settlement account at the Banco Central, the limit at JD, and the position in your ledger.

> [!NOTE]
>
> This page explains what a hosted participation is and how it behaves. [Hosting indirect participants](/en/interfaces/pix-jd/hosting-indirect-participants) covers the provisioning: the delivery-secret encryption key, the hosting posture, and the registration call. Its numbering continues from the setup page. Of those steps, only the encryption key refuses every registration on its own, so provision it first. The hosting posture gates the money paths, not the registry, so you can register participants before you turn it on.

## Who is responsible for what

***

Most operational mistakes here come from a search for the answer in the wrong column.

| | Responsibility |
| - | - |
| Banco Central / SPI | moves money **between institutions**. It knows no end customers |
| JD | the technical bridge: it delivers the notices and signs the QR codes. It makes no business decisions |
| You, the direct participant | each indirect participant's **settlement position**: the `@pi` account in your ledger, which mirrors the limit you administer at JD. You make sure that it exists, stays active, and holds a balance. You also own the settlement between institutions |
| The indirect participant | **its own customers' accounts** |

In practice, a Pix for a customer of an indirect participant stops with you. It lands in an account that represents that institution's position. You do not know, and cannot know, which of its customers owns the money. The indirect participant credits its customer in its own core, after it receives your notice.

## What registering one creates

***

A registration writes a row, and the plugin also creates that institution's **settlement position** in Midaz. That is a ledger account whose alias starts with `@pi_` and ends with the institution's ISPB, the eight-digit code that BACEN gives to every participant. An indirect on ISPB `12345678` settles at `@pi_12345678`.

That position holds that institution's money. The response returns it as `piAccountAlias`. The plugin derives the alias from `ispb`. You never choose it, and a client never creates the account.

Each institution has one position. A credit for one indirect lands only on that indirect's account. One institution's money therefore never mixes with another's, and never with your own. The registry exists to give that segregation.

> [!NOTE]
>
> The alias uses an **underscore**, not a slash: `@pi_12345678`. Midaz rejects a slash in a user alias, so a path-shaped name resolves to nothing.

## Before you register anyone

***

Indirect participation is off by default. The per-tenant systemplane flag **`plugin-br-pix-jd.indirects/enabled`** must be on, and its default value is `false`.

The flag gates two halves, and they behave differently:

* **The management API works with the flag off.** You can register participants, list them, and read one before enablement. Onboarding before go-live is deliberate.
* **No money moves with the flag off.** Resolution decides which indirect an incoming credit belongs to. With the flag off, it reports the feature as disabled. No inbound credit goes to a `@pi` account, and no indirect can originate an outbound order.

Two operations refuse outright while the flag is off, with `422 PIX-0111`. One is the own-QR-certificate write on `PATCH /v1/indirects/{indirectId}`. The other is `GET /v1/indirects/{indirectId}/jwks`.

> [!NOTE]
>
> The read fails closed. When a money path "goes back to direct behavior" and nobody changed the key, this is the cause. Look at the systemplane.

## Registering one

***

**1. Turn the feature on for the tenant**

Set `plugin-br-pix-jd.indirects/enabled` to `true`. Registration works without it, but nothing settles until it is on.

**2. POST /v1/indirects**

Send the institution's `name`, its `ispb`, and a `delivery` block with `endpointUrl` and `secret`. The answer is `201`. It carries `indirectId`, the identifier that every later call routes by, and `piAccountAlias`.

**3. Nothing to poll: a 201 means ready**

Every check runs **before the plugin writes the registry row**. First comes the ISPB uniqueness check, then the optional JD directory check, then the creation of the `@pi_{ispb}` account in Midaz. Only then does the plugin write the row, with status `ACTIVE`. There is no intermediate state and nothing to wait for.

**4. On a failure, fix the cause and POST again**

A failed step answers a **coded error** that names the step. The plugin writes **no registry row**, so the ISPB stays free. Fix the cause and send the POST again. That is the recovery. There is no separate retry route, because no half-written row remains to resume.

**Registration is atomic: a `201` means ready, and a failure leaves no registry row.** On a `201`, `status` is always `ACTIVE`. Do not write a client that polls until the participant becomes routable. That loop waits for a change that cannot happen.

A failure can leave only the **settlement account** behind, when that step succeeded and a later one failed. The plugin does not roll it back, and it does no harm. Nothing routes to a `@pi` account without an `ACTIVE` registry row that points at it. The account creation is idempotent by alias, so your next attempt adopts the same account and does not make a second one. A failure never leaves a registry row or a held ISPB.

The response still carries a `provisioning` object with a `failedStep` field. It is **legacy and always `null`** for every registration of this service, because a failed registration leaves no row.

The lifecycle states are `ACTIVE`, `SUSPENDED`, and `CLOSED`.

> [!WARNING]
>
> `PENDING_PROVISIONING` is a **retired** state with a sharp edge. No registration goes into it now. `GET /v1/indirects` still accepts it as a filter, so that rows from before atomic registration read back as themselves. But that state has **no lifecycle transitions in either direction**. You cannot suspend or close a legacy row. Every action on it answers `409 PIX-0094`.
>
> Such a row is readable but **not routable**, and it still holds its ISPB against the open-uniqueness index. It therefore blocks a new registration of that institution, and no API call can free it. To clear one is an operator and data decision, and it is not an API operation. If your tenant is older than atomic registration, run `GET /v1/indirects?status=PENDING_PROVISIONING` one time to find any such rows.

## How money reaches an indirect participant

***

Follow one inbound Pix. The indirect calls no endpoint in this path. Your plugin does the work.

1. **"Can this account receive?"** Before the Banco Central moves the money, it asks if the destination account accepts the credit. The question comes to you, because the indirect participant has no line to the SPI.
2. **A Pix arrives** for an account at the indirect institution. It reaches your direct participation through the plugin's cash-in webhook.
3. **Resolution finds the indirect** from the ISPB in the receiver block, in the participation registry. There are four outcomes, and only the first one credits an indirect:

   * The ISPB matches an `ACTIVE` participation. The credit posts to that participation's `@pi_{ispb}` alias.
   * The ISPB is **your own**. It is your book, and the CRM resolves the account as usual.
   * The ISPB matches nothing, or a suspended or closed participation. The plugin **refuses** the credit with `404 PIX-0119`. It tells JD that it does not serve that receiver. It stores nothing, and no money settles.
   * The resolution fails on infrastructure. The plugin **neither credits nor refuses**. It answers an error, so that JD delivers the credit again. It fails closed on purpose and guesses nothing about money.

   The plugin never caches a resolution miss. An indirect that just became active therefore never hides behind an earlier negative answer.
4. **The credit lands on `@pi_{ispb}`.** The plugin records the movement against that settlement position and links its own transaction record to the indirect. **It records the notice in the same database transaction as the credit.** Either both exist, or neither does.
5. **The plugin pushes a signed notice** to the `delivery.endpointUrl` that you registered, with JD's payload byte for byte. The plugin calls the institution, not the reverse.
6. **The indirect participant credits its own customer**, in its own core.

> [!WARNING]
>
> The plugin does not ask the CRM on the indirect path. The destination comes from the participation registry, never from caller data. That is deliberate. If an indirect participant had your own ISPB by mistake, credits for your own book would land in its account. The "is this ISPB ours?" check therefore runs before the "does it match an indirect participant?" check.

The notice carries two headers the receiving institution verifies:

| Header | Value |
| - | - |
| `X-Lerian-Signature` | `sha256=` followed by the hex HMAC-SHA256 of the exact raw body bytes, keyed with that indirect's registered `secret`. |
| `X-Lerian-Timestamp` | The send time in Unix-epoch seconds, so the receiver can bound replay with its own freshness window. |

Delivery is **at-least-once**. The plugin can send the same notice again after a retryable failure, or after a crash between the send and the bookkeeping. The `endToEndId` stays the same across attempts. A receiver must deduplicate by `endToEndId` and treat a repeated payload as already handled.

> [!NOTE]
>
> The stored `secret` is write-only. Every read of an indirect returns `delivery.secret` as `***`, so a lost secret is replaced with a `PATCH`, never recovered.

## When the notice never arrives

***

The push can fail for good. The retries run out, or the endpoint answers `4xx`. After that, the plugin marks the notice invalid and never tries it again. **The money is correct either way.** The movement is real, and the institution does not know about it.

`GET /v1/indirects/{indirectId}/transactions` closes that gap. It returns the movements that settled on one indirect's `@pi_{ispb}` account. It is therefore the authoritative record, not the notice. An institution that reads it on a schedule no longer depends on the delivery. It is also the only way to read a window again after an outage of its own.

[List an indirect participant's transactions](/en/reference/interfaces/pix-jd/list-indirect-participant-transactions) gives the rules that make a reconciliation correct. They cover the required half-open `since` window, integer centavos, oldest-first cursor paging, and the silent clamp on `limit`. A read of the feed changes nothing and sends no notice again.

## Returning a Pix that an indirect participant received

***

A devolução of a Pix that landed on an indirect participant's position comes from that indirect. Send `POST /v1/refunds` with the `indirectId` of that participant. The devolução then debits its `@pi_{ispb}` position.

The `indirectId` must name exactly the participant that received the original Pix. The plugin answers `422 PIX-0135` and moves no money when:

* the original Pix landed on an indirect's position, and the refund has no `indirectId`.
* the refund names another indirect participant.
* the original Pix landed on a direct account, and the refund has an `indirectId`.

The `indirectId` then passes the same checks as on a payment order: `422 PIX-0111` when the feature is off, `404 PIX-0095` for an unknown participant, and `422 PIX-0100` when the participation is not `ACTIVE`.

## Hosting the QR code under the institution's own certificate

***

By default, the plugin publishes an indirect's dynamic QR code under your direct participation. An indirect can publish its own instead. Set `qrCertificate.ownCertificate` with a `publicBaseUrl` on `PATCH /v1/indirects/{indirectId}`. The institution then serves the signed document from its own host.

The institution cannot make the validation keys itself. JDPI holds the certificate and does the signing. `GET /v1/indirects/{indirectId}/jwks` returns the JWK Set for that indirect. The institution publishes it on its own host, and payer PSPs validate against it. Fetch it when you configure the certificate, and again after each rotation.

Lifecycle status deliberately does not gate that read. A suspended or closed indirect still has live QR codes in circulation. Without the key, their validation would break.

## Reading the registry

***

```bash theme={null}
# one participation
curl -s "$PIX_JD_BASE_URL/v1/indirects/$INDIRECT_PARTICIPANT_ID" -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" | jq

# the list — filters are exact and combine with AND
curl -s -G "$PIX_JD_BASE_URL/v1/indirects" -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" \
  --data-urlencode 'status=ACTIVE' --data-urlencode 'limit=25' | jq
```

[List indirect participants](/en/reference/interfaces/pix-jd/list-indirect-participants) gives the cursor-paging rules and the silent clamp on `limit`.

A `GET` by id, and the list, always show the current truth. The money paths read a cached projection. Every replica can take up to the resolution cache TTL to see a suspension. The TTL is 30 seconds by default. The ledger lock from `suspend` applies at the moment of the call.

## Suspending, reactivating, and closing

***

`PATCH /v1/indirects/{indirectId}` carries at most one lifecycle `action`: `suspend`, `reactivate`, or `close`. Each one writes the ledger as well as the registry.

```bash theme={null}
curl -s -X PATCH "$PIX_JD_BASE_URL/v1/indirects/$INDIRECT_PARTICIPANT_ID" \
  -H "Authorization: Bearer $PIX_JD_BEARER_TOKEN" -H 'Content-Type: application/json' \
  -d '{"action":"suspend"}'
```

* **`suspend`** stops both sending and receiving on the indirect's `@pi` account. The ledger itself refuses that participant's money. A suspension therefore holds even on a replica whose resolution cache is stale. **`reactivate`** starts both again.
* **`close`** is permanent. `CLOSED` is terminal, and after it the plugin refuses every field change on the row too.

A close deletes nothing. The plugin blocks the `@pi` account for good but keeps it. A later registration of the same ISPB reuses that account. The account is unblocked, active again, and keeps its accounting history.

A `PATCH` with only fields and no `action` changes those fields. An empty `PATCH` changes nothing and returns the current row. It is not an error.

> [!WARNING]
>
> **There is no DELETE on `/v1/indirects`, and `CLOSED` is terminal.** The only exit from the registry is `close`, which keeps the row and the account. A mistaken registration in a live tenant stays in that tenant's registry for good. Its ISPB stays held against the open-uniqueness constraint until you close it. Every institution code that you spend is permanent. Check `name`, `ispb`, and the delivery endpoint before you call.

## What goes wrong

***

The operation pages list every refusal of this registry, with its status and exact condition. They also say what the plugin wrote or did not write when it refused. See [Register an indirect participant](/en/reference/interfaces/pix-jd/register-an-indirect-participant), [Update an indirect participant](/en/reference/interfaces/pix-jd/update-an-indirect-participant), [Get an indirect participant](/en/reference/interfaces/pix-jd/get-an-indirect-participant), [List indirect participants](/en/reference/interfaces/pix-jd/list-indirect-participants), [Get an indirect participant's JWK Set](/en/reference/interfaces/pix-jd/get-an-indirect-participant-jwk-set), and [List an indirect participant's transactions](/en/reference/interfaces/pix-jd/list-indirect-participant-transactions). The [Pix JD error list](/en/reference/interfaces/pix-jd/pix-jd-error-list) has every code, with the exact `detail` of each one.

> [!NOTE]
>
> **The status tells you whether to retry, not the code family.** `PIX-0107` and `PIX-0123` are the same condition, seen two ways. A `409` means that the rail read the configuration and found that the key does not exist. Only an operator can change that, so a retry loops forever. A `503` means that the read did not complete. The rail does not know that the key is absent, so a retry is right. Neither one stores anything.

## Where to go next

***

* **[Hosting indirect participants](/en/interfaces/pix-jd/hosting-indirect-participants)**: the provisioning, with the encryption key, the posture, and the registration call.
* **[Register an indirect participant](/en/reference/interfaces/pix-jd/register-an-indirect-participant)**: the full request contract and every refusal.
* **[List an indirect participant's transactions](/en/reference/interfaces/pix-jd/list-indirect-participant-transactions)**: the reconciliation feed, with the full paging rules.
* **[Update an indirect participant](/en/reference/interfaces/pix-jd/update-an-indirect-participant)**: field changes, lifecycle actions, and the own-certificate configuration.
* **[Direct Pix via JD](/en/interfaces/pix-jd/direct-pix-via-jd)**: the direct participation that all of this rides on, and how settled movements land in Midaz.


# List an indirect participant's transactions
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/list-indirect-participant-transactions

/en/openapi/v3-current/pix.yaml get /v1/indirects/{indirectId}/transactions
Returns the movements booked on ONE indirect participant's `@pi_{ispb}` account, so that participant can reconcile its own books against this ledger. Each row carries the end-to-end id, the direction, the amount, the settlement status, the instant it was booked, and both parties as captured at booking — the payee block being the indirect's own client on a credit.

**Reconcile on `status`, not on presence.** An inbound credit is booked `PENDING` the moment it is claimed and turns `EXECUTED` once the ledger credit landed, in the same row; a row can therefore appear `PENDING` in one sweep and `EXECUTED` in the next, and a row that stays `PENDING` is a credit that never landed (RUNBOOK §2.6). The feed does not hide claims, because it is ordered by booking time and a status filter would drop a row that settles after its booking instant has already been swept past.

Call it whenever you need the authoritative record rather than the notice: this plugin PUSHES a message to the indirect's delivery endpoint on every movement, and that push can die permanently (the retries are exhausted, or the endpoint answers 4xx, after which the notice is parked as INVALID and never retried). The money is booked correctly either way, so a movement whose notice failed is invisible to the indirect until it is read here. Sweeping this feed on a schedule is what closes that gap; it is also the only way to re-read a window after a local outage.

Read-only; nothing changes, and no notice is re-sent.

**amount is in CENTAVOS, as an integer** — 1050 is R$ 10,50. It is never a decimal, and never reais.

**since is REQUIRED**, as an RFC 3339 instant. The feed is always read over a bounded window: without a lower bound the query is an unbounded sweep of the money table whose answer is not reproducible between two calls, so a caller could not tell a slow response from a truncated one. The window is HALF-OPEN — `since` is inclusive, `until` is exclusive — so two adjacent sweeps neither double-count a movement nor leave one in the gap between them; passing the previous window's `until` as the next window's `since` is the correct way to walk forward. `until` is optional and, when absent, leaves the window open-ended.

**Rows come back OLDEST FIRST, ordered by (occurredAt, id), and the cursor is the ONLY correct way to page.** The order is stable to the row: two movements can be booked in the same instant, and without the id as a tie-break a page boundary falling between them would return one of them and drop the other silently — which for a reconciliation is worse than returning nothing. Pass the previous page's nextCursor back as `cursor`; a null nextCursor means that page was the last one in the window. Do NOT try to page by advancing `since` past the last row's occurredAt: that skips every other movement booked in that same instant. The cursor is opaque — its content is this service's business and is free to change. `limit` defaults to 25 and is CLAMPED to 100 (a larger value is silently reduced, not rejected), so do not read the page size you asked for as the page size you got.

Optional `directIspb` names the direct participant the indirect is read as; a token confined to one direct participant has to name it.

Refusals: 404 PIX-0095 when no indirect with that id exists in this tenant — an id belonging to another tenant is deliberately indistinguishable from an unknown one, and no movement is ever read for it; 422 PIX-0128 when `directIspb` names a direct participant this deployment does not act as, before the indirect is read; 404 PIX-0147 when `directIspb` names a direct participant the indirect is not mounted on, and no movement is read; 422 PIX-0098 when `indirectId` is not a valid UUID, when `since` is absent or is not an RFC 3339 instant, when `until` is not an RFC 3339 instant or is not strictly after `since`, or when `cursor` is not a token this service issued (a cursor is refused rather than silently treated as the start of the window, which would replay settled movements as if they were new).



# List indirect participants
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/list-indirect-participants

/en/openapi/v3-current/pix.yaml get /v1/indirects
Lists this tenant's indirect participants, newest first, as one keyset page. Use it to find the indirectId an outbound order needs, and to see which participants are actually routable — status is the field that decides that: only ACTIVE resolves an inbound credit or may originate an outbound order.

Read-only; nothing changes. The status and ispb filters are exact matches and combine with AND. Pagination is cursor-based, not offset-based: pass the previous page's nextCursor back as cursor, and a null nextCursor means that page was the last. limit defaults to 25 and is CLAMPED to 100 — a larger value is silently reduced rather than rejected, so do not read the page size you asked for as the page size you got. Every row's delivery.secret is redacted.

directIspb filters by the DIRECT participant the indirects ride, and is not ispb: ispb is the indirect's own. A token confined to one direct participant has to name it in directIspb, and then sees only the indirects mounted on that participant.

The only refusal is 422 PIX-0098, for a status outside ACTIVE / SUSPENDED / CLOSED / PENDING_PROVISIONING: an unrecognized filter is rejected rather than silently ignored, so a typo cannot widen the result set. PENDING_PROVISIONING is still accepted as a filter but nothing is registered in it any more — it finds only rows written before registration became atomic, which are readable, not routable, and still hold their ispb.



# List MED fraud markers (DICT-direct)
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/list-med-fraud-markers-dict-direct

/en/openapi/v3-current/pix.yaml get /v1/med/fraud-markers/dict
Lists the fraud markers for a document via the DICT-direct query (JDPI marcacao-fraude/listar/dict, contract 2.19). taxId is required; key and limit are optional filters.



# List MED fraud markers (local base)
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/list-med-fraud-markers-local-base

/en/openapi/v3-current/pix.yaml get /v1/med/fraud-markers
Lists the fraud markers where this institution is the creator (JDPI marcacao-fraude/listar, contract 2.18). Read live from JDPI. At least one of taxId or created_from must be supplied: JDPI marks each mandatory when the other is absent, and either one alone is enough. The DICT-direct listing is a separate operation.



# List MED infractions
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/list-med-infractions

/en/openapi/v3-current/pix.yaml get /v1/med/infractions
Lists the infractions detected by the worker pollers (filed by this institution or against it), filterable by status, role ISPB, and the suspect payment's endToEndId. Read projection — no JDPI round-trip. The role ISPBs name the DIRECT participant, and the indirect participants riding it share its infractions; indirectId narrows the listing to ONE indirect — only the infractions over a payment this deployment recorded for that indirect (the payment's own indirectId, as GET /v1/transactions?indirectId= reads it), never another indirect's, never one over the direct participant's own payment, and never one over a payment this deployment did not book. A token confined to one indirect has to name it. A malformed indirectId is 400 PIX-0061; an empty match is a 200 with an empty data array.



# List MED recoveries awaiting return
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/list-med-recoveries-awaiting-return

/en/openapi/v3-current/pix.yaml get /v1/med/recoveries/awaiting-return
Lists the creator-side analyzed value recoveries this institution may still return (contract §2.22/§5, within 72h of the analysis stage closing), ordered by return deadline (earliest first). The creator ISPB is config-derived. Each row surfaces returnDeadline and a computed breached flag. Read projection — no JDPI round-trip; no action taken and no money moved. Optional ispb narrows the queue to that one direct participant (an ISPB this deployment does not act as is 422 PIX-0128); a token confined to one participant has to name it. The role and queue ISPBs name the DIRECT participant, and the indirect participants riding it share its value recoveries; indirectId narrows the listing to ONE indirect — only the value recoveries over a payment this deployment recorded for that indirect (the payment's own indirectId, as GET /v1/transactions?indirectId= reads it), never another indirect's, never one over the direct participant's own payment, and never one over a payment this deployment did not book. A token confined to one indirect has to name it. A malformed indirectId is 400 PIX-0061; an empty match is a 200 with an empty data array.



# List MED refund requests
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/list-med-refund-requests

/en/openapi/v3-current/pix.yaml get /v1/med/refunds
Lists the refund requests detected by the worker pollers (requested by this institution or against it), filterable by status, role ISPB, and the contested payment's endToEndId. Read projection — no JDPI round-trip. The role and queue ISPBs name the DIRECT participant, and the indirect participants riding it share its refund requests; indirectId narrows the listing to ONE indirect — only the refund requests over a payment this deployment recorded for that indirect (the payment's own indirectId, as GET /v1/transactions?indirectId= reads it), never another indirect's, never one over the direct participant's own payment, and never one over a payment this deployment did not book. A token confined to one indirect has to name it. A malformed indirectId is 400 PIX-0061; an empty match is a 200 with an empty data array.



# List MED refund requests pending my analysis
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/list-med-refund-requests-pending-my-analysis

/en/openapi/v3-current/pix.yaml get /v1/med/refunds/pending-analysis
Lists the OPEN refund requests this institution must analyse (contested against it), ordered by analysis deadline (earliest first). The contested ISPB is config-derived. Each row surfaces analysisDeadline (contract §5, 6h for fraud / 48h otherwise) and a computed breached flag. Read projection — no JDPI round-trip. Optional ispb narrows the queue to that one direct participant (an ISPB this deployment does not act as is 422 PIX-0128); a token confined to one participant has to name it. The role and queue ISPBs name the DIRECT participant, and the indirect participants riding it share its refund requests; indirectId narrows the listing to ONE indirect — only the refund requests over a payment this deployment recorded for that indirect (the payment's own indirectId, as GET /v1/transactions?indirectId= reads it), never another indirect's, never one over the direct participant's own payment, and never one over a payment this deployment did not book. A token confined to one indirect has to name it. A malformed indirectId is 400 PIX-0061; an empty match is a 200 with an empty data array.



# List PIX Automatico schedules
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/list-pix-automatico-schedules

/en/openapi/v3-current/pix.yaml get /v1/pix-automatico/schedules/list
Lists live JDPI scheduled payment instructions (JDPI 4.4.5), scoped by flow + due-date window, projecting each onto the local schedule status. The response is an object wrapper carrying the JDPI timestamp and the schedule snapshots. Optional ispb makes the listing AS that direct participant: JDPI answers only for what it holds.



# Open a MED refund request
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/open-a-med-refund-request

/en/openapi/v3-current/pix.yaml post /v1/med/refunds
Opens a refund request as the requesting PSP (JDPI devolucao/incluir, contract 2.7). The requesting ISPB is derived from configuration. Persists the JDPI response entity and returns it.



# Pix JD error list
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/pix-jd-error-list

Look up a PIX-NNNN code in the Pix JD catalog, the condition behind it, and the detail text the response carries.

**Error format**

The Pix JD API answers a failed request with `application/problem+json`. The `Detail` schema in this API reference describes that body, which follows RFC 9457.

```json JSON theme={null}
{
  "type": "https://errors.lerian.studio/v1/PIX-0012",
  "title": "PIX Key Not Found",
  "status": 404,
  "detail": "The specified PIX key was not found in the system. Please verify the key value and try again.",
  "code": "PIX-0012"
}
```

**Field definitions**

* **`code`** – Stable, machine-readable domain error code scoped to the emitting service. On this API it has the form `PIX-NNNN`.
* **`title`** – A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
* **`detail`** – A human-readable explanation specific to this occurrence of the problem.
* **`status`** – The HTTP status code.
* **`type`** – A URI that identifies the error in the Lerian error catalog, built as `https://errors.lerian.studio/v1/<code>`.
* **`instance`** – A URI reference that identifies the specific occurrence of the problem.
* **`errors`** – An optional list of field-level details. Each entry carries the `location` that failed, a `message`, and the `value` at that location.
* **`upstream`** – An RFC 9457 extension member. It carries the code and message a proxied third-party provider reported, and it is absent unless the service surfaced one.

**How to read these tables**

Each row starts with the HTTP status the response carries. Then it names the condition. The last column gives the `detail` text the service sends by default. Where the service composes that text from the failing request, the row says so.

At status 500 and above the response carries fixed text, not the raw cause. The `detail` column shows whether a code sends `internal error` or a sentence the service wrote for it.

## Pix service request and business rules

***

These codes come from the Pix service itself. They cover request validation, Pix key management, key claims, payment orders, returns, QR codes, indirect participants, and inbound credits.

### Request validation and access

| `code` | Description | `detail` |
| - | - | - |
| `PIX-0001` | **400** Field validation error | One or more fields contain validation errors. Please check the fields object for details and correct the invalid values. |
| `PIX-0002` | **400** Bad request | Set by the operation that raised the error. |
| `PIX-0003` | **400** Unexpected fields | Set by the operation that raised the error. |
| `PIX-0004` | **401** Unauthorized | Set by the operation that raised the error. |
| `PIX-0005` | **403** Forbidden | Set by the operation that raised the error. |
| `PIX-0006` | **404** Not found | Set by the operation that raised the error. |
| `PIX-0007` | **409** Conflict | Set by the operation that raised the error. |
| `PIX-0008` | **422** Unprocessable entity | Set by the operation that raised the error. |
| `PIX-0009` | **429** Too many requests | Set by the operation that raised the error. |
| `PIX-0058` | **400** Invalid ID | The provided ID is invalid or malformed. Please verify the ID format and try again. |
| `PIX-0059` | **401** Invalid token | The provided token is invalid or has expired. Please obtain a new token and try again. |
| `PIX-0060` | **400** Location required | Location information is required for this operation. Please provide valid location data. |
| `PIX-0061` | **400** Invalid parameters | One or more request parameters are invalid. Please check the parameter values and try again. |
| `PIX-0062` | **400** Invalid information | The provided information is invalid or incomplete. Please verify all fields and try again. |
| `PIX-0082` | **401** Authentication required | Valid authentication credentials are required to access this resource. Please provide a valid bearer token. |
| `PIX-0083` | **403** Access forbidden | You do not have sufficient permissions to perform this action. Please contact support if you believe this is an error. |
| `PIX-0084` | **400** Request validation error | The request validation failed. Please check all required fields and try again. |

### Pix keys

| `code` | Description | `detail` |
| - | - | - |
| `PIX-0010` | **422** Invalid Pix key format | The PIX key format is invalid for the specified type. Please verify the format matches the expected pattern and try again. |
| `PIX-0011` | **409** Pix key already exists | A PIX key with this value already exists. Please use a different PIX key. |
| `PIX-0012` | **404** Pix key not found | The specified PIX key was not found in the system. Please verify the key value and try again. |
| `PIX-0013` | **429** Pix key limit exceeded | You have reached the maximum number of PIX keys allowed. Please delete an existing key before creating a new one. |
| `PIX-0014` | **422** Invalid Pix key type | The PIX key type is not valid for this operation. Please use a supported key type. |
| `PIX-0015` | **422** Pix key expired | Set by the operation that raised the error. |
| `PIX-0016` | **422** Pix key pending confirmation | Set by the operation that raised the error. |
| `PIX-0017` | **422** Pix key inactive | Set by the operation that raised the error. |
| `PIX-0018` | **403** Pix key delete not allowed | This PIX key is not registered to the informed account, so it cannot be deleted. Please verify the key and the account. |
| `PIX-0067` | **422** Pix key expired | The PIX key has expired and cannot be used. Please create a new PIX key. |
| `PIX-0068` | **422** Pix key confirmation required | The PIX key requires confirmation before activation. Please check your email or SMS for the confirmation code. |
| `PIX-0069` | **404** Pix key not found | The specified PIX key was not found in the system. Please verify the key value and try again. |
| `PIX-0070` | **422** Invalid Pix key | The PIX key is invalid or has been deactivated. Please use a valid PIX key. |
| `PIX-0071` | **409** Pix key already owned | You already own this PIX key. Each PIX key can only be associated with one account. |
| `PIX-0072` | **422** Pix key limit exceeded | You have reached the maximum number of PIX keys allowed. Please delete an existing key before creating a new one. |
| `PIX-0073` | **422** Invalid Pix key status | The PIX key is not in a valid status for this operation. Please check the key status. |
| `PIX-0074` | **404** Internal Pix key not found | The internal PIX key reference was not found. Please contact support. |
| `PIX-0086` | **422** Document mismatch | The account document does not match the document associated with the PIX key. Only the key owner can claim this key. |

### Pix key claims

| `code` | Description | `detail` |
| - | - | - |
| `PIX-0020` | **404** Claim not found | The specified claim was not found for this account. Please verify the claim ID and try again. |
| `PIX-0021` | **409** Claim already exists | Set by the operation that raised the error. |
| `PIX-0022` | **422** Pix key claim or scheduled instruction is in a status this action does not allow | The PIX Automatico authorization is not in a valid status for this operation. Please check the authorization status. |
| `PIX-0023` | **422** Claim expired | Set by the operation that raised the error. |
| `PIX-0024` | **403** Claim unauthorized action | Set by the operation that raised the error. |
| `PIX-0025` | **409** Claim already processed | Set by the operation that raised the error. |
| `PIX-0026` | **422** Invalid claim data | Set by the operation that raised the error. |
| `PIX-0027` | **400** Claim names a participant that does not match the key record | Set by the operation that raised the error. |

### Transactions and payments

| `code` | Description | `detail` |
| - | - | - |
| `PIX-0028` | **404** Transaction not found | Set by the operation that raised the error. |
| `PIX-0029` | **409** Duplicate transaction | A transaction with this identifier already exists. Please use a unique transaction ID. |
| `PIX-0030` | **422** Invalid transaction amount | The transaction amount is invalid. Please provide a valid positive amount. |
| `PIX-0031` | **400** Insufficient balance | Set by the operation that raised the error. |
| `PIX-0032` | **409** Transaction limit exceeded | Set by the operation that raised the error. |
| `PIX-0033` | **422** Invalid recipient data | The recipient data is invalid. Please verify all recipient information. |
| `PIX-0034` | **422** Transaction expired | Set by the operation that raised the error. |
| `PIX-0035` | **422** Transaction cancelled | Set by the operation that raised the error. |
| `PIX-0036` | **422** Invalid transaction status | The transaction status transition is not permitted for the current state. |
| `PIX-0037` | **422** Invalid end-to-end ID | The end-to-end id is invalid for this payment order. Please check the value and try again. |
| `PIX-0075` | **409** Transaction limit exceeded | The transaction amount exceeds your configured limits. Please try a smaller amount or contact support to increase your limits. |
| `PIX-0076` | **409** Insufficient balance | Your account does not have sufficient balance for this transaction. Please add funds to your account and try again. |
| `PIX-0077` | **409** Same bank ID transfer not allowed | Transfers to the same Bank ID are not allowed for this operation. Please use a different destination. |
| `PIX-0078` | **409** Same account transfer not allowed | Transfers to the same account are not allowed. Please use a different destination account. |
| `PIX-0090` | **422** Insufficient funds for block | The payer's transactional account does not have sufficient funds to reserve the scheduled debit. (SGCTPIX001) |
| `PIX-0091` | **500** Block rejected | `internal error` |
| `PIX-0127` | **422** Payer participant required | This tenant acts as several direct participants, so the order must name the one that pays. Supply payerIspb and try again. |
| `PIX-0128` | **422** Payer participant unknown | The supplied payer participant is not a direct participant this tenant acts as. Verify payerIspb and try again. When the order carried a `payerIspb`, the detail appends it. |
| `PIX-0129` | **422** On-us payee not owned here | The receiving account banks at this participant, but it is not held in these books, so it cannot be credited as an internal transfer. No funds were reserved and no transfer was registered. When the order carried a payee ISPB, the detail appends it. |
| `PIX-0130` | **503** Ownership map unavailable | `internal error` |
| `PIX-0131` | **502** Ownership map unusable | `internal error` |
| `PIX-0132` | **422** Payee record cannot be keyed | The receiving account banks at this participant, but its branch or account on record cannot be used to establish which books hold it. No funds were reserved and no transfer was registered. |
| `PIX-0133` | **409** Earlier order refused | The earlier order sent under this idempotency key was refused and moved no money. To pay, send a new order under a new idempotency key, and a new endToEndId if you supply one. |
| `PIX-0134` | **422** On-us payee document mismatch | The receiving account belongs to a different holder than the payee document names, so it cannot be credited. No funds were reserved and no transfer was registered. Verify payee.document against payee.branch, payee.accountNumber and payee.accountDigit. |
| `PIX-0136` | **409** Payment signing misconfigured | Composed by the service. It says that the payment order was not sent because it cannot be signed, names the signing setting to correct and the reason, and says that no funds were moved. See [Payment-order signing](/en/interfaces/pix-jd/payment-order-signing). |
| `PIX-0145` | **422** On-us payee refused | The receiving account banks at this participant and refused the credit. No funds were debited: the reserved amount was released. Verify the payee before trying again. |
| `PIX-0146` | **503** On-us payee unreachable | The receiving account banks at this participant and could not be reached. No funds were debited: the reserved amount was released. Try again later with a new request. |
| `PIX-0149` | **409** Fee configuration deducts from amount | The fee for a payment to an account at this participant is configured to be deducted from the amount; it must be charged on top. No funds were debited: the reserved amount will be released. Contact support. |

### Returns and refunds

| `code` | Description | `detail` |
| - | - | - |
| `PIX-0038` | **403** Return not allowed | Set by the operation that raised the error. |
| `PIX-0039` | **422** Invalid return reason | Set by the operation that raised the error. |
| `PIX-0040` | **422** Return amount exceeds original | Set by the operation that raised the error. |
| `PIX-0041` | **403** Return window expired | Set by the operation that raised the error. |
| `PIX-0042` | **404** Original transaction not found | Set by the operation that raised the error. |
| `PIX-0087` | **400** Cannot refund own transaction | You cannot request a refund for your own outgoing transaction. Only the recipient can request a refund. |
| `PIX-0088` | **400** Cannot refund transaction not received | You can only request refunds for transactions you have received. |
| `PIX-0089` | **400** Cannot refund outgoing transaction | Outgoing transactions (CASH\_OUT) cannot be refunded. Only received transactions can be refunded. |
| `PIX-0135` | **422** Refund participant mismatch | This transaction was not received by the participant this refund names. A Pix received on an indirect participant's position is returned by that indirect: send its indirectId. A Pix received on a direct account is returned without one. No funds were moved and no refund was registered. |
| `PIX-0142` | **409** Original ledger not configured | The payment this refund returns was booked in a ledger that is no longer configured for Pix on this deployment, so it cannot be returned here. Nothing was posted and no refund was recorded. An operator has to restore that configuration. |

### Participants and accounts

| `code` | Description | `detail` |
| - | - | - |
| `PIX-0043` | **422** Invalid bank ID | Set by the operation that raised the error. |
| `PIX-0044` | **422** Bank ID not participating | Set by the operation that raised the error. |
| `PIX-0045` | **422** Invalid account number | Set by the operation that raised the error. |
| `PIX-0046` | **422** Account blocked | Set by the operation that raised the error. |
| `PIX-0047` | **422** Account closed | Set by the operation that raised the error. |
| `PIX-0137` | **422** Account ledger not configured | The account is held in a ledger that is not configured for Pix on this participant, so it cannot be used here. No funds were reserved and nothing was registered. Use an account held in a ledger configured for Pix, or ask the operator to add its ledger to the Pix setup. When the account is known, the detail appends `Account: <id>`. |
| `PIX-0138` | **422** Account ledger undetermined | The account's record at this participant does not say which ledger holds it, so it cannot be used here. Nothing was reserved or registered. Have the account's record name its ledger, or use another account. When the account is known, the detail appends `Account: <id>`. |
| `PIX-0139` | **422** Account participant mismatch | The account's record names a different institution than the one this operation acts as, so it cannot be used here. Nothing was reserved or registered. Verify the participant named on the request. When the account is known, the detail appends `Account: <id>`. |
| `PIX-0141` | **422** Account not in indirect books | The payer account is held in a ledger other than the one the indirect participant is mounted on, so it cannot pay as that indirect. Nothing was reserved or registered. When the account is known, the detail appends `Account: <id>`. |
| `PIX-0143` | **422** Account ambiguous | The document or branch and account on this request match more than one account at this participant, so the account cannot be determined. Nothing was registered. Name the branch and account. |
| `PIX-0144` | **422** Account holder mismatch | The branch and account on this request belong to a different holder than the document it names. Nothing was registered. Verify the document against the branch and account. |
| `PIX-0147` | **404** Record not held for participant | No record with this identifier is held under the direct participant or indirect participant the request names. Nothing was read or changed. Name the participant the record was created under, or check the identifier. |

### QR codes

| `code` | Description | `detail` |
| - | - | - |
| `PIX-0048` | **422** Invalid QR code | Set by the operation that raised the error. |
| `PIX-0049` | **504** QR code expired | `internal error` |
| `PIX-0050` | **422** QR code already used | Set by the operation that raised the error. |
| `PIX-0124` | **409** Ledger scope not served | This operation only posts in the tenant's default Midaz organization and ledger, and the record it was asked to act on belongs to a different one, so nothing was posted. When the service knows the organization and the ledger of the record, the detail appends them. |

### Entities, templates and conciliation

| `code` | Description | `detail` |
| - | - | - |
| `PIX-0063` | **404** Entity not found | The specified entity was not found in the system. Please verify the identifier and try again. |
| `PIX-0064` | **409** Entity already exists | An entity with this identifier already exists. Please use a unique identifier. |
| `PIX-0065` | **409** Conciliation ID already exists | A record with this conciliation ID already exists. Please use a unique conciliation ID. |
| `PIX-0066` | **404** Template not found | The specified template was not found. Please verify the template identifier. |
| `PIX-0110` | **409** Entity already withdrawn | The specified entity has already been withdrawn and can no longer be acted on. |

### Fraud, compliance and regulation

| `code` | Description | `detail` |
| - | - | - |
| `PIX-0055` | **400** Fraud detected | Set by the operation that raised the error. |
| `PIX-0056` | **403** Compliance violation | Set by the operation that raised the error. |
| `PIX-0057` | **403** Regulatory restriction | Set by the operation that raised the error. |

### Service and dependency faults

| `code` | Description | `detail` |
| - | - | - |
| `PIX-0051` | **503** Service unavailable | The PIX integration is temporarily unavailable for this tenant. Please try again shortly. |
| `PIX-0052` | **504** Timeout | `internal error` |
| `PIX-0053` | **500** Internal error | `internal error` |
| `PIX-0054` | **502** External service error | `internal error` |
| `PIX-0079` | **502** External service error | `internal error` |
| `PIX-0080` | **500** Core banking error | `internal error` |
| `PIX-0085` | **500** Database connection error | `internal error` |
| `PIX-0109` | **500** Server failure the service could not attribute to a specific condition | `internal error` |
| `PIX-0126` | **503** License unavailable | `internal error` |

### Tenant configuration

| `code` | Description | `detail` |
| - | - | - |
| `PIX-0092` | **409** Tenant Pix integration not provisioned | The PIX integration for this tenant has not been provisioned. Please contact support to complete tenant onboarding. |
| `PIX-0105` | **409** Tenant route configuration missing | The PIX routing configuration for this tenant is missing or invalid. Please contact support to complete tenant onboarding. |
| `PIX-0106` | **409** Tenant ledger configuration missing | The Midaz ledger identity for this tenant is not provisioned, so no transaction was posted. The posting organization, the ledger, the posting asset and the external clearing account must all be set: the organization and the ledger in the tenancy/jd\_integration\_binding fields organizationId and ledgerId, the asset and the clearing account in the systemplane keys tenant\_policy/midaz.asset\_id and tenant\_policy/midaz.external\_id. There is no environment-variable fallback for any of the four. Only an operator can supply them, so repeating this request without that change will fail identically. |
| `PIX-0107` | **409** Indirect delivery encryption not provisioned. Raised when the tenant's delivery-secret encryption key is absent, blank, or malformed, and when no cipher is wired at all. Absent and wrong-shaped share this code because they share the fix: an operator changes the value. On a self-hosted deployment that value is `INDIRECTS_DELIVERY_ENCRYPTION_KEY`, and it must be exactly 64 hexadecimal characters (a hex-encoded AES-256 key) | No delivery-secret encryption key is provisioned for this tenant, so the indirect participant was not saved and no secret was stored. Self-hosted deployments set INDIRECTS\_DELIVERY\_ENCRYPTION\_KEY; on Lerian Cloud, Lerian manages this key. Only an operator can supply it, so repeating this request without that change will fail identically. |
| `PIX-0108` | **422** Ledger account alias unresolved | Set by the operation that raised the error. |
| `PIX-0121` | **409** Tenant Pix integration ISPB invalid | The PIX integration for this tenant is misconfigured: the "ispb" field of the systemplane key tenancy/jd\_integration\_binding must be exactly 8 digits. Please contact support to correct the tenant's PIX integration binding. |
| `PIX-0122` | **503** Tenant configuration unreadable | A piece of this tenant's configuration could not be read from the tenant configuration plane, so the request was not carried out. The configuration is not known to be missing — the read itself did not complete — so this is a fault on our side rather than an onboarding gap. Please try again shortly; if it persists, contact support. |
| `PIX-0123` | **503** Indirect delivery key source unavailable | The delivery-secret encryption key for this tenant could not be read from its key source, so the indirect participant was not saved and no secret was stored. The key is not known to be missing — the read itself did not complete — so this is a fault on our side rather than an onboarding gap. Please try again shortly; if it persists, contact support. |
| `PIX-0125` | **500** Tenant ledger scope misprovisioned | `internal error` |

> [!NOTE]
>
> **The status, not the family, tells you whether to retry.** A `409` in this section means a provisioning gap. The service knows that the value is absent. Only an operator can supply it, and a repeat of the request cannot change that.
>
> A `503` is the *unreadable* sibling of the same condition. The service does not know that the configuration is absent, because the read itself did not complete. The answer names the faulting dependency, and a retry can succeed.
>
> The pairs are `PIX-0092`/`PIX-0121` against `PIX-0051`, `PIX-0106` against `PIX-0122`, and `PIX-0107` against `PIX-0123`.

### Indirect participants

| `code` | Description | `detail` |
| - | - | - |
| `PIX-0093` | **409** Indirect ISPB conflict | An indirect participant with this ISPB is already registered and active for this tenant. A closed indirect may be re-registered, but an open one is unique per ISPB. |
| `PIX-0094` | **409** Illegal indirect transition | The requested lifecycle change is not permitted for the indirect participant's current status. |
| `PIX-0095` | **404** Indirect not found | The specified indirect participant was not found for this tenant. Please verify the identifier and try again. |
| `PIX-0096` | **409** Cannot close indirect with balance | The indirect participant cannot be closed while its PIX account holds funds. Settle the available balance and on-hold amount to zero and try again. |
| `PIX-0097` | **409** Indirect not awaiting provisioning | Provisioning retry is only valid for an indirect participant in the PENDING\_PROVISIONING state. |
| `PIX-0098` | **422** Invalid indirect participant | The indirect participant request is invalid. Please verify the name, ISPB, delivery endpoint, secret, and messaging mode and try again. |
| `PIX-0099` | **502** Indirect provisioning failed | `internal error` |
| `PIX-0100` | **422** Indirect not active | The specified indirect participant is not active and cannot originate a transaction. Reactivate it and try again. |
| `PIX-0102` | **422** Indirect payer mismatch | The supplied payer ISPB is not the direct participant this indirect is mounted on. Verify the indirect identifier and payer ISPB and try again. |
| `PIX-0103` | **409** Credit park not open | The parked inbound credit is no longer PARKED (it was already resolved or rejected, possibly by a concurrent request). No further action was taken. |
| `PIX-0104` | **409** Indirect target not active | The indirect participant targeted by this resolution is not ACTIVE and cannot receive the credit. Reactivate it or choose a different target. |
| `PIX-0111` | **422** Indirects feature disabled | Set by the operation that raised the error. |
| `PIX-0112` | **422** Indirect QR location too long | Set by the operation that raised the error. |
| `PIX-0113` | **422** Indirect QR host not public | Set by the operation that raised the error. |
| `PIX-0114` | **422** Indirect has no own QR certificate | Set by the operation that raised the error. |
| `PIX-0140` | **409** Indirect books not configured | The indirect participant this request names is mounted on books that are no longer configured for Pix on this deployment. Nothing was reserved or registered. An operator has to restore that configuration. |

### Inbound credits

| `code` | Description | `detail` |
| - | - | - |
| `PIX-0115` | **404** Cash-in account not found | The receiving account named by this credit was not found at this participant, so no credit was registered. |
| `PIX-0116` | **409** Cash-in destination ambiguous | The receiver document names more than one account at this participant, so the destination for this credit cannot be determined. No credit was registered. Address the credit to a specific account (recebedor.nrAgencia and recebedor.nrConta) or contact this participant to have the duplicate records corrected. |
| `PIX-0117` | **409** Cash-in holder mismatch | The account addressed by this credit belongs to a different holder than the receiver document names, so no credit was registered. Verify recebedor.cpfCnpj against recebedor.nrAgencia and recebedor.nrConta. |
| `PIX-0118` | **409** Cash-in account not creditable | The account addressed by this credit exists at this participant but is not set up to receive credits, so no credit was registered. Contact this participant to have the account record completed. |
| `PIX-0119` | **404** Cash-in receiver not served | The receiving participant named by this credit is not served by this participant, so no credit was registered. Verify recebedor.ispb. |
| `PIX-0120` | **500** Cash-in ledger misprovisioned | `internal error` |

## Pix rail and key directory

***

These codes come from the connected Pix infrastructure. The service translates a rail fault into one of these codes before it answers. A caller branches on a `PIX-NNNN` value, not on the rail's own vocabulary.

### Request validation and authentication

| `code` | Description | `detail` |
| - | - | - |
| `PIX-1000` | **400** Field validation error | One or more fields contain validation errors. Please check the fields object for details and correct the invalid values. |
| `PIX-1001` | **400** Bad request | The server could not understand the request due to malformed syntax. Please check the request format and try again. |
| `PIX-1002` | **400** Unexpected fields in request | The request body contains more fields than expected. Please send only the allowed fields as per the documentation. |
| `PIX-1003` | **401** Unauthorized | Authentication credentials were missing or incorrect. Please provide valid credentials. |
| `PIX-1004` | **403** Forbidden | The server understood the request but refuses to authorize it. Please check your permissions. |
| `PIX-1005` | **404** Not found | The requested resource was not found. Please verify the identifier and try again. |
| `PIX-1006` | **409** Conflict | The request could not be completed due to a conflict with the current state. |
| `PIX-1007` | **422** Unprocessable entity | The request was well-formed but unable to be processed due to semantic errors. |
| `PIX-1008` | **429** Too many requests | Too many requests have been sent. Please wait before making another request. |
| `PIX-1059` | **400** Authentication token missing | Authentication token is missing in the request. Please provide a valid Bearer token in the Authorization header. |
| `PIX-1060` | **400** Invalid authentication token | The authentication token provided is invalid. Please obtain a new token and try again. |
| `PIX-1061` | **400** Authentication token expired | The authentication token has expired. Please obtain a new token using the authentication endpoint. |
| `PIX-1062` | **400** Insufficient permissions | The authenticated participant does not have sufficient permissions to perform this operation. |
| `PIX-1063` | **400** Participant not authorized | The authenticated participant is not authorized to perform this operation on the specified resource. |
| `PIX-1064` | **400** Authentication or authorization rule was violated | The request violates authentication or authorization rules. Please verify your credentials and permissions. |

### Pix keys

| `code` | Description | `detail` |
| - | - | - |
| `PIX-1009` | **422** Invalid Pix key format | The PIX key format is invalid for the specified type. Please verify the format matches the expected pattern and try again. |
| `PIX-1010` | **409** Pix key already exists | A PIX key with this value already exists. Please use a different PIX key. |
| `PIX-1011` | **404** Pix key not found | The specified PIX key was not found in the system. Please verify the key value and try again. |
| `PIX-1012` | **400** Pix key limit exceeded | You have reached the maximum number of PIX keys allowed. Please delete an existing key before creating a new one. |
| `PIX-1013` | **422** Invalid Pix key type | The PIX key type is invalid. Please use a valid PIX key type. |
| `PIX-1014` | **422** Pix key expired | The PIX key has expired and cannot be used. Please create a new PIX key. |
| `PIX-1015` | **400** Pix key pending confirmation | The PIX key is pending confirmation. Please complete the confirmation process. |
| `PIX-1016` | **400** Pix key inactive | The PIX key is inactive and cannot be used. Please activate the PIX key. |
| `PIX-1017` | **403** Pix key delete not allowed | The PIX key cannot be deleted in its current state. Please check the key status. |
| `PIX-1018` | **422** Invalid account type | The account type is invalid for this operation. Please use a valid account type. |

### Pix key claims

| `code` | Description | `detail` |
| - | - | - |
| `PIX-1019` | **404** Pix key claim not found | The specified PIX key claim was not found. Please verify the claim identifier. |
| `PIX-1020` | **409** Pix key claim already exists | A PIX key claim with this identifier already exists. Please use a unique identifier. |
| `PIX-1021` | **422** Invalid claim status | The claim is not in a valid status for this operation. Please check the claim status. |
| `PIX-1022` | **422** Pix key claim expired | The PIX key claim has expired and cannot be processed. Please create a new claim. |
| `PIX-1023` | **403** Unauthorized claim action | You are not authorized to perform this action on the claim. Please check your permissions. |
| `PIX-1024` | **409** Claim already processed | The PIX key claim has already been processed and cannot be modified. |
| `PIX-1025` | **422** Invalid claim data | The claim data provided is invalid. Please verify all fields and try again. |
| `PIX-1026` | **400** Claim bank ID mismatch | There is a Bank ID mismatch in the claim request. Please verify the Bank ID values. |

### Transactions and payments

| `code` | Description | `detail` |
| - | - | - |
| `PIX-1027` | **404** Transaction not found | The specified transaction was not found. Please verify the transaction identifier. |
| `PIX-1028` | **409** Transaction already exists | A transaction with this identifier already exists. Please use a unique transaction ID. |
| `PIX-1029` | **422** Invalid transaction amount | The transaction amount is invalid. Please provide a valid positive amount. |
| `PIX-1030` | **400** Insufficient balance | The account does not have sufficient balance for this transaction. Please add funds and try again. |
| `PIX-1031` | **409** Transaction limit exceeded | The transaction amount exceeds the configured limits. Please try a smaller amount. |
| `PIX-1032` | **422** Invalid recipient data | The recipient data is invalid. Please verify all recipient information. |
| `PIX-1033` | **422** Transaction expired | The transaction has expired and cannot be processed. Please create a new transaction. |
| `PIX-1034` | **422** Transaction cancelled | The transaction has been cancelled and cannot be processed. |
| `PIX-1035` | **422** Payment validation failed | Payment validation failed. Please verify all payment details and try again. |
| `PIX-1036` | **400** Invalid end-to-end ID | The end-to-end ID format is invalid. Please use a valid end-to-end identifier. |

### Returns

| `code` | Description | `detail` |
| - | - | - |
| `PIX-1037` | **400** Return not allowed | Return is not allowed for this transaction. Please check the transaction status and return eligibility. |
| `PIX-1038` | **422** Invalid return reason | The return reason code is invalid. Please use a valid return reason code. |
| `PIX-1039` | **422** Return amount exceeds original | The return amount exceeds the original transaction amount. Please enter a valid return amount. |
| `PIX-1040` | **400** Return window expired | The return window has expired for this transaction. Returns are no longer allowed. |
| `PIX-1041` | **404** Original transaction not found | The original transaction was not found for this return. Please verify the transaction identifier. |

### Participants and accounts

| `code` | Description | `detail` |
| - | - | - |
| `PIX-1042` | **422** Invalid bank ID | The Bank ID code is invalid. Please provide a valid Bank ID code. |
| `PIX-1043` | **422** Bank ID not participating | The Bank ID is not participating in the PIX system. Please use a participating Bank ID. |
| `PIX-1044` | **422** Invalid account number | The account number format is invalid. Please provide a valid account number. |
| `PIX-1045` | **422** Account blocked | The account is blocked and cannot be accessed. Please contact support. |
| `PIX-1046` | **400** Account closed | The account is closed and cannot be accessed. Please use an active account. |

### QR codes

| `code` | Description | `detail` |
| - | - | - |
| `PIX-1047` | **422** Invalid QR code | The QR code format is invalid or corrupted. Please verify the QR code and try again. |
| `PIX-1048` | **404** QR code expired | The QR code has expired and cannot be used. Please generate a new QR code. |
| `PIX-1049` | **422** QR code already used | The QR code has already been used and cannot be used again. |
| `PIX-1065` | **422** QR payload URL unreachable | Composed by the service. It says that the QR code's payload could not be fetched from its URL, names the URL's host, says that the host belongs to the institution receiving the payment and that the failure is the host's, and appends JDPI's own explanation when JDPI gives one. |

### Rail availability

| `code` | Description | `detail` |
| - | - | - |
| `PIX-1050` | **503** JDPI service unavailable | JDPI service is temporarily unavailable. Please try again later. |
| `PIX-1051` | **504** JDPI service timeout | JDPI service request timed out. Please try again. |
| `PIX-1052` | **500** JDPI internal error | An internal JDPI error occurred. Please contact support if the issue persists. |
| `PIX-1053` | **429** Too many requests | Too many requests have been sent. Please wait before making another request. |
| `PIX-1054` | **503** JDPI connection error | `internal error` |
| `PIX-1055` | **502** External service error | `internal error` |

### Fraud, compliance and regulation

| `code` | Description | `detail` |
| - | - | - |
| `PIX-1056` | **403** Fraud detected | The transaction was blocked due to fraud detection. Please contact support. |
| `PIX-1057` | **403** Compliance violation | A compliance violation was detected. Please ensure all requirements are met. |
| `PIX-1058` | **403** Regulatory restriction | A regulatory restriction applies to this operation. Please contact support. |

## Failures that originate outside the Pix rail

***

A Pix request can also fail because another platform service refused it. Three code bands carry those refusals: customer records, authorization, and the Midaz ledger.

On the inbound cash-in webhook (`POST /v1/webhooks/cash-ins`), a CRM, Access Manager, or Midaz outage answers `500` instead of `503` or `504`. The `code` is the code of the dependency, for example `PIX-3007`, and the `detail` names the dependency.

### Customer records

| `code` | Description | `detail` |
| - | - | - |
| `PIX-2000` | **422** Invalid metadata nesting | The metadata object cannot contain nested values. Please ensure that the value is not nested and try again. |
| `PIX-2001` | **422** Metadata key too long | The metadata key exceeds the maximum allowed length. Please use a shorter key name. |
| `PIX-2002` | **400** Missing fields in request | Your request is missing one or more required fields. Please provide all required fields and try again. |
| `PIX-2003` | **400** Invalid field type in request | One or more fields have incorrect data types. Please check the field types and try again. |
| `PIX-2004` | **400** Invalid path parameter | The path parameters are in incorrect format. Please verify the parameter format. |
| `PIX-2005` | **400** Unexpected fields in the request | The request contains more fields than expected. Please send only the allowed fields as per the documentation. |
| `PIX-2006` | **422** Pagination limit exceeded | The pagination limit exceeds the maximum allowed value. Please use a smaller limit. |
| `PIX-2007` | **400** Invalid sort order | The sort order must be either "asc" or "desc". Please use a valid sort order. |
| `PIX-2008` | **400** Metadata value too long | The metadata value exceeds the maximum allowed length. Please use a shorter value. |
| `PIX-2009` | **409** Account already associated | The account can only be associated with one related account. Please use a different account. |
| `PIX-2010` | **400** Bad request | The server cannot understand the request due to invalid syntax. Please check the request format. |
| `PIX-2011` | **400** Invalid query parameter | The query parameters are in incorrect format. Please verify the parameter values. |
| `PIX-2012` | **422** Unable to delete holder | The holder cannot be deleted due to associated accounts. Please remove associated accounts first. |
| `PIX-2013` | **400** Missing headers in request | Required header parameters are missing from the request. Please include all required headers. |
| `PIX-2014` | **400** Invalid metadata format | The metadata parameter format is incorrect. Please use the correct metadata format. |
| `PIX-2015` | **404** Holder ID not found | The specified holder ID does not exist. Please verify the holder ID and try again. |
| `PIX-2016` | **404** Account ID not found | The specified account ID does not exist. Please verify the account ID and try again. |
| `PIX-2017` | **403** CRM authentication failed | CRM authentication failed. Please verify your credentials. |
| `PIX-2018` | **409** Document association error | The document can only be associated with one holder. Please use a different document. |
| `PIX-2019` | **500** Internal server error | `internal error` |
| `PIX-2020` | **503** CRM connection error | `internal error` |
| `PIX-2021` | **504** CRM service timeout | `internal error` |
| `PIX-2022` | **503** CRM service unavailable | `internal error` |
| `PIX-2023` | **401** CRM authentication failed | CRM authentication failed. Please verify your credentials. |
| `PIX-2024` | **429** CRM rate limit exceeded | CRM service rate limit exceeded. Please wait before making another request. |
| `PIX-2025` | **403** CRM refused the partner | The CRM refused this request under the partner credential's own rules for The CRM. The partner needs a grant for The CRM that covers this operation. When the CRM gives a reason, the detail appends it. |

### Authorization

| `code` | Description | `detail` |
| - | - | - |
| `PIX-3000` | **400** Missing fields in request | Your request is missing one or more required fields. Please provide all required fields and try again. |
| `PIX-3001` | **422** Invalid grant type | The provided grant type is invalid. Please use "client\_credentials" for authentication. |
| `PIX-3002` | **422** Grant type missing fields | Required fields are missing for the grant type. Please provide client\_id and client\_secret. |
| `PIX-3003` | **422** Unsupported grant type | The grant type is not supported by the application. Please use "client\_credentials". |
| `PIX-3004` | **401** Invalid client | The provided client credentials are invalid. Please verify your client ID and client Secret. |
| `PIX-3005` | **400** Bad request | The server cannot understand the request due to invalid syntax. Please check the request format. |
| `PIX-3006` | **400** Access manager connection error | Failed to connect to Access Manager service. Please check service availability and try again. |
| `PIX-3007` | **504** Access manager timeout. For example, the Access Manager did not answer in time when the service asked for its own token. | `internal error` |
| `PIX-3008` | **503** Access manager service unavailable. For example, the token request of the service to the Access Manager got no answer or a `5xx` status. | `internal error` |

### Ledger

| `code` | Description | `detail` |
| - | - | - |
| `PIX-4000` | **503** Midaz connection error | `internal error` |
| `PIX-4001` | **504** Midaz service timeout | `internal error` |
| `PIX-4002` | **503** Midaz service unavailable. For example, a Midaz account read timed out or got a `5xx` status, or Midaz answered `401` or `403` to the service. | `internal error` |
| `PIX-4005` | **400** Invalid Midaz request | Invalid request to Midaz service. Please verify the request format. |
| `PIX-4006` | **404** Midaz account not found | The specified Midaz account was not found. Please verify the account ID and try again. |
| `PIX-4007` | **422** Midaz account blocked | The Midaz account is blocked and cannot be accessed. Please contact support. |
| `PIX-4008` | **400** Midaz account closed | The Midaz account is closed and cannot be accessed. Please contact support. |
| `PIX-4009` | **422** Insufficient Midaz balance | The account does not have sufficient balance for this operation. Please add funds and try again. |
| `PIX-4010` | **503** Midaz balance fetch error | `internal error` |
| `PIX-4011` | **500** Midaz transaction failed | `internal error` |
| `PIX-4012` | **500** Midaz debit failed | `internal error` |
| `PIX-4013` | **500** Midaz credit failed | `internal error` |
| `PIX-4014` | **404** Midaz transaction not found | The specified Midaz transaction was not found. Please verify the transaction ID. |
| `PIX-4015` | **409** Duplicate Midaz transaction | A Midaz transaction with this identifier already exists. Please use a unique transaction ID. |
| `PIX-4016` | **422** Invalid transaction amount | The transaction amount is invalid. Please provide a valid positive amount. |
| `PIX-4017` | **409** Midaz transaction limit exceeded | The transaction amount exceeds Midaz configured limits. Please try a smaller amount. |
| `PIX-4018` | **422** Midaz transaction denied | The transaction was denied by the institution's transaction validation rules. |
| `PIX-4019` | **403** Midaz refused the partner | Midaz refused this request under the partner credential's own rules for Midaz. The partner needs a grant for Midaz that covers this operation. When Midaz gives a reason, the detail appends it. |

## Notification delivery

***

The Pix key ownership flows send a one-time code by email or by SMS. These codes report a failure on that delivery leg.

### Email delivery

| `code` | Description | `detail` |
| - | - | - |
| `PIX-5000` | **401** Invalid API key | The SendGrid API key is invalid, deleted, or permissions have changed. Please verify your API key. |
| `PIX-5001` | **400** Malformed payload | The SendGrid API payload request is malformed. Please check the request format. |
| `PIX-5002` | **403** Insufficient permissions | You have insufficient permissions for this SendGrid operation. Please check your account permissions. |
| `PIX-5003` | **429** Rate limit exceeded | SendGrid rate limit exceeded. Please wait before making another request. |
| `PIX-5004` | **400** SendGrid connection error | Failed to connect to SendGrid email service. Please check service availability and try again. |
| `PIX-5005` | **504** SendGrid service timeout | SendGrid email service request timed out. Please try again. |
| `PIX-5006` | **503** SendGrid service unavailable | SendGrid email service is temporarily unavailable. Please try again later. |

### SMS delivery

| `code` | Description | `detail` |
| - | - | - |
| `PIX-6000` | **403** Permission denied | Permission denied for Twilio SMS operation. Please check your account permissions and try again. |
| `PIX-6001` | **401** Invalid access token | The Twilio access token is invalid. Please verify your authentication credentials. |
| `PIX-6002` | **401** Authentication failed | Twilio SMS authentication failed. Please verify your account credentials. |
| `PIX-6003` | **400** Trial account limitation | This feature is not available for trial accounts. Please upgrade your Twilio account. |
| `PIX-6004` | **400** Invalid URL format | Invalid URL format for Twilio webhook. Please verify the URL format and try again. |
| `PIX-6005` | **400** HTTP protocol violation | HTTP protocol violation in Twilio request. Please check the request format. |
| `PIX-6006` | **429** SMS rate limit exceeded | Twilio SMS send rate limit exceeded. Please wait before sending more messages. |
| `PIX-6007` | **400** Phone not SMS capable | The from phone number is not SMS capable. Please use an SMS-capable phone number. |
| `PIX-6008` | **400** Reply limit exceeded | TwiML Reply message limit exceeded. Please reduce the number of reply messages. |
| `PIX-6009` | **400** Verb used for the SMS request is not allowed | Invalid Verb for SMS Reply. Please use a valid TwiML verb. |
| `PIX-6010` | **400** Invalid phone for trial | Invalid destination phone number for trial mode. Please verify the number or upgrade your account. |
| `PIX-6011` | **400** Sender phone number is not verified | The from phone number is not verified for your Twilio account. Please verify the number. |
| `PIX-6012` | **400** Sender phone number is not verified | The from phone number is not verified for your Twilio account. Please verify the number. |
| `PIX-6013` | **400** Invalid destination phone number | The destination phone number format is invalid. Please use a valid phone number. |
| `PIX-6014` | **400** Invalid sender phone number | The sender phone number format is invalid. Please use a valid phone number. |
| `PIX-6015` | **400** Twilio connection error | Failed to connect to Twilio SMS service. Please check service availability and try again. |
| `PIX-6016` | **504** Twilio service timeout | Twilio SMS service request timed out. Please try again. |
| `PIX-6017` | **503** Twilio service unavailable | Twilio SMS service is temporarily unavailable. Please try again later. |

## MED refund rejection reasons

***

A MED refund request that this participant analyzes and rejects carries a numbered rejection reason. The domain uses the values 0, 1, 3 and 4.

| Value | Label | What it means |
| - | - | - |
| `0` | Falta de saldo | The customer account does not hold the balance to fund the refund. |
| `1` | Relacionamento encerrado | The relationship with the customer is closed. |
| `3` | Generico | A reason the other three values do not cover. |
| `4` | Requisicao invalida | The refund request is invalid. This value applies when the refund reason is an operational failure. |

## Pix return reason codes

***

A returned Pix carries a Bacen return reason of its own, separate from the `PIX-NNNN` codes above. This API reference documents the allowed values on the field that carries them. That field is `codigoDevolucao` on an inbound credit. On the refund credit status view it is `refundCode`. On a refund request it is `code`.


# Process a payee-bank-initiated PIX devolução
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/process-a-payee-bank-initiated-pix-devolu-o

/en/openapi/v3-current/pix.yaml post /v1/webhooks/refunds
Registers a PIX devolução that the PAYEE's bank initiated and JDPI has already executed (JDPI section 9.3.3). This participant does not initiate it and does not decide it: JDPI pushes it once the return has settled, and this call records the money coming back. It is idempotent on endToEndIdDevolucao: a redelivery of a devolução already registered, carrying the same amount against the same endToEndIdOriginal, answers 200 and credits nothing twice. While the devolução still awaits the original's settlement (below) that 200 is the acknowledgement the first delivery got; once the credit is booked it names that credit (its idCreditoSgct and dtHrCreditoSgct).

On success the returned amount is credited back to the account that funded the ORIGINAL payment, and the response carries the section 9.3.3 acknowledgement: idReqJdPi, idCreditoSgct (the identifier of the entry this participant recorded) and dtHrCreditoSgct. The original payment is located by endToEndIdOriginal; the payer's identity and destination are read from the record written when that payment was created, never re-resolved, so a devolução always returns to where the money left from. The one exception is an indirect participant's payment: its destination is that indirect's `@pi_{ispb}` settlement position, read from the indirects registry (below).

A MED devolução (codigoDevolucao BE08 or FR01) is the same call: it credits the same original payer, or, when this engine never made the original payment, the account the recebedor block names, booked on the MED clearing account rather than the ordinary refund one.

WHEN THIS PARTICIPANT NEVER MADE THE ORIGINAL PAYMENT — the account moved here after paying it — the devolução is still credited, because SPI has already settled it. It goes to the account the recebedor block names, resolved exactly as a cash-in to it would be, and books the amount SPI settled; it is neither capped nor parked. This is the only case that reads pagador and recebedor: a devolução of a payment made here never does, so neither block can refuse it.

ONE SUCCESS SHAPE IS NOT A COMPLETED CREDIT, and it is the case an integrator must plan for. When the original payment is still PENDING here (its SPI outcome has not been reconciled yet), the devolução is ACCEPTED AND OWNED rather than credited: it is recorded as awaiting the original's settlement, the acknowledgement is the same 200 shape with idCreditoSgct naming that record, and a background sweep completes the credit once the original settles. So a 200 asserts this participant has taken responsibility for the devolução, not that the money has already moved.

WHEN THE ORIGINAL PAYMENT BELONGED TO AN INDIRECT PARTICIPANT, the devolução follows it. This participant may serve indirect participants — other institutions registered here with POST /v1/indirects that reach SPI through this participant's ISPB. A payment originated for one of them was debited from its `@pi_{ispb}` settlement position, so the return credits that same position and the recorded devolução is stamped with the same institution as the original. Nothing in the section 9.3.3 payload says so — the linkage comes from the original payment's record, or, when this participant never made that payment, from the recebedor resolved as a cash-in's would be — and the 200 body is identical either way.

An indirect-linked devolução also queues a NOTICE to that registration's delivery.endpointUrl: one HTTPS POST forwarding this webhook's JD body verbatim, carrying X-Lerian-Signature ('sha256=' followed by the hex HMAC-SHA256 of the exact body bytes under the registration's shared secret) and X-Lerian-Timestamp. It is queued on the same conditions the cash-in notice is, and with the same asymmetry: a queued notice rides the devolução's own database transaction, but a devolução can be credited and answered 200 with NO notice queued — when this deployment has no outbound queue configured, or when the verbatim JD body could not be retained for forwarding. Delivery of a queued notice is AT-LEAST-ONCE and independent of this 200: it can repeat, and it can fail permanently while the money stays booked. The institution must dedup on endToEndIdDevolucao and read GET /v1/indirects/{indirectId}/transactions as the record of truth — which is also the only place a devolução whose notice was never queued becomes visible.

A devolução that CANNOT be registered is answered with an HTTP error carrying a distinct code in the problem body's `code` member:

- 409 PIX-0029 - this endToEndIdDevolucao was already registered here for a DIFFERENT devolução: another amount or another endToEndIdOriginal. Nothing was credited for this delivery; the original registration stays unchanged.
- 422 PIX-0030 - the devolução amount is not greater than zero.
- 500 PIX-4011 - whether the credit landed is not settled yet: an earlier delivery of this endToEndIdDevolucao is still being credited, or the ledger could not answer whether its credit landed. Nothing more was credited; redeliver, and the redelivery that finds the credit gets its acknowledgement.
- 503 / 504 - the ledger was unreachable or timed out on the credit. Redeliver: the redelivery adopts a credit that landed rather than posting it twice.
- 400 PIX-0061 - the body failed schema validation at the edge, before any lookup ran.

When this participant never made the original payment, the recebedor can also refuse the credit, with the codes a cash-in to that account would get. Nothing is credited on any of them:

- 400 PIX-0061 - recebedor is missing, is not a participant block, carries a malformed CPF/CNPJ or ISPB, or does not name recebedor.ispb, recebedor.cpfCnpj and recebedor.nrConta.
- 404 PIX-0115 - the account the recebedor names was not found here, or pagador.ispb identifies Bacen (99999).
- 404 PIX-0119 - recebedor.ispb is neither this participant's own ISPB nor an ACTIVE indirect participant registered in this tenant.
- 409 PIX-0116 - recebedor.cpfCnpj names more than one account here.
- 409 PIX-0117 - the addressed account belongs to a different holder than recebedor.cpfCnpj names.
- 409 PIX-0118 - the addressed account exists here but is not set up to receive credits.
- 500 PIX-0120 - a provisioning fault at this participant; redeliver once it is corrected.

A customer or registry lookup that fails answers 500 with nothing credited, and the devolução is safe to redeliver. For a devolução of a payment made here, none of the refusals are specific to an indirect participant: the linkage is read from the original payment rather than resolved from this request.



# Process an inbound JDPI cash-in
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/process-an-inbound-upstream-cash-in

/en/openapi/v3-current/pix.yaml post /v1/webhooks/cash-ins
Registers an inbound PIX credit that JDPI has settled to this participant (JDPI section 9.3.2). JDPI calls it once per received credit, after settlement; it is idempotent on the end-to-end id (the mandatory Chave-Idempotencia header). A redelivery of a credit already settled here, carrying the same amount, receiving account and organization/ledger, answers 200 with the acknowledgement the first delivery got (the same idCreditoSgct and dtHrCreditoSgct) and posts nothing.

On success the credit is posted to the receiving customer's account and the response carries the three section 9.3.2 members: idReqJdPi, idCreditoSgct (the identifier of the credit entry this participant recorded) and dtHrCreditoSgct (when it was recorded). That response is an assertion that the money was booked; there is no field in it for a refusal.

NOT EVERY CREDIT LANDS ON A CUSTOMER ACCOUNT. This participant may also serve INDIRECT participants — other institutions that reach SPI through this participant's ISPB and are registered here with POST /v1/indirects. When recebedor.ispb names one of them and its registration is ACTIVE, the credit is posted to THAT institution's `@pi_{ispb}` settlement position instead of to a customer account. The destination is read from the registry row, never from the payload, and the recorded credit is stamped with the institution it belongs to. The 200 body is identical in both cases, so the response does not tell you which destination was used; that institution's own movements are read with GET /v1/indirects/{indirectId}/transactions.

An indirect credit also queues a NOTICE to the endpoint that registration carries (delivery.endpointUrl): one HTTPS POST forwarding this webhook's JD body verbatim, carrying X-Lerian-Signature ('sha256=' followed by the hex HMAC-SHA256 of the exact body bytes under the registration's shared secret) and X-Lerian-Timestamp (the send time in Unix seconds, not covered by the signature).

THE CREDIT IS NOT CONDITIONAL ON THE NOTICE, AND THE NOTICE IS NOT GUARANTEED BY THE CREDIT. When a notice is queued it rides the same database transaction as the credit, so a queued notice always belongs to money that was booked. The reverse does not hold: a credit posts and is answered 200 with NO notice queued at all when this deployment has no outbound queue configured, or when the verbatim JD body could not be retained for forwarding (retention is best-effort — it is skipped for an empty body and abandoned on a write failure, and the credit proceeds either way, because the money is not held hostage to the forwarding). Delivery of a notice that WAS queued is AT-LEAST-ONCE and independent of this 200: the same notice can arrive more than once, and it can also fail permanently while the money stays booked. So a receiving institution must dedup on endToEndId, and must treat GET /v1/indirects/{indirectId}/transactions — not the notice — as the record of truth. Reconciling from that feed is not a fallback for a failed notice; it is the only way to see a movement whose notice was never queued.

Three ordering rules decide the destination and cannot be inferred from the payload:

- A pagador.ispb identifying Bacen (99999) short-circuits FIRST, ahead of any indirect matching, so it never reaches a settlement position either.
- A recebedor.ispb equal to this participant's OWN ISPB is always resolved against this participant's own customer records, never against the indirect registry.
- While this tenant's indirect-participants feature is switched OFF, recebedor.ispb is not read against the registry at all: every credit is resolved ONLY against this participant's own customer records, exactly as before indirect participants existed. Two things follow, and the second is the dangerous one. PIX-0119 becomes unreachable, because nothing consults the registry to find the receiver unserved. And a credit addressed to a registered institution is normally answered 404 PIX-0115, because no customer here holds that account number — but it is NOT refused on the account number alone. Should a local customer hold the same recebedor.nrConta AND the same recebedor.cpfCnpj, the credit is POSTED TO THAT CUSTOMER and answered 200, with the institution's `@pi_{ispb}` never involved; a number that collides under a different holder is refused 409 PIX-0117 instead. Sending recebedor.nrAgencia narrows that further — it is optional in section 9.3.2, and this participant adds it to the account lookup only when you send one, so a credit that omits it is matched on the account number alone. Register the institution AND enable the feature before pointing any credit at it.

A credit that CANNOT be registered is therefore answered with an HTTP error, never with a 200. Each carries a distinct code in the problem body's `code` member:

- 404 PIX-0115 - the receiving account named by the credit was not found here. Check recebedor.nrAgencia/recebedor.nrConta, or recebedor.cpfCnpj when no account coordinates are sent.
- 404 PIX-0119 - recebedor.ispb is neither this participant's own ISPB nor an ACTIVE indirect participant registered in this tenant. It covers both a receiver with no registration at all and one whose registration is not ACTIVE (suspended, closed, or a legacy row that never finished being set up); the two are deliberately not distinguished on the wire, because neither is something the sender can act on differently. It presupposes the indirect-participants feature is ON — with it off nothing consults the registry and this code cannot be answered at all.
- 409 PIX-0116 - recebedor.cpfCnpj names more than one account here, so the destination is undeterminable. Address the credit to specific account coordinates.
- 409 PIX-0117 - the account addressed by recebedor.nrAgencia/recebedor.nrConta belongs to a different holder than recebedor.cpfCnpj names.
- 409 PIX-0118 - the addressed account exists here but is not set up to receive credits.
- 409 PIX-0029 - this end-to-end id was already registered here for a DIFFERENT credit: another amount, another receiving account or another organization/ledger. Nothing was posted for this delivery; the original registration stays unchanged, and its settlement may still be in progress.
- 500 PIX-0120 - a provisioning fault at this participant, not a problem with the request. The credit is safe to redeliver once it is corrected.
- 500 PIX-4011 - whether the credit landed is not settled yet, typically because an earlier delivery of this end-to-end id is still being credited. Nothing more was posted; redeliver, and the redelivery that finds the credit settled gets its acknowledgement.
- 500 with a dependency code - a service this participant reads through to register the credit did not answer. Section 9.3.2 lists no 503 or 504, so an outage the rest of this API answers 503/504 is answered 500 here, keeping the code and a detail that names the dependency: PIX-3007 (Access Manager timed out) and PIX-3008 (Access Manager unavailable), which authenticate the customer lookup; PIX-2020, PIX-2021 and PIX-2022 (CRM unreachable, timed out, unavailable); PIX-4000, PIX-4001, PIX-4002 and PIX-4010 (Midaz unreachable, timed out, unavailable, balance unreadable). Nothing was posted; redeliver once the dependency recovers.

WHICH OF THOSE AN INDIRECT CREDIT CAN ACTUALLY HIT is a shorter list, because its destination comes from the registry rather than from a customer lookup — and the whole list below presupposes the indirect-participants feature is ON, since with it off there is no indirect path to be on. PIX-0119 is the one: it is what a receiver ISPB with no ACTIVE registration answers, and it exists only on this path. PIX-0115, PIX-0116, PIX-0117, PIX-0118 and PIX-0120 are all decided by the own-customer lookup and are unreachable once recebedor.ispb resolves to an ACTIVE registration — so seeing any of them means the credit was NOT treated as an indirect one. PIX-0029 behaves identically on both paths. A registry read that fails is a 500 like any other dependency failure: nothing is registered, and the credit is safe to redeliver.

Besides the redelivery of a settled credit above, one outcome acknowledges 200 WITHOUT any credit ever being posted: a pagador.ispb identifying Bacen (99999), which this participant nulls by design. Its response carries the acknowledgement echo (idReqSistemaCliente, idReqJdPi, endToEndIdOriginal, endToEndIdDevolucao) and no idCreditoSgct.

Malformed payloads are rejected with 400 at the edge, before any resolution runs: 400 PIX-0061 for a body that fails schema validation, and 400 PIX-0061 for a missing endToEndId, a valor that is not a positive finite amount, or a malformed CPF/CNPJ or ISPB on either participant block.



# Receive a PIX Automatico authorization cancellation registration event
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/receive-a-pix-automatico-authorization-cancellation-registration-event

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/events/authorization-cancellation-registered
Receives the JDPI notifica-cancelamento-autorizacao-callback push event (section 6, body section 5.2.5): an async re-delivery of the cancellation registration. It reuses the inbound 5.2.5 register use case (Aceito cancels + soft-deletes; Rejeitado is ack-only). Idempotent: a re-delivery on an already-cancelled row is a no-op. No response body.



# Receive a PIX Automatico authorization cancellation status event
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/receive-a-pix-automatico-authorization-cancellation-status-event

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/events/authorization-cancellation-status
Receives the JDPI situacao-cancelamento-autorizacao-callback push event (section 6, body section 4.3.6): the plugin is the server. The pushed stCancelamento Aceito/Rejeitado outcome is projected onto the local authorization. Idempotent: a duplicate re-delivery is a clean 200 no-op. No response body.



# Receive a PIX Automatico authorization status event
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/receive-a-pix-automatico-authorization-status-event

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/events/authorization-status
Receives the JDPI situacao-autorizacao-callback push event (section 6, body section 4.3.4): the plugin is the server. The pushed stJdPiProc/stJdPi situation is projected onto the local authorization keyed on idRecorrencia. Idempotent: a duplicate re-delivery is a clean 200 no-op. No response body.



# Receive a PIX Automatico payer-side authorization registration event
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/receive-a-pix-automatico-payer-side-authorization-registration-event

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/events/authorization-payer-registered
Receives the JDPI notifica-autorizacao-pagador-callback push event (section 6, body section 5.2.3): an async re-delivery of the payer-side solicitation registration. It reuses the inbound 5.2.3 register use case (payer-side genesis). Idempotent: a re-delivered solicitation resolves to a 409 conflict, never a 500. No response body.



# Receive a PIX Automatico recipient-side authorization registration event
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/receive-a-pix-automatico-recipient-side-authorization-registration-event

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/events/authorization-recipient-registered
Receives the JDPI notifica-autorizacao-recebedor-callback push event (section 6, body section 5.2.4): an async re-delivery of the recipient-side authorization registration. It reuses the inbound 5.2.4 register use case (load + transition to Accepted/Rejected). Idempotent: a re-delivery converging on the same status is a no-op. No response body.



# Receive a PIX Automatico schedule cancellation registration event
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/receive-a-pix-automatico-schedule-cancellation-registration-event

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/events/schedule-cancellation-registered
Receives the JDPI notifica-cancelamento-agendamento-callback push event (section 6, body section 5.3.4): an async re-delivery of the schedule cancellation registration. It reuses the inbound 5.3.4 register use case (Aceito cancels + soft-deletes; Rejeitado is ack-only). Idempotent: a re-delivery on an already-cancelled row is a no-op. No response body.



# Receive a PIX Automatico schedule cancellation status event
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/receive-a-pix-automatico-schedule-cancellation-status-event

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/events/schedule-cancellation-status
Receives the JDPI situacao-cancelamento-agendamento-callback push event (section 6, body section 4.4.4): the plugin is the server. The pushed stCancelamento Aceito/Rejeitado outcome is projected onto the local schedule. Idempotent: a duplicate re-delivery is a clean 200 no-op. No response body.



# Receive a PIX Automatico schedule registration event
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/receive-a-pix-automatico-schedule-registration-event

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/events/schedule-registered
Receives the JDPI notifica-agendamento-pagador-callback push event (section 6, body section 5.3.3): an async re-delivery of the payer-side schedule registration. It reuses the inbound 5.3.3 register use case (inbound genesis). Idempotent: a re-delivered instruction resolves to a 409 conflict, never a 500. No response body.



# Receive a PIX Automatico schedule status event
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/receive-a-pix-automatico-schedule-status-event

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/events/schedule-status
Receives the JDPI situacao-agendamento-callback push event (section 6, body section 4.4.2): the plugin is the server. The pushed stJdPiProc/stJdPi situation is projected onto the local schedule keyed on endToEndId. Idempotent: a duplicate re-delivery is a clean 200 no-op. No response body.



# Receive an asynchronous account validation
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/receive-an-asynchronous-account-validation

/en/openapi/v3-current/pix.yaml post /v1/webhooks/validates/async
Receives a section 9.3.4 asynchronous validation: up to 500 credits, each a payment order JD holds on the CSM channel until this participant says whether the receiving account may take it. This operation only stores the call and answers 202 with {idValidacaoSgct, dtHrAvisoSgct}; each credit is then validated with the section 9.3.1 checks and its result registered on JD through section 8.4.12. A credit whose idConciliacaoRecebedor another order to the same receiving account holds with a Válido is answered DUPL. A Válido JD has not answered holds until it expires unsent, 45 minutes after its receipt. A Válido JD accepted holds until its credit lands, up to 24 hours.

Chave-Idempotencia is the call's identity: a redelivery under the same key and the same body answers the first 202 again without a second validation, and the same key with a different body is 409. A body the edge rejects is 400; a call that could not be stored is 500 and is safe to redeliver.



# Register a MED fraud marker
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/register-a-med-fraud-marker

/en/openapi/v3-current/pix.yaml post /v1/med/fraud-markers
Opens a fraud marker as the creator PSP (JDPI marcacao-fraude/incluir, contract 2.15). The creator ISPB is derived from configuration. tpFraude is validated against the create domain {0..3} before any JDPI call.



# Register an inbound PIX Automatico payment instruction
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/register-an-inbound-pix-automatico-payment-instruction

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/schedules/inbound/register
Registers an inbound scheduled payment instruction delivered by JDPI to the PSP Pagador (section 5.3.3, the plugin is the server). This is inbound genesis: it creates the payer-side schedule row (Requested on an accepted registration, Rejected on a rejected one) and returns the local SGCT id. A re-delivered instruction resolves to a 409 conflict.



# Register an inbound PIX Automatico schedule cancellation
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/register-an-inbound-pix-automatico-schedule-cancellation

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/schedules/inbound/cancellation/register
Registers a schedule cancellation outcome delivered by JDPI (section 5.3.4, the plugin is the server). An accepted cancellation (stCancelamento=0) transitions the schedule to Cancelled and soft-deletes the row; a rejected cancellation (stCancelamento=1) is acknowledged with no state change. Returns the local SGCT id.



# Register an indirect participant
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/register-an-indirect-participant

/en/openapi/v3-current/pix.yaml post /v1/indirects
Registers an indirect participant in this tenant's registry and makes it usable in one step. Call it once per indirect you onboard, before any inbound credit or outbound order names it.

REGISTRATION IS ATOMIC: a 201 means the participant is READY, and a failure means nothing was created. Before writing anything the service checks the ispb is not already held by a non-CLOSED indirect, optionally checks (on a tenant with JD directory validation enabled) that it exists as an SPI participant at JD, and creates the participant's `@pi_{ispb}` settlement account in Midaz — THE PLUGIN creates that account, a client never does. Only then is the row written, and it is written ACTIVE, so there is no intermediate state to poll and no `provisioning` field to read on the response. If any of those steps fails you get a coded error naming the step, NO registry row exists, and the ispb is still free: fix the cause and POST again. There is no retry endpoint, because there is nothing half-written to resume.

WHICH DIRECT PARTICIPANT THE INDIRECT RIDES IS DECIDED HERE AND NEVER AGAIN. This deployment may act as several direct SPI participants, and an indirect reaches SPI through exactly ONE of them: `directIspb` names it, and the registry records that participant together with the Midaz organization and default ledger its `@pi` settlement account belongs to. Omit `directIspb` and the deployment's default participant is used, which is where every indirect lived before this deployment could act as several. An ISPB this deployment does not act as is 422 PIX-0128. The chosen participant, organization and ledger come back on the response as `directIspb`, `organizationId` and `ledgerId`, and PATCH cannot change them — an account exists in exactly one ledger, so re-pointing would orphan the position rather than move it.

THIS WRITE IS PERMANENT once it succeeds. There is no DELETE on /v1/indirects: the registry's only exit is PATCH with action `close`, CLOSED is terminal (nothing leaves it), and even a close keeps the row and its `@pi` account — the account is blocked, never deleted. An indirect registered by mistake against a live tenant stays in that tenant's registry, and its ispb is held against the open-uniqueness constraint until it is closed. Verify name, ispb and the delivery endpoint before calling.

Refusals, all of which leave the registry untouched: 409 PIX-0093 when a non-CLOSED indirect already holds this ispb — a CLOSED one may be re-registered and reuses its historical `@pi` account; 422 PIX-0128 when directIspb names a direct participant this deployment does not act as; 422 PIX-0098 for a missing or over-120-character name, an ispb that is not exactly 8 digits, a delivery.endpointUrl that is not a valid https URL, a missing delivery.secret, an unknown messagingMode, an absent ispb (the `@pi_{ispb}` alias derives from it, so the MVP requires one), or — on a tenant with JD directory validation enabled — an ispb JD does not know as an SPI participant; 502 PIX-0099 when a step failed on a retryable fault, naming the step (validateISPB or createPIAccount) so you know which dependency to check before re-POSTing; 503 PIX-4002 when the ledger could not be reached to create the settlement account; 409 PIX-0107 when no delivery-secret encryption key is provisioned for this tenant — an operator has to provision it, so re-POSTing unchanged fails identically, and the response body names the knob; 503 PIX-0123 when that key could not be READ from its key source, which is a fault on our side rather than a missing value and is safe to repeat shortly.

Re-POSTing after a failure is safe: the settlement account is created by alias, so an attempt that got that far and then failed leaves an account the next attempt adopts rather than duplicating.



# Request a PIX Automatico schedule send
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/request-a-pix-automatico-schedule-send

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/schedules
Requests the send of a recurring-payment instruction as the recipient's PSP (JDPI 4.4.1). Persists the schedule in the Requested state and returns the JDPI acknowledgement. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. The recipient is resolved by the document, or by branch and account: 422 PIX-0143 when they match more than one account, and 422 PIX-0144 when the branch and account belong to a different holder than the document.



# Reserve an inbound PIX Automatico debit hold
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/reserve-an-inbound-pix-automatico-debit-hold

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/settlements/inbound/block
Reserves a debit HOLD on the payer's transactional account for a scheduled PIX Automatico payment (section 5.4.1, the plugin is the SGCT server). JDPI calls this when it begins processing the scheduled payment. The reserve is parameterizable and disabled by default. On insufficient funds the result is returned inline (200) as a resultado=0 outcome with motivo SGCTPIX001, never an HTTP error. A schedule that is still in flight — registered but not yet confirmed by the section 6 situacao stream — is NOT refused: it answers 422 with code PIX-0022 and MUST be re-delivered, and the re-delivery is accepted once the confirmation lands.



# Reverse an inbound PIX Automatico settlement debit
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/reverse-an-inbound-pix-automatico-settlement-debit

/en/openapi/v3-current/pix.yaml delete /v1/pix-automatico/settlements/inbound/debit/{endToEndId}
Reverses the prior settlement debit (or releases a still-pending hold) on a negative SPI return (section 5.4.3, the plugin is the SGCT server). The reverse is parameterizable and disabled by default. Returns the SGCT reversal-operation id (idOperacaoSgct).



# Start a MED value recovery return stage
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/start-a-med-value-recovery-return-stage

/en/openapi/v3-current/pix.yaml post /v1/med/recoveries/{idRecValores}/return
Starts the refund stage of a value recovery (JDPI recuperacao-valores/{id}/devolver, contract 2.22). It MOVES NO MONEY — it transitions stRecValores->4 and makes DICT emit refund requests. An unknown id returns a coded 404. Optional ispb names the direct participant the request acts for: named, the record has to be one that participant is a party to, or the answer is 404 PIX-0147 before anything is read from JDPI or changed; an ISPB this deployment does not act as is 422 PIX-0128 before any record is read; a token confined to one participant has to name it. Optional indirectId names the registered indirect participant the request acts for: named, the value recovery has to be over a root payment this deployment recorded for that indirect — the rule GET /v1/med/recoveries/awaiting-return?indirectId= lists by — or the answer is 404 PIX-0147 before anything is read from JDPI or changed; a token confined to one indirect has to name it; a malformed indirectId is 400 PIX-0061.



# Tell the JD Courier which Pix Automático traffic is this engine's
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/tell-the-jd-courier-which-pix-automatico-traffic-is-this-engine-s

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/courier-ownership
Operator backfill for the Pix cutover, idempotent and safe to repeat. Claims on the Courier every recurrence this engine authorized as the payer's PSP (retrying those another engine held), then declares every debit block not yet reversed (a debited one for a day, as its reversal can still follow) and every schedule that can still be cancelled. Last, it claims the charger side of every live recurrence this engine opened as the recipient's PSP, retrying those another engine held. Run it again after the vendor is repointed at the Courier, so legs opened in between are declared too. heldElsewhere lists the keys the Courier gives to another engine; an operator resolves each one. 503 PIX-0130: the Courier is not configured for this tenant or could not be reached; run it again.



# Update an indirect participant
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/update-an-indirect-participant

/en/openapi/v3-current/pix.yaml patch /v1/indirects/{indirectId}
Applies mutable-field changes and/or ONE lifecycle action to an indirect. Absent (null) body fields are left untouched, so a PATCH carrying only action moves the lifecycle and changes nothing else; a PATCH carrying neither a field nor an action is a no-op that returns the current row without writing anything, not an error.

The lifecycle actions are suspend, reactivate and close, and each one writes the LEDGER as well as the registry. suspend disables both sending and receiving on the indirect's `@pi` account, so the ledger refuses that participant's money even if another replica's resolution cache is still stale; reactivate re-enables both. close is IRREVERSIBLE — CLOSED is terminal, nothing leaves it, and afterwards every field mutation on the row is refused too. close never deletes: the `@pi` account is permanently blocked but kept, so a later re-registration of the same ISPB reuses it. When a lifecycle action and field changes arrive together, the action is what the audit trail records.

Optional directIspb names the direct participant the indirect is changed as, checked before anything is changed; a token confined to one direct participant has to name it. Refusals: 422 PIX-0128 when directIspb names a direct participant this deployment does not act as, before the indirect is read — nothing is changed; 404 PIX-0147 when directIspb names a direct participant the indirect is not mounted on — nothing is changed; 409 PIX-0094 when the action is illegal from the current status (any action on a legacy PENDING_PROVISIONING row or on a CLOSED one, reactivate on anything but SUSPENDED) — re-issuing an action the row already reached is illegal too, not an idempotent success; 409 PIX-0096 when close is attempted while the `@pi` account still holds an available or on-hold balance, refused so the funds cannot be stranded (settle it to zero first); 409 PIX-0007 when another writer changed the row concurrently — reload and retry; 404 PIX-0095 for an unknown id; 422 PIX-0098 for an unknown action, a name over 120 characters, a delivery.endpointUrl that is not a valid https URL, or a qrCertificate.publicBaseUrl that is absent while ownCertificate is true, carries a scheme, is not a bare host with an optional path, or does not name a publicly resolvable host; 422 PIX-0111 when the body carries qrCertificate and this tenant's indirect-participants feature is not enabled — the WHOLE patch is refused, including any name or delivery change riding alongside; 503 PIX-4002 when the ledger could not be reached to check the balance or move the account flags.



# Validate a receiving account synchronously
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/validate-a-receiving-account-synchronously

/en/openapi/v3-current/pix.yaml post /v1/webhooks/validates
Pre-checks a receiving account before a payment is sent, and answers the section 9.3.1 envelope {resultado, motivo, motivoComplemento, dtHrValidacao}. JDPI calls it BEFORE settlement, on behalf of the payer's PSP, so that a payment that would fail is not sent.

EVERY VALIDATION OUTCOME IS HTTP 200, including a rejection: resultado carries the verdict and motivo the reason. Do not branch on the HTTP status here — a 200 with resultado inválido is a refusal, and treating it as success is the mistake this shape invites. It is read-only: nothing is recorded, no money moves, and calling it twice changes nothing.

The checks run in a fixed order and the FIRST one that decides, decides:

1. When the payment carries a conciliation id, a QR charge already paid within the last 24 hours is refused as a duplicate (motivo BE17), and so is a payer whose document differs from the one the charge was issued for — but only when that charge was created demanding the payer be validated.
2. A pagador.ispb identifying Bacen (99999) passes unconditionally.
3. The account to check is the one on WHICHEVER participant block carries THIS participant's own ISPB — pagador first, then recebedor. If neither block does, the answer is motivo AC03 (account not found).
4. That account is then looked up by its branch and account number and its holder document compared: no such account is AC03; a lookup that could NOT BE COMPLETED is a 500, never a verdict — an unreadable record establishes nothing about the account, and AC03 would tell the payer's PSP that a live account is absent; a document that does not match the account's holder is motivo BE01 (inconsistent data).
5. The RECEBEDOR's account, by branch and number as the credit resolves it, is then read in the ledger (even when step 3 chose the pagador block): closed is motivo AC07, blocked is motivo AC06, and an account the ledger does not hold is AC03; a ledger that could NOT BE READ is a 500, never a verdict. Coordinates naming no account or several, and every other account status, leave the account valid.
6. A devolução (creditoDevolucao) that account would accept is refused with motivo AM09 when its valor exceeds what is left to return of the payment endToEndIdOriginal names: that payment's amount less every devolução already settled against it, booked or still awaiting its payment's settlement here. A payment this participant never made is not measured, and a balance that could NOT BE READ is a 500, never a verdict.

⚠️ THIS CHECK READS ONLY THIS PARTICIPANT'S OWN CUSTOMER RECORDS. Step 3 is the reason: it selects a block by this participant's own ISPB, and an INDIRECT participant served by this participant (registered with POST /v1/indirects) has an ISPB of its own, which never equals it. A payment addressed to an indirect participant therefore matches neither block and is answered AC03 here, even though POST /v1/webhooks/cash-ins would register that same credit against that institution's `@pi_{ispb}` settlement position. Do NOT read an AC03 from this operation as evidence that a credit to an indirect participant would be refused, and do not use this operation to pre-check indirect destinations.

Refusals, as opposed to verdicts, are only transport-level: 400 PIX-0061 when the body fails schema validation at the edge, and 500 when a record this check has to read is unavailable — in which case nothing was validated and the call can be retried.



# Validate an inbound PIX Automatico payment instruction
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/validate-an-inbound-pix-automatico-payment-instruction

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/schedules/inbound/validate
Validates an inbound scheduled payment instruction (pain.013) pushed by JDPI (section 5.3.1, the plugin is the server). The SGCT validates the charge data against the previously-confirmed authorization; the result is returned inline (200) as a Valido=1/Invalido=0 outcome, never an HTTP error.



# Validate an inbound PIX Automatico schedule cancellation
Source: https://docs.lerian.studio/en/reference/interfaces/pix-jd/validate-an-inbound-pix-automatico-schedule-cancellation

/en/openapi/v3-current/pix.yaml post /v1/pix-automatico/schedules/inbound/cancellation/validate
Validates an inbound schedule cancellation request (camt.055) pushed by JDPI (section 5.3.2, the plugin is the server). The cancellation is valid iff a live schedule exists and the FSM permits a transition to Cancelled from its current status; the result is returned inline (200).



# Acknowledge a Key Claim
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/acknowledge-a-claim

/en/openapi/v3-current/indirect-pix.yaml post /v1/dict/claims/{claim_id}/acknowledge
Use this endpoint to acknowledge receipt of a claim by the donor participant.



# Acknowledge an Infraction Report
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/acknowledge-an-infraction-report

/en/openapi/v3-current/indirect-pix.yaml post /v1/dict/infraction-reports/{infraction_id}/acknowledge
Use this endpoint to acknowledge receipt of an infraction report notification. This endpoint is used by the counterparty participant to acknowledge that they have received and are aware of the infraction report filed against a transaction. The report must be in OPEN status to be acknowledged. This operation is idempotent.



# Cancel a Key Claim
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/cancel-a-claim

/en/openapi/v3-current/indirect-pix.yaml post /v1/dict/claims/{claim_id}/cancel
Use this endpoint to cancel a portability or ownership claim.



# Cancel a Fraud Marker
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/cancel-a-fraud-marker

/en/openapi/v3-current/indirect-pix.yaml post /v1/dict/fraud-markers/{fraud_marker_id}/cancel
Use this endpoint to cancel a previously registered fraud marker.

**Notes:**
- Cancellation is only allowed for markers in REGISTERED status.
- Only the participant who created the fraud marker can cancel it.
- For fraud markers created from infraction report closures, the counterparty participant who closed the infraction can cancel the marker.
- Cancelled markers cannot be reactivated.



# Cancel a Funds Recovery Request
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/cancel-a-funds-recovery-request

/en/openapi/v3-current/indirect-pix.yaml post /v1/dict/funds-recoveries/{funds_recovery_id}/cancel
Use this endpoint to cancel a funds recovery request. Cancellation is allowed before refund has been initiated (CREATED, TRACKED, AWAITING_ANALYSIS, or ANALYSED status).

**Notes:**
- Cancelled requests cannot be reopened or modified
- Cancellation is not allowed for requests in REFUNDING, COMPLETED, or CANCELLED status



# Cancel a Pix Automático Authorization
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/cancel-a-pix-automatico-authorization

/en/openapi/v3-current/indirect-pix.yaml post /v1/recurrences/payer/authorizations/{id}/cancel
Cancel an active authorization. `reasonKind=PAYER` cancels the caller's own mandate; `reasonKind=FRAUD` records the caller as the operator and requires `reasonText`. `X-Idempotency` is optional but recommended; replays within the window are de-duplicated.



# Cancel a Pix Schedule
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/cancel-a-pix-schedule

/en/openapi/v3-current/indirect-pix.yaml delete /v1/schedules/{schedule_id}
Cancel a schedule that is still in SCHEDULED status. Compare-and-swap: a PROCESSING row returns 409 PIX-0809, a terminal row returns 409 PIX-0814, a cross-account request returns 404 PIX-0800.



# Cancel a Refund Request
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/cancel-a-refund-request

/en/openapi/v3-current/indirect-pix.yaml post /v1/dict/refund-requests/{refund_id}/cancel
Use this endpoint to cancel a refund request before it is processed.

**Notes:**
- Cancellation is only allowed for requests in OPEN status.
- Cancelled requests cannot be reopened or modified.
- This operation notifies BACEN and the contested participant.



# Cancel an Infraction Report
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/cancel-an-infraction-report

/en/openapi/v3-current/indirect-pix.yaml post /v1/dict/infraction-reports/{infraction_id}/cancel
Use this endpoint to cancel an infraction report that is no longer valid. This endpoint is used to cancel infractions reported by your own PSP.

**Notes:**
- Cancellation is only allowed for reports in OPEN or ACKNOWLEDGED status
- Cancelled reports cannot be reopened or modified
- Cancellation reason should be provided for audit purposes



# Cancel a stuck or long-running TemposTransacoes job
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/cancel-transaction-times-job

/en/openapi/v3-current/indirect-pix.yaml post /v1/statistics/tempos-transacoes/jobs/{referenceMonth}/cancel
Use this endpoint to mark the reference month's active (PENDING/RUNNING) job as FAILED, releasing the month for a new attempt. An already-terminal job (COMPLETED/FAILED) is rejected with 422, not returned unchanged. Bookkeeping only — background processing is not guaranteed to stop, and a computation that finishes afterwards overwrites the cancellation with the real result.



# Close a Refund Request
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/close-a-refund-request

/en/openapi/v3-current/indirect-pix.yaml post /v1/dict/refund-requests/{refund_id}/close
Use this endpoint to provide the closure decision and outcome for a refund request.

**Notes:**
- This operation is typically triggered by BACEN's analysis completion.
- Closing a request sets its status to CLOSED and records the analysis result.
- For accepted refunds, a refund transaction ID is recorded.
- Once closed, the request cannot be modified.



# Close an Infraction Report
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/close-an-infraction-report

/en/openapi/v3-current/indirect-pix.yaml post /v1/dict/infraction-reports/{infraction_id}/close
**DEPRECATED:** This endpoint is deprecated and will be removed in a future release due to MED 2.0 changes. MED 2.0 manages infraction report updates through the Funds Recovery lifecycle.

Use this endpoint to submit the closure analysis for an infraction report received. This endpoint must be used to respond to infractions reported to your PSP, meaning when the account was the receiver of the transaction reported as fraud, within 7 days with the analysis result.

**Notes:**
- Closing a report sets its status to CLOSED and records the analysis result
- Once closed, the report cannot be modified
- For `REFUND_REQUEST` infractions, the report must be closed by the payee's PSP
- For `REFUND_CANCELLED` infractions, the report must be closed by the payer's PSP



# Complete a Key Claim
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/complete-a-claim

/en/openapi/v3-current/indirect-pix.yaml post /v1/dict/claims/{claim_id}/complete
Use this endpoint to complete a claim by the claimer. As a result, the link between the key and the claiming party is created.



# Confirm a Key Claim
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/confirm-a-claim

/en/openapi/v3-current/indirect-pix.yaml post /v1/dict/claims/{claim_id}/confirm
Use this endpoint to confirm a claim operation. As a consequence, the link between the key and the donor participant is removed.



# Confirm a scanned Pix Automático recurrence
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/confirm-a-scanned-pix-automatico-recurrence

/en/openapi/v3-current/indirect-pix.yaml post /v1/recurrences/payer/qr/confirm
Approve or reject a recurrence scanned from a QR Code (journeys J2 and J4 step 2). `X-Idempotency` is optional but recommended; replays within the window are de-duplicated.



# Create a Key Claim
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/create-a-claim

/en/openapi/v3-current/indirect-pix.yaml post /v1/dict/claims
Use this endpoint to create a new key claim for portability or ownership.



# Create a Dynamic Charge with Due Date
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/create-a-dynamic-charge-with-due-date

/en/openapi/v3-current/indirect-pix.yaml post /v1/collections/duedate
Use this endpoint to create a due date Pix collection (cobrança com vencimento) with complex payment rules including fines, interest, discounts, and rebates.

**Notes:**
- Similar to traditional boletos with Pix payment capability
- Due date defines when payment is expected
- Supports complex amount calculations with fines, interest, discounts, and rebates
- Requires complete debtor and receiver information
- Transaction ID (txId) must be unique per receiver
- Collection remains valid for a configurable period after the due date



# Create a Fraud Marker
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/create-a-fraud-marker

/en/openapi/v3-current/indirect-pix.yaml post /v1/dict/fraud-markers
Use this endpoint to register a fraud marker for a tax ID or Pix key.

**Notes:**
- Fraud markers are used to flag documents (CPF/CNPJ) or Pix keys associated with fraudulent activity.
- The taxIdNumber field is required and represents the person/entity being marked.
- The key field is optional and can be used to associate the marker with a specific Pix key.
- Fraud markers can also be automatically created when closing an infraction report with AGREED result.



# Create a Funds Recovery Request
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/create-a-funds-recovery-request

/en/openapi/v3-current/indirect-pix.yaml post /v1/dict/funds-recoveries
Use this endpoint to create a new funds recovery request for a Pix transaction suspected of fraud.

**Notes:**
- The rootTransactionId must be a valid 32-character Pix End-to-End ID
- situationType indicates the type of fraud situation (SCAM, ACCOUNT_TAKEOVER, COERCION, FRAUDULENT_ACCESS, OTHER, UNKNOWN)
- Contact information (email and phone) is required for communication during the recovery process



# Create a Pix Schedule
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/create-a-pix-schedule

/en/openapi/v3-current/indirect-pix.yaml post /v1/schedules
Create a single-shot scheduled Pix instruction. The schedule is persisted with status SCHEDULED; the schedule worker dispatches the cashout at the scheduled fire time. The destination snapshot comes from the payment initiation that initiationId references.



# Create a Refund Request
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/create-a-refund-request

/en/openapi/v3-current/indirect-pix.yaml post /v1/dict/refund-requests
Use this endpoint to open a refund request for a Pix transaction.

**Notes:**
- Refund requests must be associated with a valid Pix transaction.
- Requests can optionally be linked to an infraction report.
- The contested participant must respond within the specified timeframe.



# Create a Static QR Code
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/create-a-static-qr-code

/en/openapi/v3-current/indirect-pix.yaml post /v1/brcode/static
Use this endpoint to create a static Pix BR Code that can be reused for multiple payments.

**Notes:**
- Static QR Codes are reusable and can be paid multiple times
- Amount is optional - if not provided, the payer will enter the amount
- The receiver key must be owned by the account holder making the request
- The QR Code payload (EMV) is generated following the EMV QCO specification



# Create an Immediate Charge
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/create-an-immediate-charge

/en/openapi/v3-current/indirect-pix.yaml post /v1/collections/immediate
Use this endpoint to create an immediate Pix collection (cobrança imediata) with a dynamic QR Code that is valid for a defined period.

**Notes:**
- Each immediate collection is unique and can only be paid once
- Amount and expiration time are required
- Transaction ID (txId) must be unique per receiver
- Status changes to COMPLETED when payment is received



# Create an Infraction Report
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/create-an-infraction-report

/en/openapi/v3-current/indirect-pix.yaml post /v1/dict/infraction-reports
**DEPRECATED:** This endpoint is deprecated and will be removed in a future release due to MED 2.0 changes. The MED 2.0 specification introduces a new flow where infraction reports are replaced by a simplified dispute resolution mechanism handled through the Special Return flow.

Use this endpoint to report infractions associated to Pix transfers. This endpoint must be used when there is a fraud related to a transaction in scenarios where the client is the payer PSP, meaning the transaction was initiated and sent from an account within your arrangement.

**Notes:**
- Transactions can only be reported within 90 days from the transaction date



# Trigger the asynchronous TemposTransacoes computation
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/create-transaction-times-job

/en/openapi/v3-current/indirect-pix.yaml post /v1/statistics/tempos-transacoes/jobs
Use this endpoint to start the asynchronous computation of the BACEN TemposTransacoes payer-experience percentiles for a closed reference month. Returns immediately with the job in PENDING; poll the job or wait for the completion webhook for the result. Only one active job (PENDING/RUNNING) per reference month is allowed (409 otherwise), and at most two jobs run concurrently service-wide (429 beyond that).



# Decide on a Pix Automático Authorization Request
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/decide-on-a-pix-automatico-authorization-request

/en/openapi/v3-current/indirect-pix.yaml post /v1/recurrences/payer/authorization-requests/{id}/decision
Accept or reject a pending authorization request. Uses the DICT "external first, persist after" pattern. `X-Idempotency` is optional but recommended; replays within the window are de-duplicated.



# Decode a Pix QR Code
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/decode-a-pix-qr-code

/en/openapi/v3-current/indirect-pix.yaml post /v1/qrcodes/decode
Use this endpoint to decode a Pix BR Code payload and extract the payment data it contains. This service supports all Pix QR Code types: static, immediate collections, and due date collections. When the code carries a Pix Automático recurrence location, the response includes a `recurrence` block. When an immediate collection carries Pix Saque or Pix Troco data, the response includes a `withdrawal` block. The response type varies with the QR code type (STATIC, IMMEDIATE, DUE_DATE, or RECURRENCE).



# Delete an Immediate Charge
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/delete-an-immediate-charge

/en/openapi/v3-current/indirect-pix.yaml delete /v1/collections/immediate/{collection_id}
Use this endpoint to delete (cancel) an immediate collection.

**Notes:**
- This operation cancels the collection and changes its status
- Collections with status COMPLETED cannot be deleted
- The deletion reason is required



# Get a Pix Automático Authorization
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/get-a-pix-automatico-authorization

/en/openapi/v3-current/indirect-pix.yaml get /v1/recurrences/payer/authorizations/{id}
Retrieve a single authorization by id. Scoped to the authenticated payer.



# Get a Pix Automático Authorization Request
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/get-a-pix-automatico-authorization-request

/en/openapi/v3-current/indirect-pix.yaml get /v1/recurrences/payer/authorization-requests/{id}
Retrieve a single authorization request by id. Scoped to the authenticated payer.



# Get a Pix Automático Charge
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/get-a-pix-automatico-charge

/en/openapi/v3-current/indirect-pix.yaml get /v1/recurrences/payer/charges/{id}
Retrieve a single charge by id. Scoped to the authenticated payer. The response carries the sanitized attempts array; the internal debit result code is never exposed.



# Get a Pix Schedule
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/get-a-pix-schedule

/en/openapi/v3-current/indirect-pix.yaml get /v1/schedules/{schedule_id}
Retrieve a schedule by its unique identifier. Cross-account lookups return 404 — existence is never leaked across accounts.



# Get a Refund
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/get-a-refund

/en/openapi/v3-current/indirect-pix.yaml get /v1/refunds/{refund_id}
Use this endpoint to retrieve a refund by its unique identifier.



# Get inbound webhook by id
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/get-an-inbound-webhook

/en/openapi/v3-current/indirect-pix.yaml get /v1/webhooks/inbound/{id}
Gets a single inbound webhook by id. Intended for low-frequency operator use.



# Get outbound webhook by id
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/get-an-outbound-webhook

/en/openapi/v3-current/indirect-pix.yaml get /v1/webhooks/outbound/{id}
Gets a single outbound webhook by id. Dead-letter rows are resolved transparently and surfaced with status="DEAD_LETTER" and additional dead-letter fields populated.



# Get the TemposTransacoes job of a reference month
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/get-transaction-times-job

/en/openapi/v3-current/indirect-pix.yaml get /v1/statistics/tempos-transacoes/jobs/{referenceMonth}
Use this endpoint to read the current state of the reference month's latest computation job. When status is COMPLETED, result carries the computed percentiles in the same shape delivered by webhook.



# Indirect Pix error list
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/indirect-pix-error-list

Indirect Pix returns structured error responses, so you can identify what went wrong and how to fix it.

**Error format**

```json JSON theme={null}
{
   "code": "<error_code>",
   "title": "<error_title>",
   "message": "<error_message>"
}
```

**Field definitions**

* **`code`** – A stable, unique identifier for the error. Useful for programmatic handling and support requests.
* **`title`** – A short, human-readable summary of the issue.
* **`message`** – Detailed guidance to help you resolve the error.

## Indirect Pix errors

***

The following errors can occur when interacting with the Indirect Pix endpoints. Each error follows our standard structure.

### Internal Server error

| `code` | `title` | `message` |
| - | - | - |
| PIX-0000 | Internal Server Error | The server encountered an unexpected error. Please try again later. |

### Middleware errors

| `code` | `title` | `message` |
| - | - | - |
| PIX-0001 | Missing Headers in Request | Your request is missing one or more required header params. Please refer to the documentation to ensure all necessary header params are included in your request. |
| PIX-0002 | Invalid Header Value | One or more header values are invalid. Please refer to the documentation to verify the expected format and allowed values for each header. |
| PIX-0003 | Missing Fields in Request | Your request is missing one or more required fields. Please refer to the documentation to ensure all necessary fields are included in your request. |
| PIX-0004 | Invalid Field Values in Request | Your request contains one or more fields with invalid values. Please refer to the documentation to verify that all fields have the correct values. |
| PIX-0005 | Invalid Field Type in Request | Your request contains one or more fields with an invalid data type. Please refer to the documentation to verify that all fields have the correct type. |
| PIX-0006 | Unexpected Fields in Request | The request body contains more fields than expected. Please send only the allowed fields as per the documentation. |
| PIX-0007 | Missing Path Parameters in Request | Your request is missing one or more required path parameters. Please refer to the documentation to ensure all necessary path parameters are included in your request. |
| PIX-0008 | Invalid Path Parameter in Request | One or more path parameters are invalid. Please refer to the documentation to verify the expected format and allowed values for each path parameter. |
| PIX-0009 | Missing Query Params in Request | Your request is missing one or more required query params. Please refer to the documentation to ensure all necessary query params are included in your request. |
| PIX-0010 | Invalid Query Param in Request | One or more query params are invalid. Please refer to the documentation to verify the expected format and allowed values for each query param. |
| PIX-0011 | Invalid Timestamp Format | The timestamp format is invalid. Please refer to the documentation to verify the expected format. |
| PIX-0012 | Invalid Metadata | The metadata is invalid. Please refer to the documentation to verify the expected format. |
| PIX-0013 | Limit Exceeded | The request exceeded the allowed limit. |

### DICT errors

| `code` | `title` | `message` |
| - | - | - |
| PIX-0101 | EVP Key Cannot Be Provided | EVP keys cannot be provided manually, they are automatically generated. |
| PIX-0102 | Invalid Key Format | Invalid format for the specified keyType. |
| PIX-0103 | Pix Key Already Exists | The Pix key is already registered. |
| PIX-0105 | CPF Mismatch | CPF does not match holder document in CRM. |
| PIX-0106 | CNPJ Mismatch | CNPJ does not match holder document in CRM. |
| PIX-0107 | Pix Key Limit Exceeded for Holder | The key limit has been exceeded for the holder. |
| PIX-0108 | Pix Key Limit Exceeded for Type | The key type limit has been exceeded. |
| PIX-0109 | Invalid Opening Date | The opening date in CRM is invalid. Please provide a valid date in the 'yyyy-mm-dd' format. |
| PIX-0110 | Pix Key Belongs to Another Holder | The Pix key is already registered to another holder. Please initiate an ownership claim to acquire this key. |
| PIX-0111 | Pix Key Already Linked to Another Account | The Pix key is already linked to another account of the same holder. Please initiate a portability request to transfer this key. |
| PIX-0112 | Entry Not Found | The entry was not found. |
| PIX-0113 | Claim Not Found | The claim was not found. |
| PIX-0114 | Key In Custody Account | The entry queried is in custody of the participant making the query. |
| PIX-0115 | EVP Key Cannot Be Updated | EVP keys cannot be updated. |
| PIX-0116 | Empty Keys Array | The keys array must not be empty. |
| PIX-0117 | Keys Array Exceeded Limit | The keys array must not exceed 200 items. |
| PIX-0118 | Key Claim Type Not Allowed | Only PHONE keys are allowed for ownership claims. |
| PIX-0119 | Pix Key Already Claimed | You already have a claim in progress for this key. |
| PIX-0120 | Key Does Not Exist | The Pix key does not exist in DICT. |
| PIX-0121 | Pix Key Locked By Claim | The Pix key is currently locked by another claim process. |
| PIX-0122 | EVP Key Cannot Be Claimed | EVP keys cannot be claimed. |
| PIX-0123 | Key Already Belongs to Holder | The Pix key is already linked to the requesting holder. |
| PIX-0124 | Cannot Claim Key | It is not possible to claim this key. |
| PIX-0165 | Entry Inactive | The entry is not in active status. |

### Claim errors (confirm)

| `code` | `title` | `message` |
| - | - | - |
| PIX-0125 | Waiting Resolution Status | The claim must be in WAITING\_RESOLUTION status to execute the action. |
| PIX-0126 | Must Be Donor Participant | The claim must be from the donor participant to confirm. |
| PIX-0127 | Portability Cannot Be Confirmed | Portability claims cannot be confirmed with DEFAULT\_OPERATION reason. |
| PIX-0128 | Ownership Cannot Be Confirmed | Ownership claims cannot be confirmed with DEFAULT\_OPERATION reason before the resolution period has ended. |

### Claim errors (cancel)

| `code` | `title` | `message` |
| - | - | - |
| PIX-0134 | Claim Cannot Be Cancelled | The claim cannot be cancelled in current status. |
| PIX-0135 | Donor Cannot Cancel Open Claim | The donor participant cannot cancel a claim in OPEN status. |
| PIX-0136 | Invalid Reason for Claimer | The claimer cannot cancel with the provided reason in this status. |
| PIX-0137 | Invalid Reason for Donor | The donor cannot cancel with the provided reason in this status. |
| PIX-0141 | Donor Cannot Cancel Confirmed Portability | The donor cannot cancel a confirmed portability claim. |
| PIX-0142 | Resolution Period Not Ended | The resolution period has not ended yet for DEFAULT\_OPERATION cancellation. |
| PIX-0143 | Ownership Cancel Period Not Ended | Ownership claims with DEFAULT\_OPERATION can only be cancelled after CompletionPeriodEnd + 16 days. |
| PIX-0144 | Donor Cancel Period Expired | The donor can only cancel with FRAUD while CompletionPeriodEnd has not passed. |
| PIX-0145 | Unknown Actor | The participant is neither the claimer nor the donor. |

### Claim errors (complete)

| `code` | `title` | `message` |
| - | - | - |
| PIX-0146 | Claim Not Confirmed | The claim must be in CONFIRMED status. |
| PIX-0147 | Must Be Claimer Participant | Only the claimer participant can complete a claim. |
| PIX-0148 | Ownership Completion Period Not Ended | Ownership claims can only be completed after the completion period has ended. |
| PIX-0149 | Claim Not Acknowledgeable | The claim does not meet acknowledgement preconditions (must be OPEN status and caller must be the donor participant). |
| PIX-0160 | Claim Already Completed | The claim has already been completed. |
| PIX-0161 | Claim Is Cancelled | The claim has been cancelled and cannot be completed. |
| PIX-0162 | Claim Cannot Be Completed | The claim cannot be completed in its current status. |
| PIX-0163 | Completion Period Not Set | The completion period is not set for this claim. |
| PIX-0164 | Completion Period Expired | The completion period has expired for this claim. |

### VSync / CID errors

| `code` | `title` | `message` |
| - | - | - |
| PIX-0150 | CID File Not Found | The specified CID file was not found or is not ready for download. |
| PIX-0151 | Invalid CID Format | The CID must be a 64-character lowercase hexadecimal string. |
| PIX-0152 | CID Not Found | The specified CID was not found in DICT. |

### MED errors (infraction reports)

| `code` | `title` | `message` |
| - | - | - |
| PIX-0200 | Infraction Report Not Found | The infraction report was not found. |
| PIX-0201 | Report Details Too Long | The report details exceed the maximum allowed length of 2000 characters. |
| PIX-0202 | Invalid Email Format | The email format is invalid. |
| PIX-0203 | Invalid Phone Format | The phone format is invalid. |
| PIX-0204 | Duplicate Infraction Report | An infraction report already exists for this transaction. |
| PIX-0205 | Invalid Transaction ID Format | The transaction ID format must match a E2E ID format. |
| PIX-0206 | Infraction Report Cannot Be Cancelled | The infraction report cannot be cancelled in current status. |
| PIX-0207 | Infraction Report Cannot Be Closed | The infraction report cannot be closed in current status. |
| PIX-0208 | Infraction Fraud Type Required | The fraud type is required when analysis result is AGREED. |
| PIX-0209 | Infraction Analysis Details Required | The analysis details are required when fraud type is OTHER. |
| PIX-0210 | Infraction Analysis Details Too Long | The analysis details exceed the maximum allowed length of 2000 characters. |
| PIX-0211 | Transaction Not Found | The specified transaction was not found. |
| PIX-0212 | Transaction Too Old | The transaction occurred more than 80 days ago and cannot be reported. |
| PIX-0213 | Unauthorized to Open Refund Request | A refund request infraction report can only be opened by the payer's PSP. |
| PIX-0214 | Unauthorized to Open Cancellation Report | A cancellation of refund infraction report can only be opened by the payee's PSP. |
| PIX-0215 | Invalid Transaction Type | The transaction is not a refund transaction. Cancellation of refund infractions can only be used for refund transactions (pacs.004). |
| PIX-0216 | Unauthorized to Close Refund Request | A refund request infraction report must be closed by the payee's PSP. |
| PIX-0217 | Unauthorized to Close Cancellation Report | A cancellation of refund infraction report must be closed by the payer's PSP. |
| PIX-0218 | Cancellation Reason Too Long | The cancellation reason exceeds the maximum allowed length of 500 characters. |
| PIX-0219 | Invalid ID Format | The ID must be a valid UUID format. |
| PIX-0220 | Invalid Date Range Order | The modified\_before timestamp must be after modified\_after timestamp. |
| PIX-0221 | Refund Transaction Too Old | The refund transaction occurred more than 30 days ago and cannot be reported for cancellation. |
| PIX-0222 | Invalid Situation Type | Refund cancellation infraction reports must use situationType OTHER. |
| PIX-0223 | Infraction Report Cannot Be Acknowledged | The infraction report cannot be acknowledged in current status. |

### MED errors (refund requests)

| `code` | `title` | `message` |
| - | - | - |
| PIX-0230 | Invalid Refund Amount Format | The refund amount must be in decimal format with exactly 2 decimal places (e.g., 100.50). |
| PIX-0231 | Refund Details Too Long | The refund details exceed the maximum allowed length of 2000 characters. |
| PIX-0232 | Refund Amount Exceeds Transaction | The refund amount cannot exceed the original transaction amount. |
| PIX-0233 | Missing Refund Details | The refundDetails field is required when refundReason is OPERATIONAL\_FLAW. |
| PIX-0234 | Refund Request Not Found | The specified refund request was not found. |
| PIX-0235 | Missing Refund Transaction ID | The refund transaction ID is required when the refund is accepted (TOTALLY\_ACCEPTED or PARTIALLY\_ACCEPTED). |
| PIX-0236 | Invalid Request Status | The request cannot be closed because it is already in CLOSED or CANCELLED status. |
| PIX-0237 | Missing Rejection Reason | The refundRejectionReason is required when analysisResult is REJECTED. |
| PIX-0238 | Missing Analysis Details | The analysisDetails field is required when analysisResult is REJECTED and refundRejectionReason is INVALID\_REQUEST. |
| PIX-0239 | Cannot Cancel Request | The request cannot be cancelled because it is already in CLOSED or CANCELLED status. |
| PIX-0240 | Missing Infraction Report | A refund request with reason FRAUD requires a prior infraction report that has been closed with AGREED result. |
| PIX-0241 | Infraction Report Expired | The infraction report was closed more than 72 hours ago. Refund requests must be created within 72 hours of infraction report closure. |
| PIX-0242 | Duplicate Refund Request | A refund request already exists for this transaction. |
| PIX-0243 | Refund Request Already Closed | The refund request is already closed. |
| PIX-0244 | Refund Request Already Cancelled | The refund request is already cancelled. |
| PIX-0245 | Date Range Exceeds 90 Days | The date range between modifiedAfter and modifiedBefore cannot exceed 90 days. |

### MED errors (fraud markers)

| `code` | `title` | `message` |
| - | - | - |
| PIX-0261 | Invalid Key Format | The key must be between 8 and 32 characters. |
| PIX-0262 | Fraud Marker Not Found | The specified fraud marker was not found. |
| PIX-0263 | Cannot Cancel Marker | The fraud marker cannot be cancelled because it is already in CANCELLED status. |

### MED errors (statistics)

| `code` | `title` | `message` |
| - | - | - |
| PIX-0280 | Invalid Key Value | The key value is invalid or exceeds the maximum length of 77 characters. |

### QR Code errors

| `code` | `title` | `message` |
| - | - | - |
| PIX-0300 | Invalid EMV Format | The EMV payload does not follow the valid EMV QCO format specification. |
| PIX-0301 | Corrupted QR Code | The QR Code data is corrupted and cannot be decoded. |
| PIX-0302 | Unsupported QR Code Version | The QR Code version or format is not supported. |
| PIX-0303 | Invalid Payment Date | The payment date exceeds the valid payment period. |
| PIX-0304 | Invalid Amount | The amount must be greater than zero and follow the 0.00 format with two decimals. |
| PIX-0305 | Invalid City | The city must contain only letters and spaces. |
| PIX-0306 | Invalid TxID Format | The txId format is invalid. |
| PIX-0307 | Receiver Key Required | The receiverKey is required. |
| PIX-0309 | Invalid Category Code Format | The categoryCode must be numeric. |
| PIX-0310 | Invalid Merchant Name | The merchant name is required. |
| PIX-0311 | Receiver Key Not Found | The receiverKey was not found. |
| PIX-0312 | Invalid Receiver Key | The receiverKey is invalid. |
| PIX-0314 | EMV Required | The EMV is required. |
| PIX-0315 | Empty EMV Payload | The EMV payload cannot be empty. |
| PIX-0316 | EMV Not Found | The EMV QR Code was not found. |
| PIX-0317 | Invalid City Code | The city code is invalid. |
| PIX-0318 | BR Code Not Found | The requested BR Code was not found. |
| PIX-0319 | Receiver Key Not Associated | The receiver key is not associated with the account. |
| PIX-0320 | Invalid Merchant Name | The merchant name is required. |
| PIX-0321 | Invalid Merchant City | The merchant city must contain only letters and spaces. |
| PIX-0322 | Invalid Merchant Category Code | The merchant category code must be numeric. |
| PIX-0324 | Invalid Amount Value | The amount is not a valid decimal. |
| PIX-0327 | Invalid Client Request ID | The client request ID must be a valid UUID. |
| PIX-0328 | Invalid Image Type | The image type must be one of: Gif, Jpeg, Png. |
| PIX-0329 | Invalid Pixels Per Module | The pixels per module value is out of bounds. |
| PIX-0330 | Service Unavailable | The decode service is temporarily unavailable. |

### Transfers errors

| `code` | `title` | `message` |
| - | - | - |
| PIX-0400 | Description Too Long | The description field exceeds the maximum allowed length of 140 characters. |
| PIX-0401 | Description Contains HTML | The description contains invalid HTML characters. |
| PIX-0402 | Invalid Amount Format | The amount must be in format 0.00 with exactly 2 decimal places (1-10 digits before decimal). |
| PIX-0403 | Amount Must Be Positive | The amount must be greater than zero. |
| PIX-0404 | Invalid UUID Format | The UUID format is invalid. |
| PIX-0405 | Invalid End-to-End ID Format | The end-to-end ID format is invalid. |
| PIX-0406 | Intra PSP Not Supported | INTRA PSP transfers (same participant) are not supported. The destination bank ISPB cannot be the same as the source PSP. |
| PIX-0407 | Transfer Account Mismatch | The transfer does not belong to the specified account. |

### Initiation errors

| `code` | `title` | `message` |
| - | - | - |
| PIX-0410 | Initiation Not Found | The payment initiation was not found. |
| PIX-0411 | Initiation Expired | The payment initiation has expired. |
| PIX-0412 | Initiation Already Used | The payment initiation has already been processed. |
| PIX-0413 | Initiation Invalid State | The payment initiation is in an invalid state. |
| PIX-0414 | Destination Required | Destination is required for MANUAL initiation type. |
| PIX-0415 | Invalid Initiation Type | The initiation type is invalid. |
| PIX-0416 | Key Required | Key is required for KEY initiation type. |
| PIX-0417 | EMV Required | EMV is required for QR\_CODE initiation type. |
| PIX-0418 | Invalid Destination | The destination is invalid for MANUAL initiation type. |

### Cashout errors

| `code` | `title` | `message` |
| - | - | - |
| PIX-0420 | Cashout Not Found | The cashout transaction was not found. |
| PIX-0421 | Insufficient Balance | Insufficient balance to complete the transaction. |
| PIX-0422 | Amount Mismatch | The amount does not match the fixed amount from QR code. |
| PIX-0423 | Duplicate End-to-End ID | A transaction with this end-to-end ID already exists. |
| PIX-0424 | Invalid Amount Value | The amount must be greater than zero. |
| PIX-0425 | Cashin Not Found | The cashin transaction was not found. |
| PIX-0426 | Transfer Not Found | The transfer was not found. |
| PIX-0427 | Refund Not Found | The refund was not found. |
| PIX-0428 | Duplicate Refund | A refund already exists for this transaction. |

### Account errors

| `code` | `title` | `message` |
| - | - | - |
| PIX-0430 | Account Not Found | The account was not found in ledger. |
| PIX-0431 | Account Blocked | The account is blocked and cannot perform transactions. |

### Refund errors

| `code` | `title` | `message` |
| - | - | - |
| PIX-0440 | Original Transfer Not Cashin | Only cashin transfers can be refunded with cashout refunds. |
| PIX-0441 | Original Transfer Not Complete | Only completed transactions can be refunded. |
| PIX-0442 | Refund Exceeds Original | The refund amount exceeds the original transaction amount. |
| PIX-0443 | Invalid Refund Reason | The refund reason code is invalid. |
| PIX-0444 | Refund Exceeds Net Amount | The partial refund amount exceeds net amount available after fees. |
| PIX-0445 | Invalid Transaction Status | Only completed transactions can be refunded. |

### Destination validation errors

| `code` | `title` | `message` |
| - | - | - |
| PIX-0450 | Destination Bank Required | The destination bank is required. |
| PIX-0452 | Destination Branch Required | The destination branch is required. |
| PIX-0453 | Destination Account Required | The destination account is required. |
| PIX-0454 | Destination Account Type Invalid | The destination account type is invalid. |
| PIX-0455 | Destination Document Required | The destination document is required. |
| PIX-0457 | Destination Name Required | The destination name is required. |
| PIX-0458 | Destination Person Type Invalid | The destination person type is invalid. |
| PIX-0459 | Destination Person Type Mismatch | Person type does not match document: CPF requires NATURAL\_PERSON, CNPJ requires LEGAL\_PERSON. |

### Status transition errors

| `code` | `title` | `message` |
| - | - | - |
| PIX-0470 | Invalid Status Transition | The status transition is invalid. |
| PIX-0471 | Transfer Already Terminal | The transaction is already in a terminal state. |
| PIX-0472 | Cannot Cancel | Cannot cancel transaction in current status. |
| PIX-0473 | Already Terminal | The operation is already in a terminal state. |

### Integration errors (CRM)

| `code` | `title` | `message` |
| - | - | - |
| PIX-0500 | CRM Connection Error | Failed to connect to CRM service. |
| PIX-0501 | CRM Authentication Error | Failed to authenticate with CRM service. |
| PIX-0502 | Account Not Found in CRM | The account was not found in CRM for the given criteria. |
| PIX-0503 | Holder Not Found in CRM | The holder was not found in CRM. |
| PIX-0504 | Invalid Branch in CRM | The branch returned by CRM is invalid. Expected exactly 4 digits. |
| PIX-0505 | Invalid Account Number in CRM | The account number returned by CRM is invalid. Expected 1-20 digits. |
| PIX-0506 | Invalid Document in CRM | The document (CPF/CNPJ) returned by CRM is invalid. |
| PIX-0507 | Invalid Name in CRM | The name returned by CRM is invalid or exceeds 120 characters. |
| PIX-0508 | Invalid Trade Name in CRM | The trade name returned by CRM is invalid or exceeds 100 characters. |
| PIX-0509 | Invalid Opening Date in CRM | The opening date returned by CRM is invalid. Expected format: yyyy-mm-dd. |
| PIX-0510 | Invalid Account Type in CRM | The account type returned by CRM is invalid. Expected: CACC, SLRY, SVGS, TRAN, or OTHR. |
| PIX-0599 | CRM Bad Request | CRM returned a bad request error. |

### Integration errors (Midaz)

| `code` | `title` | `message` |
| - | - | - |
| PIX-0600 | Midaz Insufficient Funds | Insufficient funds in the source account. |
| PIX-0601 | Midaz Account Blocked | The account is blocked and cannot perform transactions. |
| PIX-0602 | Midaz Connection Error | Failed to connect to Midaz. |

### Integration errors (Fee Service)

| `code` | `title` | `message` |
| - | - | - |
| PIX-0650 | Fee Service Connection Error | Failed to connect to Fee service. |

### Collection errors

| `code` | `title` | `message` |
| - | - | - |
| PIX-0700 | Collection Not Found | The collection was not found. |
| PIX-0701 | Duplicate Collection TxID | A collection with this txId already exists for the receiver. |
| PIX-0702 | Collection Already Deleted | The collection has already been deleted. |
| PIX-0703 | Invalid Collection Type | The collection type is invalid. |
| PIX-0704 | Invalid Collection Status | The collection status is invalid or does not allow this operation. |
| PIX-0705 | Invalid Collection Amount | The collection amount is invalid. |
| PIX-0706 | Invalid Collection Expiration / Receiver Key Not Owned | The collection expiration is invalid / The receiver key is not associated with the account. |
| PIX-0707 | Invalid Due Date / Invalid Debtor | The due date is invalid / The debtor information is invalid. |
| PIX-0708 | Expiration Too Long / Collection Has No Provider ID | The expiration exceeds the maximum allowed: 30 days (2,592,000 seconds) / The collection has no pactual ID. |
| PIX-0709 | Invalid TxID / Invalid Delete Reason | The txID is invalid or cannot be empty / The delete reason must be DELETED\_BY\_USER or DELETED\_BY\_PSP. |
| PIX-0710 | Invalid Receiver Document | The receiver document is invalid or cannot be empty. |
| PIX-0711 | Invalid Receiver Name | The receiver name is invalid or cannot be empty. |
| PIX-0712 | Invalid Receiver Address | The receiver address is required. |
| PIX-0713 | Invalid Debtor Name | The debtor name is invalid or cannot be empty. |
| PIX-0714 | Invalid CPF Format | The CPF format is invalid: must be exactly 11 digits. |
| PIX-0715 | Invalid CNPJ Format | The CNPJ format is invalid: must be exactly 14 digits. |
| PIX-0716 | Invalid Account ID | The account ID is invalid or cannot be empty. |
| PIX-0717 | Invalid Pactual ID | The pactual ID is invalid or cannot be empty. |
| PIX-0718 | Invalid Location ID | The location ID is invalid or cannot be empty. |
| PIX-0719 | Invalid Fine | The fine configuration is incomplete: both type and value must be provided. |
| PIX-0720 | Invalid Interest | The interest configuration is incomplete: both type and value must be provided. |
| PIX-0721 | Invalid Discount | The discount configuration is incomplete: type, value and days before due must be provided. |
| PIX-0722 | Invalid Abatement | The abatement configuration is incomplete: both type and value must be provided. |
| PIX-0723 | Too Many Additional Info | The number of additional info items exceeds the maximum allowed: 50. |
| PIX-0724 | Pix Troco Amount Mismatch | Pix Troco transaction amount must equal original amount. |
| PIX-0725 | Invalid Pix Saque Configuration | Pix Saque cannot have transaction amount, only withdrawal amount. |
| PIX-0726 | Collection Update Not Allowed | Updates are not allowed for this collection. |
| PIX-0727 | Debtor Document Mismatch | The payment debtor document does not match the collection debtor. |
| PIX-0728 | Type Mismatch | The payment type does not match the collection type. |
| PIX-0729 | Collection Amount Mismatch | The payment amount does not match the collection amount. |

### Provider errors (BTG)

| `code` | `title` | `message` |
| - | - | - |
| PIX-1000 | Provider Connection Error | Failed to connect to provider. |
| PIX-1001 | Provider Authentication Error | Failed to authenticate with provider. |
| PIX-1002 | Provider Request Timeout | Provider request timed out. |
| PIX-1003 | Rate Limit Exceeded | Rate limit exceeded. Please try again later. |
| PIX-1004 | Provider Service Unavailable | Provider service is temporarily unavailable. |
| PIX-1005 | Key Not Found | The Pix key was not found. |
| PIX-1006 | Key Already Exists | The Pix key already exists. |
| PIX-1007 | Provider Internal Error | Provider returned an internal error. |
| PIX-1008 | Provider Invalid Response | Provider returned an invalid response. |
| PIX-1009 | Provider Bad Request | Provider rejected the request due to invalid data. |
| PIX-1010 | Provider Unprocessable | Provider cannot process the request. |
| PIX-1099 | Provider Unmapped Error | Provider returned an unmapped error. |

### Provider errors (MED)

| `code` | `title` | `message` |
| - | - | - |
| PIX-1065 | Duplicate Refund Request | The provider reports that a refund request already exists for this transaction. |
| PIX-1068 | Invalid Request Status | The provider reports that the request is in an invalid state for this operation. |
| PIX-1069 | Cannot Cancel Request | The provider reports that the request cannot be cancelled due to its current state. |
| PIX-1080 | Duplicate Fraud Marker | The provider reports that a fraud marker already exists for this document and key combination. |
| PIX-1081 | Invalid Fraud Type | The provider reports that the fraud type is not valid for this operation. |
| PIX-1083 | Cannot Cancel Marker | The provider reports that the marker cannot be cancelled due to its current state. |
| PIX-1090 | Person Statistics Not Found | The provider reports that no statistics were found for the specified tax ID. |
| PIX-1091 | Key Statistics Not Found | The provider reports that no statistics were found for the specified Pix key. |


# Initiate a Pix Transfer
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/initiate-a-pix-transfer

/en/openapi/v3-current/indirect-pix.yaml post /v1/transfers/cashout/initiate
Use this endpoint to start a Pix cash-out by creating an initiation record. This endpoint retrieves and validates destination information without moving funds. Supports MANUAL, KEY, and QR_CODE initiation. The request body is intentionally an opaque raw-bytes payload (no typed schema): unknown fields are ignored.



# List All Reconciliation Jobs
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-all-reconciliation-jobs

/en/openapi/v3-current/indirect-pix.yaml get /v1/dict/reconciliation
Use this endpoint to list all reconciliation jobs with optional filters.
Returns empty array [] if no jobs match the criteria.



# List All VSync States
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-all-vsync-states

/en/openapi/v3-current/indirect-pix.yaml get /v1/dict/vsync
Use this endpoint to list all VSync states for PIX key types with optional filters.
Returns empty array [] if no VSync states match the criteria.
Note: This table has at most 5 records (one per PIX key type: CPF, CNPJ, EMAIL, PHONE, EVP).



# List Key Claims
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-claims

/en/openapi/v3-current/indirect-pix.yaml get /v1/dict/claims
Use this endpoint to list key claims with filters and pagination. Returns empty array [] if no claims match the criteria.



# List Dynamic Charges with Due Date
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-dynamic-charges-with-due-date

/en/openapi/v3-current/indirect-pix.yaml get /v1/collections/duedate
Use this endpoint to list all due date collections for an account with optional filters and pagination. Returns empty array [] if no collections match the criteria.



# List Fraud Markers
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-fraud-markers

/en/openapi/v3-current/indirect-pix.yaml get /v1/dict/fraud-markers
Use this endpoint to list fraud markers with filters. Returns empty array [] if no markers match the criteria.

**Notes:**
- This endpoint is a proxy to BTG and does not persist data locally.
- Uses cursor-based pagination via modified_after/modified_before filters.
- When hasMoreElements is true, use the updatedAt of the last item as modified_after for the next request.



# List Funds Recoveries
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-funds-recoveries

/en/openapi/v3-current/indirect-pix.yaml get /v1/dict/funds-recoveries
Use this endpoint to list funds recovery requests with optional filters and pagination.



# List Infraction Reports
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-funds-recovery-infraction-reports

/en/openapi/v3-current/indirect-pix.yaml get /v1/dict/funds-recoveries/{funds_recovery_id}/infraction-reports
Use this endpoint to list all infraction reports associated with a funds recovery request.



# List Refunds
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-funds-recovery-refunds

/en/openapi/v3-current/indirect-pix.yaml get /v1/dict/funds-recoveries/{funds_recovery_id}/refunds
Use this endpoint to list all refunds associated with a funds recovery request.



# List Immediate Charges
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-immediate-charges

/en/openapi/v3-current/indirect-pix.yaml get /v1/collections/immediate
Use this endpoint to list all immediate collections for an account with optional filters and pagination. Returns empty array [] if no collections match the criteria.



# List inbound webhooks
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-inbound-webhooks

/en/openapi/v3-current/indirect-pix.yaml get /v1/webhooks/inbound
Lists persisted inbound webhooks (received from BTG). The entity_type query parameter is required.



# List Infraction Reports
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-infraction-reports

/en/openapi/v3-current/indirect-pix.yaml get /v1/dict/infraction-reports
Use this endpoint to list infraction reports with optional filters and pagination.



# List outbound webhooks
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-outbound-webhooks

/en/openapi/v3-current/indirect-pix.yaml get /v1/webhooks/outbound
Lists persisted outbound webhooks (sent to clients). The flow_type query parameter is required. Dead-letter rows are surfaced transparently with status="DEAD_LETTER".



# List Pix Automático Authorization Requests
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-pix-automatico-authorization-requests

/en/openapi/v3-current/indirect-pix.yaml get /v1/recurrences/payer/authorization-requests
List authorization requests belonging to the authenticated payer with optional filters and page/limit pagination.



# List Pix Automático Authorizations
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-pix-automatico-authorizations

/en/openapi/v3-current/indirect-pix.yaml get /v1/recurrences/payer/authorizations
List active authorizations belonging to the authenticated payer with optional filters and page/limit pagination. Includes computed `nextChargeAt` / `nextChargeAmount`.



# List Pix Automático Charges by Authorization
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-pix-automatico-charges-by-authorization

/en/openapi/v3-current/indirect-pix.yaml get /v1/recurrences/payer/authorizations/{authorizationId}/charges
List the charges belonging to one authorization, scoped to the authenticated payer. Supports page/limit pagination plus status and createdAt date-range filters.



# List Pix Schedules
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-pix-schedules

/en/openapi/v3-current/indirect-pix.yaml get /v1/schedules
List schedules belonging to the caller's account with optional status filter and pagination.



# List Pix Transfers
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-pix-transfers

/en/openapi/v3-current/indirect-pix.yaml get /v1/transfers
Use this endpoint to list Pix Transfers with optional filters and pagination.



# List Refund Requests
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-refund-requests

/en/openapi/v3-current/indirect-pix.yaml get /v1/dict/refund-requests
Use this endpoint to list refund requests with filters and pagination. Returns empty array [] if no requests match the criteria.



# List Refunds
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-refunds

/en/openapi/v3-current/indirect-pix.yaml get /v1/refunds
Use this endpoint to list refunds with optional filters and pagination.



# List Static QR Codes
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-static-qr-codes

/en/openapi/v3-current/indirect-pix.yaml get /v1/brcode/static
Use this endpoint to list all static Pix BR Codes for an account with optional filters. Returns empty array [] if no QR codes match the criteria.



# List Transaction Reports
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-transaction-reports

/en/openapi/v3-current/indirect-pix.yaml get /v1/transaction-reports
Use this endpoint to list TRCK002 transaction reports with optional filters and pagination.



# List TemposTransacoes report job executions
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/list-transaction-times-jobs

/en/openapi/v3-current/indirect-pix.yaml get /v1/statistics/tempos-transacoes/jobs
Use this endpoint to see every execution across all reference months, not just the latest attempt per month — getting the job of a reference month returns only the latest one, which hides superseded attempts (e.g. a cancelled run followed by a retry). Supports filtering by status and reference-month range, and pagination.



# Pay and confirm a scanned Pix Automático recurrence (J3)
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/pay-and-confirm-a-scanned-pix-automatico-recurrence

/en/openapi/v3-current/indirect-pix.yaml post /v1/recurrences/payer/qr/pay-and-confirm
J3 inseparable-act saga: process the pre-created immediate-charge cashout (`initiationId`) and confirm the scanned recurrence (`idRec`). Returns 200 when the cashout settled immediately (authorization request is APPROVING); 202 when it is still processing. The payer account is the authenticated `X-Account-Id`. `X-Idempotency` is optional but recommended; replays within the window are de-duplicated.



# Process a Pix Transfer
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/process-a-pix-transfer

/en/openapi/v3-current/indirect-pix.yaml post /v1/transfers/cashout/process
Process a previously initiated Pix cash-out and move funds between accounts. The request body is intentionally an opaque raw-bytes payload (no typed schema): unknown fields are ignored.



# Refund a Received Pix Transfer
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/refund-a-received-pix-transfer

/en/openapi/v3-current/indirect-pix.yaml post /v1/transfers/{transfer_id}/refunds
Use this endpoint to initiate a refund for a previously received Pix transfer. Optionally provide an operations array for distributed partial refunds from multiple accounts. Only received Pix transfers (cash-in) can be refunded; the sum of all refunds cannot exceed the original amount.



# Request Refund
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/request-funds-recovery-refund

/en/openapi/v3-current/indirect-pix.yaml post /v1/dict/funds-recoveries/{funds_recovery_id}/refund
Use this endpoint to request a refund for a funds recovery. This is only allowed when the funds recovery is in ANALYSED status.

**Notes:**
- Refund request triggers the MED refund flow
- The funds recovery status will transition to REFUNDING



# Get a Key Claim
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/retrieve-a-claim

/en/openapi/v3-current/indirect-pix.yaml get /v1/dict/claims/{claim_id}
Use this endpoint to retrieve the details of a specific key claim.



# Get a Pix Transfer
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/retrieve-a-pix-transfer

/en/openapi/v3-current/indirect-pix.yaml get /v1/transfers/{transfer_id}
Use this endpoint to retrieve a Pix transfer by its unique identifier.



# Retrieve a Refund Request
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/retrieve-a-refund-request

/en/openapi/v3-current/indirect-pix.yaml get /v1/dict/refund-requests/{refund_id}
Use this endpoint to retrieve the details of a specific refund request.



# Retrieve Static QR Code Details
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/retrieve-a-static-qr-code

/en/openapi/v3-current/indirect-pix.yaml get /v1/brcode/static/{brcode_id}
Use this endpoint to retrieve detailed information about a specific static Pix BR Code.



# Retrieve Infraction Report details
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/retrieve-an-infraction-report

/en/openapi/v3-current/indirect-pix.yaml get /v1/dict/infraction-reports/{infraction_id}
Use this endpoint to retrieve the full details of a single infraction report.



# Retrieve Dynamic Charge with Due Date Details
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/retrieve-dynamic-charge-with-due-date-details

/en/openapi/v3-current/indirect-pix.yaml get /v1/collections/duedate/{collection_id}
Use this endpoint to retrieve detailed information about a specific due date collection.



# Retrieve Funds Recovery details
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/retrieve-funds-recovery-details

/en/openapi/v3-current/indirect-pix.yaml get /v1/dict/funds-recoveries/{funds_recovery_id}
Use this endpoint to retrieve the full details of a single funds recovery request.



# Retrieve Tracking Graph
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/retrieve-funds-recovery-tracking-graph

/en/openapi/v3-current/indirect-pix.yaml get /v1/dict/funds-recoveries/{funds_recovery_id}/tracking-graph
Use this endpoint to retrieve the tracking graph for a funds recovery request. The tracking graph shows the flow of funds from the root transaction.

**Notes:**
- Optional parameters can be used to customize the graph generation
- The graph includes persons, accounts, and transactions related to the fraud



# Retrieve Immediate Charge Details
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/retrieve-immediate-charge-details

/en/openapi/v3-current/indirect-pix.yaml get /v1/collections/immediate/{collection_id}
Use this endpoint to retrieve detailed information about a specific immediate collection.



# Get Key Statistics
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/retrieve-key-statistics

/en/openapi/v3-current/indirect-pix.yaml get /v1/dict/statistics/keys/{key}
Use this endpoint to fetch usage and risk statistics for a specific Pix key.

**Notes:**
- Returns both key-level statistics and owner-level statistics in a single response.
- Key statistics track data specific to the Pix key as an entity independent of its current owner.
- Owner statistics provide the same data as the person statistics endpoint for the key's current owner.
- This endpoint queries the provider directly and does not store data locally.
- Use this information for comprehensive risk assessment when processing payments to a Pix key.



# Get Person Statistics
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/retrieve-person-statistics

/en/openapi/v3-current/indirect-pix.yaml get /v1/dict/statistics/persons/{tax_id}
Use this endpoint to fetch aggregated Pix statistics for a person identified by their tax ID (CPF or CNPJ).

**Notes:**
- Statistics include transaction settlement data, fraud markers, infraction reports, and entry information.
- Data is aggregated over different time periods: d90 (last 90 days), m12 (last 12 months), m60 (last 60 months).
- This endpoint queries the provider directly and does not store data locally.
- Use this information for risk assessment before processing Pix transactions.



# Retry inbound webhook
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/retry-an-inbound-webhook

/en/openapi/v3-current/indirect-pix.yaml post /v1/webhooks/inbound/{id}/retry
Re-arms a FAILED inbound webhook so it is retried. Returns 202 Accepted. The retry preserves the current attempt count and raises the retry ceiling.



# Retry outbound webhook
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/retry-an-outbound-webhook

/en/openapi/v3-current/indirect-pix.yaml post /v1/webhooks/outbound/{id}/retry
Re-arms a FAILED outbound webhook. A webhook that has already moved to the dead-letter queue is restored (preserving its original id) and removed from the dead-letter queue atomically. Returns 202 Accepted.



# Start Full Reconciliation
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/start-full-reconciliation

/en/openapi/v3-current/indirect-pix.yaml post /v1/dict/reconciliation/full
Triggers full reconciliation for all key types that are currently out of sync.

This endpoint detects which key types have OUT_OF_SYNC status and requests CID files from BTG for each of them. The actual reconciliation processing happens asynchronously via webhooks when the files become available.

**Response codes:**
- **202 Accepted**: One or more reconciliation jobs were created
- **200 OK**: All key types are already synchronized (no jobs created)



# Submit a Transaction Report
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/submit-a-transaction-report

/en/openapi/v3-current/indirect-pix.yaml post /v1/transaction-reports/{id}/submit
Use this endpoint to manually trigger the submission of a TRCK002 transaction report to BTG. Fallback for reports not submitted through the normal worker-driven flow. Idempotent: reports already PROCESSING or CONFIRMED are left unchanged. Accepted for asynchronous processing; the final outcome is delivered later via the BTG CAMT025 status webhook.



# Unblock a Pix Refund
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/unblock-a-pix-refund

/en/openapi/v3-current/indirect-pix.yaml post /v1/refunds/{refund_id}/unblock
Use this endpoint to unblock a refund stuck in PROCESSING status. The endpoint fetches the current reversal status from BTG and triggers the appropriate refund settlement flow if BTG shows the reversal has completed or failed. The optional request body field allowNotFoundUnblock (default false) opts into resolving a CASHOUT refund as FAILED when BTG reports the reversal absent (404). The request body is intentionally an opaque raw-bytes payload (no typed schema): unknown fields are ignored, and an empty body is valid.



# Unblock a Pix Transfer
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/unblock-a-pix-transfer

/en/openapi/v3-current/indirect-pix.yaml post /v1/transfers/{transfer_id}/unblock
Use this endpoint to unblock a transaction that is stuck in PENDING or PROCESSING status. The endpoint fetches the current status from BTG and triggers the appropriate settlement flow if BTG shows the transaction has completed or failed. The optional request body field allowNotFoundUnblock (default false) gates ONLY the not-found (HTTP 404) branch. The request body is intentionally an opaque raw-bytes payload (no typed schema): unknown fields are ignored, and an empty body is valid.



# Update a Dynamic Charge with Due Date
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/update-a-dynamic-charge-with-due-date

/en/openapi/v3-current/indirect-pix.yaml patch /v1/collections/duedate/{collection_id}
Use this endpoint to update a due date collection. Only collections in ACTIVE status can be updated.



# Update a Funds Recovery Request
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/update-a-funds-recovery-request

/en/openapi/v3-current/indirect-pix.yaml patch /v1/dict/funds-recoveries/{funds_recovery_id}
Use this endpoint to update an existing funds recovery request. Updates are only allowed for requests in CREATED, TRACKED, or AWAITING_ANALYSIS status.

**Notes:**
- Only the situationType, reportDetails, and contactInformation can be updated
- Updates are not allowed for requests in terminal states (COMPLETED, CANCELLED)



# Update a Pix Entry Data
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/update-an-entry

/en/openapi/v3-current/indirect-pix.yaml patch /v1/dict/entries/{entry_id}
Use this endpoint to update an existing Pix entry data associated with an account.



# Update an Immediate Charge
Source: https://docs.lerian.studio/en/reference/interfaces/pix-btg/update-an-immediate-charge

/en/openapi/v3-current/indirect-pix.yaml put /v1/collections/immediate/{collection_id}
Use this endpoint to update an immediate collection. Only collections in ACTIVE status can be updated.

**Mutable Fields (can be updated):**
- expirationSeconds: Time in seconds until collection expires
- receiverKey: PIX key that will receive the payment
- debtorDocument: CPF/CNPJ of the payer (must be provided with debtorName)
- debtorName: Name of the payer (must be provided with debtorDocument)
- description: Custom description for the collection
- additionalInfo: Additional key-value information
- tags: Array of custom tags

**Immutable Fields (cannot be updated):**
- id, accountId, txId, amount, status, pactualId, emv, locationUrl, createdAt, updatedAt

**State Restrictions:**
- Collections can ONLY be updated when status is ACTIVE
- Collections with status COMPLETED, DELETED, or EXPIRED cannot be updated



# Cancel a Transfer
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/cancel-transfer

/en/openapi/v3-current/ted.yaml post /v1/transfers/{transferId}/cancel
Use this endpoint to cancel a transfer that has not yet been submitted for processing. Only transfers in CREATED or PENDING status can be cancelled. Cancelling a transfer releases the held funds in Midaz and sets the status to CANCELLED. Calling cancel on an already-cancelled transfer returns success.

This endpoint takes no request body — the transfer is identified by the path parameter alone.



# Check Ledger Routing Readiness
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/check-ledger-routing-readiness

/en/openapi/v3-current/ted.yaml get /v1/transfers/routing/preflight
Use this endpoint to check whether this tenant is ready for ledger-scoped routing. The report lists one line per Midaz organization, ledger, and transfer type:

- Every tuple that has carried a transfer, whatever its outcome. `transferCount` measures traffic, not settlement.
- Every tuple that the chargeback path demands although nothing has transferred on it and no binding addresses it (`transferCount` 0): the inbound tuple that every `TED_OUT` ledger owes for the refund (`derivedFrom: ted_out_refund`), and the outbound tuple that every `TED_IN` ledger owes for the compensation (`derivedFrom: ted_in_compensation`).
- One organization-level line per Midaz organization that the tenant registered to receive inbound TED and that has no inbound binding at any ledger (`derivedFrom: ispb_onboarded_organization`). `ledgerId` is empty, because the recipient account record decides the ledger when the credit arrives. Any inbound line for that organization answers the demand, and the line disappears.

Both chargeback tuples are demanded of a ledger that the configuration only declares, in either mode, as well as of one that has carried traffic. Once a binding answers the demand, the line is reported as a configured scope with no `derivedFrom`, and it is still judged. `ready` is `true` only when every line clears. A declared scope, and the chargeback counterpart of a declared binding, are judged like any other line, because a binding is a promise about money that the operator intends to move, and a route that does not verify on it holds or refuses that ledger's first transfer. An explicit `mode: omit` answers any line, because it posts with the route fields left off, and a chargeback against money that landed unrouted posts back unrouted. The one pairing that it cannot express, a ledger that routes its incoming credits while it declares their compensation unrouted, is refused when the configuration is read and never reaches this report.

The report also lists the bindings that the configuration carries, each with whether a binding covers it and whether the accounting routes it names exist inside that exact scope in Midaz. `legacyPendingInitiations` counts the live initiations still pending from before ledger-scoped routing, which this service answers with 409 (BTF-0112). `readbackBudgetExhausted` is `false` for every configuration that the contract accepts. A `true` value means a service defect: report it instead of retrying. The scopes past the budget then read `unavailable`.

This is a read-only administrative endpoint. It never writes the configuration and never moves money. It does not require the `X-Organization-Id` header. In multi-tenant deployments the report is scoped to the caller's resolved tenant.



# Get dashboard summary
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/get-dashboard-summary

/en/openapi/v3-current/ted.yaml get /v1/transfers/dashboard/summary
Returns aggregated transfer counters and operational health snapshot for dashboards. The `window` parameter sets the period that the counters cover. `byReconciliationStatus`, `health.processingCount`, and `health.pendingCount` count the current state and ignore the window.



# Initiate a Transfer
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/initiate-transfer

/en/openapi/v3-current/ted.yaml post /v1/transfers/initiate
Use this endpoint to initiate a transfer by validating sender data, checking operating hours and usage limits, detecting duplicates, and calculating the fee. No funds are held at this step. The returned initiationId is valid for 24 hours and must be confirmed via the Process Transfer endpoint. Use the `X-Idempotency` header for guaranteed deduplication.



# List pending reconciliation transfers
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/list-pending-reconciliation

/en/openapi/v3-current/ted.yaml get /v1/transfers/reconciliation/pending
Lists the transfers that still need a reconciliation action, oldest first.



# List unresolved TED IN reconciliation gaps
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/list-ted-in-reconciliation-gaps

/en/openapi/v3-current/ted.yaml get /v1/transfers/ted-in/reconciliation-gaps
Use this endpoint to list durable traces of ambiguous TED IN inbound-message outcomes that an operator must verify. This is a read-only administrative endpoint; the resolve or close action is a separate concern. It is organization-independent and does not require the `X-Organization-Id` header. In multi-tenant deployments the results are scoped to the caller's resolved tenant database.



# List Transfers
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/list-transfers

/en/openapi/v3-current/ted.yaml get /v1/transfers
Use this endpoint to retrieve a paginated list of transfers. You can filter by ledger, type, status, reconciliation status, date range, and amount range. The default limit is 50 items, with a maximum of 200. Only returns transfers belonging to the same organization.



# Prepare Transfer Signing Payload
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/prepare-transfer-signing

/en/openapi/v3-current/ted.yaml post /v1/transfers/signing/prepare
Use this endpoint to freeze the canonical STR0008 payload for a previously initiated TED OUT transfer and obtain the exact bytes that must be signed before calling Process Transfer. The response includes a `signingArtifactId` and a reserved `transferId`. The reserved `transferId` is not queryable until Process Transfer succeeds.

Use the `X-Idempotency` header for guaranteed deduplication. Repeated calls with the same key replay the cached response.



# Process a Transfer
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/process-transfer

/en/openapi/v3-current/ted.yaml post /v1/transfers/process
Use this endpoint to confirm and execute a previously initiated transfer. The system validates the initiationId, checks the sender's balance, holds funds in Midaz, and routes the transfer to JD SPB (for TED OUT) or creates an internal Midaz transaction (for P2P). Submitting the same initiationId returns the same transferId.



# Repair Transfer Ledger Scope
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/repair-transfer-ledger-scope

/en/openapi/v3-current/ted.yaml post /v1/transfers/{transferId}/scope/repair
Use this endpoint to correct the accounting scope of one transfer whose ledger is the all-zeroes UUID. That value addresses no Midaz ledger and matches no routing binding, so the transfer's refund stays held, and no configuration that an operator could write frees it.

The operator supplies the ledger, because only a person may authorize an edit to the scope of a money row. CRM must report the same ledger for the transfer's own account before anything is written; if the two disagree, nothing is written. No money moves here and no ledger call is made: the next reconciliation or poller cycle moves the money, once, on the routes that the repaired ledger resolves.

The operator `reason` is required. It is recorded in the transfer's status history and audit trail with the subject from the bearer token. This endpoint requires the `transfers:repair` permission and a user token.



# Resolve Transfer Reconciliation
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/resolve-transfer-reconciliation

/en/openapi/v3-current/ted.yaml post /v1/transfers/{transferId}/reconciliation/resolve
Use this endpoint to resolve by hand one transfer that reconciliation parked in manual review. Each action serves exactly one transfer type.

On an outbound TED whose hold is preserved:

- `SETTLE` commits the hold and completes the transfer.
- `REVERT` cancels the hold and fails the transfer.

On an inbound credit whose STR0010R2 chargeback refund the automatic path could not finish:

- `RE_POST` pays the refund again. Before it pays anything, it asks the ledger what became of the compensation already on file. Only a compensation that moved nothing licenses a posting. One that already moved the gross closes the row where it stands, with nothing posted. One that moved any other amount is refused for good. Even the licensed case first searches the ledger for this chargeback's own refunds and adopts a live one already paying the gross instead of filing a second, so a refund that was paid can never be paid twice. A compensation on file that the ledger prices as live enters that same search as one of its members, so while a second live refund stands beside it, the row is not closed on it and no difference is quoted against it.
- `SETTLED_BY_HAND` posts nothing and records that the refund was arranged outside this platform, so it requires an `evidenceReference` that names the outside movement. Because this record also takes the row off the pending list, it is filed only over a ledger reading that completed and priced every posting it saw. A scan that the ledger truncated, a scan that it could not answer, and a scan holding a posting in a status this service cannot price are each refused as not confirmed instead of closed. Send the same request again under a new `X-Idempotency` key.

When the ledger holds more than one live refund for a chargeback, this platform debited the beneficiary more than once, and no action here takes a posting back: `RE_POST` is refused, and `SETTLED_BY_HAND` closes the row with every one of those transactions named on the closing record.

On every action except `RE_POST`, the ledger moves first, and the row is written only once the ledger reaches the state that the resolution claims, so a failure midway leaves the transfer exactly as it was found. `RE_POST` runs in the other order, because it is the one action that pays: the new compensation is stamped on the transfer the moment the ledger returns its ID, before anything judges what it paid. Every later failure leaves the row parked and naming the money, and repeating the identical request under a new `X-Idempotency` key (the key that earned the failure is fenced) converges on that stamp instead of paying a second time. A stamped compensation that the ledger cannot find is undecided, not absent, and is refused: wait, repeat the identical request under a new `X-Idempotency` key, and close the row with `SETTLED_BY_HAND` if it never clears. A refund that the ledger prices at anything other than the gross is a verdict that no retry changes, whether it is the compensation on file, one that the ledger scan found, or the one that this request filed: the row stays parked, the remaining difference is settled outside this platform, and the row is closed with `SETTLED_BY_HAND`.

The operator `reason` is required on every action. It is recorded in the audit trail with the subject resolved from the bearer token. This endpoint requires the `transfers:resolve` permission and a user token.



# Get a Transfer
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/retrieve-transfer

/en/openapi/v3-current/ted.yaml get /v1/transfers/{transferId}
Use this endpoint to retrieve the current status and details of a transfer, including its type, status history, sender and recipient details, amounts, and timestamps. Only returns transfers belonging to the same organization.



# Retry Transfer Reconciliation
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/retry-transfer-reconciliation

/en/openapi/v3-current/ted.yaml post /v1/transfers/{transferId}/reconciliation/retry
Use this endpoint to return an outbound TED parked in manual review to the reconciliation queue, so the worker queries its settlement again. No transfer is re-sent and no hold is touched: only the reconciliation state moves back to `AWAITING`, with a zeroed attempt counter. The operator `reason` is required and is recorded in the audit trail.



# Trigger reconciliation sweep
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/trigger-reconciliation-sweep

/en/openapi/v3-current/ted.yaml post /v1/transfers/reconciliation/tick
Forces one immediate reconciliation cycle for the current tenant. This operator endpoint runs the same reconciliation sweep used by the scheduled background worker. Repeated calls with the same `X-Idempotency` key replay the cached response.



# Trigger TED IN Poller
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/trigger-ted-in-poll

/en/openapi/v3-current/ted.yaml post /v1/transfers/ted-in/poll
Use this endpoint to force one immediate JD inbound poll cycle for the current tenant. This is an operational endpoint intended to accelerate receipt of JD return messages without waiting for the scheduled poll interval. It does not require the `X-Organization-Id` header — the tenant is derived from the authenticated context.

Same-key retries replay the cached response instead of draining JD again. An in-flight duplicate is rejected with 409 by the route-level idempotency middleware.



# Cancel an issued boleto
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/cancel-boleto

/en/openapi/v3-current/payments.yaml post /v1/boletos/{id}/cancel
Cancels a boleto in CREATED status. No ledger entry is recorded: issuance takes no balance reservation, so cancellation has nothing to reverse.



# Cancel a payment
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/cancel-payment

/en/openapi/v3-current/payments.yaml post /v1/payments/{id}/cancel
Payment cancellation is not available. Every request that passes authentication and request validation is answered with 501 Not Implemented and error code PBP-0203, including a request for a payment that is already canceled. No cancellation is performed and no payment is changed. A request refused before that keeps its own 4xx status and error code.



# Configure outbound webhook
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/configure-webhook

/en/openapi/v3-current/payments.yaml post /v1/admin/webhooks
Registers or updates the callback URL for receiving status change notifications. One configuration per tenant.



# Connect provider with the tenant's client credentials
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/connect-provider

/en/openapi/v3-current/payments.yaml post /v1/admin/providers/connect
Connects the tenant to the banking provider. It checks that the provider client credentials configured for the tenant can obtain an access token, stores that token, and resolves the provider company_id from the organization named in X-Organization-Id. On a deployment that verifies provider accounts, it also verifies that the credentials resolve to exactly one usable provider account, and account_verified in the answer says whether the account was verified. The tenant's provider client credentials must be configured before this call.

X-Organization-Id is required. It names the Midaz organization whose legalDocument (CNPJ) becomes the provider company_id; that organization owns the tenant's provider account. A request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025 and nothing is sent to the provider. Connecting again with a different organization replaces the company_id: the last successful connect wins.

Send an empty JSON object as the body: {}. The body is required: a request with no body, or with null, is refused with 400, and any field in it is rejected.

Account verification failures: 422 means the account setup at the provider must be corrected — there is no default account, there is more than one, or the default account is locked or not active. 502 means the provider returned an invalid answer, or the account does not belong to the credentials that would pay for it.

account_verified reports whether the provider account was verified. When it is true, provider_account_id identifies the verified account. When it is false, the connection is established but the account was NOT verified on this deployment and provider_account_id is absent: a successful connection is not evidence that the credentials resolve to the correct account. Do not treat the account as validated; contact support to have verification enabled.

MULTI-TENANT DEPLOYMENTS ONLY: the answer also carries webhook_url and webhook_signing_key. webhook_url is this tenant's inbound address for provider deliveries, and the token it contains identifies the tenant. webhook_signing_key is the key the provider uses to compute the HMAC-SHA256 of each delivery body, sent in the x-webhook-baas-signature header. It is a signing key, not a bearer token: never place it in an Authorization header. The two are registered together at the provider; webhook_subscription_registered reports whether this call registered them. Both fields are absent in single-tenant deployments.

THE SIGNING KEY IS SHOWN EXACTLY ONCE. No endpoint returns it again, so record it when you read it. Calling connect again ROTATES the connection: it issues a new webhook_url and a new webhook_signing_key, and the previous pair keeps authenticating deliveries for a grace window so that deliveries already in flight are not lost.

If the webhook URL or the signing key may have been exposed, call connect again with the same `X-Organization-Id`. A successful call rotates both. The exposed pair keeps working until its grace window closes, 30 minutes by default. After a failed call, the exposed pair stays in use.

THIS OPERATION IS NOT IDEMPOTENT. An Idempotency-Key header is ignored and does not replay a previous answer. Retrying a connect whose response you did not receive issues a new connection and replaces the one the provider may already be using, which then authenticates only until its grace window closes.



# Consult a bill by digitable line
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/consult-a-bill-by-digitable-line

/en/openapi/v3-current/payments.yaml post /v1/payments/consult
Consults a bill by its digitable line without paying it: the source's own view of the amount, the dates and who receives the money.

**Why POST for a read.** The digitable line identifies a payable bill and is sensitive, so it travels in the body instead of the URL, where proxies, logs and browser history would keep it. Nothing is created or changed: the request carries no Idempotency-Key and repeating it is safe.

**Local validation first.** The line must be 47 digits for a bank slip or 48 digits starting with 8 for a utilities bill, digits only and never normalized: any other form is refused with 400 PBP-0001 before any check digit is computed. A line in the right form whose check digits do not match is refused with 422 PBP-0100. Neither reaches the source.

**Segments differ.** Every member of the answer is always present; a member the segment does not report is null. A bank slip reports payability, the face value, fine, interest, discount, the due and limit dates, the beneficiary and the receiving bank. A utilities bill reports the assignor, its segment, the state, the payment window and a settlement date, which is not a due date. A bank slip the source does not know is 404 PBP-0110; a utilities line the source does not know is refused with 422 PBP-0111.

**Permission.** The operation requires `payments/create`, the same permission as initiating a payment: consulting is the first step of paying.

**Isolation.** The tenant and the provider credential come from the token, never from the request. The `X-Organization-Id` header is required and validated in form (a canonical UUID); it does not scope the consult, which reads no stored data of any organization.



# Download boleto PDF
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/download-boleto-pdf

/en/openapi/v3-current/payments.yaml get /v1/boletos/{id}/pdf
Streams the FEBRABAN-rendered PDF for a previously emitted boleto. The PDF is fetched on demand from the provider; if the provider has not finished registering the boleto, the response is 503 with a Retry-After header.



# Get boleto by ID
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/get-boleto

/en/openapi/v3-current/payments.yaml get /v1/boletos/{id}
Retrieves a single boleto by its ID with full detail.



# Get boleto dashboard
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/get-boleto-dashboard

/en/openapi/v3-current/payments.yaml get /v1/dashboards/boletos
Returns aggregated counts, amounts, and breakdowns of boletos for the specified period.



# Get installment series
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/get-installment-series

/en/openapi/v3-current/payments.yaml get /v1/boletos/installments/{series_id}
Installment series lookup is not available on this service. A request that passes authentication, authorization and parameter validation is answered with 501 Not Implemented. A request refused earlier keeps its own status: 401 or 403 for authentication and authorization, and 400 PBP-0001 when series_id is not a UUID.



# Get payment by ID
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/get-payment

/en/openapi/v3-current/payments.yaml get /v1/payments/{id}
Retrieves a single payment by its ID with full detail, including the DARF fields when applicable.



# Get payment dashboard
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/get-payment-dashboard

/en/openapi/v3-current/payments.yaml get /v1/dashboards/payments
Returns aggregated counts, amounts, and breakdowns of payments for the specified period.



# Get webhook configuration
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/get-webhook-configuration

/en/openapi/v3-current/payments.yaml get /v1/admin/webhooks
Retrieves the current outbound webhook configuration for the tenant.



# Initiate a DARF payment
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/initiate-darf-payment

/en/openapi/v3-current/payments.yaml post /v1/payments/darf
Initiates a DARF (federal tax) payment with specific tax fields.



# Initiate a payment
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/initiate-payment

/en/openapi/v3-current/payments.yaml post /v1/payments
Initiates a bankslip or utilities bill payment. The type is classified automatically from the digitable line. The payment is executed immediately; this operation does not accept a scheduling date. A request that sends scheduledDate is refused with 400 PBP-0001, naming body.scheduledDate as an unexpected property.



# Issue a single boleto
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/issue-boleto

/en/openapi/v3-current/payments.yaml post /v1/boletos
Issues a traditional boleto through the banking provider. The supported boleto type is TRADITIONAL; a request with type HYBRID or QR_CODE is refused with 422 PBP-0006. The boleto is issued without a guarantor (sacador avalista), and this operation does not accept one: a request that sends guarantor is refused with 400 PBP-0001, naming body.guarantor as an unexpected property. A nosso numero already held by an active boleto of the same provider account is refused with 422 PBP-0108 before the provider is called. When that holder can be read, the PBP-0108 detail names the boleto that holds the number, and the problem carries its id as ourNumberHolderBoletoId. When it is an earlier emission still without the provider's answer, the detail says so and does not ask for another number, because that emission can still become a live boleto; when it is a boleto the provider already answered, the detail asks for it to be consulted before another number is informed, because it may be an earlier emission of the same charge whose answer was lost. When a title the local index cannot see holds the number — for example, one issued through another deployment or another tenant sharing the provider account — the provider accepts the emission and refuses it later, and the boleto moves to FAILED, unless the title holding the number belongs to this same emission, in which case the boleto is bound to that title. The boleto stays PENDING instead when the provider's search cannot tell whose title holds the number — it lists a live title with that number that it attributes to no emission, more than one title of this same emission, or one of this emission without the provider's identifier or that disagrees with the boleto — or when the search could not be made or read whole; it also stays PENDING, transiently, while the search does not answer or is postponed to a later reconciliation pass.



# Issue installment boletos
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/issue-installment-boletos

/en/openapi/v3-current/payments.yaml post /v1/boletos/installments
Installment boleto issuance is not available on this service. A request that passes authentication, authorization and request validation is answered with 501 Not Implemented, and no boleto or installment series is created. A request refused earlier keeps its own status: 401 or 403 for authentication and authorization, 400 PBP-0012 for a missing or malformed Idempotency-Key, and 400 PBP-0001 for a body that fails schema validation, including one that sends guarantor, which this operation does not accept.



# List boletos
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/list-boletos

/en/openapi/v3-current/payments.yaml get /v1/boletos
Lists boletos with optional status, kind, type and date filters, paginated.



# List payments
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/list-payments

/en/openapi/v3-current/payments.yaml get /v1/payments
Lists payments with optional status, type, creation-date and due-date filters, paginated.



# Payments error list
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/payments-error-list

Look up any Payments error code, the HTTP status it arrives with, and the condition it names, so you can branch on a failed request.

**Error format**

The Payments API answers a failed request with one of three bodies. Which body you get
depends on where the service catches the failure, not on which endpoint you called.

A failure that the request pipeline catches before the API layer sees it answers a flat
JSON body on `application/json`. The pipeline authenticates the caller (PBP-0003 at 401)
and authorizes the action (PBP-0004 at 403). It also opens the tenant's storage (PBP-0008 at 503)
and runs the idempotency check. Everything the API layer catches answers an RFC 9457 problem
document on the `application/problem+json` media type. The service-wide rate limiter answers 429
with the plain text `Too Many Requests` and no error code.

```json Problem document theme={null}
{
  "type": "https://errors.lerian.studio/v1/PBP-0101",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "bankslip digitable line must have 47 digits",
  "code": "PBP-0101"
}
```

```json Flat body theme={null}
{
  "code": "PBP-0013",
  "title": "Idempotency Key Conflict",
  "message": "The request body does not match the original request for this idempotency key."
}
```

**Field definitions**

* **`type`** – A URI that identifies the error in the Lerian error catalog. Built as `https://errors.lerian.studio/v1/<code>`.
* **`title`** – The HTTP status text, for example `Unprocessable Entity`.
* **`status`** – The HTTP status code.
* **`detail`** – Text about this occurrence of the condition. The wording comes from the branch that raised it.
* **`code`** – A stable identifier for the condition. Branch on this value.
* **`errors`** – Optional list of per-field validation details, each with a `message`, a `location`, and the `value` found there.

At status 500, 502 and 503 the `detail` member carries a fixed text instead of a description of your request, so read `code` to identify the condition.

The flat body carries `code`, `title`, `message`, and an optional `details` object. It
never carries `type`, `status` or `detail`.

Five codes reach you as a flat body when the idempotency check raises them: PBP-0002,
PBP-0007, PBP-0008, PBP-0012 and PBP-0013. The pipeline also answers this way for a failure
that no handler caught. So read the media type rather than the code to tell the two bodies apart.

## Platform errors

***

These codes are not specific to one rail. The transport layer, the request pipeline and the handlers raise them.

| `code` | Description | Status |
| - | - | - |
| PBP-0001 | Malformed request, or a field that fails validation | 400 |
| PBP-0002 | An unexpected condition inside the service | 500 |
| PBP-0003 | The service could not establish who the caller is | 401 |
| PBP-0004 | The caller may not perform this action | 403 |
| PBP-0005 | The resource named in the request does not exist | 404 |
| PBP-0006 | A rule declines a well formed request, including a capability this API version does not carry | 422 |
| PBP-0007 | The request conflicts with the resource state, or with a request still in flight | 409 |
| PBP-0008 | A dependency this operation needs did not answer | 503 |
| PBP-0010 | The request body goes past the size limit | 413 |
| PBP-0012 | The operation needs an idempotency key, and the request carries none or one that is not a valid UUID | 400 |
| PBP-0013 | The idempotency key belongs to an earlier request that differs from this one | 422 |
| PBP-0017 | The provider account for this tenant is not fully set up | 422 |
| PBP-0019 | The path exists, and it does not accept this HTTP method | 405 |
| PBP-0020 | The request body did not arrive in time | 408 |
| PBP-0022 | The operation does not accept the content type you sent | 415 |
| PBP-0023 | A client-side failure that carries no code of its own | 400 |
| PBP-0025 | The `X-Organization-Id` header is absent or not a valid UUID | 400 |
| PBP-0026 | The `ledgerId` member is absent or not a valid UUID | 400 |

## Provider errors

***

These codes carry the payment provider's answer. What is safe to resend depends on the operation, so read the operation's error descriptions in the [API reference](/en/reference/interfaces/payments-btg/initiate-payment) before you resend.

| `code` | Description | Status |
| - | - | - |
| PBP-0014 | The payment provider read the instruction and rejected it | 422 |
| PBP-0015 | The payment provider is unavailable | 503 |
| PBP-0016 | The provider answered with something this service cannot use | 502 |
| PBP-0113 | The provider answered the pre-payment consult in a shape this service cannot use | 502 |
| PBP-0114 | The source of the bill is temporarily unavailable to the bill consult | 503 |
| PBP-0211 | The payment provider did not receive the payment instruction, and nothing was paid | 503 |

## Boleto errors

***

These codes answer the boleto rail: issuance, installments, cancellation and PDF retrieval.

| `code` | Description | Status |
| - | - | - |
| PBP-0103 | The boleto sits in a state that cancellation does not accept | 422 |
| PBP-0105 | The boleto PDF is not ready yet at the provider | 503 |
| PBP-0106 | Boleto issuance cannot check the funding account on this deployment | 422 |
| PBP-0107 | The provider has no register for the boleto this cancellation names | 422 |
| PBP-0108 | The nosso número is already in use on the provider account | 422 |
| PBP-0109 | The installment boleto operations refuse every request | 501 |

## Payment errors

***

These codes answer the bill payment rail: bankslip, utilities, DARF and the bill consult.

| `code` | Description | Status |
| - | - | - |
| PBP-0100 | The digitable line fails its FEBRABAN checksum | 422 |
| PBP-0101 | The digitable line lacks the digit count its payment type requires | 422 |
| PBP-0110 | The source has no bank slip under this digitable line | 404 |
| PBP-0111 | The source refused the line for a reason of its own | 422 |
| PBP-0112 | The caller went past the bill consult rate limit | 429 |
| PBP-0200 | The DARF fields fail validation | 400 |
| PBP-0202 | Payment initiation cannot check the funding account on this deployment | 422 |
| PBP-0203 | The payment cancellation operation refuses every request | 501 |
| PBP-0204 | The funding account's owner record is absent or incomplete, so the payer cannot be established | 400 |
| PBP-0205 | The funding account's owner record is inconsistent, so the payer cannot be established | 422 |
| PBP-0206 | The records that identify the funding account's owner could not be reached | 503 |
| PBP-0207 | The funding account owner's name is longer than a DARF can carry | 422 |
| PBP-0208 | The funding account owner's tax document is not all digits | 422 |
| PBP-0210 | The provider's pre-payment consult says the slip cannot be paid | 422 |

## Ledger errors

***

These codes carry the ledger's side of a payment. What is safe to resend depends on the operation, so read the operation's error descriptions in the [API reference](/en/reference/interfaces/payments-btg/initiate-payment) before you resend.

| `code` | Description | Status |
| - | - | - |
| PBP-0300 | The funding account lacks the available balance the write needs | 422 |
| PBP-0301 | The ledger did not complete its step, or the service could not record the payment and did not send it to the provider | 503 |
| PBP-0302 | The write would take the funding account past its overdraft limit | 422 |

## Webhook configuration errors

***

These codes answer a request that configures where this API pushes event notifications.

| `code` | Description | Status |
| - | - | - |
| PBP-0400 | The callback URL is invalid, or this deployment blocks it | 400 |
| PBP-0401 | The signing secret is shorter than the minimum length this API accepts | 400 |
| PBP-0402 | The event list is absent, or it names an event type this API does not publish | 400 |

## Inbound provider webhook errors

***

These four codes answer the payment provider that posts settlement events to the webhook endpoint. They tell that caller which repair its delivery needs.

| `code` | Description | Status |
| - | - | - |
| PBP-0500 | The delivery signature did not authenticate | 401 |
| PBP-0501 | The delivery body is absent, does not parse, or breaks the envelope schema | 400 |
| PBP-0502 | The delivery body goes past the endpoint limit | 413 |
| PBP-0503 | A required envelope member arrives present and blank | 400 |


# Preflight the accounting routes of a ledger
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/preflight-accounting-routes

/en/openapi/v3-current/payments.yaml get /v1/admin/accounting-routes/preflight
Reports whether the plugin can post against one (organization, ledger) of the caller's tenant, and the state of each canonical flow there: BOLETO_IN, PAYMENT_OUT and DARF_OUT, each complete, absent, incomplete (with the missing route codes), ambiguous (with the repeated codes) or malformed (with the code and the reason).

The routes reported are the ORGANIZATION's: from Midaz v4.1.0 on, a listing through any ledger of the organization returns every route of it, so two ledgers of one organization report the same flows. `validateRoutes` and `ready` are the requested ledger's.

READ-ONLY. It reads the ledger live, with GET requests only, and bypasses the accounting routes cache: nothing is posted, cached or stored, so it is safe to run right after provisioning and as often as needed.

`ready` is the verdict on the WHOLE ledger: a flow reported complete in a ledger that is not ready still does not post. `reason` names the class of the verdict: accounting_routes_not_provisioned (ready: no canonical route, and the ledger does not validate routes), accounting_routes_required_but_absent, accounting_routes_incomplete, accounting_routes_ambiguous, accounting_routes_malformed, accounting_routes_dependency_unavailable, accounting_routes_access_denied or accounting_routes_unreadable. It is absent for a ledger that holds every canonical route.

The ACCOUNTING_ROUTES_ENABLED knob is REPORTED, NOT OBEYED: the verdict is judged as if it were on, because this is what runs before it is turned on, and its current value is in `accountingRoutesEnabled`.

The organization comes from the X-Organization-Id header (400 PBP-0025) and the ledger from the ledgerId query parameter (400 PBP-0026). An organization or ledger the ledger does not know, for this tenant, is answered 404 without saying which.



# Receive a provider webhook
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/receive-provider-webhook

/en/openapi/v3-current/payments.yaml post /v1/webhooks/btg
Accepts a settlement event pushed by the payment provider, persists it verbatim and returns 202 only after that persistence succeeds. This route is served only by a single-tenant deployment; a multi-tenant deployment serves the per-connection route at this path plus a connection token instead, and this document advertises both because it is generated without a deployment mode. If the deployment's storage is unavailable the event is not persisted and the response is 503 (retryable) instead of 202. Authentication is an HMAC-SHA256 signature over the raw request body, sent as lowercase hex in x-webhook-baas-signature and computed with a secret agreed with the provider, not the platform identity used by the rest of this API. The body is the provider envelope: pactualId, entity and status are required, clientRequestId and createTimestamp are optional, and any further member is accepted and stored as sent. Member names are matched without regard to case. The x-webhook-baas-entity and x-webhook-baas-event headers are optional copies of entity and status; where a header disagrees with the body the body is authoritative, because only the body is signed. The x-webhook-baas-notifyid header identifies the logical notification and, when sent, is what this endpoint deduplicates on; a delivery without it is still accepted and deduplicated on a key derived from pactualId, entity, status and createTimestamp. The x-webhook-baas-deliveryid header names one attempt to deliver that notification rather than the notification itself; it is optional, it decides nothing, and it is recorded only in this endpoint's logs, so that a delivery can be matched against the provider's own list of failed attempts. A delivery whose status names a provider TRANSPORT event rather than a business one — PING, which the provider's own webhook test emits and which belongs to no entity's event catalogue — is the single exception to all of the above: it is answered 202 without being deduplicated and without being persisted.



# Receive a provider webhook on a tenant connection
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/receive-provider-webhook-by-connection

/en/openapi/v3-current/payments.yaml post /v1/webhooks/btg/{connection_token}
Accepts a settlement event pushed by the payment provider on a per-tenant webhook connection, persists it verbatim and returns 202 only after that persistence succeeds. This route is served only by a multi-tenant deployment; a single-tenant deployment serves the unparameterised provider webhook route instead, and this document advertises both because it is generated without a deployment mode. The connection_token path segment names a webhook connection this service issued when a tenant connected the provider: it selects the tenant the delivery belongs to, the storage it is written to, and the key its signature is verified under. Authentication is an HMAC-SHA256 signature over the raw request body, sent as lowercase hex in x-webhook-baas-signature and computed with the secret agreed for that one connection, not a platform identity and not a key shared between tenants. A connection_token that names no connection, a connection that has been revoked, and a signature that does not match the body are refused with the same 401 and cannot be told apart. If the tenant's storage is unavailable the event is not persisted and the response is 503 (retryable) instead of 202. The body is the provider envelope: pactualId, entity and status are required, clientRequestId and createTimestamp are optional, and any further member is accepted and stored as sent. Member names are matched without regard to case. The x-webhook-baas-entity and x-webhook-baas-event headers are optional copies of entity and status; where a header disagrees with the body the body is authoritative, because only the body is signed. The x-webhook-baas-notifyid header identifies the logical notification and, when sent, is what this endpoint deduplicates on; a delivery without it is still accepted and deduplicated on a key derived from pactualId, entity, status and createTimestamp. The x-webhook-baas-deliveryid header names one attempt to deliver that notification rather than the notification itself; it is optional, it decides nothing, and it is recorded only in this endpoint's logs, so that a delivery can be matched against the provider's own list of failed attempts. A delivery whose status names a provider TRANSPORT event rather than a business one — PING, which the provider's own webhook test emits and which belongs to no entity's event catalogue — is the single exception to all of the above: it is answered 202 without being deduplicated and without being persisted.



# Re-present a quarantined provider webhook
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/represent-quarantined-webhook

/en/openapi/v3-current/payments.yaml post /v1/admin/quarantine/webhooks/{id}/represent
Returns ONE inbound provider webhook out of quarantine and back into the reconciliation sweep's claim set, with a full retry budget. Quarantine is the terminal PERMANENTLY_FAILED state: the service modelled the event, could not apply it within its retry budget, and stopped claiming the row. NOTHING IS APPLIED BY THIS CALL. It does not contact the ledger, does not contact the provider and does not change any boleto or payment. It changes one row of the webhook journal so that the ordinary drain picks the delivery up again on its next cycle, through exactly the same processing path every other delivery takes. Watch the drain, not this response, to learn whether the delivery finally applied. A request under a new Idempotency-Key for a row that is no longer in quarantine — because a previous call already released it, or because it never was — is refused with 409 PBP-0007 rather than released a second time. Fix the cause before re-presenting; a row released into the same failing condition simply returns to quarantine.



# Re-register the tenant's existing webhook subscription at a provider
Source: https://docs.lerian.studio/en/reference/interfaces/payments-btg/resubscribe-provider-webhook

/en/openapi/v3-current/payments.yaml post /v1/admin/providers/webhooks/{provider_type}/resubscribe
Re-registers this tenant's EXISTING webhook subscription at the provider, without rotating the connection.

WHAT IT DOES, EXACTLY: it reads the connection this tenant currently serves deliveries on, recomposes that connection's delivery URL, and sends the provider a subscription write carrying the declared resource set pointed at that URL. The connection record is untouched — same connection token, same signing key, same delivery URL — so a URL or a key you are already holding stays valid, and nothing you have configured elsewhere needs to change.

⚠️ WHAT IT DOES NOT DO, AND THE LIMIT IS THE POINT. When the provider reports a subscription as BLOCKED after repeated delivery failures, the procedure that returns it to service is NOT MEASURED by this service. This operation re-registers; whether the provider's consecutive-error counter resets, and whether deliveries resume, is something you OBSERVE afterwards — in the provider's own subscription state and in this service's webhook.subscription.blocked gauge — rather than something this call promises. Confirm the procedure with the provider before treating a blocked channel as repaired.

⛔ THE WRITE REPLACES THE PROVIDER'S RESOURCE ARRAY WHOLE, WHICH IS WHY IT READS BEFORE IT WRITES. The resources field of the answer is the entire set that is registered afterwards; any resource the provider held that is not in that list would no longer be subscribed, and the provider reports nothing about a removal. On a deployment where several consumers share one provider credential, that array is shared too, so the resource at risk may not even be yours. This operation therefore reads the subscription the provider currently holds under your credential BEFORE writing, and refuses with 409 if that subscription carries anything outside the set below — the answer then names resources that would have been removed, and nothing is written. The read exists only to refuse: the write's resource array is always the declared set and is never assembled from what the provider reports. If that read cannot be completed the call is refused with 502, because a read that failed says nothing about what the provider is holding.

⚠️ THERE IS ONE WAY PAST THAT 409, AND IT IS EXPLICIT: send the optional acknowledge_revoking naming exactly the resources the refusal reported. The call then proceeds and THOSE RESOURCES ARE REMOVED from the provider's subscription. The set is measured again on that call and compared against what you sent, so a name you left out — or a name the provider is not holding outside the declared set — is refused with another 409 saying which, and still writes nothing. It is NOT a conditional write: the provider offers none, so the window between this service reading the subscription and writing it is as open as it ever was. What the acknowledgement rules out is acting on a stale picture — a resource that appeared between the refusal you read and the call you sent makes your call FAIL instead of destroying something you never saw.

IT IS A LIVE TENANT'S SELF-SERVICE ACTION, AND THAT BOUNDS WHO YOU ACT AS, NOT WHAT YOU AFFECT. The tenant comes from the credentials you authenticate with and there is no tenant parameter anywhere in this request, so you cannot name somebody else. The provider, however, files ONE subscription per provider credential, not one per tenant: where several tenants share a credential, that single subscription is what this write re-points at YOUR tenant's delivery URL, and the others keep receiving deliveries only because their own health poller notices the registered address is not the one it composed and re-registers on its next tick. Which tenants share a credential is not something this service can see.

THE ANSWER CARRIES THE DELIVERY URL, WHICH IS A CREDENTIAL — the connection's routing token is a segment of it. Treat the response body as secret. It carries NO signing key.

A tenant with no connection to re-present, and a provider_type this deployment does not serve, are both refused with 404. The operation declares no Idempotency-Key: a retry re-executes, and re-executing sends the identical write.

⚠️ A RETRY OF A CALL THAT CARRIED acknowledge_revoking IS THE ONE EXCEPTION TO THAT, AND THE 409 IT ANSWERS PROVES LESS THAN IT LOOKS LIKE. Once a forced write has landed, the resources you acknowledged are gone from the provider's subscription — so on the retry they are no longer outside the declared set, your acknowledgement names something that is not there, and the call is refused with 409. That refusal reports one thing only: the set measured on this call is no longer the set you named. It is consistent with your first call having landed, and equally consistent with it never having reached the provider while some OTHER actor removed those resources in the meantime — on a shared provider credential, another consumer's own health poller is exactly such an actor. So it is not evidence of either on its own: do not read it as proof the write happened, and do not read it as "nothing was written" either. Check whether the removal already happened before re-sending, and re-send WITHOUT the field to see the current state. This is why a retry on a timeout should be a plain call, not a repeated force.



# Close Unsettled TED IN Credit
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/close-unsettled-ted-in-credit

/en/openapi/v3-current/ted.yaml post /v1/transfers/ted-in/unsettled/{messageId}/close
Use this endpoint to record where an unsettled inbound credit actually went, after a person moved it by hand. An inbound credit is unsettled when its message carries an open retention (neither credited nor returned), or when its devolution sits in `RETAINED` (a return that the tenant never authorized) or `FAILED` (a return that the clearing house refused).

No money moves here, and no ledger or JD call is made. Every outcome names an act performed outside this system, and this endpoint is the record of it:

- `RETURNED`: a person sent the funds back to the paying bank, out of band, under the return control number that the devolution row has kept since the day of receipt.
- `CREDITED`: a person credited the beneficiary.
- `ABSORBED`: the tenant keeps funds that reached neither end.

A credit written down twice, as an open retention and as a `RETAINED` devolution, is closed on both rows in one transaction or on neither. A retention that the poller resolves by itself is refused: the credit lands on its own once the blocking condition lifts, and declaring it settled would tell the tenant to keep money that the service is about to deliver.

This is a tenant-wide administrative action. It requires the `transfers:resolve` permission and a user token, because the closure records which person decided. It does not require the `X-Organization-Id` header. In multi-tenant deployments it is scoped to the caller's resolved tenant database.



# Create a Webhook Registration
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/create-webhook

/en/openapi/v3-current/ted.yaml post /v1/webhooks
Use this endpoint to register a tenant-scoped webhook endpoint that receives transfer event notifications. The registration is scoped to the caller's tenant, derived from the bearer JWT (`tenantId` claim), never from a request header.

The server generates the `signingSecret` and returns it **exactly once** in this response. Store it securely — it is never returned again. Use it to verify the signature on every delivered event. To obtain a new secret, call the rotate endpoint.

Use the `X-Idempotency` header for guaranteed deduplication. Repeated calls with the same key replay the cached response.



# Delete a Webhook Registration
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/delete-webhook

/en/openapi/v3-current/ted.yaml delete /v1/webhooks/{webhookId}
Use this endpoint to soft-delete a webhook registration. After deletion the endpoint stops receiving events. Only registrations belonging to the caller's tenant can be deleted.

Use the `X-Idempotency` header for guaranteed deduplication.



# Get TED IN Poller Status
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/get-ted-in-poller-status

/en/openapi/v3-current/ted.yaml get /v1/transfers/ted-in/poller
Use this endpoint to check whether the inbound TED poller is enabled, running, and stale, with its stop reason and last cycle timestamps, without scraping the readiness probe. The status uses the same rules as the TED IN poller check of `/readyz`, so the two cannot disagree on what stale or down means. A disabled poller (JD polling turned off) is a configuration fact: it answers `200` with `enabled: false`, not an error.

This is a read-only endpoint. It never provisions, starts, or resumes a poller. It does not require the `X-Organization-Id` header. In multi-tenant deployments the body describes the poller of the caller's resolved tenant, not the deployment-wide aggregate that the readiness probe publishes, and carries `tenantId`. In single-tenant deployments `tenantId` is omitted.



# Get a Webhook Registration
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/get-webhook

/en/openapi/v3-current/ted.yaml get /v1/webhooks/{webhookId}
Use this endpoint to retrieve a single webhook registration by ID. Only returns registrations belonging to the caller's tenant. The signing secret is never included in this response.



# List Retained TED IN Messages
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/list-retained-ted-in-messages

/en/openapi/v3-current/ted.yaml get /v1/transfers/ted-in/retained
Use this endpoint to list the inbound JD messages that this service neither credited nor returned, oldest first, so an operator can see what is stuck, why, for how long, and how much money is behind it.

By default (`state=open`) the list shows only what is still open. A retention closed through [Close Unsettled TED IN Credit](/en/reference/interfaces/ted-jd/close-unsettled-ted-in-credit) leaves this list and every retained gauge, which lets an alert on those numbers clear. `state=closed` or `state=all` bring the closed rows back, each with its outcome, its note, and the person who wrote it.

Six retention reasons are written. A person ends four of them:

- `UNRECOGNIZED_TYPE`: the message type is not one that this service consumes.
- `ACCOUNT_NOT_OWNED`: the recipient account is not one that this service owns.
- `CLASSIFICATION_FAILED`: the credit carries an amount that nothing can credit.
- `RECIPIENT_NOT_FOUND_RETURN_UNAUTHORIZED`: the recipient was not found, and the tenant has not authorized the automatic return to the clearing house.

Two end by themselves and carry `drained: false`:

- `LEDGER_ROUTE_UNRESOLVED`: no ledger routing binding answers the organization, ledger, and transfer type that the credit was refused for (`TED_OUT` for a chargeback compensation, which debits the beneficiary).
- `RECIPIENT_AMBIGUOUS_ORGANIZATIONS`: the recipient sits in several of the tenant's own organizations under the receiving ISPB.

These two are written only when the tenant's database carries the current migrations. Before that, a routing hold writes no row and appears on no list, so an empty list does not prove that no credit is held. The poller asks their question again on every cycle. When the configuration answers it, the credit lands and the row leaves this list with no operator action, so the close endpoint refuses them with BTF-0217. That check does not see a recipient re-homed in CRM: after such a repair, call [Replay TED IN Backlog](/en/reference/interfaces/ted-jd/replay-ted-in-poll), which re-drives every held row once. A credit held because the ISPB-to-organization binding could not be read writes no row and is not listed here. It lands by itself once the read recovers.

The `reason` filter also accepts `ACCOUNT_UNASSIGNED`, `AMBIGUOUS_CONTROL_ID`, and `OWNERSHIP_DECISION_UNAVAILABLE`. No row carries these reasons, so a filter on one of them returns an empty list.

Returning funds is irreversible; retention is not. Nothing from the original message is rendered: `contentBytes` says how much is held without showing any of it. A closed row carries the operator's note verbatim. The note is free text that a member of staff wrote about their own decision, 10 to 500 characters, never derived from the message and not sanitized. The retained records kept on the undeliverable side are listed by [List Undeliverable TED IN Credits](/en/reference/interfaces/ted-jd/list-undeliverable-ted-in-credits) with `status=RETAINED`.

This is a read-only administrative endpoint. It does not require the `X-Organization-Id` header. In multi-tenant deployments the list is scoped to the caller's resolved tenant database.



# List Undeliverable TED IN Credits
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/list-undeliverable-ted-in-credits

/en/openapi/v3-current/ted.yaml get /v1/transfers/ted-in/undeliverables
Use this endpoint to list the inbound TED credits that could not be delivered, so an operator can tell a recipient that does not exist from a ledger refusal, and see how far the re-querying of each one has got, without database access. The rejection reason is a fixed sentence derived from the category; no customer identity or upstream error text is exposed.

This is a read-only administrative endpoint. It does not require the `X-Organization-Id` header. In multi-tenant deployments the list is scoped to the caller's resolved tenant database.



# List DLQ Messages
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/list-webhook-dlq-messages

/en/openapi/v3-current/ted.yaml get /v1/webhooks/dlq
Use this endpoint to list messages currently in the webhook dead-letter queue, scoped to the caller's tenant. The tenant is derived from the bearer JWT (`tenantId` claim), never from a request header.

This route is only mounted when authentication is enabled and a DLQ inspector is configured. Otherwise it is not exposed and any request is rejected with 503.



# List Webhook Event Types
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/list-webhook-event-types

/en/openapi/v3-current/ted.yaml get /v1/webhooks/event-types
Use this endpoint to retrieve the deterministic inventory of event types accepted in webhook registrations. Use these values to populate the `eventTypes` field when creating or patching a registration.



# List Webhook Registrations
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/list-webhooks

/en/openapi/v3-current/ted.yaml get /v1/webhooks
Use this endpoint to retrieve a paginated list of webhook registrations for the caller's tenant. Set `enabled=true` to return only enabled registrations. Signing secrets are never included in this response.



# Replay TED IN Backlog
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/replay-ted-in-poll

/en/openapi/v3-current/ted.yaml post /v1/transfers/ted-in/replay
Use this endpoint to force one immediate replay pass over persisted, unprocessed JD inbound messages for the current tenant. Unlike `/ted-in/poll`, this route does not read JD's destructive queue — it only reprocesses durable backlog rows already persisted locally.

Use the `X-Idempotency` header for guaranteed deduplication.



# Resume TED IN Poller
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/resume-ted-in-poller

/en/openapi/v3-current/ted.yaml post /v1/transfers/ted-in/resume
Use this endpoint to clear the fail-closed at-most-once receive latch and re-arm a latched or dead TED IN poller without restarting the pod. This is a higher-privilege operator endpoint than `/ted-in/poll` because it re-opens JD destructive-read consumption. Reach for it only when auto-recovery cannot revive the poller — a panicked multi-tenant child or a single-tenant poller past the panic hard-cap.

Resume never bypasses the money-path durable-gap gate. When the live receive-state-unknown latch is set, the current latch's reconciliation-gap row must be durable before the poller resumes; otherwise the request is refused with `409` and the poller stays dead. Verify the pending gap with [List TED IN Reconciliation Gaps](/en/reference/interfaces/ted-jd/list-ted-in-reconciliation-gaps) before calling resume.

The optional body `{acknowledge, note}` additionally marks the current latch's reconciliation gap resolved and stamps an operator annotation on it. `acknowledge` defaults to `false`, leaving the gap OPEN so it remains visible for review. A healthy, not-latched poller returns `200` with `resumed: false` and `reason: "not_latched"` — the call is a safe idempotent no-op. Same-key retries replay the cached response.

The route is organization-independent and does not require the `X-Organization-Id` header — the tenant is resolved from the authenticated context. In multi-tenant deployments, an inactive tenant is rejected with `503`.



# Retry DLQ Message
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/retry-webhook-dlq-message

/en/openapi/v3-current/ted.yaml post /v1/webhooks/dlq/{messageId}/retry
Use this endpoint to re-publish a specific DLQ message back to the main webhook processing queue. Only messages belonging to the caller's tenant are eligible. The tenant is derived from the bearer JWT (`tenantId` claim).

This route is only mounted when authentication is enabled and a DLQ inspector is configured. Otherwise it is not exposed and any request is rejected with 503.



# Rotate a Webhook Signing Secret
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/rotate-webhook-signing-secret

/en/openapi/v3-current/ted.yaml post /v1/webhooks/{webhookId}/signing-secret/rotate
Use this endpoint to generate a new server-owned signing secret for a webhook registration. The new `signingSecret` is returned **only** in this response — store it securely and update your signature verification. The previous secret stops being valid. Only registrations belonging to the caller's tenant can be rotated.

Use the `X-Idempotency` header for guaranteed deduplication.



# Bank Transfer error list
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/ted-error-list

**Bank Transfer** returns structured error responses, so you can identify what went wrong and how to fix it.

**Error format**

```json JSON theme={null}
{
  "type": "https://errors.lerian.studio/v1/BTF-0203",
  "title": "Conflict",
  "status": 409,
  "detail": "this initiation has already been processed",
  "code": "BTF-0203",
  "category": "deterministic",
  "requestId": "6d3e2a68-1f2b-4c3d-9e4f-5a6b7c8d9e0f",
  "service": "plugin",
  "transferId": "019c96a0-ab10-7cde-f1a2-0e1f2a3b4c5d"
}
```

**Field definitions**

* **`type`** – A URI that names the error code: `https://errors.lerian.studio/v1/<code>`.
* **`title`** – The HTTP status text.
* **`status`** – The HTTP status code.
* **`detail`** – A human-readable explanation of this error.
* **`code`** – A stable identifier for the error (e.g. `BTF-0010`).
* **`requestId`** – Correlation ID for the request. Present even when empty. Include it in support requests.
* **`service`** – The service or domain that produced the error (e.g. `plugin`, `crm`, `midaz`, `fees`, `jd_spb`).
* **`category`** – Machine-readable error category for retry decisions: `deterministic`, `transient`, `rate_limit`, or `plugin`.
* **`errors`** – Optional. One entry for each rejected field, with `message` and `location` (`body.<field>` or `query.<field>`).
* **`upstream`** – Optional. The error code that an upstream provider, such as JD SPB, returned. It is on `upstream.code`, verbatim.

## Bank Transfer errors

***

The following errors can occur when interacting with the Bank Transfer endpoints. Each error follows our standard structure.

Refer to the tables below for a list of possible error codes, what they mean, and how to resolve them.

### 202

| `code` | Name | Description |
| - | - | - |
| BTF-9010 | Transfer Escalated To Reconciliation | The TED OUT advance failed, and the plugin escalated the transfer to reconciliation. The Midaz hold is intact. Poll `GET /v1/transfers/{transferId}` for the final status. The body is a problem document, not a transfer response. |

### 400

| `code` | Name | Description |
| - | - | - |
| BTF-0001 | Invalid Input | The request contains invalid fields. Check the field details below. |
| BTF-0210 | Retention Reason Invalid | The retention reason filter is outside the declared vocabulary. |
| BTF-0214 | Retained State Invalid | The `state` filter is not `open`, `closed`, or `all`. |

### 401

| `code` | Name | Description |
| - | - | - |
| BTF-0401 | Unauthorized | Authentication failed. The token is missing, invalid, or expired. |

### 403

| `code` | Name | Description |
| - | - | - |
| BTF-0403 | License Invalid | Organization is not licensed. Contact support to activate your license. |
| BTF-0405 | Forbidden | Insufficient permissions to perform this action. |
| BTF-0406 | Operator Identity Required | The token does not identify a person (a service account or a token of another type), so the plugin cannot attribute this by-hand write to an operator. No grant fixes this. Call the endpoint with a user token. |
| BTF-0408 | Tenant Suspended | The tenant manager refused this tenant access to the service. |

### 404

| `code` | Name | Description |
| - | - | - |
| BTF-0200 | Transfer Not Found | Transfer not found |
| BTF-0201 | Initiation Not Found | Initiation not found or belongs to different organization |
| BTF-0215 | Unsettled Incoming Not Found | The message carries nothing that an operator can close. A message that does not exist returns the same code. |
| BTF-0306 | Webhook Not Found | The webhook registration does not exist or belongs to another tenant. |
| BTF-0404 | Organization Not In Tenant | `X-Organization-Id` names an organization that this tenant does not operate. |
| BTF-0407 | Tenant Not Found | The tenant manager does not know the tenant that the token names. |
| BTF-0500 | Account Not Found | Sender account does not exist in CRM |
| BTF-1092 | Signing Artifact Not Found | The signing artifact was not found. |
| BTF-2001 | Midaz Account Not Found | The Midaz account was not found. |

### 409

| `code` | Name | Description |
| - | - | - |
| BTF-0012 | Duplicate Transfer | Duplicate transfer detected |
| BTF-0016 | Idempotency Request In Progress | A request under this `X-Idempotency` key still holds the in-flight lease. While the first request still runs, resend the identical request after the `Retry-After` interval. If an earlier request under this key answered 5xx, no answer comes from it: read the resource, and send the work under a new key only if it did not land. |
| BTF-0018 | Idempotency Replay Unavailable | The request under this `X-Idempotency` key already completed, and its response was too large to store for replay. Read the resource. Do not resend under a new key, because that runs the work a second time. |
| BTF-0107 | TED IN Poller Busy | Another TED IN poll or replay cycle is already in progress for this tenant. Try again when it finishes. |
| BTF-0108 | Resume Gap Not Durable | The poller resume was refused. The receive-state-unknown latch has no durable reconciliation gap yet, so the poller stays stopped. Retry after the gap row is persisted. |
| BTF-0109 | Manual Retry State Mismatch | The transfer is not a `TED_OUT` parked in `PROCESSING` and `MANUAL_REVIEW` (or its legacy equivalent `EXHAUSTED`) with a preserved hold. Nothing was written, and a repeat cannot change that. |
| BTF-0110 | Manual Resolution Not Allowed | This action does not resolve this transfer, and nothing was resolved. Read the transfer again. |
| BTF-0111 | Ledger State Contradicts Resolution | The ledger contradicts the requested resolution. Issue the other action. |
| BTF-0112 | Initiation Predates Scoped Routing | The initiation was created before ledger-scoped routing and cannot be processed. Nothing was written. Initiate the transfer again. |
| BTF-0113 | Transfer Scope Not Repairable | The transfer has nothing to repair, for example because its ledger is already set or another operator repaired it first. Read the transfer again. |
| BTF-0114 | Transfer Scope Ledger Mismatch | CRM reports a different ledger for the account of this transfer. Nothing was written, and the response does not echo either ledger. |
| BTF-0115 | Posting Not Completable | The ledger holds a live posting for this chargeback, and this service cannot complete the chargeback on it. Read that transaction in the ledger, settle what remains outside this platform, and close the transfer with `SETTLED_BY_HAND`. |
| BTF-0116 | Refund Cancelled | A hand `RE_POST` filed its refund, and the ledger cancelled it, so it paid nothing. Issue `RE_POST` again to file a new refund. |
| BTF-0117 | Refunded Twice | The ledger holds more than one live refund for this chargeback. Nothing was posted, and the transfer was not closed. Do not issue `RE_POST` again. Read every transaction in `transactionIds`. If `liveRefundSetComplete` is `false`, `transactionIds` does not name every live refund: find the others in the ledger. Return the surplus to the beneficiary outside this platform, then close the transfer with `SETTLED_BY_HAND`. |
| BTF-0203 | Already Processed | This initiation has already been processed |
| BTF-0216 | Unsettled Incoming Already Closed | Somebody already recorded where this money went. Read that decision before you write another. |
| BTF-0217 | Retention Resolves Automatically | This retention ends by itself, so do not close it by hand. The credit lands once its ledger route or ownership answer arrives. Fix that configuration instead. |
| BTF-0305 | DLQ Retries Exceeded | The DLQ message exceeded the maximum number of manual retry attempts. |
| BTF-0307 | Rotation Conflict | A signing-secret rotation is already in progress for this webhook registration. Retry the rotation. |
| BTF-1094 | Signing Artifact Used | The signing artifact was already used. |
| BTF-1095 | Signing Artifact Mismatch | The signing artifact does not match the expected payload. |
| BTF-2002 | Midaz State Conflict | Midaz reported a transaction state conflict. |
| BTF-9009 | Reconciliation Cycle Busy | A reconciliation sweep is already in progress. Retry after the `Retry-After` delay. |

### 410

| `code` | Name | Description |
| - | - | - |
| BTF-0202 | Initiation Expired | Initiation expired after 24 hours. Create a new initiation. |
| BTF-1093 | Signing Artifact Expired | The signing artifact expired. The error carries `expiresAt`. |

### 422

| `code` | Name | Description |
| - | - | - |
| BTF-0002 | Domain Validation | The payload violates a domain rule, for example an invalid webhook endpoint URL or an unsupported event type. |
| BTF-0003 | Payload Field Missing | The STR0008 payload is missing a required field. |
| BTF-0004 | Unsupported Type | The operation does not support this transfer type, for example signing prepare on a transfer that is not a TED OUT. |
| BTF-0010 | Operating Hours Violation | Transfers can only be initiated Monday-Friday between 06:30 and 17:00 Brasília time |
| BTF-0011 | Limit Exceeded | Transfer amount exceeds daily limit |
| BTF-0013 | Constraint Violation | The data violates a database constraint. |
| BTF-0014 | Idempotency Outcome Unrecorded | An earlier request under this `X-Idempotency` key answered 5xx, so the key is fenced for the retention window. Read the resource and, only if the work did not land, send the identical request under a new key. |
| BTF-0015 | Idempotency Record Unusable | This service cannot read the idempotency record under this key. Read the resource and, only if the work did not land, send the identical request under a new key. |
| BTF-0017 | Idempotency Key Reused | This `X-Idempotency` key was already used for a different request. A repeat must be byte-identical, and a new request needs a new key. |
| BTF-0204 | Cannot Cancel | Transfer cannot be cancelled in its current status. Only CREATED or PENDING transfers can be cancelled. |
| BTF-0501 | CRM Invalid Response | The CRM account record is missing a required field (`organizationId`). Contact your platform team to fix the account data in the CRM. |
| BTF-1001 | JD SPB Rejected | JD SPB rejected the transfer. The JD code is on `upstream.code`. |
| BTF-1090 | Signing Artifact Required | A TED OUT needs a signing artifact before it is processed. |
| BTF-1096 | Invalid Signature | The digital signature is missing or invalid. |
| BTF-2003 | Midaz Validation | Midaz rejected the transaction request. |
| BTF-2004 | Midaz Transaction Denied | The Tracer of the Midaz ledger denied the transfer under a limit or a rule. Nothing was posted. |
| BTF-2005 | Midaz Fee Refused | In `native` fee mode, the Midaz Fees Engine refused to price the transfer. For example, two fee packages match it equally (Midaz refuses such a posting with error `0198`), or a fee taken out of the amount is larger than the amount. This code covers every Midaz fee error, `0179` to `0233`. Nothing was posted. Correct the fee packages, then initiate the transfer again. |
| BTF-3002 | Deductible TED OUT Fee | The fee package that matches a TED OUT takes the fee out of the amount. A TED OUT charges its fee on top of the amount, so set `isDeductibleFrom: false` on the fees of that package and initiate again. Nothing reached JD. When the error carries `transferId`, an earlier process call of this initiation reserved that transfer, and any ledger hold it placed stays until an operator releases it. |
| BTF-4003 | Payee Not Held Here | The recipient account is on this institution, but this engine does not hold it. The transfer was not created. |
| BTF-4004 | Payee Key Unusable | The CRM record of the recipient cannot be keyed for the ownership map. Correct the branch and account of the recipient in CRM. A retry does not help. The transfer was not created. |

> [!NOTE]
>
> When JD SPB answers an error with its own code, the problem document carries that code verbatim on `upstream.code`. Examples are `ACE95` for request timeouts, `AAC90` for invalid signature rejections, and `ALN01` for control-number-not-found responses. Refer to the JD SPB vendor documentation for the full list and the corresponding retry policy for each code.

### 429

| `code` | Name | Description |
| - | - | - |
| BTF-0429 | Rate Limited | Too many requests. Retry after the interval indicated by the `Retry-After` header. |

> [!NOTE]
>
> Rate-limit responses use the `rate_limit` category and include a `Retry-After` header. Back off using HTTP status `429` and that header.

### 500

| `code` | Name | Description |
| - | - | - |
| BTF-0106 | Manual Reconciliation Required | A cancellation could not confirm or record the Midaz hold state. Manual reconciliation is required. |
| BTF-9000 | Internal Error | An unexpected error occurred. Contact support if it persists. |
| BTF-9002 | Post-Dispatch Failure | The transfer was sent, but the bookkeeping after dispatch failed. Do not retry. The error carries `transferId` and `transferStatus`. |
| BTF-9006 | Unexpected Empty Response | The service layer returned an unexpected empty response. |
| BTF-9011 | Transfer Stranded | When the TED OUT advance and its escalation to reconciliation both failed, reconciliation picks up the transfer within ten minutes and releases its hold once the clearing house is open again, so do not retry `/process`. When a duplicate TED OUT request was caught after the Midaz hold and its revert failed, check Midaz for an unreconciled hold before you retry `/process`. |
| BTF-9012 | Origin ISPB Missing | The deployment has no origin ISPB configured, so the transfer type cannot be classified. |
| BTF-9014 | Ledger Moved, Row Unwritten | The ledger moved, and the transfer did not reach its final state. Read the transfer, then send the identical request again under a new `X-Idempotency` key. The repeat converges on the ledger state of this transfer, so it cannot move money twice. If the repeat does not clear the error, the transfer needs manual inspection. |

### 502

| `code` | Name | Description |
| - | - | - |
| BTF-0501 | CRM Invalid Response | The CRM returned an ambiguous or unparseable response. Contact your platform team. (BTF-0501 also appears under 422 when the CRM record is missing a required field.) |
| BTF-1007 | JD Credentials Rejected | JD SPB rejected the credentials. The JD code is on `upstream.code`. |
| BTF-1008 | JD Certificate Rejected | JD SPB rejected the signing certificate or the digital signature. The JD code is on `upstream.code`. |
| BTF-1009 | JD Configuration Rejected | JD SPB rejected the configuration. The JD code is on `upstream.code`. |
| BTF-3001 | Fees Invalid Response | The fee service returned an invalid or unparseable response. Contact your platform team. |
| BTF-4001 | Ownership Map Invalid Response | The ownership map returned an answer that could not be used. The transfer was not settled. |

### 503

| `code` | Name | Description |
| - | - | - |
| BTF-0019 | Idempotency Key Unprotected | The work under this `X-Idempotency` key ran, and neither its response nor its outcome fence could be stored. The key protects nothing, so a resend can run the operation a second time. Read the resource before you send anything else. |
| BTF-0020 | Idempotency Receipt Unstored | The work under this `X-Idempotency` key ran, and its response could not be stored for replay, but the key is still held. Read the resource, and resend under a new key only if the work did not land. |
| BTF-0402 | Authorization Unavailable | The Access Manager did not answer, so the request was refused. Try again later. |
| BTF-0409 | Tenant Resolution Unavailable | The tenant manager or its connection pool did not answer, so the database of this tenant could not be resolved. Try again later. |
| BTF-0410 | Tenant Not Provisioned | The tenant has no database for this service. A retry does not help: the onboarding of the tenant has to be completed. |
| BTF-0502 | CRM Service Unavailable | Unable to validate account. The CRM service is temporarily unavailable. Try again later. |
| BTF-0503 | CRM Auth Failure | CRM rejected the credentials of Bank Transfer. |
| BTF-1000 | JD SPB Unavailable | JD SPB is unavailable. |
| BTF-1003 | JD SPB Timeout | JD SPB timed out. |
| BTF-2000 | Midaz Unavailable | Unable to process transfer. The Midaz ledger service is temporarily unavailable, or it refused the Midaz credentials of Bank Transfer. If Midaz is unavailable, try again later. A refused credential does not clear on retry: check its permissions. In `native` fee mode, it needs `packages` (`get`) and `estimates` (`post`). With `MIDAZ_FEE_MODE=native` set explicitly, it also needs `organizations` (`get`). |
| BTF-3000 | Fee Service Unavailable | Unable to calculate fee. The fee service is temporarily unavailable. Try again later. |
| BTF-4000 | Ownership Map Unavailable | The ownership map is unavailable, and the transfer was not settled. Try again later. |
| BTF-4002 | Ownership Lookup Refused Locally | The plugin refused the ownership lookup locally. Nothing was sent, and the transfer was not settled. |
| BTF-9000 | Idempotency Store Unavailable | The idempotency store was not available, so the plugin did not run the request. Send the same request again under the same `X-Idempotency` key. |
| BTF-9001 | Usage Limit Service Unavailable | The usage-limit service is temporarily unavailable, so the transfer cannot proceed. |
| BTF-9003 | Duplicate Guard Unavailable | The duplicate check service is unavailable. |
| BTF-9004 | Reconciliation Subsystem Unavailable | The reconciliation subsystem is unavailable. |
| BTF-9005 | Dependency Not Configured | A required service dependency is not configured. |
| BTF-9007 | Repository Timeout | A database operation timed out. |
| BTF-9008 | Repository Unavailable | The database is unavailable. |
| BTF-9015 | Route Config Missing | A routing configuration could not be read. The `systemplaneKey` field names the configuration document. |
| BTF-9016 | Schema Not Ready | The database of this tenant cannot record this write, and nothing was written. Apply the pending migrations to this tenant, then send the identical request again under a new `X-Idempotency` key. |
| BTF-9017 | Organization Scope Unavailable | The organization list of the tenant is absent or unreadable. Retry with the same idempotency key once it is configured. |
| BTF-9018 | Tenant ISPB Set Invalid | The tenant binds more than one ISPB, so its identity on the clearing house cannot be decided. Nothing was written. |


# Patch a Webhook Registration
Source: https://docs.lerian.studio/en/reference/interfaces/ted-jd/update-webhook

/en/openapi/v3-current/ted.yaml patch /v1/webhooks/{webhookId}
Use this endpoint to update one or more fields of a webhook registration. Only the fields present in the request body are changed. Sending `eventTypes` as `null` clears the filter so the registration receives every event type. Only registrations belonging to the caller's tenant can be patched.

Use the `X-Idempotency` header for guaranteed deduplication.



# Access Manager API overview
Source: https://docs.lerian.studio/en/reference/platform/access-manager/am-api-introduction

Access Manager exposes Auth and Identity APIs to handle authentication, authorization, and user and application management across the Lerian ecosystem.

> [!TIP]
>
> **This section is for developers.** If you're looking for a business-level overview of Access Manager, see [Access Manager](/en/platform/access-manager).

Access Manager provides two services that handle authentication, authorization, and identity management across the Lerian ecosystem.

Use these APIs to authenticate users, manage M2M connections, and control access permissions programmatically.

## API architecture

***

Access Manager has two services, each with its own APIs:

> **[Auth APIs](/en/reference/platform/access-manager/am-auth-apis)**
>
> Manages authentication flows, tokens, and session control.

> **[Identity APIs](/en/reference/platform/access-manager/am-identity-apis)**
>
> Manages users, groups, applications, providers, application-provider links, and MFA configuration.

> **[Error list](/en/reference/platform/access-manager/access-manager-error-list)**
>
> Review Auth and Identity error codes.

## API requirements

***

> [!CAUTION]
>
> With Access Manager enabled, protected product APIs require authentication.
>
> Every request must include an `Authorization` header with a valid Bearer token. A request without a valid token gets a `401 Unauthorized` response.

### Request headers

All authenticated requests must include:

```http theme={null}
Authorization: Bearer {access_token}
```

### Token expiration

* Access tokens expire after **3600 seconds (1 hour)**
* Refresh tokens expire after **24 hours**
* Plan token refresh before expiration to avoid service interruption

## Endpoint groups

***

Use these overview pages to find the endpoint you need:

* [Auth APIs](/en/reference/platform/access-manager/am-auth-apis): token requests, token refresh, logout, user information, permission checks, and MFA login challenges.
* [Identity APIs](/en/reference/platform/access-manager/am-identity-apis): users, groups, applications, providers, provider links, and MFA management.
* [Access Manager error list](/en/reference/platform/access-manager/access-manager-error-list): error codes returned by Auth and Identity.

## Next steps

***

* Review the [Using Access Manager](/en/platform/access-manager/using-access-manager) guide for workflow examples.
* Learn about [Access Manager Components](/en/platform/access-manager/am-components) architecture.
* Check [Best Practices](/en/platform/access-manager/am-best-practices) for security recommendations.


# Auth APIs
Source: https://docs.lerian.studio/en/reference/platform/access-manager/am-auth-apis

Authenticate users and M2M applications, refresh access tokens, revoke sessions, and complete MFA challenges through the Access Manager Auth APIs.

With the Auth APIs, you can authenticate users and applications, refresh tokens, and manage user sessions.

Use these endpoints when a client needs runtime access: issuing tokens, refreshing sessions, retrieving the authenticated profile, checking permissions, or completing MFA login challenges.

## Available Endpoints

***

### Authentication API

Manage access tokens and user sessions:

* [**Request an Access Token**](/en/reference/platform/access-manager/request-access-token) - Authenticate users with password grant or M2M applications with client credentials.
* [**Refresh the Access Token**](/en/reference/platform/access-manager/refresh-token) - Renew expired access tokens using a refresh token.
* [**End User Session**](/en/reference/platform/access-manager/end-user-session) - Revoke active tokens and terminate user sessions.

### Single sign-on API

Start a single sign-on login from the login screen:

* [**Discover How an Email Signs In**](/en/reference/platform/access-manager/discover-how-an-email-signs-in) - Find out whether a person signs in with a password or an SSO provider.
* [**Start an SSO Login**](/en/reference/platform/access-manager/start-an-sso-login) - Send the browser to the SSO provider of the person's tenant.

### Authorization API

Control access permissions:

* [**Validate User Permission**](/en/reference/platform/access-manager/validate-user-permission) - Check if a user has permission to perform a specific action.

### User Information API

Retrieve authenticated user details:

* [**Retrieve User Information**](/en/reference/platform/access-manager/retrieve-user-information) - Get basic information about the authenticated user.
* [**Retrieve User Permissions**](/en/reference/platform/access-manager/retrieve-user-permissions) - List all permissions assigned to the authenticated user.

### MFA Login API

Complete MFA challenges during authentication:

* [**Initiate MFA Challenge**](/en/reference/platform/access-manager/initiate-mfa-challenge) - Start a login challenge for a user with MFA enabled.
* [**Verify MFA Login**](/en/reference/platform/access-manager/verify-mfa-login) - Verify the MFA login passcode and complete authentication.

## Related references

***

* [Identity APIs](/en/reference/platform/access-manager/am-identity-apis) - Manage the users, applications, providers, and MFA settings used by Auth.
* [Access Manager error list](/en/reference/platform/access-manager/access-manager-error-list) - Review Auth error codes.


# Identity APIs
Source: https://docs.lerian.studio/en/reference/platform/access-manager/am-identity-apis

Create and manage users, M2M applications, permission groups, identity providers, and MFA settings across tenants with the Access Manager Identity APIs.

With the Identity APIs, you can create and manage user accounts, configure M2M applications, and query permission groups. You can also configure providers, link providers to applications, and manage MFA settings. On Lerian Cloud, the bearer token determines the scope of user, group, and application results. Clients should not pass tenant ownership through request payloads.

## Available Endpoints

***

### Groups API

Query permission groups:

* [**List Groups**](/en/reference/platform/access-manager/list-groups)
* [**Retrieve Group Details**](/en/reference/platform/access-manager/retrieve-group-details) - Get detailed information about a specific group, including assigned users.

Use the group IDs returned here when creating or updating users.

### Applications API

Manage M2M application credentials:

* [**Create an Application**](/en/reference/platform/access-manager/create-an-application) - Register a new application for machine-to-machine authentication.
* [**List Applications**](/en/reference/platform/access-manager/list-applications)
* [**Retrieve Application Details**](/en/reference/platform/access-manager/retrieve-application-details) - Get detailed information about a specific application.
* [**Delete an Application**](/en/reference/platform/access-manager/delete-application) - Remove an application and its credentials.

Current M2M application names include `midaz`, `plugin-fees`, `plugin-crm`, `reporter`, `plugin-br-pix-jd`, `plugin-br-pix-indirect-btg`, and `plugin-br-bank-transfer`.

### Partners API

Manage partners and read the scope catalog of each product:

* [**List Partners**](/en/reference/platform/access-manager/list-partners) - Retrieve the partners of your organization.
* [**Create a Partner**](/en/reference/platform/access-manager/create-a-partner) - Register one of your customers as a partner.
* [**Retrieve a Partner**](/en/reference/platform/access-manager/retrieve-a-partner) - Get the full details of one partner.
* [**Update a Partner**](/en/reference/platform/access-manager/update-a-partner) - Change the access, validity window, IP allowlist, or state of a partner.
* [**Delete a Partner**](/en/reference/platform/access-manager/delete-a-partner) - Remove a partner that has no applications.
* [**Retrieve the Partner Ceiling of a Product**](/en/reference/platform/access-manager/retrieve-the-partner-ceiling-of-a-product) - Get the most that a partner can receive in one product.
* [**List Scope Catalogs**](/en/reference/platform/access-manager/list-scope-catalogs) - Retrieve the scope dimensions of each product that publishes them.
* [**Retrieve a Product's Scope Catalog**](/en/reference/platform/access-manager/retrieve-a-product-s-scope-catalog) - Get the scope dimensions of one product.

### Providers API

Manage communication providers for MFA delivery:

* [**List Providers**](/en/reference/platform/access-manager/list-providers) - Retrieve available communication providers.
* [**Create a Provider**](/en/reference/platform/access-manager/create-a-provider) - Create a new communication provider.
* [**Retrieve a Provider**](/en/reference/platform/access-manager/retrieve-a-provider) - Get details for a specific provider.
* [**Update a Provider**](/en/reference/platform/access-manager/update-a-provider) - Update provider configuration.
* [**Delete a Provider**](/en/reference/platform/access-manager/delete-a-provider) - Remove a provider.

### Application Providers API

Manage provider links for applications:

* [**List Application Providers**](/en/reference/platform/access-manager/list-application-providers) - Retrieve providers linked to an application.
* [**Link Provider to Application**](/en/reference/platform/access-manager/link-provider-to-application) - Link a provider to an application.
* [**Update Application Provider Link**](/en/reference/platform/access-manager/update-application-provider-link) - Update a provider link.
* [**Unlink Provider from Application**](/en/reference/platform/access-manager/unlink-provider-from-application) - Remove a provider link from an application.
* [**Set Default Application Provider**](/en/reference/platform/access-manager/set-default-application-provider) - Select the default provider for an application.

### Users API

Manage user accounts and credentials:

* [**Create a User**](/en/reference/platform/access-manager/create-user) - Create a new user account with group assignments.
* [**List Users**](/en/reference/platform/access-manager/list-users)
* [**Retrieve User Details**](/en/reference/platform/access-manager/retrieve-user-details) - Get detailed information about a specific user.
* [**Update a User**](/en/reference/platform/access-manager/update-user) - Modify user information and group memberships.
* [**Delete a User**](/en/reference/platform/access-manager/delete-user) - Remove a user from the system.
* [**Reset a User Password**](/en/reference/platform/access-manager/reset-user-password) - Reset a user's password (admin action).
* [**Update a User Password**](/en/reference/platform/access-manager/update-user-password) - Change a user's password with current password verification.
* [**List Own Tenants**](/en/reference/platform/access-manager/list-own-tenants) - List the tenants where your email has an active account.
* [**Set Own Default Tenant**](/en/reference/platform/access-manager/set-own-default-tenant) - Choose the tenant that your next sign-in goes to.

### MFA API

Manage MFA setup and user MFA preferences:

* [**Initiate MFA Setup**](/en/reference/platform/access-manager/initiate-mfa-setup) - Start MFA setup for a user.
* [**Verify MFA Passcode**](/en/reference/platform/access-manager/verify-mfa-passcode) - Verify an MFA setup passcode.
* [**Enable MFA**](/en/reference/platform/access-manager/enable-mfa) - Enable MFA after setup verification.
* [**Get MFA Status**](/en/reference/platform/access-manager/get-mfa-status) - Retrieve the current MFA status for a user.
* [**Set Preferred MFA Method**](/en/reference/platform/access-manager/set-preferred-mfa-method) - Change the user's preferred MFA method.
* [**Request an MFA Disable Confirmation Code**](/en/reference/platform/access-manager/request-an-mfa-disable-confirmation-code) - Send a code by email that confirms an MFA disable.
* [**Disable MFA**](/en/reference/platform/access-manager/disable-mfa) - Disable MFA for a user.

## Related references

***

* [Auth APIs](/en/reference/platform/access-manager/am-auth-apis) - Request tokens, refresh tokens, retrieve user information, and validate permissions.
* [Access Manager error list](/en/reference/platform/access-manager/access-manager-error-list) - Review Identity error codes.


# Add Permissions to a User
Source: https://docs.lerian.studio/en/reference/platform/access-manager/assigns-permissions-to-a-user

/en/openapi/v3-current/AM-identity.yaml post /v1/users/{id}/permissions
Grants permissions straight to one person, bypassing roles and groups.

Reach for this last. A direct grant has to be revoked person by person. The maintainable path is to grant the role to a group and manage membership.

Granting a permission the person already holds directly is not an error. On success the response has no body (204).

Failures:
- `400` — `permissions` is missing or empty.
- `404` — no such user in your organization, or one of the permissions does not exist.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Add Members to a Group
Source: https://docs.lerian.studio/en/reference/platform/access-manager/assigns-users-to-a-group

/en/openapi/v3-current/AM-identity.yaml post /v1/groups/{id}/users
Puts one or more people into a group.

`{id}` is the group's `name`, a slug such as `midaz-viewer-group`; each entry in `users` is a user id. Called after a person is created, and whenever someone changes team.

Adding somebody already in the group is not an error: the call is idempotent per member, so a partially applied form can safely be submitted again. On success the response has no body (204).

Failures:
- `400` — `users` is missing or empty.
- `404` — no such group in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Create a Group
Source: https://docs.lerian.studio/en/reference/platform/access-manager/create-a-group

/en/openapi/v3-current/AM-identity.yaml post /v1/groups
Creates a group. `name` is the identifier you will address it by everywhere else — it is NOT a generated UUID, and it cannot be changed afterwards; `displayName` is the label people see and can be changed at any time.

A new group is empty and grants nothing. Add people with `POST /v1/groups/{id}/users` and grant it roles with `POST /v1/roles/{id}/groups`; until both happen the group has no effect on anyone's access.

Failures:
- `400` — a required member is missing.
- `409` — a group with that `name` already exists in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Create a partner
Source: https://docs.lerian.studio/en/reference/platform/access-manager/create-a-partner

/en/openapi/v3-current/AM-identity.yaml post /v1/partners
Registers one of your customers as a partner and fixes, up front, everything its future credentials will be allowed to reach: `permissions` says WHAT it may do in each product (collections × verbs) and `scope` says WHERE (which organization, which ledgers). The two are combined with AND at every request, so a partner reaches only the intersection.

This is the FIRST call in the flow. Nothing is issued here — no credential, no secret. Once the partner exists you create M2M applications against it with `POST /v1/applications { "partnerId": "<the id returned here>" }`, one per product, and hand the resulting clientId/clientSecret to the customer. A partner with no application is inert.

On success a new record is created in YOUR organization (resolved from your token — there is no tenant field to send) with a server-generated UUID `id`, state `active`, and the permissions, scope, validity window and IP allowlist you supplied. Nothing in any product changes: the scope values are recorded, never verified against the product and never created there.

Failures:
- `400 IDE-1042` — a scope `field` is not one the product's published scope catalog declares. `GET /v1/scope-catalog/{product}` lists the accepted dimensions; the message names the offending field.
- `400 IDE-0001` (scope) — the product's catalog marks a dimension `required` and the scope has no line for it.
- `400 IDE-0002` (scope) — several values on a dimension the catalog does not mark `multi`.
- `400 IDE-1043` — a permission asks for a resource, an action, or a resource/action pair that no ONE enabled permission bound to your organization's `<product>-editor-role` holds, or that role holds nothing in the product. That is the ceiling; you cannot delegate more than you hold. Each permission of the role counts on its own: a pair is allowed only when one permission holds both its resource and its action, so a verb held for one resource is never borrowed by another. The message names the offending resource, action or pair; drop it from the line, or have it granted to the editor role first.
- `400 IDE-1054` — a permission names a product that is not ready for partners yet: it has not published a scope catalog, so a partner could not be narrowed to any of its instances. The message names the offending `permissions[i].product`; remove that line.
- `400 IDE-1055` — a permission names a product that has a scope catalog but has not opted in to partners (its manifest does not declare `partners: true`; `GET /v1/scope-catalog/{product}` shows `partners: false`). Nothing in your request can change that: remove the line, or wait for the product to publish the opt-in. `errors[0].location` is `body.permissions[i].product`.
- `400 IDE-1056` — a permission grants a write (`post`, `put`, `patch`, `delete`) that the product performs at a level wider than the partner's scope: a partner confined to one ledger cannot be granted creating ledgers, which acts on the whole organization. The product's levels are in `GET /v1/scope-catalog/{product}` (`levels`). Remove that action, or scope the partner at the level the write needs. `errors[0].location` is `body.permissions[i]`; nothing is written.
- `400 IDE-1052` — any other refusal of the identity provider; the message repeats its code and sentence.
- `400 IDE-1044` — a product appears in `scope` but not in `permissions`, which would authorize nothing.
- `400 IDE-1045` — `validUntil` is not later than `validFrom`.
- `400 IDE-1047` — `"*"` was used in `permissions.resources` or `permissions.actions`. A wildcard means allow-all and is refused; list the values.
- `400 IDE-1048` — `ipAllowlist` is an empty array. Omit it or send null to inherit the organization's list.
- `400 IDE-0036` / `400 IDE-1050` — an `ipAllowlist` entry has an unparseable `cidr`, or the same network appears twice.
- `409 IDE-1040` — `displayName` is already used by another partner of yours.
- `403` — your token does not hold the `partners` resource.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Create an Application
Source: https://docs.lerian.studio/en/reference/platform/access-manager/create-an-application

/en/openapi/v3-current/AM-identity.yaml post /v1/applications
Registers an application and issues its credentials.

⚠️ The response carries the `clientSecret` IN FULL, and no other Identity API response returns it. Store it when you receive it; a later read of the same application does not show it again. Losing it means deleting the application and creating another.

Send `partnerId` to bind the credential to one of your customers: the application is then confined to that partner's permissions and scope, and reaches only the intersection of the two.

Failures:
- `400` — a required member is missing or malformed.
- `404 IDE-1046` — `partnerId` names a partner that does not exist in your organization.
- `503 IDE-0064` — another application for the same product is being created in your organization at the same moment. Creates for one product are applied one at a time, so this request waits up to about 10 seconds for its turn and answers this only if the other create is still running. Nothing about the request was wrong and nothing was created; retry it.
- `503 IDE-0065` — the service that coordinates concurrent creates did not answer within that wait. Nothing was created; retry it.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Create a user
Source: https://docs.lerian.studio/en/reference/platform/access-manager/create-user

/en/openapi/v3-current/AM-identity.yaml post /v1/users
Creates a user in your organization and places it in the groups you name, which is what gives it its permissions.

This is the first call in a member's life cycle. The password you supply is the initial one; the member changes it through `PATCH /v1/users/{id}/update-password`, and an administrator resets it through `PATCH /v1/users/{id}/reset-password`.

`phone` and `countryCode` travel TOGETHER — the identity provider validates the number against the country and refuses an unresolvable pair.

Failures:
- `400` — a required member is missing, or `email`/`phone` is malformed.
- `409 IDE-0017` — the username or e-mail already belongs to another user.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Delete a Group
Source: https://docs.lerian.studio/en/reference/platform/access-manager/delete-a-group

/en/openapi/v3-current/AM-identity.yaml delete /v1/groups/{id}
Removes an empty group permanently. A group that still has members, or that other groups are nested under, is NOT deleted: the request is refused and nothing changes. Remove the members with the group's member routes first — each of them then stops holding whatever the group granted, which for someone whose only access came through this group means losing it entirely.

On success the response has no body (204).

Failures:
- `404` — no such group in your organization.
- `409 IDE-1058` — the group still has members; remove them, then delete the group.
- `409 IDE-1059` — other groups are nested under this one; delete or move them first.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Delete a partner
Source: https://docs.lerian.studio/en/reference/platform/access-manager/delete-a-partner

/en/openapi/v3-current/AM-identity.yaml delete /v1/partners/{id}
Removes a partner permanently. This is not the way to pause a partner — use `PATCH` with `state: "suspended"` for that, which is reversible.

Called at the end of a partner's life, after its credentials have been revoked. The delete is refused while any application still points at the partner, so the order is: delete the applications, then delete the partner.

On success the record is gone and the response has no body (204).

Failures:
- `409 IDE-1049` — applications are still attached. The problem document's `errors` list names each blocking application.
- `404 IDE-1046` — no such partner in your organization.
- `422` — `id` is not a UUID.
- `403` — your token does not hold the `partners` resource.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Delete an Application
Source: https://docs.lerian.studio/en/reference/platform/access-manager/delete-application

/en/openapi/v3-current/AM-identity.yaml delete /v1/applications/{id}
Removes an application and revokes its credentials.

Deleting every application attached to a partner is also the prerequisite for deleting the partner itself, which is refused while any credential still points at it.

On success the response has no body (204).

Failures:
- `404` — no such application in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Delete a user
Source: https://docs.lerian.studio/en/reference/platform/access-manager/delete-user

/en/openapi/v3-current/AM-identity.yaml delete /v1/users/{id}
Removes a user permanently. Its group and role memberships go with it; nothing else in the organization changes.

On success the response has no body (204).

Failures:
- `400` — `{id}` is not a UUID.
- `404` — no such user in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Disable MFA
Source: https://docs.lerian.studio/en/reference/platform/access-manager/disable-mfa

/en/openapi/v3-current/AM-identity.yaml delete /v1/users/{id}/mfa
Turns OFF every second factor on the account at once. After this a password alone signs the member in.

SELF-SERVICE ONLY: `{id}` must be the caller's own user id. An administrative role does not open this route for somebody else, and there is no administrative equivalent of it. To clear somebody else's factors, an administrator removes them one at a time with `DELETE /v1/users/{id}/mfa/admin/{mfaType}` — including a legacy `sms` enrollment, which is what unblocks `DELETE /v1/users/{id}/phone`.

To remove one channel and keep the others, use `DELETE /v1/users/{id}/mfa/{mfaType}` instead — this route is the whole-account switch and does not ask which.

The body carries a 6-digit `code` proving an ENABLED factor: the member's preferred method when it is enabled, otherwise their only enabled one, and the authenticator when both are enabled with no usable preference. For `app` it is the current passcode from their authenticator app; for `email`, the code mailed by `POST /v1/users/{id}/mfa/disable/challenge`. A mailed code never proves the reset for a member without the `email` channel enabled. The code is checked after the account-state refusals, so a request that was going to fail anyway never spends it.

On success the response has no body (204).

Failures:
- `400 IDE-0007` / `IDE-0001` / `IDE-0002` — the body is missing or malformed.
- `400 IDE-0041` — MFA is not enabled on the account, or only a legacy `sms` enrollment is left (clear it with `DELETE /v1/users/{id}/mfa/sms`).
- `400 IDE-0042` — the code is wrong (or, for `app`, already used).
- `400 IDE-0060` — no live mailed code: none was requested, it expired, or it was spent.
- `400 IDE-0061` — the mailed code was answered wrongly too many times; request a new one.
- `400 IDE-0063` — the authorization server locked authenticator verification; wait.
- `400 IDE-0045` — the MFA operation could not be completed.
- `404 IDE-0013` — `{id}` is not the token's subject. Distinct from `IDE-0057`, the 403 the self-scope guard raises on the profile routes.
- `404` — no such user.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Discover how an email signs in
Source: https://docs.lerian.studio/en/reference/platform/access-manager/discover-how-an-email-signs-in

/en/openapi/v3-current/AM-auth.yaml post /v1/sso/discover
Tells the login screen, from an email address alone, how that person can sign in: whether password login is enabled for their tenant and which SSO provider, if any, it offers. It is called before login, by an unauthenticated browser, so the login screen can skip a manual tenant field; it changes nothing.

It fails open: an email that resolves to no tenant answers 200 with passwordEnabled=true and no provider, the same answer a tenant with password login and no SSO provider gets. The resolved tenant is never returned; the email is what the browser carries forward to GET /v1/sso/start.

Errors use the {code, title, message} envelope, plus fields on body validation errors. 400: Content-Type missing or not application/json (AUT-0009), email missing (AUT-0001) or not an email address (AUT-0009), an unexpected member (AUT-0003). When the authorization server cannot be reached, is too slow to answer, or is failing, the answer is 503 AUT-0033: nothing about the request was wrong, and it may be retried later.



# Enable MFA
Source: https://docs.lerian.studio/en/reference/platform/access-manager/enable-mfa

/en/openapi/v3-current/AM-identity.yaml post /v1/users/{id}/mfa/enable
Turns a VERIFIED channel on. From here the account is protected: the next sign-in asks for the second factor.

Third and last of the enrollment calls. Before doing this, make sure the recovery codes have been stored.

On success the response has no body (204).

Failures:
- `400` — the channel was never verified.
- `404` — no such user.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Log out
Source: https://docs.lerian.studio/en/reference/platform/access-manager/end-user-session

/en/openapi/v3-current/AM-auth.yaml post /v1/logout
Invalidates the session. The ID token is supplied via the id_token_hint form field or, as a fallback, the Authorization Bearer header; at least one is required. Returns 204 No Content. When the authorization server cannot be reached, is too slow to answer, or is failing, the answer is 503 AUT-0033: nothing about the request was wrong, and it may be retried later.



# Get user effective permissions
Source: https://docs.lerian.studio/en/reference/platform/access-manager/get-effective-permissions

/en/openapi/v3-current/AM-identity.yaml get /v1/users/{id}/effective-permissions
Called to answer "why can this person do that?" without walking groups and roles by hand. It is the resolved view.

Read-only: nothing changes.

Failures:
- `400` — the request could not be read.
- `404` — no such user in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Get MFA Status
Source: https://docs.lerian.studio/en/reference/platform/access-manager/get-mfa-status

/en/openapi/v3-current/AM-identity.yaml get /v1/users/{id}/mfa
Returns which second factors the account holds, which is preferred, and whether MFA is on at all.

This is the read a member makes about their own account — the self-service profile (`GET /v1/users/{id}/profile`) deliberately leaves MFA out and points here.

Read-only. The response carries `Cache-Control: no-store`: knowing which factors an account holds is exactly what an attacker wants before choosing an approach.

Failures:
- `404` — no such user.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Initiate an MFA challenge
Source: https://docs.lerian.studio/en/reference/platform/access-manager/initiate-mfa-challenge

/en/openapi/v3-current/AM-auth.yaml post /v1/login/mfa/challenge
Use this endpoint with `mfaType: email` to request a new verification code sent via email. The API also accepts `app`, but it does not send a code for that method: authenticator apps generate passcodes locally. Clients using an authenticator app can proceed directly to verification.

Requires a valid `mfaToken` obtained from the access token endpoint.



# Initiate MFA Setup
Source: https://docs.lerian.studio/en/reference/platform/access-manager/initiate-mfa-setup

/en/openapi/v3-current/AM-identity.yaml post /v1/users/{id}/mfa/setup
Begins enrolling one second factor and returns what the device needs to complete it — for an authenticator app, the secret and its QR code; for e-mail, a code is sent to the address already on the account.

Two channels are served: `app` and `email`. SMS is not one of them, and asking for it is refused.

First of THREE calls, and none of them alone protects anything: setup, then `POST /v1/users/{id}/mfa/verify` to prove the device works, then `POST /v1/users/{id}/mfa/enable` to turn it on. A channel left after step one or two is not protecting the account.

Failures:
- `400` — the channel is not one this service serves.
- `404` — no such user.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# List Applications
Source: https://docs.lerian.studio/en/reference/platform/access-manager/list-applications

/en/openapi/v3-current/AM-identity.yaml get /v1/applications
Returns the applications registered in your organization.

An application is a credential: it is what a program signs in as, in contrast to a user, who is a person. Each one holds a clientId and a clientSecret, and the Identity API returns the secret in full only when the application is created.

The `clientSecret` is NOT returned here: every row carries its `clientId`, and no row carries a secret. A lost secret cannot be recovered through any Identity API read; delete the application and create another.

Pass `partnerId` to narrow the list to the credentials issued to ONE of your customers. Omit it for all of them.

This listing is NOT paginated: it returns a plain array, and there is no `page` or `limit`.

Read-only: nothing changes.

Failures:
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# List Available Applications
Source: https://docs.lerian.studio/en/reference/platform/access-manager/list-available-applications

/en/openapi/v3-current/AM-identity.yaml get /v1/applications/available
Returns the catalog of applications this deployment knows how to serve — the Lerian products it can issue credentials for, with the identifier to use when creating one.

Called to populate the product picker on a create-application screen, so a caller does not have to guess an identifier. It is a STATIC catalog: it describes the deployment, not your organization, and it is identical for every caller.

Read-only: nothing changes. Note that this path is matched before `GET /v1/applications/{id}`, so no application whose id is literally "available" can be read through that route.



# List Groups
Source: https://docs.lerian.studio/en/reference/platform/access-manager/list-groups

/en/openapi/v3-current/AM-identity.yaml get /v1/groups
Returns your organization's groups, one page at a time, each with the usernames of its members.

A group is how permissions reach a person: you grant roles to a group and put people in it, rather than granting anyone individually. Called whenever the group list is shown, and after any create or delete to refresh it. `name` narrows the page by case-insensitive substring.

Read-only: nothing changes. Only groups of the organization resolved from your token are ever returned.

Failures:
- `400 IDE-0018` — `limit` is above the deployment's maximum (100 by default).
- `400 IDE-0019` — `page` is below 1.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# List own tenants
Source: https://docs.lerian.studio/en/reference/platform/access-manager/list-own-tenants

/en/openapi/v3-current/AM-identity.yaml get /v1/users/{id}/tenants
Lists the tenants your e-mail has an active account in, oldest tenant first.

Each item says whether it is your default tenant (`isDefault`, where your next sign-in goes), whether it is the tenant of the token making this request (`isCurrent`), and whether it has an active single sign-on provider (`ssoEnabled`). When you have no default tenant, every `isDefault` is false.

Any authenticated member may call this for THEMSELVES; an `{id}` other than your token's subject is refused with `403 IDE-0057`. The e-mail is read from your own user record, never from the request.

Read-only. The response carries `Cache-Control: no-store`.

Failures:
- `400` — `{id}` is not a UUID.
- `401` — no bearer token.
- `403 IDE-0057` — `{id}` is not you.
- `404` — no such user.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# List partners
Source: https://docs.lerian.studio/en/reference/platform/access-manager/list-partners

/en/openapi/v3-current/AM-identity.yaml get /v1/partners
Returns your organization's partners, one page at a time, each with its full permissions and scope and with `applicationsCount` — how many M2M credentials currently point at it. The count is served here so a list screen does not have to issue one applications query per row, and it is also what tells you in advance whether a delete will be refused.

Called whenever the partner list is shown, and after any create or delete to refresh it. Use `GET /v1/applications?partnerId=<id>` to see WHICH credentials a partner holds.

Read-only: nothing changes. Only partners of the organization resolved from your token are ever returned; there is no parameter that widens that.

Failures:
- `400 IDE-0018` — `limit` is above the deployment's maximum (100 by default).
- `403` — your token does not hold the `partners` resource.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# List scope catalogs
Source: https://docs.lerian.studio/en/reference/platform/access-manager/list-scope-catalogs

/en/openapi/v3-current/AM-identity.yaml get /v1/scope-catalog
Returns, for every product that has published one, the dimensions a partner can be scoped on in that product — the WHERE half of a partner, next to the collections and verbs of its permissions. Each product declares its own catalog when it starts, so the list follows the products actually deployed; a product absent from it publishes none.

Called when a partner editor opens, to render one picker per dimension in tree order (the first dimension is the top of the funnel; each later one narrows inside it). The rules a partner write is held to come from here: a `required` dimension must have a scope line (`IDE-0001`), a dimension that is not `multi` takes one value (`IDE-0002`), and listing or creating in a dimension's `collection` is denied to a partner scoped on it, because that is where its siblings live.

Read-only and global: the catalog describes the product, not your organization, so every caller sees the same list.

Failures:
- `403` — your token does not hold the `partners` resource.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# List Users
Source: https://docs.lerian.studio/en/reference/platform/access-manager/list-users

/en/openapi/v3-current/AM-identity.yaml get /v1/users
Returns your organization's users, one page at a time, each with the groups it belongs to and its MFA status.

Called whenever the user list is shown, and after any create or delete to refresh it. `name`, `roleId` and `groupId` narrow the page; they combine, and an empty value is ignored.

Read-only: nothing changes. Only users of the organization resolved from your token are ever returned; there is no parameter that widens that.

⚠️ `mfa` is TRI-STATE on this route and the null is meaningful: it means the per-user MFA read did not complete, NOT that the member has no MFA. Render it as unknown. The single-user read (`GET /v1/users/{id}`) always resolves it.

Failures:
- `400 IDE-0018` — `limit` is above the deployment's maximum (100 by default).
- `400 IDE-0019` — `page` is below 1.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Exchange a refresh token for an access token
Source: https://docs.lerian.studio/en/reference/platform/access-manager/refresh-token

/en/openapi/v3-current/AM-auth.yaml post /v1/login/oauth/refresh_token
Exchanges a valid refresh token for a new OAuth2 access token. Public: authenticated by the refresh token in the body.



# Remove user phone number
Source: https://docs.lerian.studio/en/reference/platform/access-manager/remove-an-user-s-phone-number

/en/openapi/v3-current/AM-identity.yaml delete /v1/users/{id}/phone
Clears the user's phone number and country code together. Idempotent: removing an already-absent phone succeeds.

Refused while a legacy SMS MFA enrollment is still recorded for the user, because its codes were delivered to that number. This is NOT achievable through `PATCH /v1/users/{id}`, which ignores an empty phone by design.

TWO kinds of caller reach this route and they are authorized differently: a member clearing their OWN number needs no administrative role, while anyone clearing SOMEONE ELSE'S needs the same grant that `PATCH /v1/users/{id}` requires.

On success the response has no body (204).

Failures:
- `400` — `{id}` is not a UUID.
- `401` — no bearer token.
- `403` — you may not act on this user.
- `404` — no such user.
- `409 IDE-0056` — a legacy SMS MFA enrollment is still recorded for this user.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Remove one Permission from a User
Source: https://docs.lerian.studio/en/reference/platform/access-manager/removes-a-single-permission-from-a-user

/en/openapi/v3-current/AM-identity.yaml delete /v1/users/{id}/permissions/{permId}
Revokes one direct grant. `{id}` is the PERSON and `{permId}` is the PERMISSION — the order of the two matters, and swapping them revokes a grant nobody asked to revoke.

The batch form, `POST /v1/users/{id}/permissions/remove`, does the same for a list.

Only the DIRECT grant goes: if the permission also reaches the person through a role or group they keep it, and the call still answers 204. Revoking a permission the person does not hold directly is not an error. On success the response has no body (204).

Failures:
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Remove one Member from a Group
Source: https://docs.lerian.studio/en/reference/platform/access-manager/removes-a-single-user-from-a-group

/en/openapi/v3-current/AM-identity.yaml delete /v1/groups/{id}/users/{userId}
Takes one person out of one group. `{id}` is the GROUP (a slug such as `midaz-viewer-group`) and `{userId}` is the PERSON — the order of the two matters, and swapping them removes a membership nobody asked to remove.

The batch form, `POST /v1/groups/{id}/users/remove`, does the same thing for a list of people.

The account is not deleted: it loses only what this group granted. Removing somebody who is not a member is not an error. On success the response has no body (204).

Failures:
- `404` — no such group in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Remove Permissions from a User in Batch
Source: https://docs.lerian.studio/en/reference/platform/access-manager/removes-multiple-permissions-from-a-user-batch

/en/openapi/v3-current/AM-identity.yaml post /v1/users/{id}/permissions/remove
Revokes several direct grants, naming them in the body.

It is a POST rather than a DELETE because the permissions travel in a request body; `DELETE /v1/users/{id}/permissions/{permId}` does the same for exactly one.

Only the DIRECT grant goes. If the same permission also reaches the person through a role or a group, they keep it and the call still answers 204 — check `GET /v1/users/{id}/effective-permissions` afterwards if the intent was to take the ability away. Revoking a permission the person does not hold directly is not an error. On success the response has no body (204).

Failures:
- `400` — `permissions` is missing or empty.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Remove Members from a Group in Batch
Source: https://docs.lerian.studio/en/reference/platform/access-manager/removes-multiple-users-from-a-group-batch

/en/openapi/v3-current/AM-identity.yaml post /v1/groups/{id}/users/remove
Takes several people out of a group in one call, naming them in the body.

It is a POST rather than a DELETE because the members travel in a request body; `DELETE /v1/groups/{id}/users/{userId}` does the same thing for exactly one person. Both exist and both are supported — use whichever fits the screen you are building.

Nobody is deleted: they keep their account and lose only what this group granted them, which for someone whose access came solely through it means losing all of it. Removing somebody who is not a member is not an error. On success the response has no body (204).

Failures:
- `400` — `users` is missing or empty.
- `404` — no such group in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Request a password reset code
Source: https://docs.lerian.studio/en/reference/platform/access-manager/request-a-password-reset-code

/en/openapi/v3-current/AM-identity.yaml post /v1/users/forgot-password/send-code
Mails a one-time code to a member who cannot sign in. PUBLIC: this route takes NO bearer token, because the caller has no way to obtain one.

Available only where the deployment enables password recovery.

First of two calls. The second is `POST /v1/users/forgot-password/reset`, which spends the code and sets the new password. Possession of the emailed code is the only credential in the flow.

On success the response has no body (204). It answers the same way whether or not the address belongs to a known member, so the route cannot be used to enumerate them.

Failures:
- `400` — the e-mail is missing or malformed.



# Request an access token
Source: https://docs.lerian.studio/en/reference/platform/access-manager/request-access-token

/en/openapi/v3-current/AM-auth.yaml post /v1/login/oauth/access_token
Issues an OAuth2 access token. No Bearer token is needed; the grant itself is the credential.

Two request formats are accepted, chosen by Content-Type, and each has its own response shape:
- application/json with camelCase members (grantType, clientId, clientSecret, username, password, code, state, codeVerifier) answers with the camelCase token (accessToken, tokenType, expiresIn, ...).
- application/x-www-form-urlencoded with the standard OAuth2 members (grant_type, client_id, client_secret, username, password, code) answers with the standard snake_case token (access_token, token_type, expires_in, ...). Client credentials may instead be sent as HTTP Basic authentication, which then takes precedence over client_id/client_secret in the form.

grantType is one of password, client_credentials or sso_code. password requires username and password; client_credentials requires clientId and clientSecret; sso_code requires code, state and codeVerifier (the PKCE verifier of the code_challenge sent to GET /v1/sso/start), and is a JSON-only grant.

When the person signing in has MFA enabled, a password or sso_code grant does not issue a token: it answers 200 with mfaRequired=true and an mfaToken, which is then sent to POST /v1/login/mfa/verify to obtain the token.

Errors use the {code, title, message} envelope, plus fields on body validation errors. 400: Content-Type missing or not one of the two formats, malformed form or Basic credentials (AUT-0009), a grant missing the members it needs (AUT-0014), an invalid or expired SSO code (AUT-0027). 401: wrong username or password (AUT-1002), wrong client credentials (AUT-1004), password grant for a person created through SSO with no password (AUT-1006), suspended or expired partner (AUT-1009, AUT-1010). 403: caller IP outside the IP allowlist (AUT-0021), person not allowed to sign in (AUT-1008). 429: account temporarily locked after repeated failures (AUT-1007). 503 AUT-0028: the sign-in needs a second factor and this server has no MFA signing secret configured.



# Request an MFA disable confirmation code
Source: https://docs.lerian.studio/en/reference/platform/access-manager/request-an-mfa-disable-confirmation-code

/en/openapi/v3-current/AM-identity.yaml post /v1/users/{id}/mfa/disable/challenge
Mails a 6-digit confirmation code to the member's account e-mail, for the disables that are proven by e-mail: `DELETE /v1/users/{id}/mfa/email`, and `DELETE /v1/users/{id}/mfa` when e-mail is the factor that proves it. Only a member with the `email` channel enabled is sent one.

The authenticator channel needs NO challenge — `DELETE /v1/users/{id}/mfa/app` is proven by the current passcode from the member's authenticator app — and a legacy `sms` clear needs no code at all. There is no request body: the destination is the address already on the account, never one the caller supplies.

Self-service only; `{id}` must be the caller's own user id. Sends are budgeted per member.

On success the response has no body (204).

Failures:
- `400 IDE-0041` — MFA is not enabled on the account.
- `400 IDE-0048` — the account has no e-mail to send to.
- `400 IDE-0049` — no disable on this account is proven by a mailed code: the `email` channel is not enabled (for example, an authenticator-only member, whatever their preference).
- `400 IDE-0045` — the code could not be sent or the challenge could not be recorded.
- `400 IDE-0062` — the send budget for the current window is spent; wait before asking again.
- `404 IDE-0013` — `{id}` is not the token's subject.
- `404` — no such user.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Reset a password with a verification code
Source: https://docs.lerian.studio/en/reference/platform/access-manager/reset-a-password-with-a-verification-code

/en/openapi/v3-current/AM-identity.yaml post /v1/users/forgot-password/reset
Spends the code mailed by `POST /v1/users/forgot-password/send-code` and sets the new password. PUBLIC: no bearer token, by design.

Available only where the deployment enables password recovery.

Second and last call of the flow. The code is single-use and expires; a wrong or stale code is refused and the password is unchanged.

On success the response has no body (204) and the member can sign in with the new password.

Failures:
- `400` — the code is wrong or expired, or the new password fails the password policy.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Reset a user password
Source: https://docs.lerian.studio/en/reference/platform/access-manager/reset-user-password

/en/openapi/v3-current/AM-identity.yaml patch /v1/users/{id}/reset-password
Sets a user's password WITHOUT the old one. This is the administrative reset, used when a member cannot sign in and cannot complete the e-mailed-code flow either.

There is no possession check on this route — the authorization IS the check — so it is granted narrowly.

On success the response has no body (204).

Failures:
- `400` — `{id}` is not a UUID, or the new password fails the password policy.
- `404` — no such user.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Retrieve a partner
Source: https://docs.lerian.studio/en/reference/platform/access-manager/retrieve-a-partner

/en/openapi/v3-current/AM-identity.yaml get /v1/partners/{id}
Returns one partner in full: its permissions, its scope, its validity window, its IP allowlist and how many applications are attached.

Called to open a partner's detail screen, and before a PATCH — the update replaces `permissions` and `scope` wholesale rather than merging entry by entry, so an editor has to start from the current lists.

Read-only: nothing changes.

Failures:
- `404 IDE-1046` — no such partner in your organization. An id that belongs to ANOTHER tenant answers exactly this, deliberately: telling the two apart would confirm another tenant's records exist.
- `422` — `id` is not a UUID.
- `403` — your token does not hold the `partners` resource.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Retrieve a product's scope catalog
Source: https://docs.lerian.studio/en/reference/platform/access-manager/retrieve-a-product-s-scope-catalog

/en/openapi/v3-current/AM-identity.yaml get /v1/scope-catalog/{product}
Returns the dimensions one product lets a partner be scoped on, in tree order, with the rules each one carries: `required`, `multi`, and the `collection` its siblings live in. `name` is the value to send as `field` on a partner's `scope` line; values are the product's own identifiers (as its list APIs return them) and are not checked for existence.

Called by a partner editor that already knows which product it is scoping, and before a create or an update to know which lines the write will need.

Read-only and global: the same for every organization.

Failures:
- `404 IDE-1053` — the product has not published a scope catalog. None of its partners can be scoped until it does.
- `403` — your token does not hold the `partners` resource.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Retrieve Application details
Source: https://docs.lerian.studio/en/reference/platform/access-manager/retrieve-application-details

/en/openapi/v3-current/AM-identity.yaml get /v1/applications/{id}
Returns one application: its identity, the partner it is bound to if any, and its clientId.

The `clientSecret` is NOT returned here. The Identity API returns it only in the create response.

Read-only: nothing changes.

Failures:
- `404` — no such application in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Retrieve Group details
Source: https://docs.lerian.studio/en/reference/platform/access-manager/retrieve-group-details

/en/openapi/v3-current/AM-identity.yaml get /v1/groups/{id}
Returns one group with the usernames of its members.

`{id}` is the group's `name` — a slug such as `midaz-viewer-group`, not a UUID. Called to open a group's detail screen, and before a PATCH.

Read-only: nothing changes. To see what the group can DO, read the roles granted to it; this response carries membership, not permissions.

Failures:
- `404` — no such group in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Retrieve own user profile
Source: https://docs.lerian.studio/en/reference/platform/access-manager/retrieve-the-caller-s-own-profile

/en/openapi/v3-current/AM-identity.yaml get /v1/users/{id}/profile
Returns a REDUCED projection of your own record: id, name, username, e-mail, phone and country code. Groups, roles, permissions and MFA state are deliberately left out — read your MFA state from `GET /v1/users/{id}/mfa`, and the full record is the administrative `GET /v1/users/{id}`.

Any authenticated member may call this, without an administrator's role — but only for THEMSELVES: an `{id}` other than your token's subject is refused with `403 IDE-0057`.

Read-only: nothing changes. The response carries `Cache-Control: no-store`, because it holds your e-mail and phone number.

Failures:
- `400` — `{id}` is not a UUID.
- `401` — no bearer token.
- `403 IDE-0057` — `{id}` is not you.
- `404` — no such user.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Retrieve the partner ceiling of a product
Source: https://docs.lerian.studio/en/reference/platform/access-manager/retrieve-the-partner-ceiling-of-a-product

/en/openapi/v3-current/AM-identity.yaml get /v1/partners/ceiling
Returns the most a partner of your organization can be granted in one product: everything your organization's `<product>-editor-role` holds, as one entry in `grants` per enabled permission bound to that role. It is the ceiling every partner write is checked against, so it is what a partner editor should offer.

Read it PAIRWISE. A permission line may grant a `(resource, action)` only when ONE entry holds both — a verb an entry holds for one collection is never available for a collection another entry holds. `head` is granted together with `get`, inside the entry that holds `get`. Asking for more is refused on write with `400 IDE-1043`.

Called when a partner editor opens a product, before it renders the grid of collections and verbs. The ceiling can narrow after a partner was written; a partner then keeps only what is still inside it.

Read-only: nothing changes. The organization is always the one resolved from your token; there is no parameter that names another.

An empty `grants` is a legitimate answer: the role holds nothing in the product, and no partner can be granted anything there.

Failures:
- `400 IDE-0001` — `product` is blank.
- `400 IDE-1057` — the identity provider refused the request; the message repeats its code and sentence.
- `403` — your token does not hold the `partners` resource.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Retrieve User details
Source: https://docs.lerian.studio/en/reference/platform/access-manager/retrieve-user-details

/en/openapi/v3-current/AM-identity.yaml get /v1/users/{id}
Returns one user's full administrative record: identity, contact details, and the groups it holds.

Called to open a user's detail screen, and before a PATCH. A member reading their OWN record uses `GET /v1/users/{id}/profile` instead, which returns a reduced projection and does not require an administrator's role.

Read-only: nothing changes. Only users of the organization resolved from your token are returned.

Failures:
- `400` — `{id}` is not a UUID.
- `404` — no such user in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Get OIDC user info
Source: https://docs.lerian.studio/en/reference/platform/access-manager/retrieve-user-information

/en/openapi/v3-current/AM-auth.yaml get /v1/userinfo
Returns the OIDC-standard user profile for the Bearer token subject.



# List the caller's permissions
Source: https://docs.lerian.studio/en/reference/platform/access-manager/retrieve-user-permissions

/en/openapi/v3-current/AM-auth.yaml get /v1/permissions
Retrieves the permissions granted to the Bearer token subject, as a resource-to-actions map. When the authorization server cannot be reached, is too slow to answer, or is failing, the answer is 503 AUT-0033: nothing about the request was wrong, and it may be retried later.



# List the Direct Permissions of a User
Source: https://docs.lerian.studio/en/reference/platform/access-manager/returns-the-permissions-assigned-to-a-user

/en/openapi/v3-current/AM-identity.yaml get /v1/users/{id}/permissions
Returns only what was granted to this person DIRECTLY, as a plain array — this listing is NOT paginated.

Read this one when you want to know what an administrator attached to the account itself. It is NOT the answer to "what can this person do?": permissions also arrive through roles and through groups, and those do not appear here: a permission is listed only when it names this user itself, never because a role held by the user or by one of their groups carries it. `GET /v1/users/{id}/effective-permissions` is the resolved view, with the source of each grant.

Read-only: nothing changes. A person with no direct grants returns an empty array, not a 404.

Failures:
- `404` — no such user in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Set own default tenant
Source: https://docs.lerian.studio/en/reference/platform/access-manager/set-own-default-tenant

/en/openapi/v3-current/AM-identity.yaml put /v1/users/{id}/tenants/default
Makes `tenantId` your default tenant: your next sign-in goes there. Setting the tenant that is already your default succeeds again.

`tenantId` must be one of the tenants `GET /v1/users/{id}/tenants` lists. Any other value is refused with the same `403 IDE-0057` as another user's `{id}`, which does not say why.

Any authenticated member may call this for THEMSELVES; an `{id}` other than your token's subject is refused with `403 IDE-0057`.

On success the response has no body (204).

Failures:
- `400` — `{id}` is not a UUID, or `tenantId` is missing or empty.
- `401` — no bearer token.
- `403 IDE-0057` — `{id}` is not you, or you have no active account in that tenant.
- `404` — no such user.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Set Preferred MFA Method
Source: https://docs.lerian.studio/en/reference/platform/access-manager/set-preferred-mfa-method

/en/openapi/v3-current/AM-identity.yaml patch /v1/users/{id}/mfa/preferred
Chooses which enabled channel is offered first at sign-in. It changes the order, never what is enabled — nothing is turned on or off here, and the account is exactly as protected afterwards.

On success the response has no body (204).

Failures:
- `400` — that channel is not enabled on the account.
- `404` — no such user.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Set own user phone number
Source: https://docs.lerian.studio/en/reference/platform/access-manager/set-the-caller-s-phone-number

/en/openapi/v3-current/AM-identity.yaml patch /v1/users/{id}/phone
Sets your phone number and country code. BOTH are required and they travel together: the identity provider validates the number against the country and refuses an unresolvable pair.

This is the self-service twin of the administrative `PATCH /v1/users/{id}`. An empty phone here is refused with 400 rather than clearing anything — clearing is `DELETE /v1/users/{id}/phone`.

Any authenticated member may call this for THEMSELVES; an `{id}` other than your token's subject is refused with `403 IDE-0057`.

On success the response has no body (204).

Failures:
- `400` — `{id}` is not a UUID, or the number/country pair is malformed or empty.
- `401` — no bearer token.
- `403 IDE-0057` — `{id}` is not you.
- `404` — no such user.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Start an SSO login
Source: https://docs.lerian.studio/en/reference/platform/access-manager/start-an-sso-login

/en/openapi/v3-current/AM-auth.yaml get /v1/sso/start
Starts an SSO login. The Console's login screen sends the browser here — not an API client — after POST /v1/sso/discover offered an SSO provider for the email typed. The tenant is resolved from the email server-side and is never accepted from the caller. The flow is stored server-side under a single-use state, and the browser is redirected (302, Location) to the identity provider's authorize URL; no cookie is set. The identity provider then returns the browser to the Console with a code, which is redeemed with the sso_code grant of POST /v1/login/oauth/access_token, presenting the PKCE verifier of the code_challenge sent here.

Errors use the {code, title, message} envelope and are not redirects. 400: email, provider or code_challenge missing, or a code_challenge that is not a well-formed S256 challenge (AUT-0022). 401: this server has no SSO callback configured (AUT-0026). 404: the provider named is not one the tenant offers (AUT-0024). When the authorization server cannot be reached, is too slow to answer, or is failing, the answer is 503 AUT-0033: nothing about the request was wrong, and it may be retried later.



# Update a Group
Source: https://docs.lerian.studio/en/reference/platform/access-manager/update-a-group

/en/openapi/v3-current/AM-identity.yaml patch /v1/groups/{id}
Changes a group's label and contact details. Anything you omit is left alone.

The group's `name` — the identifier in `{id}` — CANNOT be changed here or anywhere else; it is what roles and memberships point at. Membership is not edited here either: use `POST /v1/groups/{id}/users` and its remove counterpart.

The response carries the group's full projection, which is wider than the one `GET` returns.

Failures:
- `400` — a supplied member is malformed.
- `404` — no such group in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Update a partner
Source: https://docs.lerian.studio/en/reference/platform/access-manager/update-a-partner

/en/openapi/v3-current/AM-identity.yaml patch /v1/partners/{id}
Changes a partner's access, its validity window, its IP allowlist or its state. Every member is optional and anything you omit is left alone — but `permissions` and `scope`, when supplied, REPLACE the stored list wholesale. There is no per-entry merge, because a merge would make "remove the last ledger" impossible to express.

Called to widen or narrow a partner mid-life, and to suspend or reactivate one (`state: "suspended"` / `"active"`). Suspending is the reversible kill switch; deleting is not.

`ipAllowlist` has THREE meanings here and they are not interchangeable: omit the member to leave the list as it is, send `null` to go back to inheriting the organization's list, send entries to replace it with the partner's own. An empty array is refused.

`validFrom` and `validUntil` work the same way, one bound at a time: omit the member to keep the stored bound, send an RFC 3339 instant to set it, send `null` to remove it and leave the window open on that side (no start date: honoured from now on; no end date: never expires — a partner already past its end date is honoured again unless it is suspended). An empty string is refused with `422`. When you send only one bound it is checked against the other one as stored: moving `validFrom` to or past the stored `validUntil`, or `validUntil` to or before the stored `validFrom`, is `400 IDE-1045` and nothing is written. To move a window to a later period, send both bounds in the same request.

What changes: the stored record, and with it every future authorization.

Failures: every code `POST` can return, applied to the record as it will be after the patch (`IDE-1042`, `IDE-1043`, `IDE-1044`, `IDE-1045`, `IDE-1047`, `IDE-1048`, `IDE-0036`, `IDE-1050`, `IDE-1052`, `409 IDE-1040`), plus:
- `400 IDE-1054` — the product is not ready for partners yet: it has not published a scope catalog. Raised only when the request sends `permissions`: a partner that already holds such a line can still be suspended, reactivated or renamed, and the line can be removed.
- `400 IDE-1055` — a permission names a product that has not opted in to partners. Like IDE-1054 it is raised only when the request sends `permissions`, for every line; remove the line to proceed.
- `400 IDE-1056` is checked when either `permissions` or `scope` changes: granting a write and narrowing the scope under a write already granted both put the write above the scope. Narrow the scope and drop the write in the same update.
- `404 IDE-1046` — no such partner in your organization.
- `403` — your token does not hold the `partners` resource.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Update a user
Source: https://docs.lerian.studio/en/reference/platform/access-manager/update-user

/en/openapi/v3-current/AM-identity.yaml patch /v1/users/{id}
Changes a user's identity and contact details, and its group membership.

This is the ADMINISTRATIVE merge and it can touch e-mail, name and group membership at once. A member changing their own phone number uses `PATCH /v1/users/{id}/phone` instead, which writes only those two fields — routing a self-service form through this merge would put group membership inside its blast radius.

An empty `phone` here is IGNORED, not cleared; clearing is `DELETE /v1/users/{id}/phone`.

The response echoes the members you submitted, not a re-read of the record.

Failures:
- `400` — `{id}` is not a UUID, or a supplied member is malformed.
- `404` — no such user in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Update a user password
Source: https://docs.lerian.studio/en/reference/platform/access-manager/update-user-password

/en/openapi/v3-current/AM-identity.yaml patch /v1/users/{id}/update-password
Changes a password by proving possession of the current one. Send both the old and the new password.

This is the self-service change. An administrator setting a password WITHOUT the old one uses `PATCH /v1/users/{id}/reset-password`.

On success the response has no body (204).

Failures:
- `400` — `{id}` is not a UUID, the old password is wrong, or the new one fails the password policy.
- `404` — no such user.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Enforce a user permission
Source: https://docs.lerian.studio/en/reference/platform/access-manager/validate-user-permission

/en/openapi/v3-current/AM-auth.yaml post /v1/authorize
Enforces a permission for the Bearer token subject against a resource and action. A denied permission is returned as 200 with authorized=false, not 403. A 403 means the caller IP is outside the IP allowlist (AUT-0021).



# Verify an MFA challenge
Source: https://docs.lerian.studio/en/reference/platform/access-manager/verify-mfa-login

/en/openapi/v3-current/AM-auth.yaml post /v1/login/mfa/verify
Verifies a one-time passcode or recovery code against the MFA session token and issues OAuth2 tokens. Public: authenticated by the mfaToken in the body.



# Verify MFA Setup
Source: https://docs.lerian.studio/en/reference/platform/access-manager/verify-mfa-passcode

/en/openapi/v3-current/AM-identity.yaml post /v1/users/{id}/mfa/verify
Proves the enrolling device works, by sending back the code it produced or received.

Second of the three enrollment calls. It does NOT turn the factor on — `POST .../mfa/enable` does. Verifying and stopping there leaves the account exactly as protected as before.

On success the response has no body (204).

Failures:
- `400` — the code is wrong or expired.
- `404` — no such user.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Access Manager error list
Source: https://docs.lerian.studio/en/reference/platform/access-manager/access-manager-error-list

The Access Manager returns structured error responses that show what went wrong and how to fix it.

## Auth errors

***

The following errors can occur when interacting with the [Auth APIs](/en/reference/platform/access-manager/am-auth-apis) endpoints.

**Error format**

Auth returns errors in two formats. The format depends on the endpoint.

[Request an access token](/en/reference/platform/access-manager/request-access-token), [Discover how an email signs in](/en/reference/platform/access-manager/discover-how-an-email-signs-in), and [Start an SSO login](/en/reference/platform/access-manager/start-an-sso-login) return this format:

```json JSON theme={null}
{
   "code": "<error_code>",
   "title": "<error_title>",
   "message": "<error_message>"
}
```

A body validation error can also have a `fields` object.

The other Auth endpoints return errors as RFC 9457 problem details with the `application/problem+json` media type:

* **`type`** – `https://errors.lerian.studio/v1/` followed by the error code.
* **`title`** – The HTTP status name. It is not the title in the tables below.
* **`status`** – The HTTP status code.
* **`detail`** – The message in the tables below. For `500` and `503` errors, the value is `internal error`.
* **`instance`** – The trace ID of the request, when the request has one.
* **`code`** – The error code in the tables below.
* **`errors`** – The field validation details, when there are any.

When the request body does not match the endpoint schema, the error has no `code` and no `type`.

A request that Auth refuses before it reaches the endpoint, such as a rate-limited request, can use a different format.

### 400

| Code | Title | Message |
| - | - | - |
| AUT-0001 | Missing Fields in Request | Your request is missing one or more required fields. Please refer to the documentation to ensure all necessary fields are included in your request. |
| AUT-0003 | Unexpected Fields in the Request | The request body contains more fields than expected. Please send only the allowed fields as per the documentation. The unexpected fields are listed in the fields object. |
| AUT-0009 | Bad Request | The server could not understand the request due to malformed syntax. Please check the listed fields and try again. |
| AUT-0013 | Invalid Grant Type | The provided 'grantType' `[{value}]` is not valid. Accepted grant types are password, client\_credentials, refresh\_token, or others. Please provide a valid type. |
| AUT-0014 | Grant Type Missing Fields | The provided 'grant\_type' `[{value}]` is missing required fields. Please refer to the documentation for guidance. |
| AUT-0022 | Missing SSO Parameters | The SSO request is missing the required 'email', 'provider', or 'code\_challenge' parameter. Please include all three and try again. |
| AUT-0027 | Invalid SSO Code | The SSO code is invalid, expired, or has already been used. Please restart the SSO login. |
| AUT-1001 | Unsupported Grant Type | The provided 'grantType' is not supported by this application. Please refer to the application's supported grant types. |

### 401

| Code | Title | Message |
| - | - | - |
| AUT-0006 | Token Missing | A valid token must be provided in the request header. Please include a token and try again. |
| AUT-0007 | Invalid Token | The provided token is expired, invalid or malformed. Please provide a valid token and try again. |
| AUT-0016 | Invalid MFA Code | The provided MFA verification code is incorrect. Please check the code and try again. |
| AUT-0017 | MFA Session Expired | The MFA session has expired. Please initiate a new login to receive a fresh MFA challenge. |
| AUT-0020 | Invalid MFA Token | The provided MFA token is invalid, expired or malformed. Please initiate a new login. |
| AUT-0026 | SSO Login Failed | The SSO login could not be completed. Please restart the SSO login and try again. |
| AUT-0029 | Invalid Recovery Code | The provided recovery code is not valid or has already been used. Please try one of your other recovery codes. |
| AUT-1002 | Invalid Username or Password | The provided 'username' or 'password' is incorrect. Please verify the credentials and try again. |
| AUT-1003 | Invalid Token | The provided token is expired, invalid or malformed. Please provide a valid token and try again. |
| AUT-1004 | Invalid Client | The provided 'clientId' or 'clientSecret' is incorrect. Please verify the credentials and try again. |
| AUT-1005 | Invalid Refresh Token | The provided 'refreshToken' is invalid, expired or revoked. Please verify the token and try again. |
| AUT-1006 | Password Login Unavailable | This account was created through single sign-on and has no password. Please sign in with SSO, or use the 'forgot password' flow to set a password and try again. |
| AUT-1009 | Partner Suspended | The partner this credential belongs to is suspended, so no token can be issued for it. The credential itself is unchanged and starts working again if the partner is reactivated. |
| AUT-1010 | Partner Outside Its Validity Window | The partner this credential belongs to is outside its validity window, so no token can be issued for it. Ask the administrator who created it to extend the window. |
| AUT-1011 | Application Not Found | The application this token was issued to no longer exists, so the token can no longer be honoured. Retrying will not help; ask an administrator for a new credential. |
| AUT-1012 | Partner Not Found | The partner this credential belongs to no longer exists, so the credential can no longer be honoured. Retrying will not help; ask an administrator for a new credential. |

### 403

| Code | Title | Message |
| - | - | - |
| AUT-0021 | IP Not Allowed | Access from your network is not allowed for this workspace. Contact your administrator. |
| AUT-1008 | Sign-In Not Allowed | This account is not allowed to sign in. Please contact your administrator. |

### 404

| Code | Title | Message |
| - | - | - |
| AUT-0024 | SSO Provider Not Found | The requested SSO provider was not found. Please check the provider name and try again. |
| AUT-1015 | Enforcement Sub Not Found | No subject was found for the provided 'sub'. Please refer to the enforcement documentation for guidance on the correct 'sub' value. |

### 429

| Code | Title | Message |
| - | - | - |
| AUT-0018 | Too Many Requests | Too many failed MFA verification attempts. Please wait and try again later. |
| AUT-0030 | Too Many Requests | Too many verification codes have been requested for this session. Please wait and try again later. |
| AUT-1007 | Too Many Requests | Too many failed sign-in attempts. Please wait and try again later. |

### 500

| Code | Title | Message |
| - | - | - |
| AUT-0005 | Internal Server Error | The server encountered an unexpected error. Please try again later or contact support. |

### 503

| Code | Title | Message |
| - | - | - |
| AUT-0028 | MFA Secret Not Set | The MFA secret is not set on this server, so multi-factor authentication is unavailable. Please contact your administrator. |
| AUT-0031 | Verification Temporarily Unavailable | Multi-factor authentication is temporarily unavailable. Please wait a moment and try again. |
| AUT-0032 | Verification Code Not Sent | The verification code could not be sent. Please try again, or choose another verification method. |
| AUT-0033 | Authorization Server Unavailable | The authorization server could not be reached to decide this request. Please wait a moment and try again. |

## Identity errors

***

The following errors can occur when interacting with the [Identity APIs](/en/reference/platform/access-manager/am-identity-apis) endpoints.

### 400

| `code` | `title` | `message` |
| - | - | - |
| IDE-0001 | Missing Fields in Request | Your request is missing one or more required fields. Please refer to the documentation to ensure all necessary fields are included in your request. |
| IDE-0002 | Invalid Field Type | One or more fields in the request body have an invalid type. Verify the field types against the API documentation and try again. |
| IDE-0003 | Invalid Path Parameter | One or more path parameters are in an incorrect format. Please check the following parameters `[{value}]` and ensure they meet the required format before trying again. |
| IDE-0004 | Unexpected Fields in the Request | The request body contains more fields than expected. Please send only the allowed fields as per the documentation. The unexpected fields are listed in the fields object. |
| IDE-0005 | Invalid Query Parameter | One or more query parameters are in an incorrect format. Please check the following parameters `'[{value}]'` and ensure they meet the required format before trying again. |
| IDE-0007 | Bad Request | The server could not understand the request due to malformed JSON syntax. |
| IDE-0012 | Invalid Application Name | The application name provided is not part of the managed applications allowlist, so it cannot be created or deleted. Supported values: `{value}`. |
| IDE-0018 | Pagination Limit Exceeded | The pagination limit exceeds the maximum allowed of `{value}` items per page. Please verify the limit and try again. |
| IDE-0019 | Invalid Page | Query parameter page is invalid. The page must be greater than 0. |
| IDE-0020 | Password Too Short | The password must be at least 12 characters long. |
| IDE-0021 | Password No Uppercase | The password must contain at least one uppercase letter. |
| IDE-0022 | Password No Lowercase | The password must contain at least one lowercase letter. |
| IDE-0023 | Password No Digit | The password must contain at least one digit. |
| IDE-0024 | Password No Special Char | The password must contain at least one special character. |
| IDE-0025 | Password Consecutive Repeated | The password must not contain consecutive repeated characters. |
| IDE-0027 | Old Password Invalid | The old password provided is invalid. |
| IDE-0028 | Password Same As Old | The new password must be different from the current password. |
| IDE-0030 | Username Empty | The username cannot be empty. |
| IDE-0031 | Username Too Short | The username must be at least 2 characters long. |
| IDE-0032 | Username Too Long | The username must not exceed 255 characters. |
| IDE-0033 | Username Invalid Character | The username can only contain letters, numbers, hyphens, and underscores. |
| IDE-0034 | Email Domain Mismatch | The user's email domain does not match the tenant's domain. Please use an email address within the tenant's domain and try again. |
| IDE-0035 | IP Allowlist Too Large | The IP allowlist is too large: the combined, comma-separated entries must not exceed `{value}` characters. Please remove some entries and try again. |
| IDE-0036 | Invalid IP Allowlist Entry | The IP allowlist entry `{value}` is not a valid IP address or CIDR block. Please correct it and try again. |
| IDE-0037 | Invalid IP Allowlist Scope | The IP allowlist enforcement scope `{value}` is not supported. Please use console, api, or both, and try again. |
| IDE-0038 | IP Allowlist Entry Too Broad | The IP allowlist entry `{value}` covers too wide a range to restrict access. Please use a prefix of at least `/{value}` and try again. |
| IDE-0041 | MFA Not Enabled | Multi-factor authentication is not enabled for this account. |
| IDE-0042 | Invalid MFA Passcode | The code entered is incorrect. Please try again. |
| IDE-0043 | MFA Setup Not Initiated | MFA setup has not been initiated. Please start the setup process first. |
| IDE-0044 | Invalid MFA Type | The provided MFA type is invalid. Allowed types are: `{value}`. |
| IDE-0045 | MFA Operation Failed | The MFA operation could not be completed. Please try again. |
| IDE-0046 | MFA Verification Failed | MFA verification failed. Please check the passcode and try again. |
| IDE-0047 | MFA Secret Required | The secret field is required for TOTP (app) MFA type. Please provide the secret returned from the setup step. |
| IDE-0048 | MFA Destination Not Configured | There is no `{value}` on file for this account. Add one to the profile first. |
| IDE-0049 | MFA Method Not Enabled | The `{value}` verification method is not enabled for this account. |
| IDE-0051 | MFA Setup Not Verified | MFA setup has been initiated but not yet verified. Please complete the verify step before enabling. |
| IDE-0052 | MFA Secret Mismatch | The provided MFA secret does not match the secret issued during setup. Restart the setup flow and use the latest secret. |
| IDE-0053 | MFA Recovery Code Mismatch | The provided recovery code does not belong to this MFA setup. Use one of the recovery codes returned by the setup step. |
| IDE-0054 | MFA Recovery Codes Replace Uncertain | The recovery-code regeneration could not be confirmed, and your previous recovery codes may already have been invalidated. Retry the regeneration: it is safe to repeat and will issue a new set of codes. |
| IDE-0055 | MFA App Enrollment Forbidden | MFA app enrollment cannot be enabled by an administrator on behalf of another user |
| IDE-0058 | Password Reset Rejected | The password reset could not be completed. Request a new code and try again. |
| IDE-0059 | Pagination Page Exceeded | The requested page exceeds the maximum allowed of `{value}`. Please verify the page and try again. |
| IDE-0060 | MFA Disable Confirmation Required | There is no active confirmation code: it has expired, has already been used, or was never sent. Request a new code and enter it before it expires. |
| IDE-0061 | MFA Disable Confirmation Attempts Exceeded | The confirmation code was entered incorrectly too many times and can no longer be used. Request a new code to continue. |
| IDE-0062 | MFA Disable Confirmation Resend Limit Reached | Too many confirmation codes have been requested. Wait a while before requesting another one. |
| IDE-0063 | MFA Verification Temporarily Locked | Too many incorrect codes have been entered, so verification is temporarily blocked. Close this and come back later. |
| IDE-1009 | Invalid Provider Type | The provider type is not valid for the specified category. Please check the supported types and try again. |
| IDE-1010 | Invalid Provider Category | Only Email, SMS and OAuth provider categories are supported. Please specify a valid category. |
| IDE-1014 | Missing Issuer URL | A Custom OAuth provider requires issuerUrl for OIDC discovery, or all of customAuthUrl, customTokenUrl and customUserInfoUrl explicitly. Please provide the issuer URL and try again. |
| IDE-1015 | OIDC Discovery Failed | OIDC discovery from the issuer URL failed: the issuer must be a reachable http(s) endpoint that serves a .well-known/openid-configuration document exposing the authorization, token and userinfo endpoints. Please verify the issuer URL and try again. |
| IDE-1017 | Test Message Not Delivered | The test message was not delivered to the destination, and the provider did NOT report a credential failure — the configuration may well be correct. Trial accounts are the common cause: Twilio trial accounts refuse delivery to recipients that have not been verified in the Twilio console, whatever the credentials. Verify the destination, or use one already verified with the provider, and test again. This outcome is also returned when the provider's response is inconclusive, so that a working provider is never reported as having bad credentials. Provider reported: `{value}` |
| IDE-1032 | Invalid Provider Endpoint URL | issuerUrl, customAuthUrl, customTokenUrl and customUserInfoUrl must each be an absolute http(s) URL. |
| IDE-1041 | Unknown Product | The product `{value}` is not a supported product. Please use one of: `{value}`. |
| IDE-1042 | Unknown Scope Field | The scope is not accepted by the product: `{value}`. Please scope only the dimensions the product publishes (`GET /v1/scope-catalog/{product}`). |
| IDE-1043 | Permission Above Product Ceiling | The permission is above what your organization holds in the product: `{value}`. A partner cannot be delegated more than your organization's editor role holds; please remove it and try again. |
| IDE-1044 | Scope Without Permissions | The product `{value}` has a scope entry but no permissions entry, which would authorize nothing. Please add the permissions for this product or remove its scope. |
| IDE-1045 | Invalid Validity Window | The field validUntil must be later than validFrom. Please correct the validity window and try again. |
| IDE-1047 | Wildcard Not Allowed | The field `{value}` must not contain the wildcard `*`, which would grant everything the product offers. Please list the values explicitly and try again. |
| IDE-1048 | Empty IP Allowlist | The field ipAllowlist must not be an empty array. Send null to inherit the organization's list, or suspend the partner to block it entirely. |
| IDE-1050 | Duplicate IP Allowlist Entry | The IP allowlist entry `{value}` appears more than once. Please keep a single entry per CIDR and try again. |
| IDE-1052 | Partner Rejected | The partner could not be stored because the identity provider refused the request: `{value}`. Please correct the request and try again. |
| IDE-1054 | Product Not Ready For Partners | The product is not ready for partners yet: it has not published a scope catalog: `{value}`. Please remove its permissions entry and try again. |
| IDE-1055 | Product Not Opted In To Partners | The product has not opted in to partners, so it cannot be granted to one: `{value}`. Please remove its permissions entry and try again. |
| IDE-1056 | Partner Write Exceeds Its Scope | A write in the permissions acts at a level wider than the partner's scope: `{value}`. Please remove that action, or widen the partner's scope, and try again. |
| IDE-1057 | Partner Read Rejected | The identity provider refused the request: `{value}`. Please correct the request and try again. |

### 401

| `code` | `title` | `message` |
| - | - | - |
| IDE-0008 | Token Missing | A valid token must be provided in the request header. Please include a token and try again. |
| IDE-0009 | Invalid Token | The provided token is expired, invalid or malformed. Please provide a valid token and try again. |

### 403

| `code` | `title` | `message` |
| - | - | - |
| IDE-0057 | Not Your Profile | This operation may only be performed on your own account. The requested user ID does not match the authenticated user. |
| IDE-1023 | System Role Immutable | System roles cannot be modified or deleted. Only custom roles can be changed. |

### 404

| `code` | `title` | `message` |
| - | - | - |
| IDE-0013 | User ID Not Match | The provided ID does not match the token owner. Users are only allowed to update their own password. Please ensure you are using the correct ID and try again. |
| IDE-1001 | Application ID Not Found | The provided application ID does not exist in our records. Please verify the application ID and try again. |
| IDE-1002 | No Applications Found | No applications were found in the search. Please review the search criteria and try again. |
| IDE-1003 | User ID Not Found | The provided user ID does not exist in our records. Please verify the user ID and try again. |
| IDE-1004 | No Users Found | No users were found in the search. Please review the search criteria and try again. |
| IDE-1006 | Group ID Not Found | The provided group ID does not exist in our records. Please verify the group ID and try again. |
| IDE-1007 | Provider Not Found | The provided provider ID does not exist in our records. Please verify the provider ID and try again. |
| IDE-1012 | Provider Not Linked | The specified provider is not linked to this application. Please verify the provider ID and try again. |
| IDE-1020 | Role Not Found | The provided role ID does not exist in our records. Please verify the role ID and try again. |
| IDE-1024 | Permission Not Found | The provided permission ID does not exist in our records. Please verify the permission ID and try again. |
| IDE-1031 | Organization Not Found | The organization resolved from the access token does not exist. Please verify the token and try again. |
| IDE-1046 | Partner Not Found | The provided partner ID does not exist in this organization. Please verify the ID and try again. |
| IDE-1053 | Scope Catalog Not Found | The product `{value}` has not published a scope catalog, so none of its partners can be scoped. Check the product slug, or deploy a version of the product that declares its scope. |

### 409

| `code` | `title` | `message` |
| - | - | - |
| IDE-0017 | User Already Exists | A user with this username or email already exists. Please use a different username or email and try again. |
| IDE-0040 | MFA Already Enabled | Multi-factor authentication is already enabled for this user. |
| IDE-0056 | Phone Number In Use By SMS MFA | The phone number cannot be removed while a legacy SMS multi-factor enrollment is still recorded for this user, because SMS codes were delivered to it. Clear the enrollment first: an administrator calls DELETE `/v1/users/{id}/mfa/admin/sms`, or the member calls DELETE `/v1/users/{id}/mfa/sms` with their own token. The phone number can be removed afterwards, and the member can enroll app or email. |
| IDE-1008 | Provider Already Exists | A provider with this name already exists. Please use a different name and try again. |
| IDE-1011 | Provider Already Linked | This provider is already linked to the application. Use PATCH to update the link configuration. |
| IDE-1022 | Role Already Exists | A role with this name already exists. Please use a different name and try again. |
| IDE-1030 | Group Already Exists | A group with this name already exists. Please use a different name and try again. |
| IDE-1040 | Partner Display Name Already Exists | A partner named `{value}` already exists in this organization. Please choose a different displayName and try again. |
| IDE-1049 | Partner Has Applications | This partner still has `{value}` application(s) attached and cannot be deleted. Please delete the applications listed in the errors field and try again. |
| IDE-1058 | Group Has Members | This group still has members, so it cannot be deleted. Remove the group's members before deleting it. |
| IDE-1059 | Group Has Subgroups | Other groups are nested under this group, so it cannot be deleted. Delete or move the group's subgroups before deleting it. |

### 422

| `code` | `title` | `message` |
| - | - | - |
| IDE-1016 | Provider Credentials Rejected | The provider rejected the configured credentials, so it cannot send messages. This is a credential failure, not a delivery failure: correct the provider's credentials (clientId / clientSecret, or the SMTP login) and test again. Provider reported: `{value}` |
| IDE-1018 | Test Send Not Supported | Only Email and SMS providers can be test-sent. An OAuth provider has no message to send; its configuration is exercised by an actual sign-in. |

### 500

| `code` | `title` | `message` |
| - | - | - |
| IDE-0006 | Internal Server Error | The server encountered an unexpected error. Please try again later or contact support. |

### 503

| `code` | `title` | `message` |
| - | - | - |
| IDE-0064 | Application Creation Busy | Another application for this product is being created in your organization right now. Retry the request. |
| IDE-0065 | Lock Store Unavailable | The service that coordinates concurrent changes is temporarily unavailable. Nothing was changed. Retry the request. |
| IDE-0066 | Identity Provider Unavailable | The identity provider is temporarily unavailable. Retry the request. |


# Admin Disable MFA
Source: https://docs.lerian.studio/en/reference/platform/access-manager/admin-disable-mfa

/en/openapi/v3-current/AM-identity.yaml delete /v1/users/{id}/mfa/admin/{mfaType}
Turns off one of ANOTHER member's channels — the route for a member locked out by a lost device, or by a legacy `sms` enrollment.

`{id}` is the TARGET, not the administrator.

`app`, `email` and `sms` are all accepted. `sms` is CLEARING ONLY — the channel is retired and cannot be re-enrolled — and this is the only route that can clear it for somebody else: the whole-account reset `DELETE /v1/users/{id}/mfa` refuses an administrator's token, and a member holding only a legacy `sms` enrollment cannot sign in to obtain their own. Clearing it also unblocks `DELETE /v1/users/{id}/phone`.

⚠️ This LOWERS someone else's protection without their participation, and it is the step an attacker who reaches an administrative token would take first.

No confirmation code is taken, by design: an administrator holds neither the member's authenticator nor their mailbox, so there is no code they could legitimately produce. The administrative MFA resource is what authorizes this route.

On success the response has no body (204).

Failures:
- `400` — the channel name is not one this deployment serves.
- `403` — your token does not hold the administrative MFA resource.
- `404` — no such user.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Admin Enable MFA
Source: https://docs.lerian.studio/en/reference/platform/access-manager/admin-enable-mfa

/en/openapi/v3-current/AM-identity.yaml post /v1/users/{id}/mfa/admin/enable
Enables a second factor on ANOTHER member's account, and returns that member's recovery codes.

`{id}` is the TARGET — the member being protected — not the administrator. The administrator is identified by the token.

This is the route for onboarding someone who cannot complete enrollment themselves, and it skips the three-step self-service flow entirely: there is no device to prove, so nothing is verified. That is why it is granted to administrative roles only.

⚠️ The response body IS the target member's credential and is shown once. Hand it to them over a channel you trust.

Failures:
- `400` — the channel is unknown, or the target account lacks what it needs.
- `403` — your token does not hold the administrative MFA resource.
- `404` — no such user.
- `409` — that channel is already enabled for the target.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Grant a Role to Groups
Source: https://docs.lerian.studio/en/reference/platform/access-manager/assigns-groups-to-a-role

/en/openapi/v3-current/AM-identity.yaml post /v1/roles/{id}/groups
Gives one or more groups a role. Everybody in those groups can do what the role allows, and so can anybody added to them later.

This is the normal way access is granted here: grant to the group once, then manage people by membership. `{id}` is the role's slug; each entry in `groups` is a group's `name`, such as `midaz-viewer-group`.

Granting a role a group already holds is not an error. On success the response has no body (204).

Failures:
- `400` — `groups` is missing or empty.
- `404` — no such role in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Add Permissions to a Role
Source: https://docs.lerian.studio/en/reference/platform/access-manager/assigns-permissions-to-a-role

/en/openapi/v3-current/AM-identity.yaml post /v1/roles/{id}/permissions
Widens a role: everyone who already holds it — directly, or through a group — can do the added things.

`{id}` is the role's `name`, a slug such as `midaz-editor`; each entry in `permissions` is a permission id. There is no separate step to push the change out to holders; the role IS the grant.

Adding a permission the role already carries is not an error, so a partially applied form can safely be submitted again. On success the response has no body (204).

Failures:
- `400` — `permissions` is missing or empty.
- `404` — one of the permissions does not exist.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Grant a Role to Users
Source: https://docs.lerian.studio/en/reference/platform/access-manager/assigns-users-to-a-role

/en/openapi/v3-current/AM-identity.yaml post /v1/roles/{id}/users
Gives one or more people a role directly, without putting them in a group.

This is the exception rather than the rule: the usual path is to grant the role to a group (`POST /v1/roles/{id}/groups`) and put people in it. Use it for a genuinely individual case.

Granting it to somebody who already holds it is not an error. On success the response has no body (204).

Failures:
- `400` — `users` is missing or empty.
- `404` — no such role in your organization, or one of the users does not exist.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Create a Provider
Source: https://docs.lerian.studio/en/reference/platform/access-manager/create-a-provider

/en/openapi/v3-current/AM-identity.yaml post /v1/providers
Registers a message or login provider and stores its credentials.

Creating a provider does NOT put it in use. It becomes live only when it is linked to an application (`POST /v1/applications/{id}/providers`), so a new provider is inert and safe to configure ahead of time.

The credentials are stored but not verified here. To find out whether they actually work, call `POST /v1/providers/{id}/test-send`, which sends one real message.

Failures:
- `400` — a required member is missing or malformed.
- `409` — a provider with that name already exists.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Create a Role
Source: https://docs.lerian.studio/en/reference/platform/access-manager/create-a-role

/en/openapi/v3-current/AM-identity.yaml post /v1/roles
Creates a role. `name` is the identifier you will address it by everywhere else — it is NOT a generated UUID and cannot be changed afterwards.

A new role grants nothing until you put permissions in it (`POST /v1/roles/{id}/permissions`) and give it to someone (`POST /v1/roles/{id}/groups` or `POST /v1/roles/{id}/users`). Prefer granting to a GROUP.

Failures:
- `400` — a required member is missing or malformed.
- `409` — a role with that `name` already exists in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Delete a Provider
Source: https://docs.lerian.studio/en/reference/platform/access-manager/delete-a-provider

/en/openapi/v3-current/AM-identity.yaml delete /v1/providers/{id}
Removes a provider and its stored credentials permanently.

⚠️ Any application still linked to it loses that channel. Deleting the provider that carries SMS MFA codes means second factors stop being delivered; deleting the one that carries e-mail means password-reset codes stop arriving. Unlink it from every application first (`DELETE /v1/applications/{id}/providers/{providerId}`) and confirm another provider covers the category.

On success the response has no body (204).

Failures:
- `404` — no such provider in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Delete a Role
Source: https://docs.lerian.studio/en/reference/platform/access-manager/delete-a-role

/en/openapi/v3-current/AM-identity.yaml delete /v1/roles/{id}
Removes a role permanently, and with it every grant of that role — to groups and to people alike. Nobody is deleted, but everyone who held access ONLY through this role loses it without a per-holder confirmation.

There is no reversible pause. To take access away from one holder, revoke the grant (`DELETE /v1/roles/{id}/groups/{groupId}`) instead of deleting the role; to narrow it for everyone, remove permissions from the role.

On success the response has no body (204).

Failures:
- `404` — no such role in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Delete SSO provider configuration
Source: https://docs.lerian.studio/en/reference/platform/access-manager/delete-sso-provider-configuration

/en/openapi/v3-current/AM-identity.yaml delete /v1/sso/provider
Removes your organization's SSO provider configuration.

⚠️ Sign-in through that provider stops working immediately.

Unlike the other deletes in this API, this one answers `200`, not `204`.

Failures:
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Disable a single MFA channel
Source: https://docs.lerian.studio/en/reference/platform/access-manager/disable-a-single-mfa-channel

/en/openapi/v3-current/AM-identity.yaml delete /v1/users/{id}/mfa/{mfaType}
Turns off ONE channel — `app`, `email`, or a legacy `sms` enrollment — and leaves the others in place.

The body carries a 6-digit `code` that must prove THE CHANNEL BEING REMOVED: for `app`, the current passcode from the member's authenticator (there is no challenge step); for `email`, the code mailed by `POST /v1/users/{id}/mfa/disable/challenge`. Neither channel accepts the other's code.

`sms` is accepted for CLEARING ONLY. The channel was retired: it cannot be enrolled, cannot be chosen as the preferred method, and is never offered at sign-in. An enrollment recorded before the retirement can still be removed here, which is also what unblocks `DELETE /v1/users/{id}/phone`. It is the ONE channel that needs no code and no body: SMS is refused at sign-in, and there is no SMS proof to demand. A member whose ONLY factor is a legacy `sms` enrollment cannot sign in to call this route themselves — an administrator clears it for them with `DELETE /v1/users/{id}/mfa/admin/sms`.

Removing the last enabled channel leaves the account with no second factor, the same end state as `DELETE /v1/users/{id}/mfa`, so check `GET /v1/users/{id}/mfa` first if that is not the intention.

On success the response has no body (204).

Failures:
- `400` — the channel name is not one this deployment serves.
- `400 IDE-0007` / `IDE-0001` / `IDE-0002` — `app` or `email` with the body missing or malformed.
- `400 IDE-0042` — the code is wrong (or, for `app`, already used).
- `400 IDE-0060` — `email` with no live mailed code: none was requested, it expired, or it was spent.
- `400 IDE-0061` — the mailed code was answered wrongly too many times; request a new one.
- `400 IDE-0063` — the authorization server locked authenticator verification; wait.
- `400 IDE-0045` — the MFA operation could not be completed.
- `404` — no such user.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Get Organization IP Allowlist
Source: https://docs.lerian.studio/en/reference/platform/access-manager/get-organization-ip-allowlist

/en/openapi/v3-current/AM-identity.yaml get /v1/security/ip-allowlist
Returns the IP addresses and CIDR blocks your organization accepts requests from, and which surfaces that restriction is enforced on.

An EMPTY `entries` list means the allowlist is OFF; read it as "not enforcing", never as "locked down".

The organization is resolved from your token. There is no parameter naming another one, so this cannot read someone else's allowlist.

Read-only: nothing changes.

Failures:
- `403` — two different failures share this status, so read the `code`. Without a code it is a permissions problem: your token lacks the `security` resource. With `AUT-0021` it is the LOCKOUT case: your own address is outside the allowlist you are trying to read.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Get SSO provider configuration
Source: https://docs.lerian.studio/en/reference/platform/access-manager/get-sso-provider-configuration

/en/openapi/v3-current/AM-identity.yaml get /v1/sso/provider
Returns your organization's SSO provider configuration — the identity provider your people sign in through.

A tenant has AT MOST ONE active OAuth provider, so this route needs no id: it reads the one belonging to the organization resolved from your token, and cannot be pointed at another tenant's. It is a composed view over the generic `/v1/providers` catalog, which is still where Email and SMS providers are managed.

Read-only: nothing changes.

Failures:
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Link Provider to Application
Source: https://docs.lerian.studio/en/reference/platform/access-manager/link-provider-to-application

/en/openapi/v3-current/AM-identity.yaml post /v1/applications/{id}/providers
Attaches an existing provider to an application.

Linking is the step that makes a configuration live, so it is also the step that can break delivery. Test the provider first (`POST /v1/providers/{id}/test-send`).

Failures:
- `404` — no such application, or no such provider.
- `409` — that provider is already linked to this application.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# List Application Providers
Source: https://docs.lerian.studio/en/reference/platform/access-manager/list-application-providers

/en/openapi/v3-current/AM-identity.yaml get /v1/applications/{id}/providers
Returns the providers linked to one application, and which of them is the default for its category.

This is the answer to "where does this application's mail actually go?" — a provider exists in the catalog, but it only carries anything for an application it is linked to.

This listing is NOT paginated: it returns a plain array.

Read-only: nothing changes.

Failures:
- `404` — no such application in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# List Permissions
Source: https://docs.lerian.studio/en/reference/platform/access-manager/list-permissions

/en/openapi/v3-current/AM-identity.yaml get /v1/permissions
Returns the catalog of permissions this deployment knows about, one page at a time.

A permission is the smallest unit of access — a resource and the verbs allowed on it. You do not create them: each product DECLARES its own through `PUT /v1/declarations/{slug}` and the server reconciles the catalog, which is why this family is read-only.

Read this to find out what you can put INTO a role. `product` narrows to one product's declarations and `resource` to one collection; `name` is the substring match.

This is not the list of what a partner can be granted in a product: that is everything your organization's `<product>-editor-role` holds, which can span more permissions than `product` returns here. Read it from `GET /v1/partners/ceiling?product=<product>`.

Read-only: nothing changes.

Failures:
- `400 IDE-0018` — `limit` is above the deployment's maximum (100 by default).
- `400 IDE-0019` — `page` is below 1.
- `400 IDE-1041` — `product` is not a known catalog slug. The message lists the catalog. A whitespace-only `product` is treated as absent instead.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# List Providers
Source: https://docs.lerian.studio/en/reference/platform/access-manager/list-providers

/en/openapi/v3-current/AM-identity.yaml get /v1/providers
Returns the message and login providers configured for your organization, one page at a time.

A provider is an outbound channel: an SMTP or e-mail service that carries verification and password-reset mail, an SMS service that carries MFA codes, or an OAuth identity provider people sign in through. Filter with `category` — `Email`, `SMS` or `OAuth`.

Read-only: nothing changes. A provider listed here is configured but not necessarily in USE — what makes it live is being linked to an application (`GET /v1/applications/{id}/providers`).

Failures:
- `400 IDE-0018` — `limit` is above the deployment's maximum (100 by default).
- `400 IDE-0019` — `page` is below 1.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# List Roles
Source: https://docs.lerian.studio/en/reference/platform/access-manager/list-roles

/en/openapi/v3-current/AM-identity.yaml get /v1/roles
Returns your organization's roles, one page at a time.

A role is a named bundle of permissions. It is what you grant to a group (or, less commonly, straight to a person); the permissions inside it are what the holder may then do. Called whenever the role list is shown, and after any create or delete to refresh it.

The filters are relational, not text matching: `userId` narrows to the roles that user holds and `groupId` to the roles granted to that group, which is how you answer "what does this person have?" without walking every role. `name` is the substring match.

Read-only: nothing changes.

Failures:
- `400 IDE-0018` — `limit` is above the deployment's maximum (100 by default).
- `400 IDE-0019` — `page` is below 1.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Preflight an SSO provider configuration
Source: https://docs.lerian.studio/en/reference/platform/access-manager/preflight-an-sso-provider-configuration

/en/openapi/v3-current/AM-identity.yaml post /v1/sso/provider/preflight
Validates a candidate SSO configuration and WRITES NOTHING.

Call it before `PUT /v1/sso/provider`. The upsert is the call that can lock an organization out of its own login screen; this one costs nothing, so there is no reason to skip it.

The response is a report, not a yes/no: it names what it could and could not verify.

Failures:
- `400` — the candidate configuration is malformed enough that it cannot be checked at all.



# Regenerate MFA Recovery Codes
Source: https://docs.lerian.studio/en/reference/platform/access-manager/regenerate-mfa-recovery-codes

/en/openapi/v3-current/AM-identity.yaml post /v1/users/{id}/mfa/recovery-codes
Issues a fresh set of recovery codes and INVALIDATES the previous set immediately.

⚠️ The response body IS the credential. These codes bypass every second factor, they are returned once and never again, and anyone holding one can sign in without the device. Store them where the account's password is stored, not next to it.

Call this when the old set was used up, exposed, or lost.

The response carries `Cache-Control: no-store`.

Failures:
- `400` — MFA is not enabled on the account, so there is nothing to recover.
- `404` — no such user.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Revoke a Role from one Group
Source: https://docs.lerian.studio/en/reference/platform/access-manager/removes-a-single-group-from-a-role

/en/openapi/v3-current/AM-identity.yaml delete /v1/roles/{id}/groups/{groupId}
Takes a role away from one group. `{id}` is the ROLE and `{groupId}` is the GROUP — both are slugs, so the order of the two is the only thing telling them apart, and swapping them revokes a grant nobody asked to revoke.

The batch form, `POST /v1/roles/{id}/groups/remove`, does the same for a list.

The group itself is untouched and keeps its members. Revoking from a group that does not hold the role is not an error. On success the response has no body (204).

Failures:
- `404` — no such role in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Remove one Permission from a Role
Source: https://docs.lerian.studio/en/reference/platform/access-manager/removes-a-single-permission-from-a-role

/en/openapi/v3-current/AM-identity.yaml delete /v1/roles/{id}/permissions/{permId}
Takes one permission out of one role. `{id}` is the ROLE and `{permId}` is the PERMISSION — both are slugs, so the order of the two is what tells them apart, and swapping them narrows something nobody asked to narrow.

The batch form, `POST /v1/roles/{id}/permissions/remove`, does the same for a list.

Removing an existing permission the role does not carry is not an error. On success the response has no body (204).

Failures:
- `404` — the permission does not exist.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Revoke a Role from one User
Source: https://docs.lerian.studio/en/reference/platform/access-manager/removes-a-single-user-from-a-role

/en/openapi/v3-current/AM-identity.yaml delete /v1/roles/{id}/users/{userId}
Takes a role away from one person. `{id}` is the ROLE and `{userId}` is the PERSON — the order of the two matters, and swapping them revokes a grant nobody asked to revoke.

The batch form, `POST /v1/roles/{id}/users/remove`, does the same for a list.

Only the DIRECT grant is revoked: if the person also holds this role through a group they keep it, and the call still answers 204. Revoking from somebody who does not hold the role is not an error. On success the response has no body (204).

Failures:
- `404` — no such role in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Revoke a Role from Groups in Batch
Source: https://docs.lerian.studio/en/reference/platform/access-manager/removes-multiple-groups-from-a-role-batch

/en/openapi/v3-current/AM-identity.yaml post /v1/roles/{id}/groups/remove
Takes a role away from several groups at once, naming them in the body.

It is a POST rather than a DELETE because the groups travel in a request body; `DELETE /v1/roles/{id}/groups/{groupId}` does the same for exactly one.

The groups themselves are untouched and keep their members. Revoking from a group that does not hold the role is not an error. On success the response has no body (204).

Failures:
- `400` — `groups` is missing or empty.
- `404` — no such role in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Remove Permissions from a Role in Batch
Source: https://docs.lerian.studio/en/reference/platform/access-manager/removes-multiple-permissions-from-a-role-batch

/en/openapi/v3-current/AM-identity.yaml post /v1/roles/{id}/permissions/remove
Narrows a role by several permissions at once, naming them in the body.

It is a POST rather than a DELETE because the permissions travel in a request body; `DELETE /v1/roles/{id}/permissions/{permId}` does the same for exactly one. Both exist and both are supported.

Removing an existing permission the role does not carry is not an error. On success the response has no body (204).

Failures:
- `400` — `permissions` is missing or empty.
- `404` — one of the permissions does not exist.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Revoke a Role from Users in Batch
Source: https://docs.lerian.studio/en/reference/platform/access-manager/removes-multiple-users-from-a-role-batch

/en/openapi/v3-current/AM-identity.yaml post /v1/roles/{id}/users/remove
Takes a role away from several people at once, naming them in the body.

It is a POST rather than a DELETE because the people travel in a request body; `DELETE /v1/roles/{id}/users/{userId}` does the same for exactly one.

Only the DIRECT grant is revoked. Somebody who also holds this role through a group keeps it, and the call still answers 204 — if the intent is to remove their access entirely, take them out of the group too. Revoking from somebody who does not hold the role is not an error. On success the response has no body (204).

Failures:
- `400` — `users` is missing or empty.
- `404` — no such role in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Retrieve Provider details
Source: https://docs.lerian.studio/en/reference/platform/access-manager/retrieve-a-provider

/en/openapi/v3-current/AM-identity.yaml get /v1/providers/{id}
Returns one provider's configuration.

Secrets are not returned in full. Read this to see how a provider is configured and which category it serves, not to recover a credential.

Read-only: nothing changes.

Failures:
- `404` — no such provider in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Retrieve Permission details
Source: https://docs.lerian.studio/en/reference/platform/access-manager/retrieve-permission-details

/en/openapi/v3-current/AM-identity.yaml get /v1/permissions/{id}
Returns one permission: the resource it governs, the actions it allows, and the product that declared it.

`{id}` is the permission's name — a slug, not a UUID.

Read-only: nothing changes. A permission existing in the catalog says nothing about who HOLDS it; for that, read a role's permissions or a user's effective permissions.

Failures:
- `404` — no permission with that name is declared in this deployment.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Retrieve Role details
Source: https://docs.lerian.studio/en/reference/platform/access-manager/retrieve-role-details

/en/openapi/v3-current/AM-identity.yaml get /v1/roles/{id}
Returns one role.

`{id}` is the role's `name` — a slug such as `midaz-editor`, not a UUID. Called to open a role's detail screen, and before a PATCH. The permissions inside the role are read separately with `GET /v1/roles/{id}/permissions`.

Read-only: nothing changes.

Failures:
- `404` — no such role in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# List the Permissions of a Role
Source: https://docs.lerian.studio/en/reference/platform/access-manager/returns-the-permissions-assigned-to-a-role

/en/openapi/v3-current/AM-identity.yaml get /v1/roles/{id}/permissions
Returns every permission the role carries, as a plain array — this listing is NOT paginated.

A role is a named bundle of permissions; this is what is inside the bundle. Called to open a role's detail screen, and before adding or removing entries so the form starts from the current state.

Read-only: nothing changes. It answers "what does this role allow?", not "who holds it?" — for the holders, list users or groups filtered by this role.

Failures:
- `404` — no such role in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Set Provider as Default
Source: https://docs.lerian.studio/en/reference/platform/access-manager/set-default-application-provider

/en/openapi/v3-current/AM-identity.yaml patch /v1/applications/{id}/providers/{providerId}/default
Makes one linked provider the application's default for its category — the one its messages go through when nothing more specific applies.

An application can have several providers of a category linked but only one default, so this call also DEMOTES whichever was default before. That demotion is silent and is the part worth knowing: promoting a provider is how delivery moves off the previous one.

Failures:
- `404` — no such application, or that provider is not linked to it.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Set Organization IP Allowlist
Source: https://docs.lerian.studio/en/reference/platform/access-manager/set-organization-ip-allowlist

/en/openapi/v3-current/AM-identity.yaml put /v1/security/ip-allowlist
Replaces the addresses your organization accepts requests from.

⚠️ THIS IS THE CALL THAT CAN LOCK YOU OUT. Read `GET /v1/security/ip-allowlist` first, and keep your own address in the list.

`entries` is REQUIRED and replaces the stored list wholesale — there is no per-entry merge. Bare addresses are widened to host routes (`/32`, `/128`) and CIDRs are canonicalized on save, so what you read back may be spelled differently from what you sent. An explicit EMPTY list turns the allowlist OFF; omitting the member is a `400`, never a silent wipe.

Each entry is either a bare string (`"203.0.113.0/24"`) or a labeled object (`{"cidr": "203.0.113.0/24", "description": "São Paulo office"}`), and the two forms can be mixed. A string is stored with an empty description. Only `cidr` is validated and only `cidr` decides whether a request is allowed; `description` is free text for your administrators and is stored as sent. When the same network appears twice, the first entry — and its description — is kept.

`scopes` is the member to be careful with, because it has THREE meanings:
- OMIT it — the surfaces currently enforced are left exactly as they are.
- Send `[]` — enforcement is turned off on every surface, while the entries stay stored.
- Send values — enforcement applies to exactly those surfaces.

So an entries-only update must OMIT `scopes`.

Failures:
- `400 IDE-0036` — an entry is not a valid IP or CIDR, or a labeled entry has no `cidr`. The message names the offending value.
- `400` — a scope is not one this deployment enforces, or `entries` was omitted.
- `403` — as on the read: a permissions problem, or `AUT-0021`, the lockout case.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Test send through a Provider
Source: https://docs.lerian.studio/en/reference/platform/access-manager/test-send-through-a-provider

/en/openapi/v3-current/AM-identity.yaml post /v1/providers/{id}/test-send
Sends ONE REAL message through a stored provider, to a destination you name, so you can find out whether its credentials work before anyone depends on them.

This is not a dry run: a real e-mail or SMS is delivered and, for SMS, may be billed by the carrier.

The two failure modes are deliberately distinguishable, because they call for opposite actions:
- `422 IDE-1016` — the provider REJECTED the credentials. Fatal: fix the configuration.
- `400 IDE-1017` — the credentials were accepted but the message was not delivered. The configuration may be perfectly fine — a trial account that refuses unverified recipients answers exactly this.

Other failures:
- `404` — no such provider in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Unlink Provider from Application
Source: https://docs.lerian.studio/en/reference/platform/access-manager/unlink-provider-from-application

/en/openapi/v3-current/AM-identity.yaml delete /v1/applications/{id}/providers/{providerId}
Detaches a provider from an application. The provider itself is untouched and stays in the catalog for other applications; only this application stops using it.

⚠️ If it was the DEFAULT for its category and nothing else of that category is linked, the application has no channel left: its verification mail or its MFA codes stop being delivered. Link a replacement and make it default before unlinking the last one.

On success the response has no body (204).

Failures:
- `404` — no such application, or that provider is not linked to it.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Update a Provider
Source: https://docs.lerian.studio/en/reference/platform/access-manager/update-a-provider

/en/openapi/v3-current/AM-identity.yaml patch /v1/providers/{id}
Changes a provider's configuration or credentials. Anything you omit is left alone.

⚠️ A provider that is LINKED to an application is live: changing its credentials here takes effect on the next message it carries, with no confirmation step. If that provider carries SMS MFA codes, a wrong credential stops second factors from arriving and locks people out — verify with `POST /v1/providers/{id}/test-send` after changing it.

Failures:
- `400` — a supplied member is malformed.
- `404` — no such provider in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Update a Role
Source: https://docs.lerian.studio/en/reference/platform/access-manager/update-a-role

/en/openapi/v3-current/AM-identity.yaml patch /v1/roles/{id}
Changes a role's label and description. Anything you omit is left alone.

The role's `name` — the identifier in `{id}` — CANNOT be changed here or anywhere else; it is what grants point at. The permissions inside the role are not edited here either: use `POST /v1/roles/{id}/permissions` and its remove counterpart. So this endpoint cannot widen or narrow anybody's access, which is why it is the least dangerous call in the family.

Failures:
- `400` — a supplied member is malformed.
- `404` — no such role in your organization.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Update Provider Link
Source: https://docs.lerian.studio/en/reference/platform/access-manager/update-application-provider-link

/en/openapi/v3-current/AM-identity.yaml patch /v1/applications/{id}/providers/{providerId}
Changes how one provider is used by one application. Anything you omit is left alone.

This edits the LINK, not the provider: the provider's own credentials are changed with `PATCH /v1/providers/{id}`, and a change there affects every application linked to it, while a change here affects only this one.

Failures:
- `404` — no such application, or that provider is not linked to it.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Update SSO login policy
Source: https://docs.lerian.studio/en/reference/platform/access-manager/update-sso-login-policy

/en/openapi/v3-current/AM-identity.yaml patch /v1/sso/policy
Failures:
- `400` — the policy payload is malformed.
- `404` — the application backing your organization's login was not found.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Upsert a plugin declaration
Source: https://docs.lerian.studio/en/reference/platform/access-manager/upsert-a-plugin-declaration

/en/openapi/v3-current/AM-identity.yaml put /v1/declarations/{slug}
Creates or replaces the access-manager declaration for the given plugin slug. Called by the product itself, at start-up, with its own M2M token.

The body has two sections and each is replaced ONLY when present, so a product can publish one without touching the other:
- the ACCESS section — `permissions`, `roles` and `m2m` together (a permission names the roles it grants to, so they are applied as one full sync: what the section no longer declares is removed). Served in single-tenant deployments only; in multi-tenant it answers `501`.
- the SCOPE section — `scope.dimensions`, the dimensions the product's routes address instances by, and `partners`, the product's opt-in to partner credentials (either alone is the section), plus `levels` in the scope-only form. It replaces the product's scope catalog wholesale and is served in single- AND multi-tenant deployments: the catalog is global per product. Every partner write is validated against it, and `GET /v1/scope-catalog/{product}` reads it back.

A body carrying both sections in multi-tenant applies the scope section and then answers `501` for the access section.

Failures: `422` — the manifest is malformed (the message lists every violation), declares neither section, its `service` is not the slug, no application is registered for the calling client, or the identity provider refused the scope catalog; `403` — the token does not speak for the slug; `409` — the access section could not be persisted; `501` — the access section in a multi-tenant deployment; `503 IDE-0066` — the identity provider is unavailable, retry later; `500` — another dependency failed, retry.



# Upsert SSO provider configuration
Source: https://docs.lerian.studio/en/reference/platform/access-manager/upsert-sso-provider-configuration

/en/openapi/v3-current/AM-identity.yaml put /v1/sso/provider
Creates or REPLACES your organization's SSO provider configuration.

⚠️ A configuration that is accepted here but wrong at the identity provider locks people out at the login screen. Validate the configuration first with `POST /v1/sso/provider/preflight`, which writes nothing.

Failures:
- `400` — the configuration is malformed.
- `503 IDE-0066` — the identity provider is unavailable (unreachable, too slow to answer, or failing). Nothing about the request was wrong; retry it later.



# Archive a session
Source: https://docs.lerian.studio/en/reference/platform/narya/archive-a-session

/en/openapi/v3-current/narya.yaml delete /v1/sessions/{sessionId}
Archives the session. This is an archive, not a destroy: the transcript is durable product state and remains fully queryable through the records surface and exportable. An archived session accepts no new work; branch it to continue from any entry.
It is ONE WAY, and there is no operation here that undoes it: once a session is archived, nothing can move it back to accepting work. What continues from it is a branch, which is a new session with a new id — so every reference to the archived id (a link, a script, a teammate's note) keeps pointing at a conversation that will never run again. A client that offers this to a person should ask them first.
A session with a turn in flight is refused (409) rather than archived: that turn would finish into a session no write can move afterwards.



# Create a session
Source: https://docs.lerian.studio/en/reference/platform/narya/create-a-session

/en/openapi/v3-current/narya.yaml post /v1/sessions
Creates a durable session bound to a repository. The session exists before any turn runs; submitting the first message is a separate operation.



# Describe the host process
Source: https://docs.lerian.studio/en/reference/platform/narya/describe-the-host-process

/en/openapi/v3-current/narya.yaml get /v1/host
Returns the host's version, uptime, mode and store path. This is the handshake operation clients call first, and it is gated like every other: a request without a valid token answers 401 NRY-0011 on the local socket exactly as over TCP. The socket's EXISTENCE is what tells a client a host is there; an exempt handshake would be a second trust regime. There is no shutdown operation — host lifecycle belongs to the daemon manager, outside this contract.



# Get a session
Source: https://docs.lerian.studio/en/reference/platform/narya/get-a-session

/en/openapi/v3-current/narya.yaml get /v1/sessions/{sessionId}
Returns one session with its status, model in use, token usage totals and cost.



# Hold this session back from the organisation, or hand it back
Source: https://docs.lerian.studio/en/reference/platform/narya/hold-this-session-back-from-the-organisation-or-hand-it-back

/en/openapi/v3-current/narya.yaml put /v1/sessions/{sessionId}/visibility
Marks one conversation `private`, or hands it back to `organisation`, which is what every session is until somebody says otherwise. Inside one organisation the team is the default and this mark is the only exception to it.
IT TAKES EFFECT ON THE NEXT READ, from anywhere. Nothing caches the answer: every read of a session asks the stored mark at the moment it is served, so a session marked here disappears from a colleague's list and their open window's next request at once, without a restart and without anything being pushed to them.
WHO MAY CALL IT: the session's owner, always — a person's own conversation is theirs to hold back — and a member who administers the organisation's membership, for anybody, because a departed colleague's work has to be able to come back to the team. Nobody else, and deliberately not the holder of `sessions:read-private`: that permission exists so a security question can be answered, and it does not extend to changing what everybody else may read.
Marking a session the mark it already carries is not an error: the state asked for holds. Nothing is announced and nothing is written into the transcript — who may read a conversation is a fact about it rather than something that happened in it, and its position in a session list does not move.



# Narya host API overview
Source: https://docs.lerian.studio/en/reference/platform/narya/host-api-overview

The HTTP contract between the Narya host and every client: one Unix socket, one event stream, one error envelope, and cursor paging.

> [!TIP]
>
> **This section is for developers.** If you want a business-level overview of Narya, see [What is Narya](/en/platform/narya/what-is-narya).

Narya runs coding agents behind one HTTP API. One long-lived host owns the sessions, the store and the model connections. The terminal client and the one-shot command that Lerian ships drive this API. A client you write drives the same one.

## Transport and authorization

***

The host listens on a Unix socket.

The socket is `narya.sock` inside the Narya home. The home is `$NARYA_HOME`, or `$XDG_CONFIG_HOME/narya`, or `~/.config/narya`, in that order.

Requests are HTTP/1.1 with JSON bodies. Field names are camelCase. Dial the socket and send an ordinary request:

```bash theme={null}
curl --unix-socket ~/.config/narya/narya.sock -H "Authorization: Bearer <token>" http://localhost/v1/host
```

The authority in that URL is ignored, because the connection is already the socket. Any host name works.

## Work is accepted, and results stream

***

`POST /v1/sessions/{sessionId}/messages` answers `202` with a turn id. Everything the turn produces streams over `GET /v1/events` as server-sent events.

The `data` payload is one JSON event envelope, and its `type` property says which event it is. Frames carry no `event:` or `retry:` line.

```
id: 1011
data: {"id":"1011","type":"turn-finished","sessionId":"6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d","timestamp":"2026-08-08T12:05:00Z","payload":{"turnId":"4d8e2f6a-0b1c-4d3e-9f5a-7b9c1d3e5f0a","stopReason":"completed"}}

```

Two query parameters shape the stream. `sessionId` narrows it to one session. `hostEvents=true` adds the events that belong to no session, and it applies only beside `sessionId`.

To resume, send the last id you received in the `Last-Event-ID` request header. The stream continues from the first event after it that the store still holds. Compare the first id you receive against the one you sent, and read state again through the `GET` operations when there is a gap. A cursor newer than anything the store holds gets `409` with code `NRY-0026`.

## The two envelopes

***

A paged list answers a cursor envelope: `items`, `limit` and a `nextCursor` when more remains. Cursors are opaque. Pass one back as the `cursor` query parameter to get the next page.

One error envelope: `code`, `title` and `message`. Codes are `NRY-` and four digits.

```json theme={null}
{
  "code": "NRY-0002",
  "title": "Session not found",
  "message": "No session with id 6b9f6d2e-1c3a-4f5b-9d7e-2a8c4e6f0b1d exists on this host."
}
```

> **[The host API](/en/platform/narya/the-host-api)**
>
> Read what the host serves and why the contract has this shape.

> **[Error list](/en/reference/platform/narya/host-api-error-list)**
>
> Look up every code the host answers.


# List sessions
Source: https://docs.lerian.studio/en/reference/platform/narya/list-sessions

/en/openapi/v3-current/narya.yaml get /v1/sessions
Cursor-paginated list of sessions on this host, filterable by repository, environment and status. One query across every repository.



# Put this session into a named response style
Source: https://docs.lerian.studio/en/reference/platform/narya/put-this-session-into-a-named-response-style

/en/openapi/v3-current/narya.yaml put /v1/sessions/{sessionId}/style
Points a session at one of the named response styles configuration declares, so every following answer is shaped by the text that style appends to the assembled system prompt. The empty string CLEARS, putting the prompt back byte-for-byte to what it was.
It takes effect from the next turn and touches nothing else: not a turn in flight, not which model the session runs, not its rules. The style composes with an agent recipe rather than replacing one — the recipe supplies the identity, the style shapes how it answers — and it applies to every lane of the session, delegates included, because a delegate's answer lands in the same transcript a person reads.
A NAME CONFIGURATION DOES NOT DECLARE IS REFUSED with 422, naming the file that would declare it, and the session keeps whatever style it had. Refused at the door rather than at prompt time on purpose: a session can then never hold a name that resolves to nothing. The names that exist are the person's own `[styles.*]` plus those of this session's repository once its directory is trusted, with the person's own winning a name both files declare.
The change is ANNOUNCED — one line in the transcript saying the voice changed — because an answer that reads differently with nothing saying why is unreadable. Putting a session into the style it already holds is not an error and is silent: the state asked for holds, and a script run twice must not write the line twice. An archived session is refused, on the terms setSessionModel refuses one: a style decides how the next answer reads, and there is no next answer.



# Record whether anybody is watching this session
Source: https://docs.lerian.studio/en/reference/platform/narya/record-whether-anybody-is-watching-this-session

/en/openapi/v3-current/narya.yaml put /v1/sessions/{sessionId}/posture
States, as a recorded fact, whether somebody is there to answer a permission prompt raised in this session. `detached` hands the session to the host to keep working with nobody watching: from the next ask onwards, a prompt is refused and recorded with its reason instead of blocking a turn on a question nothing can answer. `attended` is the posture every session starts under and means the opposite.
The host is already detached, so work outlives the terminal whether or not this is called — what this operation changes is what happens at the next permission prompt, and nothing else. It never touches a turn in flight, never cancels anything, and never changes which model or rules a session runs under.
Setting the posture a session already holds is not an error: the state asked for holds, and the answer is the same as the call that got it there. This is the operation the clients' exit prompt performs when a person closes a terminal on a live turn and chooses to hand it over; a session left alone by any other exit — a crash, a closed lid, a kill — keeps the posture it had.
`detached` is REFUSED with 422 in a repository nobody has trusted, and the message names the gesture that changes the answer. With nobody there to be asked, a session resolves onto the rule set that applies when no prompt can be shown, and in a directory nobody vouched for that set is wider than the untrusted one it would replace — so the handover would loosen what runs unasked rather than tightening it. The stored posture is left exactly as it was. A session already recorded detached is re-checked when the host resumes it and demoted to `attended` if the directory is still not trusted.



# Rename the session
Source: https://docs.lerian.studio/en/reference/platform/narya/rename-the-session

/en/openapi/v3-current/narya.yaml put /v1/sessions/{sessionId}/title
Renames the session. Metadata only: no lane is touched, so a rename during a running turn is legal and changes nothing about that turn. A title of only whitespace is refused rather than stored — a name made of spaces is not a name, and a client rendering it would show a session with a blank identity instead of falling back to what it does know. Nothing about this operation generates a title: the new one is the caller's, exactly as SessionCreate's is.



# Report every declared external tool server's health and cost
Source: https://docs.lerian.studio/en/reference/platform/narya/report-every-declared-external-tool-server-s-health-and-cost

/en/openapi/v3-current/narya.yaml get /v1/tool-servers
Answers, per declared MCP tool server, whether it is up, since when, how many consecutive connection attempts have failed and why the last one did — plus how many calls it has been asked to make and how many characters of model context its presence in the budgeted catalogue spends. Health is taken live off an MCP ping while answering, so a server holding an open socket and answering nothing reads as down rather than as connected. The whole sweep is bounded by the request: the pings go out in parallel, so eight silent endpoints cost one ping ceiling between them.



# Run the read-only health walk
Source: https://docs.lerian.studio/en/reference/platform/narya/run-the-read-only-health-walk

/en/openapi/v3-current/narya.yaml get /v1/doctor
Runs `narya doctor`'s own walk over this installation — home directory, config, host lock, socket, store, sessions, package jobs, tool servers, credentials, binary and terminal — and answers both the rendered text and the structured lines behind it. Read-only throughout: every check reads, the store is opened read-only, and a finding names the command that repairs it rather than running one.
It exists so a client does not have to compile the walk to offer `/doctor`. The walk lives with the engine, and the things a caller knows about itself that a host cannot — which binary is asking, which build produced it, what the caller's own terminal can render, and which desktop helpers the caller can actually deliver through — travel as parameters rather than being guessed at from the host's process. A host that is not running cannot answer this at all, which is the one case a client handles itself: it says so and names `narya doctor`, the command that walks a machine whose host is down.
One line stays the HOST's own fact whatever a caller says: the keychain check describes the session the host process runs in, since that is the process that stores and reads a credential.



# Switch the session's model
Source: https://docs.lerian.studio/en/reference/platform/narya/switch-the-session-s-model

/en/openapi/v3-current/narya.yaml put /v1/sessions/{sessionId}/model
Points the session at another model, and records that model as this installation's default for every session opened afterwards. No host restart and no new session: the next turn runs on the chosen model, and a turn already running keeps the model it started on — a switch never mutates a turn in flight. Note what that means for the message a person sends next while a turn is running: it is admitted as steering into that turn (see createMessage), so it is answered by the model the turn started on, not by the one just chosen. A client that tells them "the next message runs on it" is telling them something untrue. The switch is announced in the transcript as a system entry, like every other model change nobody typed — except when a turn is in flight, where an entry cannot be placed without separating a tool call from its result, which would fail that turn and quarantine the session on recovery; the switch still takes effect, and this response is the confirmation.

The variant travels WITH the model as one choice, never as a setting beside it: a body naming no variant runs the chosen model at its own defaults, so switching model always clears a level the previous model was running at rather than carrying it onto one that may not offer it. The variant is recorded with the model as this installation's default for sessions opened afterwards, on the same terms the model itself is.



# Create a subscription
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/create-subscription

/en/openapi/v3-current/streaming-hub.yaml post /v1/subscriptions
Creates a delivery subscription for the authenticated tenant. A `tenant_id` in the body is ignored.

A `webhook` subscription is born `pending_verification` and mints a signing secret that is returned in this response (see `signingSecret`); it stays undeliverable until a successful probe via `POST /v1/subscriptions/{id}/ping` moves it to `active`. A queue subscription (`sqs`, `rabbitmq`, `eventbridge`) is also born `pending_verification` and mints no secret; it stays undeliverable until a probe succeeds. Every queue kind activates on an outbound credential supplied and probed via `PUT /v1/subscriptions/{id}/credential`. An AWS kind (`sqs`, `eventbridge`) has a second path that stores no credential: register a delegated grant, then call `POST /v1/subscriptions/{id}/verify`. Inline `sink_config` or `credential` at create is rejected — queue credentials arrive only on the credential PUT.



# Delete a subscription
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/delete-subscription

/en/openapi/v3-current/streaming-hub.yaml delete /v1/subscriptions/{id}
Soft-deletes a subscription scoped to the authenticated tenant. The operation is idempotent: an absent, already-deleted, or cross-tenant id is a no-op that still answers `204` (no existence oracle).



# Get the operational dashboard snapshot
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/get-dashboard

/en/openapi/v3-current/streaming-hub.yaml get /v1/dashboard
Returns one consistent read of the tenant's hub: a point-in-time subscription census and push backlog, plus ingestion, push-delivery, and pull-eligibility counts over the selected period, with a time series. The period is `[from, to)`, or the rolling `window_hours` width that ends at the hub's snapshot instant. A count is `0` when nothing matched; `null` means the fact does not exist. This route never consumes events and never moves a pull cursor. Authorization checks the resource `dashboard` and the action `get`.



# List the event catalog
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/get-event-catalog

/en/openapi/v3-current/streaming-hub.yaml get /v1/catalog
Returns the manifest-fed catalog snapshot — the last-known-good aggregation of the producer manifests Streaming Hub tracks. The catalog is global in v1 (byte-identical regardless of which tenant authenticates) and control-plane only; the data plane never consults it. An empty snapshot returns `200` with `events: []` (fail-closed to last-known-good — never an error on an empty catalog).



# Prometheus metrics
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/get-metrics

/en/openapi/v3-current/streaming-hub.yaml get /metrics
Serves a Prometheus text-exposition document. Streaming Hub exports its runtime metrics over OTLP, so this endpoint serves only the static `streaming_hub_build_info` gauge — the spine metrics are scraped from the OTLP collector, not here. Unauthenticated.



# Runtime snapshot
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/get-runtime

/en/openapi/v3-current/streaming-hub.yaml get /runtime
Returns a cheap Go-runtime snapshot for incident triage (goroutine count, GC cycles, heap bytes). No tenant or high-cardinality data. Unauthenticated.



# Get a subscription
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/get-subscription

/en/openapi/v3-current/streaming-hub.yaml get /v1/subscriptions/{id}
Returns one subscription scoped to the authenticated tenant. An absent, soft-deleted, or cross-tenant id returns a uniform `404 not_found` (no existence oracle). The response never carries the signing secret. It carries `endpoint_display`, not the full destination; read that with `GET /v1/subscriptions/{id}/endpoint`.



# Read a subscription's full destination
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/get-subscription-endpoint

/en/openapi/v3-current/streaming-hub.yaml get /v1/subscriptions/{id}/endpoint
Returns the full, unmasked delivery destination of one subscription of the authenticated tenant. The list and detail routes return only `endpoint_display`. Authorization checks the resource `subscriptions` and the action `post`, the same permission that creates a subscription. An absent, soft-deleted, or cross-tenant id returns the same uniform `404 not_found` as the detail route.



# Get subscription delivery health
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/get-subscription-health

/en/openapi/v3-current/streaming-hub.yaml get /v1/subscriptions/{id}/health
Returns a consolidated, non-secret delivery-health rollup for one subscription — the "why did this tenant stop receiving events" view. The existence gate runs first, so an absent, soft-deleted, or cross-tenant id returns a uniform `404 not_found`. Outcome counts are a recent-window view, not an all-time tally.



# Get AWS delegated-grant setup artifacts
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/get-subscription-setup-artifacts

/en/openapi/v3-current/streaming-hub.yaml get /v1/subscriptions/{id}/setup-artifacts
Generates the AWS delegated-grant onboarding artifacts for an AWS-sink subscription (`sqs`, `eventbridge`): the cross-account IAM trust policy and a CloudFormation quick-create console link the customer applies in their own AWS account to create the delivery role Streaming Hub assumes. On first fetch a non-secret `sts:ExternalId` correlation value is minted and embedded in both artifacts; a re-fetch reuses it (stable artifacts). No AWS credential is ever stored or returned — the role is assumed per delivery, guarded by the `ExternalId` condition. A non-AWS sink returns `422 validation_error`.



# Build identity
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/get-version

/en/openapi/v3-current/streaming-hub.yaml get /version
Returns the build identity injected at link time. Unauthenticated.



# List dead-letter observations
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/list-dlq-observations

/en/openapi/v3-current/streaming-hub.yaml get /admin/dlq
Cross-tenant operator forensics: returns a keyset-paginated, reverse-chronological page of dead-letter observations captured from the delivery pipeline. This is an operator surface — it authorizes against an operator scope and carries no tenant context. The projection carries no secret, no customer endpoint URL, and no signing material. The `tenant_id_raw` field is an untrusted, best-effort capture surfaced for forensic value only.



# List subscriptions
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/list-subscriptions

/en/openapi/v3-current/streaming-hub.yaml get /v1/subscriptions
Lists the authenticated tenant's live subscriptions, newest-first, keyset-paginated. No read projection ever carries the signing secret. Each row carries `endpoint_display`, a short rendering of the destination; read the full destination with `GET /v1/subscriptions/{id}/endpoint`.



# List the subscriptions needing attention
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/list-subscriptions-needing-attention

/en/openapi/v3-current/streaming-hub.yaml get /v1/dashboard/subscriptions
Returns one keyset page of the tenant's subscriptions that need an operator's attention, ordered by attention rank, then most recent failure, then id. Each item carries only non-secret operational state and the period's attempt counts: never an endpoint, credential, signing secret, or raw error. To read the next page, send `next_cursor` as `cursor` with the same `from` and `to`. Authorization checks the resource `dashboard` and the action `get`.



# Liveness probe
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/liveness-probe

/en/openapi/v3-current/streaming-hub.yaml get /healthz
Returns `200` unconditionally once the process is serving, independent of dependency health. Wire it to a Kubernetes liveness probe. Unauthenticated.



# Ping a webhook subscription
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/ping-subscription

/en/openapi/v3-current/streaming-hub.yaml post /v1/subscriptions/{id}/ping
Runs a synchronous, signed webhook probe through the production delivery path and returns the classified result. A successful ping flips a `webhook` subscription from `pending_verification` to `active`. A classified probe failure is still a `200` (the probe ran and produced a verdict). This route is naturally idempotent and requires no `X-Idempotency` header. A queue subscription has no ping probe and returns `422 probe_unsupported_for_sink_kind`.



# Pull entitled events
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/pull-events

/en/openapi/v3-current/streaming-hub.yaml get /v1/events
Fetches a page of a pull subscription's entitled events in arrival-order `seq`. The read doubles as the acknowledgment (cursor-as-ack): after a successful fetch the highest returned `seq` is persisted as the subscription's cursor, monotonically. An explicit `after` cursor overrides the persisted cursor for the read; a forward seek advances the durable cursor past the unread gap (the skipped range is not re-delivered — caller-owns-the-gap), while a backward seek never rewinds it. The read is rate-limited per tenant. Events are at-least-once; deduplicate on `ceId`.



# Readiness probe
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/readiness-probe

/en/openapi/v3-current/streaming-hub.yaml get /readyz
Folds the full probe set for the replica's role into one readiness verdict. `Healthy` and `Degraded` return `200` (kept in rotation); `Down` returns `503`. Wire it to a Kubernetes readiness probe. Unauthenticated.



# Rotate the signing secret
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/rotate-subscription-secret

/en/openapi/v3-current/streaming-hub.yaml post /v1/subscriptions/{id}/secret/rotate
Mints a new webhook signing secret, returns it, persists it as the current secret, and demotes the previous secret with a 24-hour overlap during which both remain valid for verification. Delivery signs with the current secret. A subscription with no signing secret at rest (a `pull` sink) returns `422 no_secret_to_rotate`.



# Set or rotate a queue credential
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/set-subscription-credential

/en/openapi/v3-current/streaming-hub.yaml put /v1/subscriptions/{id}/credential
Sets or rotates the outbound credential for a queue subscription (`sqs`, `rabbitmq`, `eventbridge`) with probe-on-write: the candidate credential is held in memory, probed (connect + auth) immediately, and persisted encrypted only on probe success — a failed probe stores nothing. A successful probe sets `verification_state` to `active`: from `pending_verification` on the first write, and from `degraded` when a rotation fixes a destination that had started failing. It leaves the `enabled` flag exactly as it found it. The credential is write-only: it is supplied only here and is never returned, not even masked, on any read path. A classified probe failure is still a `200`. This route is naturally idempotent and requires no `X-Idempotency` header.



# Register an AWS delegated grant
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/set-subscription-delegated-grant

/en/openapi/v3-current/streaming-hub.yaml put /v1/subscriptions/{id}/delegated-grant
Registers the AWS delegated-grant coordinates for an AWS-sink subscription (`sqs`, `eventbridge`) — the non-secret cross-account delivery role ARN, region, and destination the hub uses at delivery time. This is the write that follows the customer applying the setup-artifacts trust policy in their AWS account. It is write-only: it runs no inline probe and does not change the verification state (a registered grant stays `pending_verification` until a later `verify`). No AWS credential crosses this body. The destination host is validated before the write. A non-AWS sink returns `422 validation_error`.



# Streaming Hub error list
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/streaming-hub-error-list

Look up the Streaming Hub error codes, the HTTP status each one carries, and what to correct in the request that triggered it.

**Error format**

Streaming Hub returns most errors as RFC 9457 problem details with the `application/problem+json` media type. Only a response on that media type carries the envelope below:

```json JSON theme={null}
{
  "type": "https://errors.lerian.studio/v1/not_found",
  "title": "Not Found",
  "status": 404,
  "detail": "subscription not found",
  "code": "not_found"
}
```

**Field definitions**

* **`type`** – A stable, versioned URI that identifies the problem type. Streaming Hub builds it as `https://errors.lerian.studio/v1/<code>`, and omits it for a problem it assigns no code to.
* **`title`** – A short human-readable summary, which is the HTTP status text (for example, `Not Found`).
* **`status`** – The HTTP status code, mirrored in the body.
* **`detail`** – An explanation of this occurrence. For a `5xx` response, Streaming Hub scrubs the detail to the static string `internal error`, so no internal cause leaks.
* **`code`** – The stable, low-cardinality, machine-readable token to branch on. A request-validation fault and a request that matches no route arrive with this field empty. So does an Access Manager refusal that reaches you at a status other than `401`, `403`, or `503`. Branch on `status` in these cases.

## Client errors

***

| `code` | Description | Status |
| - | - | - |
| `bad_request` | The request is malformed, or a required input is absent. | 400 |
| `missing_idempotency_key` | The request omits the required `X-Idempotency` header. Streaming Hub rejects the request before any write. | 400 |
| `invalid_idempotency_key` | The `X-Idempotency` header is longer than 2048 bytes. | 400 |
| `invalid_error_class` | The `error_class` filter on the dead-letter listing holds a value outside the recognized transport classes. Supply a recognized class. | 400 |
| `invalid_cursor` | The `after` cursor on the dead-letter listing is not a well-formed row identifier. Restart the listing. | 400 |
| `invalid_source_topic` | The `source_topic` filter on the dead-letter listing is neither a topic name nor `unknown`. | 400 |
| `unauthorized` | Authentication failed, or the request carries no trusted tenant context. | 401 |
| `forbidden` | The caller is authenticated but is not allowed to make this request. | 403 |
| `not_found` | The resource is absent, soft-deleted, held by another tenant, or of a different kind. The token is the same for each of these cases. | 404 |
| `idempotency_conflict` | A duplicate request is in flight, or the same `X-Idempotency` key arrived with a different request fingerprint. | 409 |
| `subscription_name_taken` | A live subscription in your scope already holds the `name` that the create sends. The `existing_id` field names that subscription. | 409 |
| `validation_error` | The request carries a caller-correctable shape fault: a bad `sink_kind`, or an invalid endpoint, schema, or `event_types` value. | 422 |
| `inline_sink_config_forbidden` | A create request carried inline `sink_config` or `credential` material. Send a queue credential through `PUT /v1/subscriptions/{id}/credential` instead. | 422 |
| `endpoint_blocked` | The resolved host is blocked, private, or a metadata address, or the URL carries embedded user information. Supply a public endpoint that holds no credential. | 422 |
| `no_secret_to_rotate` | A secret rotation targeted a subscription that holds no signing secret. | 422 |
| `probe_unsupported_for_sink_kind` | The sink kind has no registered probe for this operation. Sink kinds in this group verify through their own surfaces. | 422 |
| `rate_limited` | The tenant's allowance for this read is spent. Wait the `Retry-After` seconds, then retry. | 429 |

## Server errors

***

| `code` | Description | Status |
| - | - | - |
| `internal_error` | An infrastructure fault. Streaming Hub scrubs `detail` to `internal error` and logs the cause. | 500 |
| `service_unavailable` | Access Manager returned no verdict on the request. Streaming Hub scrubs `detail` to `internal error`. The condition is transient and does not mean a denial. Retry with backoff. | 503 |


# Re-pin a subscription's schema major
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/update-subscription-schema-pin

/en/openapi/v3-current/streaming-hub.yaml patch /v1/subscriptions/{id}
Narrowly changes a subscription's `schema_major` pin and, optionally, its per-attempt delivery timeout. Every call carries `schema_major`: an integer `>= 1` re-pins to the versioned topic; `null` clears the pin to follow-base. `timeout_ms` is optional; omit it to keep the stored timeout. Any other field, an out-of-range value, or an empty body is rejected with `422 validation_error` (out-of-scope fields are rejected, not ignored). The change is not a destination change: it does not reset the verification state and echoes no secret. Success returns `200` with no body.



# Re-verify and re-enable a subscription
Source: https://docs.lerian.studio/en/reference/platform/streaming-hub/verify-subscription

/en/openapi/v3-current/streaming-hub.yaml post /v1/subscriptions/{id}/verify
Re-runs the sink-appropriate probe (dispatched by sink kind) and, on a probe success, transitions the subscription back to `active` and clears any auto-disable in the same transaction. The row is transitioned in place — the id and signing secret are preserved. A classified probe failure is still a `200`. This route is naturally idempotent and requires no `X-Idempotency` header. The `webhook`, `sqs` and `eventbridge` sinks have registered verify probes. For an AWS sink this is the delegated-grant activation path, the alternative to an outbound credential on `PUT /v1/subscriptions/{id}/credential`, which probes every queue kind at write time. Any other sink kind returns `422 probe_unsupported_for_sink_kind`: a `rabbitmq` sink is probed on that credential PUT, which moves `verification_state` alone, and a `pull` subscription has no destination to probe.



# System Facts API overview
Source: https://docs.lerian.studio/en/reference/platform/system-facts/api-overview

What System Facts records, the four steps to integrate a producer, and the conventions every operation shares: tenant, idempotency, paging, sensitivity and errors.

System Facts is the shared record of what happened in your business flows. Each service that takes part in a flow, called a producer, sends an immutable fact when a business moment happens. An order is placed. A payment settles.

System Facts checks every fact against the contract its producer registered, stores it once, and links the facts that share a reference into one flow. Then you can ask what happened to order `ORD-2026-000123` and get every fact of that flow, from every producer.

A stored fact never changes. System Facts records and correlates. It does not edit history.

## Concepts

***

| Term | Meaning |
| :- | :- |
| Producer | A service that sends facts, such as `checkout-api` or `payments-api`. |
| Namespace | The dotted name a producer sends its facts under, such as `acme.checkout`. The first service that registers a contract for a producer and namespace becomes their owner. |
| Fact type | The name of one kind of business moment, such as `checkout.order_placed`. |
| Contract | One semantic version of a fact type, with the JSON Schema of its payload and the references its facts carry. |
| Reference type | A named kind of business identifier, such as `acme.order_id`. You register it once, with its scope, correlation, sensitivity and searchable settings. |
| Reference | One identifier a fact carries: a reference type, a value and a scope. For example, `acme.order_id` `ORD-2026-000123` with scope `storeId: store-sp-01`. |
| Subject | The business entity a fact is about, given as a type and an id, such as `checkout.order` `ORD-2026-000123`. |
| Fact | One immutable record that a business moment happened. It is sent as an envelope with its subject, its references and its payload (`data`). |
| Flow | The group of facts linked by their references. A `flowAggregationId` identifies it. |

When one fact links two flows, they merge into one. The absorbed flow id still resolves to the surviving flow.

A reference type registered with `searchable: true` can list every fact that carries it.

## Integrate in four steps

***

**1. Register the reference types**

Register each kind of identifier your facts carry with `PUT /v1/reference-types/{type}`, such as `acme.order_id` and `acme.payment_id`. Do this from your deploy pipeline, before any contract uses the type.

```bash theme={null}
curl -X PUT "$SYSTEM_FACTS_URL/v1/reference-types/acme.order_id" \
  -H "Authorization: Bearer $SYSTEM_FACTS_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": ["storeId"],
    "sensitivity": "none",
    "correlation": "exact",
    "searchable": true,
    "description": "Order number assigned by the checkout service, unique within a store"
  }'
```

**2. Register a contract version**

Register a version of each fact type with `PUT /v1/contracts/{producer}/{namespace}/{type}/{schemaVersion}`. Do this from your deploy pipeline, before the producer rolls out. System Facts accepts facts only after the registration succeeds.

**3. Send facts**

Send one envelope per business moment with `POST /v1/facts`. Use the producer's service credential for the tenant.

```bash theme={null}
curl -X POST "$SYSTEM_FACTS_URL/v1/facts" \
  -H "Authorization: Bearer $SYSTEM_FACTS_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "envelopeVersion": 1,
    "factId": "01a15493-ba10-7b21-9d44-3c1f8e2a9b01",
    "producer": "checkout-api",
    "namespace": "acme.checkout",
    "type": "checkout.order_placed",
    "schemaVersion": "1.0.0",
    "occurredAt": "2026-10-19T14:32:10Z",
    "subject": { "type": "checkout.order", "id": "ORD-2026-000123" },
    "references": [
      {
        "type": "acme.order_id",
        "value": "ORD-2026-000123",
        "scope": { "storeId": "store-sp-01" }
      }
    ],
    "data": { "amount": "129.90", "currency": "BRL" }
  }'
```

A first send answers `201`.

```json theme={null}
{
  "factId": "01a15493-ba10-7b21-9d44-3c1f8e2a9b01",
  "producer": "checkout-api",
  "flowAggregationId": "01a15493-bdf8-7c55-b0e2-6f4a1d9e7c33",
  "duplicate": false,
  "ingestedAt": "2026-10-19T14:32:11Z"
}
```

**4. Read the flows**

Read a flow by its id with `GET /v1/flows/{flowAggregationId}`. Find the one flow of a reference with `GET /v1/flows/by-reference`. List every fact that carries a searchable reference with `GET /v1/flows`.

```bash theme={null}
curl -G "$SYSTEM_FACTS_URL/v1/flows/by-reference" \
  -H "Authorization: Bearer $SYSTEM_FACTS_BEARER_TOKEN" \
  --data-urlencode "referenceType=acme.order_id" \
  --data-urlencode "referenceValue=ORD-2026-000123" \
  --data-urlencode "storeId=store-sp-01"
```

Every write is idempotent, so a producer can resend after a timeout.

## Authentication and permissions

***

Every request except the public health probes sends `Authorization: Bearer <token>`. Facts and flows belong to the tenant of the token. The reference-type and contract catalogs are shared by every tenant of the deployment.

| Operation | Permission |
| :- | :- |
| `GET /v1/reference-types`, `GET /v1/reference-types/{type}`, `GET /v1/contracts`, `GET /v1/contracts/{producer}/{namespace}/{type}`, `GET /v1/contracts/{producer}/{namespace}/{type}/{schemaVersion}` | `contracts:read` |
| `PUT /v1/reference-types/{type}`, `PUT /v1/contracts/{producer}/{namespace}/{type}/{schemaVersion}` | `contracts:read`, `contracts:write` and `catalog:reserved`. Every catalog name sits under a reserved prefix. |
| `POST /v1/contracts/{producer}/{namespace}/{type}/{schemaVersion}/deprecate` | `contracts:read` and `contracts:write`, plus `catalog:deprecate` for a version whose namespace you do not own |
| `POST /v1/facts` | `facts:read` and `facts:write` |
| `GET /v1/flows/{flowAggregationId}`, `GET /v1/flows/by-reference`, `GET /v1/flows` | `facts:read`. With `facts:reveal`, encrypted values come back in clear form. |

A missing permission answers `403` `SF-0014`. A missing or invalid token answers `401` `SF-0013`.

## Conventions

***

* **Tenant.** The service always takes the tenant from the token. It never takes a tenant from a path, a query parameter or a body.
* **Idempotent writes.** A first registration or send answers `201`. The same request again answers `200` and changes nothing. A fact send adds `duplicate: true`.
* **Immutability.** Different content under the same identity answers `409`. A reference type can gain a display `mask` once.
* **Paging.** A paged list answers one page and a `nextCursor`. Send it back as the cursor parameter of the page you want. Treat it as opaque. Stop when it is omitted.
* **Timestamps.** RFC 3339 in UTC, such as `2026-10-19T14:32:10Z`.
* **Size.** A fact envelope is at most 256 KiB by default. A larger one answers `413` `SF-0012`.
* **Names.** The first dotted segment of every namespace and reference-type name must be one of the reserved prefixes of the deployment. The default is `lerian`. These pages use `acme`.

## Sensitivity and protected values

***

The `sensitivity` of a reference type decides how reads show its values. A contract can mark payload fields the same way with `x-sensitivity`.

| Sensitivity | What a read returns |
| :- | :- |
| `none` | The value as sent. |
| `masked` | `****` plus the last 4 characters of a value of 12 or more characters, and `****` alone otherwise. Never the clear value. |
| `hashed` | The keyed digest `hmac-sha256:v1:<hex>`. Never the clear value. |
| `encrypted` | Stored sealed with AES-256-GCM. Returned masked, or in clear form to a caller that holds `facts:reveal`. |

With `mask: document`, a masked value shows `***.456.789-**` for 11 digits and `**.345.678/0001-**` for 14 digits. System Facts refuses any other digit count at send time.

Every class correlates exactly as `none` does, because matching starts from the clear value.

A protected value comes back with `protected: true`, and protected payload fields are listed in `protectedFields`. To find a flow by a protected reference, always send the clear value. System Facts digests it and matches the stored digest.

## Errors

***

Every error is `application/problem+json` (RFC 9457) with a stable `code`.

```json theme={null}
{
  "code": "SF-0009",
  "detail": "Verify the identifier: an identifier absorbed by a merge still resolves, an unknown one does not.",
  "instance": "0199c1f07a3e7b219d443c1f8e2a9b01",
  "status": 404,
  "title": "Not Found",
  "type": "https://errors.lerian.studio/v1/SF-0009"
}
```

> **[Error list](/en/reference/platform/system-facts/system-facts-error-list)**
>
> Look up every code, when the service answers it, and whether to retry.

> **[Register a contract version](/en/reference/platform/system-facts/register-a-contract-version)**
>
> Start with the operation every producer runs first.


# Deprecate a contract version
Source: https://docs.lerian.studio/en/reference/platform/system-facts/deprecate-a-contract-version

/en/openapi/v3-current/system-facts.yaml post /v1/contracts/{producer}/{namespace}/{type}/{schemaVersion}/deprecate
Moves one contract version from `ACTIVE` to `DEPRECATED`, so producers stop sending facts under it. No request body.

**Rules**
- Allowed to the namespace owner (the producer service the namespace is bound to) or to a caller holding `catalog:deprecate`. Anyone else is refused before the version is read, so a missing version is not revealed to them. In multi-tenant mode the owner is the producer's service credential for the tenant.
- Idempotent: the transition and a version already `DEPRECATED` both answer `200`; only the transition is audited.
- The deprecation is irreversible: to send facts again, register a new version.
- It applies to every tenant, since one contract catalog serves the whole environment, and takes effect on ingestion within 30 seconds; after that a fact under this version answers `422` `SF-0019`.
- Facts already stored under it stay readable.

**Responses**
- `200` the contract version, now `DEPRECATED`.
- `403` `SF-0005` not the owner and no `catalog:deprecate`; `SF-0014` missing permission; `SF-0027`, `SF-0028` multi-tenant credential refusals.
- `404` `SF-0017` no such version.
- `503` `SF-0094` retry later.



# Find the flow of a reference
Source: https://docs.lerian.studio/en/reference/platform/system-facts/find-the-flow-of-a-reference

/en/openapi/v3-current/system-facts.yaml get /v1/flows/by-reference
Finds the one flow a reference belongs to, such as an order number, and pages through its facts.

**Rules**
- Send the reference as `referenceType` and `referenceValue`. Every other query parameter except `factsLimit` and `factsCursor` is a scope key, such as `storeId=store-sp-01` for `acme.order_id`.
- Scope matches by containment: no scope matches every scope of that type and value, a partial scope narrows the search, the full declared scope matches at most one reference. Sending a fact needs exactly the declared scope keys.
- `referenceValue` is always the clear value, also for a protected type.
- The answer is always the current flow, so it never carries `merge`.
- Facts are paged: pass `nextCursor` as `factsCursor`; it is omitted on the last page. `factsLimit` is 1 to 500 (default 100).
- Protected values come back protected; `facts:reveal` returns encrypted ones in clear form and never refuses the request. See *Sensitivity and protected values*. Responses carry `Cache-Control: no-store`.

**Responses**
- `200` the current flow and one page of its facts.
- `404` `SF-0010` no reference matches.
- `409` `SF-0011` several flows match: pick one from `candidates[]` and read it with `getFlow`.
- `422` `SF-0006` a malformed reference or cursor; `SF-0092` a schema mismatch.
- `503` `SF-0094` retry later.



# List contract versions
Source: https://docs.lerian.studio/en/reference/platform/system-facts/list-contract-versions

/en/openapi/v3-current/system-facts.yaml get /v1/contracts
Lists registered contract versions across the whole catalog, one page at a time. Use it to discover fact types, or every contract that declares a reference type.

**Rules**
- Every filter is optional and they combine: `producer`, `namespace`, `type`, `status` (`ACTIVE` or `DEPRECATED`; both by default) and `referenceType`, which answers who uses this reference type by matching every version that declares it.
- Items are ordered by producer, namespace, fact type and schema version compared as text, so `1.10.0` sorts before `1.9.0`; use `listContractVersions` for semantic version order within one fact type.
- Items carry no payload schema: read it with `getContract`.
- Paged by an opaque cursor: pass a page's `nextCursor` to read the next page; `nextCursor` is omitted on the last page. `limit` is 1 to 100 (default 50).

**Responses**
- `200` one page; an empty page when nothing matches.
- `422` `SF-0092` a bad filter value, `limit` or cursor.
- `503` `SF-0094` retry later.



# List facts by a searchable reference
Source: https://docs.lerian.studio/en/reference/platform/system-facts/list-facts-by-a-searchable-reference

/en/openapi/v3-current/system-facts.yaml get /v1/flows
Lists every fact that carries a searchable reference, each with the flow it belongs to now.

**Rules**
- Only types registered with `searchable: true` (see `getReferenceType`).
- `referenceValue` is always the clear value, also for a protected type. Every other query parameter except `occurredFrom`, `occurredTo`, `limit`, `cursor` and `include` is a scope key, matched by containment as in `findFlowByReference`.
- `occurredFrom` (inclusive) and `occurredTo` (exclusive) are optional RFC 3339 bounds on the fact's `occurredAt`; `occurredFrom` must be before `occurredTo`.
- One item per matched fact, ordered by `occurredAt`, ties in a stable order; `flowAggregationId` is its current flow, so a later merge shows at read time. `include=flow` adds each flow's `createdAt` and `updatedAt`.
- Paged: pass `nextCursor` as `cursor`; it is omitted on the last page. `limit` is 1 to 100 (default 50).
- Protected values come back protected; `facts:reveal` returns encrypted ones in clear form and never refuses the request. See *Sensitivity and protected values*. Responses carry `Cache-Control: no-store`.

**Responses**
- `200` one page; an empty page when nothing matches, never `404` or `409`.
- `422` `SF-0024` not searchable; `SF-0006` an empty period, a malformed reference or cursor; `SF-0092` a schema mismatch.
- `503` `SF-0094` retry later.



# List reference types
Source: https://docs.lerian.studio/en/reference/platform/system-facts/list-reference-types

/en/openapi/v3-current/system-facts.yaml get /v1/reference-types
Lists the registered reference types one page at a time, ordered by name. Use it to discover the types a contract can declare.

**Rules**
- Both filters are optional and combine: `prefix` matches whole dotted segments (`acme.orders` matches `acme.orders` and `acme.orders.order_id`, never `acme.ordersx`); `correlation` is `exact` or `none`.
- An item does not list the contracts that use the type: to find them, call `listContracts` with `referenceType` (`GET /v1/contracts?referenceType=acme.order_id`).
- Paged by an opaque cursor: pass a page's `nextCursor` to read the next page; `nextCursor` is omitted on the last page. `limit` is 1 to 100 (default 50).

**Responses**
- `200` one page; an empty page when nothing matches.
- `422` `SF-0092` a bad filter value, `limit` or cursor.
- `503` `SF-0094` retry later.



# List the versions of a fact type
Source: https://docs.lerian.studio/en/reference/platform/system-facts/list-the-versions-of-a-fact-type

/en/openapi/v3-current/system-facts.yaml get /v1/contracts/{producer}/{namespace}/{type}
Lists every registered version of one fact type, with its status and content hash, in ascending semantic version order. Producer CI calls it to check a new version against the published ones.

**Rules**
- The set is bounded (the versions of one fact type), so there is no pagination.
- A fact type with no registered version answers `404`, never an empty list.

**Responses**
- `200` every version, oldest first.
- `404` `SF-0017` no version of this fact type is registered.
- `503` `SF-0094` retry later.



# Read a contract version
Source: https://docs.lerian.studio/en/reference/platform/system-facts/read-a-contract-version

/en/openapi/v3-current/system-facts.yaml get /v1/contracts/{producer}/{namespace}/{type}/{schemaVersion}
Reads one registered contract version: its schema, references, content hash and status. Your deploy pipeline calls it to verify the identity, the content hash and the `ACTIVE` status before the producer rolls out.

**Rules**
- A version is addressed by all four segments: producer, namespace, fact type and schema version.
- Each reference shows the scope and sensitivity of its reference type.

**Responses**
- `200` the contract version, `ACTIVE` or `DEPRECATED`.
- `404` `SF-0017` no version is registered under this identity.
- `503` `SF-0094` retry later.



# Read a flow
Source: https://docs.lerian.studio/en/reference/platform/system-facts/read-a-flow

/en/openapi/v3-current/system-facts.yaml get /v1/flows/{flowAggregationId}
Reads one flow, by an id you stored or received, and pages through its facts.

**Rules**
- The id may be the flow's own or one a merge absorbed; `flowAggregationId` in the response is always the current flow: replace any stored id with it.
- For an absorbed id, `merge` carries `absorbedId` (the requested id), `mergedAt` and `mergedBy` (the bridging fact's `producer` and `factId`), naming the first one that absorbed the requested id; a current id carries no `merge`.
- When a fact bridges flows, the flow with more facts survives, ties go to the oldest, and every other id keeps resolving here.
- Facts are paged: pass `nextCursor` as `factsCursor`; it is omitted on the last page. `factsLimit` is 1 to 500 (default 100).
- Protected values come back protected; `facts:reveal` returns encrypted ones in clear form and never refuses the request. See *Sensitivity and protected values*. Responses carry `Cache-Control: no-store`.

**Responses**
- `200` the current flow and one page of its facts.
- `404` `SF-0009` no flow, current or absorbed, has this id.
- `422` `SF-0092` not a UUID; `SF-0006` a malformed cursor.
- `503` `SF-0094` retry later.



# Read a reference type
Source: https://docs.lerian.studio/en/reference/platform/system-facts/read-a-reference-type

/en/openapi/v3-current/system-facts.yaml get /v1/reference-types/{type}
Reads one registered reference type: its scope keys, correlation, sensitivity, mask and whether it is searchable. Producers call it to check a type before declaring it in a contract.

**Rules**
- The name is the whole identity.
- An unregistered name answers `404`, including a name that could never be registered: the read never tells whether a name is well-formed.

**Responses**
- `200` the reference type.
- `404` `SF-0091` no reference type under this name.
- `503` `SF-0094` retry later.



# Register a contract version
Source: https://docs.lerian.studio/en/reference/platform/system-facts/register-a-contract-version

/en/openapi/v3-current/system-facts.yaml put /v1/contracts/{producer}/{namespace}/{type}/{schemaVersion}
Registers one version of a fact contract: the JSON Schema its facts must satisfy and the references they carry. Call it from your deploy pipeline, before the producer rolls out: the registration must succeed before facts are accepted.

**Rules**
- Idempotent: the same identity and content hash is a replay.
- Published versions are immutable; a new minor or patch version must stay compatible.
- The namespace starts with a reserved prefix, so every registration needs `catalog:reserved`.
- The first registration binds the namespace to the calling producer service, recorded for audit. In multi-tenant mode the owner is the producer's service credential for the tenant.
- Every declared reference type must be registered first. A reference declares only `type`, `cardinality`, `required` and `correlation`; scope and sensitivity come from the reference type and appear in the response. `exact` is refused on a `correlation: none` type.
- `x-sensitivity` (`masked`, `hashed` or `encrypted`) only on a `type: string` property reached through `properties`; `x-mask: document` only beside `masked` or `encrypted`.

**Responses**
- `201` registered and `ACTIVE`; `200` identical replay.
- `403` `SF-0005` the namespace is bound to another producer service; `SF-0014`, `SF-0027`, `SF-0028`.
- `409` `SF-0002` same version, different content (`errors[]` lists differences and the bump); `SF-0003` incompatible minor or patch.
- `422` `SF-0004`, `SF-0018`, `SF-0021`, `SF-0023`, `SF-0025`, `SF-0092`.
- `503` `SF-0094` retry later.



# Register a reference type
Source: https://docs.lerian.studio/en/reference/platform/system-facts/register-a-reference-type

/en/openapi/v3-current/system-facts.yaml put /v1/reference-types/{type}
Registers a reference type: a kind of business identifier facts carry, such as an order number, with its scope keys, correlation and sensitivity. Every contract declaring the type inherits its scope and sensitivity, and may declare `exact` correlation only on an `exact` type, so register it from your deploy pipeline before any contract uses it.

**Rules**
- Idempotent: equal content answers `200` as a replay, whoever sends it.
- A registered type is immutable, with one exception: `mask: document` can be added once to a type that has no mask, every other member equal. Omitting `mask` on a type that has one is a replay showing the stored mask; a mask can never be removed.
- `mask` accepts only `document`, and never with sensitivity `none` or `hashed`.
- The first dotted segment of the name must be one of the deployment's reserved prefixes, and the token needs `catalog:reserved`.
- `ownerIdentity` is the authenticated caller, recorded for audit.

**Responses**
- `201` registered; `200` replay, or the mask added.
- `403` `SF-0014` missing `contracts:read`, `contracts:write` or `catalog:reserved`.
- `409` `SF-0022` different content: `errors[]` lists every differing member, and nothing changes.
- `422` `SF-0023` name outside every reserved prefix; `SF-0092` invalid member.
- `503` `SF-0094` retry later.



# Send a fact
Source: https://docs.lerian.studio/en/reference/platform/system-facts/send-a-fact

/en/openapi/v3-current/system-facts.yaml post /v1/facts
Sends one fact, validated against its contract version, stored and attached to a flow atomically; answered once durably stored.

**Rules**
- Validation covers the envelope, then `data` and references. A reference carries exactly the scope keys its type declares, non-empty, never trimmed.
- Idempotent by `producer` and `factId`: resending the same content answers `200`, `duplicate: true`. Facts are immutable: a change needs a new `factId`.
- At most 256 KiB per envelope by default and five `exact` references.
- Strict envelope: a duplicate, or a member the envelope, its subject or a reference does not declare (exact, case-sensitive), is refused; `data` follows the contract's schema. The tenant comes from the token.
- Only the producer service the namespace is bound to may send facts under it; refusals are recorded for audit. In multi-tenant mode that is the producer's service credential for the tenant.
- If an operator disabled fact emission for this tenant, keep the fact pending and retry.
- `x-sensitivity` fields are stored protected, never echoed in errors. A reference whose type has `mask: document` must have 11 or 14 digits.

**Responses**
- `201` stored; `200` duplicate.
- `403` `SF-0005`, `SF-0014`, `SF-0020`, `SF-0027`, `SF-0028`.
- `409` `SF-0016`; `413` `SF-0012`.
- `422` `SF-0001`, `SF-0006`, `SF-0007`, `SF-0008`, `SF-0019`, `SF-0026`.
- `503` `SF-0094` correlation contention, with `Retry-After: 1`: resend the same envelope.



# System Facts API error list
Source: https://docs.lerian.studio/en/reference/platform/system-facts/system-facts-error-list

Every error code System Facts answers: when the service writes it, what to do next, and whether a retry can succeed.

System Facts answers every error as `application/problem+json`, with a stable `code`. Codes are `SF-` and four digits. Quote the code when you report a problem. The [API overview](/en/reference/platform/system-facts/api-overview) describes the envelope and the conventions every operation shares.

## Codes the service answers

***

The `detail` and `errors[]` members name the specific thing that failed. Read them before you act on the row below.

| Code | HTTP status | When the service answers it | What to do | Retry |
| :- | :- | :- | :- | :- |
| SF-0001 | 422 | No contract version is registered for the producer, namespace, fact type and schema version the request names (a deprecated version answers `SF-0019`). | Register the contract version from your deploy pipeline, before the producer rolls out, then send the request again. | After a fix |
| SF-0002 | 409 | A contract version with the same identity is already registered with different content. | Published versions are immutable: bump the schema version, using the differences listed in `errors[]` to choose the bump. | No |
| SF-0003 | 409 | The new version is not compatible with one or more active versions of the same major already registered for the fact type. | Fix the schema so it stays compatible, or register the change as a new major version. | No |
| SF-0004 | 422 | The contract schema is not a valid, self-contained JSON Schema, or a declared reference asks for a correlation its reference type does not allow. | Give the schema an absolute `$id`, keep every `$ref` inside the document (`#/$defs`), and fix the members listed in `errors[]`. | No |
| SF-0005 | 403 | The namespace is bound to another producer service, or the fact is sent for a producer and namespace your service did not register. | Register and send only under a namespace your service owns, with the service credential of the owning producer. | No |
| SF-0006 | 422 | The fact envelope or the query is malformed: a member is missing, has the wrong format or is not part of the envelope, or a listing period is empty. | Fix the members listed in `errors[]` and send the request again. | No |
| SF-0007 | 422 | The fact payload (`data`) does not validate against the JSON Schema of the registered contract. | Fix the payload fields listed in `errors[]` so they match the contract. | No |
| SF-0008 | 422 | The fact carries a reference the contract does not declare, a scope key its reference type does not declare, or more than five distinct exact-correlation references. | Send only the references and scope keys that the contract and its reference types declare. | No |
| SF-0009 | 404 | No flow exists with the given flow identifier. | Verify the identifier: an identifier absorbed by a merge still resolves, an unknown one does not. | No |
| SF-0010 | 404 | No flow carries a reference with the given type, value and scope. | Verify the reference type, the value and every scope key of the query. | No |
| SF-0011 | 409 | More than one flow carries the reference, so the lookup cannot choose one. | Pick a flow from `candidates[]` and read it by its `flowAggregationId`. | No |
| SF-0012 | 413 | The request body is larger than the configured size limit (256 KiB by default for a fact envelope). | Reduce the request body; for a fact, send a statement about an occurrence, not a document. | No |
| SF-0013 | 401 | The request carries no valid bearer token. | Send a valid bearer token issued for the tenant; a producer uses its service credential. | After a fix |
| SF-0014 | 403 | The token is valid but lacks a permission the operation requires, such as `catalog:reserved`, which every catalog registration needs because every catalog name sits under a reserved prefix. | Ask the tenant administrator to grant the permission the operation lists, then send the request again. | After a fix |
| SF-0015 | 500 | The service failed for a reason the request did not cause. | Retry later with the same request; writes are idempotent, so a retry is safe. | Yes, later |
| SF-0016 | 409 | A fact with the same `producer` and `factId` is already stored with different content. | Facts are immutable: send a changed occurrence as a new fact with a new `factId`, and check the producer that reused the identifier. | No |
| SF-0017 | 404 | The catalog holds no contract version with the given producer, namespace, fact type and schema version. | Verify the four path segments, and register the version from your deploy pipeline if it is missing. | No |
| SF-0018 | 422 | The content hash sent with the contract does not match the content it accompanies. | Recompute the content hash over the same content you are sending. | No |
| SF-0019 | 422 | The contract version is deprecated and no longer accepts facts. | Send the fact against an active version of the same fact type. | No |
| SF-0020 | 403 | An operator has disabled fact emission for this tenant. | Keep the fact pending and retry later; facts are accepted again once an operator enables emission. | Yes, later |
| SF-0021 | 422 | The contract declares a reference type the reference-type catalog does not hold; `errors[]` lists every missing type. | Have the owner register each reference type before you register the contract that uses it. | After a fix |
| SF-0022 | 409 | A reference type with the same name is already registered with a different definition. | Reference types are immutable: use a new type name for a new meaning. | No |
| SF-0023 | 422 | The namespace or reference-type name does not start with one of the reserved prefixes of the deployment. | Use a name whose first dotted segment is a reserved prefix of the deployment. | No |
| SF-0024 | 422 | Flows are listed by a reference type that is not registered, or is registered with `searchable: false`. | List flows only by a reference type registered with `searchable: true`, or read the one flow of an exact reference with `findFlowByReference`. | No |
| SF-0025 | 422 | An `x-sensitivity` or `x-mask` annotation in the contract schema is misplaced or carries an unknown value. | Declare `x-sensitivity` (masked, hashed or encrypted) only on a string property reached through `properties`, and `x-mask` only next to masked or encrypted. | No |
| SF-0026 | 422 | The contract version the fact names carries malformed sensitivity annotations, so its payload cannot be protected and nothing is stored. | Register a corrected contract version and send the fact against it. | After a fix |
| SF-0027 | 403 | In multi-tenant mode, the credential does not name a producer service, so namespace ownership cannot be decided. | Use the service credential of the producer for the tenant, and rotate a credential issued before it carried the producer name. | After a fix |
| SF-0028 | 403 | In multi-tenant mode, the service credential of the producer was created without naming its producer service. | Ask the tenant administrator to recreate the credential with its producer service set; rotating the same credential does not fix this. | After a fix |
| SF-0090 | 400 | The request is malformed, such as a body that is not valid JSON. | Fix the request syntax and send it again. | No |
| SF-0091 | 404 | The requested resource does not exist, such as an unknown reference type or path. | Verify the path and the resource name; a reference type exists only after its owner registers it. | No |
| SF-0092 | 422 | The request does not match the request schema of the operation, such as an unexpected member or an invalid cursor. | Fix the members listed in `errors[]` so the request matches the schema of the operation. | No |
| SF-0093 | 409 | The request conflicts with the current state of a resource. | Read the resource again and send a request consistent with its current state. | No |
| SF-0094 | 503 | The service cannot answer right now: it is starting, the authorization service is temporarily unavailable, or the correlation keys of the fact stayed busy. | Retry later with the same request, honoring `Retry-After` when the response carries it. | Yes, later |
| SF-0095 | 429 | The caller sent more requests than the rate limit allows. | Wait for the `Retry-After` delay before the next request. | Yes, later |
| SF-0096 | 400 | The request was refused for a client-side reason no more specific code describes; the response keeps the HTTP status of that reason, such as 405 or 415. | Read the `detail` member, fix the request and send it again. | No |


# Get one key's write contract
Source: https://docs.lerian.studio/en/reference/platform/systemplane/catalog-detail

/en/openapi/v3-current/systemplane.yaml get /system/-/catalog/{namespace}/{key}
Returns the expected write contract for one registered Systemplane key: its JSON schema, semantic validation rules, valid examples, default value, and the matching `PUT` path. The schema is contract metadata; the currently configured value is read from `GET /system/{namespace}/{key}`. When authentication is enabled, this discovery endpoint requires read permission for at least one Systemplane namespace.



# List the key catalog
Source: https://docs.lerian.studio/en/reference/platform/systemplane/catalog-list

/en/openapi/v3-current/systemplane.yaml get /system/-/catalog
Lists every registered Systemplane key with its kind, tenant scope, runtime class, redaction policy, description, and a detail URL. This discovery surface is opt-in per application and is served before the namespace routes, so `/system/-/catalog` is a reserved metadata path, not a real namespace. When authentication is enabled, it requires read permission for at least one Systemplane namespace.



# Delete one entry
Source: https://docs.lerian.studio/en/reference/platform/systemplane/delete-entry

/en/openapi/v3-current/systemplane.yaml delete /system/{namespace}/{key}
Deletes a runtime-managed entry by namespace and key. When authentication is enabled, this endpoint requires the namespace's write permission (for example, `system_operational_registry:write`). Success returns `204 No Content`.



# Get one entry
Source: https://docs.lerian.studio/en/reference/platform/systemplane/get-entry

/en/openapi/v3-current/systemplane.yaml get /system/{namespace}/{key}
Reads a single runtime-managed entry by namespace and key. The value is passed through the namespace's redaction policy. When authentication is enabled, this endpoint requires the namespace's read permission (for example, `system_tenant_policy:read`).



# List entries in a namespace
Source: https://docs.lerian.studio/en/reference/platform/systemplane/list-entries

/en/openapi/v3-current/systemplane.yaml get /system/{namespace}
Lists every registered runtime-managed entry under a namespace, with each entry's current value passed through the namespace's redaction policy. When authentication is enabled, this endpoint requires the namespace's read permission (for example, `system_runtime_config:read`).



# Systemplane admin API
Source: https://docs.lerian.studio/en/reference/platform/systemplane/overview

Inspect and change a Lerian application's operational configuration at runtime, without a restart, through the shared Systemplane admin API.

Systemplane is the control plane for runtime configuration that Lerian applications share. They expose it so you can inspect and change operational settings on a running service, without a restart. In regulated financial environments, taking a service down to apply a configuration change is both a compliance risk and an operational disruption. With Systemplane, you adjust the values a service safely supports while it keeps serving traffic.

This is the same admin surface across every application that mounts it. Each product documents its own configurable keys, but the routes, request and response shapes, and authorization model described here are common to all of them.

## What Systemplane is

***

Systemplane is not a standalone service. Each application mounts the same route set onto its own HTTP host and port under an application-specific path prefix. The canonical prefix documented here is `/system`, but it varies per application (see the applicability table below).

Applications register the routes programmatically, and no code generator emits them. This reference documents the surface by hand so you can operate it consistently across products.

## Namespaces

***

Configuration lives in **namespaces**, each holding flat, string-keyed entries. Rails and plugins use three canonical namespaces:

| Namespace | What it holds |
| - | - |
| `runtime_config` | Operational knobs such as rate limits, worker intervals, and connection-pool sizes. |
| `tenant_policy` | Tenant-scoped policy objects (for example, per-tenant routing tables). |
| `operational_registry` | Operational lookup data the service reads at runtime. |

Each entry's value has no type at the transport layer. Every registered key accepts its own JSON scalar, object, or array, and its own server-side validator checks the value. Not every setting is runtime-changeable. The application reads bootstrap-only settings once at startup. These settings do not appear in Systemplane and still require a restart to change.

## Endpoints

***

All paths are relative to the application's prefix (default `/system`).

| Method | Path | What it does |
| - | - | - |
| `GET` | `/system/{namespace}` | [List entries](/en/reference/platform/systemplane/list-entries) in a namespace |
| `GET` | `/system/{namespace}/{key}` | [Get one entry](/en/reference/platform/systemplane/get-entry) |
| `PUT` | `/system/{namespace}/{key}` | [Write one entry](/en/reference/platform/systemplane/put-entry) with the body `{"value": <json>}`. Returns `204`. |
| `DELETE` | `/system/{namespace}/{key}` | [Delete one entry](/en/reference/platform/systemplane/delete-entry). Returns `204`. |
| `GET` | `/system/-/catalog` | [List the key catalog](/en/reference/platform/systemplane/catalog-list) (opt-in) |
| `GET` | `/system/-/catalog/{namespace}/{key}` | [Get one key's write contract](/en/reference/platform/systemplane/catalog-detail) (opt-in) |

> [!NOTE]
>
> `/system/-/catalog` names a reserved metadata path. The application serves it before the namespace routes. The `-` segment is not a real namespace, and you cannot use it as one. Errors use a flat `{"code": <int>, "title": "<string>", "message": "<string>"}` envelope.

## Authentication and permissions

***

Authorization is **deny-all by default**. An application serves the surface only after you configure an authorizer. Without an authorizer, the application denies every request. When you enable authentication, the application enforces per-namespace role-based access control on top of a valid, platform-scoped (non-tenant) identity.

Reads require the namespace's read permission and writes require the matching write permission:

| Namespace | Read permission | Write permission |
| - | - | - |
| `runtime_config` | `system_runtime_config:read` | `system_runtime_config:write` |
| `tenant_policy` | `system_tenant_policy:read` | `system_tenant_policy:write` |
| `operational_registry` | `system_operational_registry:read` | `system_operational_registry:write` |

The read action covers `GET`. The write action covers `PUT` and `DELETE`. The catalog discovery endpoints require read permission for at least one namespace.

> [!NOTE]
>
> The exact permission strings can vary per application. Check the product's own documentation for its authorization model.

Tokens are bearer JWTs from the platform's [Access Manager](/en/platform/access-manager). Machine callers obtain one through the client-credentials flow.

## Discovering keys with the catalog

***

When an application opts into the catalog surface, `GET /system/-/catalog` lists every key it registers. The detail route `GET /system/-/catalog/{namespace}/{key}` returns one key's full write contract. The contract covers its kind, tenant scope, runtime class, redaction policy, JSON schema, validation rules, valid examples, default value, and the matching `PUT` path.

Use the catalog to learn what a service exposes before you change anything. The catalog describes the write contract. To read the current configured value, call `GET /system/{namespace}/{key}`.

## Which products expose Systemplane

***

Systemplane is opt-in per product. The table below lists products that mount it. For each product it gives the path prefix, the default HTTP port, and whether the product also serves the catalog discovery surface. The prefix and port are defaults. A deployment can override them.

| Product | Path prefix | Default port | Catalog? |
| - | - | - | - |
| [Lender](/en/products/lender/what-is-lender) | `/api/v1/systemplane` | `:8080` | No |
| [Matcher](/en/products/matcher/what-is-matcher) | `/system` | `:4018` | Yes |
| [Pix Direto (via JD)](/en/interfaces/pix/main-domains-overview) | `/system` | `:8080` | No |
| [Pix Lerian](/en/interfaces/pix-lerian/pix-lerian-environment-variables) | Provided during onboarding | Per component | No |
| [JD Courier](/en/interfaces/jd-courier/what-is-jd-courier) | `/system` | `:8080` | No |
| CCS integration | `/system` | `:4030` | No |
| [Lerian STA](/en/rails/sta/what-is-lerian-sta) | `/system` | `:4028` | No |
| [Lerian SISBAJUD Mensageria](/en/rails/sisbajud/sisbajud-operations) | `/system` | `:4031` | No |
| [Lerian SISBAJUD executor](/en/rails/sisbajud/sisbajud-executor-operations) | `/system` | Set `SERVER_ADDRESS` to `:4029` | No |
| [Lerian SLC](/en/rails/slc/what-is-lerian-slc) | `/system` | `:4111` | No |
| [Lerian Consignado — Dataprev](/en/rails/consignado/what-is-lerian-consignado) | `/system` | `:8080` | No |
| [Lerian SPB](/en/rails/spb/what-is-lerian-spb) / [Lerian SPI](/en/rails/spi/what-is-lerian-spi) | `/v1/system` | Per service | No |
| [Lerian SCR](/en/rails/scr/what-is-lerian-scr) | `/v1/system` | `:3003` | No |
| [Lerian SRC](/en/rails/src/what-is-lerian-src) | `/v1/system` | `:3006` | No |


# Write one entry
Source: https://docs.lerian.studio/en/reference/platform/systemplane/put-entry

/en/openapi/v3-current/systemplane.yaml put /system/{namespace}/{key}
Writes a runtime-managed entry by namespace and key. The request body must be `{"value": <json>}`, where `<json>` matches the shape the target key's validator accepts. A missing or invalid `value`, or a value that fails the key's validator, is rejected with `400`. When authentication is enabled, this endpoint requires the namespace's write permission (for example, `system_tenant_policy:write`). Success returns `204 No Content`.



# Systemplane error list
Source: https://docs.lerian.studio/en/reference/platform/systemplane/systemplane-error-list

Look up the error tokens the Systemplane admin API returns, the HTTP status each one carries, and what to do about it.

## Client errors

***

| `title` | Description | Status |
| - | - | - |
| `bad_request` | The request body is absent, unreadable, or holds no usable `value` field. | 400 |
| `unknown_key` | The key is not registered in the catalog. | 400 |
| `validation_error` | The value fails the validator for the key, or the namespace or key exceeds the maximum length. | 400 |
| `not_supported` | The operation is not available in this deployment. | 400 |
| `tenant_connection_missing` | The tenant database is absent from the request context. | 400 |
| `nil_context` | The request context is not available. | 400 |
| `forbidden` | The authorizer refused the action for this identity and namespace. | 403 |
| `not_found` | The requested key or catalog entry does not exist. | 404 |

> [!NOTE]
>
> Authentication runs in the application that hosts the admin surface, ahead of the configuration routes. A request that fails authentication receives a 401 from that host application, in its own error format. Refer to the API reference of the application whose configuration you manage.

## Server errors

***

| `title` | Description | Status |
| - | - | - |
| `internal_error` | The request failed inside the service. The message stays generic. Retry, then contact support if the failure continues. | 500 |
| `service_unavailable` | The configuration store is not started, or it has stopped. Retry after a short interval. | 503 |


# Answer a question the agent asked
Source: https://docs.lerian.studio/en/reference/platform/narya/answer-a-question-the-agent-asked

/en/openapi/v3-current/narya.yaml post /v1/questions/{questionId}/answer
Records what the person chose for one `ask_user` call and releases the tool call that has been blocked on it.

One answer per question, in the order the questions were asked. The indices are into the option list exactly as question-asked sent it — the engine ordered those options, so a client that reordered them would send back the wrong choice. Answering a question that is already answered, or one a host closed when its turn was interrupted, is a conflict: the tool it was blocking is no longer waiting.

A question is not a permission and this is not decidePermission: no rule can be written about a question, nothing is remembered, and the decision audit never carries one.



# Ask the host's clock to start work nobody will be present for
Source: https://docs.lerian.studio/en/reference/platform/narya/ask-the-host-s-clock-to-start-work-nobody-will-be-present-for

/en/openapi/v3-current/narya.yaml post /v1/schedules
Records a schedule: a repository, a prompt, a rule saying when it fires, and what one fire may spend. The host's own clock fires it into a new session that runs unattended — every fire opens its own session and nothing is ever appended to an earlier one.
Everything this host could not honour is refused HERE, because creation is the only moment somebody is present to answer. A rule under the five-minute floor, an instant already behind the clock, and a repository nobody has vouched for are all 422: a schedule accepted into an untrusted directory would wake at three in the morning, be refused at everything it tried, and leave an empty morning behind.
The clock itself is not on this surface. Due-ness, the sweep's cadence and how a ceiling is spent are the host's own facts; a client asks for a schedule and reads what the host decided.



# Branch a session at an earlier entry
Source: https://docs.lerian.studio/en/reference/platform/narya/branch-a-session-at-an-earlier-entry

/en/openapi/v3-current/narya.yaml post /v1/sessions/{sessionId}/branch
Creates a new session continuing from the given entry of this session's transcript. The original branch remains intact — returning to a previous point never destroys what came after it. Branching an archived session is allowed; the transcript is durable.



# Cancel a schedule
Source: https://docs.lerian.studio/en/reference/platform/narya/cancel-a-schedule

/en/openapi/v3-current/narya.yaml delete /v1/schedules/{scheduleId}
Stops the clock firing this schedule. This is a cancel, not a destroy: the row stays readable here and in the listing, carrying every fire it made and every refusal it recorded, because the sessions it created are read backwards from it.
It is ONE WAY, and nothing here undoes it — a schedule that should run again is created again, with a new id. Cancelling a schedule that is already cancelled is not an error: the state asked for holds. A fire already in flight is not recalled; what stops is every fire after it.



# Close a lane
Source: https://docs.lerian.studio/en/reference/platform/narya/close-a-lane

/en/openapi/v3-current/narya.yaml delete /v1/sessions/{sessionId}/lanes/{laneId}
Closes a side-conversation or subagent lane. The main conversation is returned to unchanged: nothing discussed in the lane enters the main context unless the user asks for it. The lane's transcript stays in the durable record. The main lane cannot be closed.



# Create an environment
Source: https://docs.lerian.studio/en/reference/platform/narya/create-an-environment

/en/openapi/v3-current/narya.yaml post /v1/environments
Provisions an environment under the identifier the caller names, on the one official image, and runs the caller's setup script inside it once. **Idempotent on that identifier** when the existing machine's setup state is recorded: such an id is answered 200 with the environment that exists, not 409 and not a second container — a client that lost the response to its first call may repeat it without paying twice. A setup-carrying create that meets a machine whose setup state was never recorded is refused rather than adopted: nobody can say whether that machine's toolchain exists. A setup script that fails or runs past the host's bound leaves the environment `unusable` carrying its own output as the cause, rather than a healthy-looking environment missing a toolchain.



# Decide a permission ask
Source: https://docs.lerian.studio/en/reference/platform/narya/decide-a-permission-ask

/en/openapi/v3-current/narya.yaml post /v1/permissions/{permissionId}/decision
Allows or denies a pending ask, optionally remembering the decision for the session or permanently. A denial is reported to the agent with its reason and the agent continues rather than crashing. Every decision is recorded in the audit. Deciding an already-decided ask is a conflict.



# Delete everything this home holds for one share
Source: https://docs.lerian.studio/en/reference/platform/narya/delete-everything-this-home-holds-for-one-share

/en/openapi/v3-current/narya.yaml delete /v1/shares/{shareId}
The INWARD half of revoking, served by the organisation's home and called by a developer's, exactly as the entries operation beside it is — the organisation's home is a narya host, so a revocation is one more operation on this contract rather than a second protocol.
IT DELETES AND THEN ANSWERS. The copied entries are gone from this home's store when this returns, which is what lets the developer's home answer its own caller truthfully rather than reporting a queued intention.
THE RECORD SURVIVES AS A TOMBSTONE, carrying the disclosure history and the revocation, so any entry offered for this share afterwards is refused 410 NRY-0031 — terminally, however long afterwards.
A SHARE THIS HOME HAS NEVER SEEN IS STILL TOMBSTONED. A home learns a share exists from its first delivery, so a person who publishes and immediately revokes can have that delivery in flight while this is being served; writing the tombstone anyway is what refuses it, rather than letting a deletion turn back into a live share.
Idempotent: the second call changes nothing and answers the same way, and the instant recorded stays that of the first revocation.



# Destroy an environment
Source: https://docs.lerian.studio/en/reference/platform/narya/destroy-an-environment

/en/openapi/v3-current/narya.yaml delete /v1/environments/{environmentId}
Ends the environment and releases what it holds. Idempotent: an identifier this host does not have is 204, because the caller's intent — that it be gone — is satisfied. Sessions bound to it are not deleted and their transcripts are untouched; each reports its environment `gone` and fails the tool calls that need it, rather than silently falling back to this machine.



# Disable a package
Source: https://docs.lerian.studio/en/reference/platform/narya/disable-a-package

/en/openapi/v3-current/narya.yaml post /v1/packages/{name}/disable
Disables a package without removing it. Disabling a code-carrying package rebuilds without it; a failed rebuild leaves the previous binary intact (NRY-0007). In the rare case the rebuild's binary swap succeeds but confirming the resulting package row does not, the response is 409 NRY-0017 instead: the change already applies and resolves automatically on the next host restart.



# Drop a message still waiting behind a running turn
Source: https://docs.lerian.studio/en/reference/platform/narya/drop-a-message-still-waiting-behind-a-running-turn

/en/openapi/v3-current/narya.yaml delete /v1/sessions/{sessionId}/inputs/{entryId}
Withdraw one message a person queued while a turn was running, before the turn reaches it. Session.pendingInputs is what lists them; this is the only way one leaves that list other than by being delivered. It exists because a queued message is otherwise a decision nobody can take back: the words are already accepted, the turn that will receive them may run for minutes, and the person who typed them has since changed their mind. Both clients show the count and the queue; neither could do anything about it. The entry STAYS in the transcript, carrying an excludedReason saying it was withdrawn. A message a person typed is not unsaid by dropping it, and a transcript that lost the row would disagree with their own memory of the session — but no model ever receives it, on this turn or any later one. A message already delivered is a 404, exactly as an entry that does not exist is: both mean there is nothing here still waiting.



# Enable a package
Source: https://docs.lerian.studio/en/reference/platform/narya/enable-a-package

/en/openapi/v3-current/narya.yaml post /v1/packages/{name}/enable
Re-enables a disabled package. Enabling a code-carrying package rebuilds with it, synchronously: unlike install, a slot conflict here answers directly with 409 NRY-0006 naming both claimants, since there is no job to poll. A failed build leaves the previous binary intact (NRY-0007). In the rare case the rebuild's binary swap succeeds but confirming the resulting package row does not, the response is 409 NRY-0017 instead: the change already applies and resolves automatically on the next host restart.



# Expand one command file into text
Source: https://docs.lerian.studio/en/reference/platform/narya/expand-one-command-file-into-text

/en/openapi/v3-current/narya.yaml post /v1/commands/{name}/expansion
Expands one command file and returns the text: its shell blocks run, their output spliced in where they stood, and the arguments substituted into what that produced. The order is deliberate and is not the caller's to choose — a pasted issue body carrying a backtick block must never become a block. Shell blocks run only in a repository somebody has trusted, and never at all for a command a package shipped; a block that did not run is replaced by a sentence saying why. They run in the named repository's own directory, and only when that repository is trusted — an untrusted checkout is never a working directory. One expansion's blocks share a ten-second deadline, so this call can take that long. A name two command files both claim is refused with 409 naming both, never awarded to one of them: listCommands lists every claimant for exactly that reason, and there is never an implicit winner.



# Expand one skill into text
Source: https://docs.lerian.studio/en/reference/platform/narya/expand-one-skill-into-text

/en/openapi/v3-current/narya.yaml post /v1/skills/{name}/expansion
Reads one skill's instructions and returns them framed the way the model's own skill tool frames them — whose they are and which directory their relative paths resolve against — with whatever the person typed after the name appended. The file is read NOW, through the confinement its origin was discovered with, so a skill edited since it was listed is returned as edited and a project skill whose path has since become a symlink out of the checkout is refused. A body that cannot be read comes back as a sentence saying so rather than as an error: the caller asked for text to put in front of a person, and text is what it gets.



# Export a session transcript
Source: https://docs.lerian.studio/en/reference/platform/narya/export-a-session-transcript

/en/openapi/v3-current/narya.yaml get /v1/sessions/{sessionId}/export
Human-readable export of one session's transcript, selected by content negotiation on the Accept header: text/markdown for reading, application/jsonl for one JSON entry per line greppable without Narya. This replaces the affordance of a file-based transcript format readable with less and grep. Works on archived sessions.
Two independent content toggles select what the export carries, both off by default. Stripping is never silent: an omitted reasoning block leaves a line saying how many blocks were left out, and an omitted tool result leaves the tool it answered, whether it failed, and the byte count it would have carried — so a reader can tell "the agent ran nothing" from "you asked me not to show it".



# Get a package job
Source: https://docs.lerian.studio/en/reference/platform/narya/get-a-package-job

/en/openapi/v3-current/narya.yaml get /v1/packages/jobs/{jobId}
Returns the progress of a package install or removal job: resolving, building, swapping, done or failed. A failed job carries the build error and guarantees the previous binary is intact.



# Get a schedule
Source: https://docs.lerian.studio/en/reference/platform/narya/get-a-schedule

/en/openapi/v3-current/narya.yaml get /v1/schedules/{scheduleId}
Returns one schedule with its rule, its ceiling and the history of what its fires did: the session the last one created, when a fire was refused and why, and how a fire that never reached a session was interrupted.



# Get a workflow run
Source: https://docs.lerian.studio/en/reference/platform/narya/get-a-workflow-run

/en/openapi/v3-current/narya.yaml get /v1/workflows/runs/{runId}
Returns a run's status with per-step progress and partial results. A failed step never silently disappears from the result.



# Get an agent recipe
Source: https://docs.lerian.studio/en/reference/platform/narya/get-an-agent-recipe

/en/openapi/v3-current/narya.yaml get /v1/agents/{name}
Returns one named agent recipe.



# Get an environment
Source: https://docs.lerian.studio/en/reference/platform/narya/get-an-environment

/en/openapi/v3-current/narya.yaml get /v1/environments/{environmentId}
One environment with the image digest it runs, whether it is answering, and what its setup script did. This is how a client tells a session waiting on an unreachable environment from a session that is merely slow.



# Get an inter-session ask
Source: https://docs.lerian.studio/en/reference/platform/narya/get-an-inter-session-ask

/en/openapi/v3-current/narya.yaml get /v1/asks/{askId}
Returns the state of a blocking question one session asked another, including the answer once given. Polling here is the simple path; the answer also arrives on the event stream as an intercom-message event, which is the recommended way to wait.



# Get the repository's saved composer draft
Source: https://docs.lerian.studio/en/reference/platform/narya/get-the-repository-s-saved-composer-draft

/en/openapi/v3-current/narya.yaml get /v1/drafts
Returns the live draft text last saved for repo's terminal composer: a debounced autosave written as the user types, restored when a client opens a session against this repository so a killed terminal never costs unsent work. Keyed by repository, not session — this client always opens a brand-new session on launch, so a session-keyed draft would be unreachable by construction, and every window open on the same repository shares one draft (last write wins). An empty string when nothing has ever been saved — not an error.



# Go back to an earlier point, on a new branch
Source: https://docs.lerian.studio/en/reference/platform/narya/go-back-to-an-earlier-point-on-a-new-branch

/en/openapi/v3-current/narya.yaml post /v1/sessions/{sessionId}/rewind
Moves back to an earlier entry and continues from there — the conversation, the files, or both. Rewinding ALWAYS branches and never deletes: the timeline walked away from stays in the tree with its own tip, navigable and continuable, so going back is a way to stop adding to something rather than a way to lose it. Undoing a rewind is continuing the abandoned branch again, not a second mechanism.
The same is true of the files. Before anything is restored, the working tree AS IT IS becomes its own restore point, so the state the rewind moved away from can be put back byte for byte. Nothing in the person's own git history sees any of it; the restore points live in narya's shadow repository beside the checkout.
scope has no default, and a request omitting it is refused. The two axes fail in opposite directions — rewinding the conversation without the code leaves the agent arguing with a working tree it cannot see, rewinding the code without the conversation throws away work the transcript still claims exists — so this operation never guesses.
A scope that moves files is refused with 409 while a turn is in flight anywhere in this checkout, which includes another session standing in it: several sessions share one working tree and one set of restore points, and restoring under a live tool would destroy whatever it is part-way through writing. The refusal names the session that is working.



# Import a transcript from another harness
Source: https://docs.lerian.studio/en/reference/platform/narya/import-a-transcript-from-another-harness

/en/openapi/v3-current/narya.yaml post /v1/sessions/import
Reads a transcript written by another harness and creates the conversation, or the branched family, it describes. Exactly two foreign formats are accepted: Claude Code's JSONL transcripts and opencode's export JSON. The raw file is the request body.
Nothing is imported silently. Every record the read did not carry is counted and named in a system entry at the head of the imported session — including sub-agent records, which are skipped as a group because a subagent's words are not the agent's.
A file whose content is not the format named is refused (400) rather than parsed, and a file with an unreadable line is refused naming that line rather than importing half a conversation.



# Install a package
Source: https://docs.lerian.studio/en/reference/platform/narya/install-a-package

/en/openapi/v3-current/narya.yaml post /v1/packages
Installs a package from a registry reference or a local path. The response is 202 with an install job, because a package carrying Go code triggers a rebuild and binary swap; poll the job (or watch events) for progress. Resource-only packages complete near-instantly. Conflicts — two packages claiming one slot — surface asynchronously, on the failed job's error envelope, as NRY-0006 naming both claimants (enable/disable are the one synchronous exception: they report a slot conflict as a direct 409 instead, since they have no job to poll). A failed build never leaves the user without a working agent: the previous binary stays in place (NRY-0007).



# Interrupt a lane
Source: https://docs.lerian.studio/en/reference/platform/narya/interrupt-a-lane

/en/openapi/v3-current/narya.yaml post /v1/sessions/{sessionId}/lanes/{laneId}/interrupt
Stops work in progress on one lane within one action, without touching the session's other lanes.



# Interrupt the session's main lane
Source: https://docs.lerian.studio/en/reference/platform/narya/interrupt-the-session-s-main-lane

/en/openapi/v3-current/narya.yaml post /v1/sessions/{sessionId}/interrupt
Stops work in progress on the session's main lane within one action. Work already completed is preserved; the interrupted turn's record stays durable. Completion of the interrupt is observable as a turn-finished event with stopReason interrupted. Queued steering and follow-up inputs are not cleared or started; the session becomes waiting when any remain, otherwise idle.



# Invoke an operation a registered extension exposes
Source: https://docs.lerian.studio/en/reference/platform/narya/invoke-an-operation-a-registered-extension-exposes

/en/openapi/v3-current/narya.yaml post /v1/extensions/{name}/invoke
The generic request lane for extension-defined behaviour, and the near half of the registered extension's own `invoke` operation: a client reaches an extension THROUGH this host, needing nothing but the extension's name and never holding its secret. The host signs the forwarded call under the registration's secret, judges the address on the way out and refuses a redirect; the payload is the extension's own contract and the host only routes it.

**The address is configuration, not a credential.** `listExtensions` shows `endpoint` to every member of the organisation on purpose — a registry that hid where an extension points would answer "what is reading our conversations" with less than the truth — so what this lane withholds is the secret and the signature, not the URL. Knowing the address buys nothing without the secret: every call in the extension contract is signed, and an extension is required to refuse anything that does not verify.

**An ordinary member's token is enough.** Invoking is using, and only registering is owning — `extensions:manage` gates the writes that create, re-point, revoke and re-order a registration.

The forward runs under the same deadline a transformation gets.



# Label one entry of a transcript
Source: https://docs.lerian.studio/en/reference/platform/narya/label-one-entry-of-a-transcript

/en/openapi/v3-current/narya.yaml put /v1/sessions/{sessionId}/entries/{entryId}/label
Puts a short tag on one moment of a conversation, or takes the tag away by sending an empty one — setting and clearing are the same write, because changing a label and removing it are the same gesture from where a person stands.
A label is what makes a branched family navigable by meaning rather than by id: "the version that worked", "before the refactor", "where it broke". One per entry, at most 128 characters, and it appears on the labels of the session's node in getSessionTree, which is also what that operation's label filter matches.
The entry must belong to the named session. This is the only write in the transcript's surface that names an entry directly, so it is the only one that could be aimed at another conversation's entry, and one that is gets 404 rather than quietly succeeding.
That 404 is deliberately not branchSession's 422 for the same fact. Here the entry is part of the ADDRESS: this session's entry with that id does not exist, which is what 404 says. branchSession carries the entry in its body, so the address (the session) does exist and it is the request that does not make sense against it, which is what 422 says.



# List a session's lanes
Source: https://docs.lerian.studio/en/reference/platform/narya/list-a-session-s-lanes

/en/openapi/v3-current/narya.yaml get /v1/sessions/{sessionId}/lanes
Lists the parallel tracks inside the session: the main lane, subagent lanes carrying delegated work, and side-conversation lanes — each with its status and what it is currently doing.



# List addressable peer sessions
Source: https://docs.lerian.studio/en/reference/platform/narya/list-addressable-peer-sessions

/en/openapi/v3-current/narya.yaml get /v1/peers
Lists the sessions on this machine that are addressable by name for inter-session messaging, with what each is working on and its liveness. A session that has gone away does not appear here — it is reported as gone (NRY-0009) when addressed, never as available.



# List agent recipes
Source: https://docs.lerian.studio/en/reference/platform/narya/list-agent-recipes

/en/openapi/v3-current/narya.yaml get /v1/agents
Lists the named agent recipes available on this host — name, description, model, allowed tools, permission policy and the package each came from. Recipes come from configuration and packages; read-only in v1, so there is no create or update operation.



# List installed packages
Source: https://docs.lerian.studio/en/reference/platform/narya/list-installed-packages

/en/openapi/v3-current/narya.yaml get /v1/packages
Lists installed packages — resource-only and code-carrying — with their enabled state and source.



# List installed skills
Source: https://docs.lerian.studio/en/reference/platform/narya/list-installed-skills

/en/openapi/v3-current/narya.yaml get /v1/skills
Lists the skills in force for work in this repository — name, the one line that says when to reach for one, the file it lives in and the rung it came from. Five origins are merged, nearest winning a name, so a skill listed here is the one that will actually load; the ones a nearer rung shadows are simply absent. The bodies are never here: progressive disclosure means a catalogue carries names, and expandSkill is what reads one. Notices carries whatever the loaders complained about while reading — a package skill something nearer displaces, a file with no description — for a client to show once.



# List model providers
Source: https://docs.lerian.studio/en/reference/platform/narya/list-model-providers

/en/openapi/v3-current/narya.yaml get /v1/providers
Lists registered model providers with their authentication state and the models each serves. Registering a new provider is configuration, not API surface, in v1.



# List models across providers
Source: https://docs.lerian.studio/en/reference/platform/narya/list-models-across-providers

/en/openapi/v3-current/narya.yaml get /v1/models
Flat, cursor-paginated list of every model available across all providers, with capability and cost metadata — the catalogue a client offers when switching model mid-session.



# List permission asks
Source: https://docs.lerian.studio/en/reference/platform/narya/list-permission-asks

/en/openapi/v3-current/narya.yaml get /v1/permissions
Lists permission asks, by default the pending ones — actions waiting on a human decision. Pending asks also arrive as permission-asked events; this list is the poll/recovery path for clients that reconnect.



# List recently chosen models
Source: https://docs.lerian.studio/en/reference/platform/narya/list-recently-chosen-models

/en/openapi/v3-current/narya.yaml get /v1/models/recent
The models chosen in a client, most recent first, bounded — the shortlist a model picker offers above the full catalogue so somebody alternating between two models never scrolls for either. The head of this list is also the default a session opened with no explicit model adopts. A model no longer in the catalogue is absent here rather than listed as unusable.



# List sessions that touched a file
Source: https://docs.lerian.studio/en/reference/platform/narya/list-sessions-that-touched-a-file

/en/openapi/v3-current/narya.yaml get /v1/records/files
Answers "which sessions touched this file", over the same three session kinds searchRecords covers: the caller's own, the ones marked for the organisation, and every session when the caller holds the read-private permission. A share adds none here either: what a share delivers is transcript entries, and a file listing reports the file changes, which a share does not carry at all. An unknown path, and a path touched only by sessions outside those three kinds, both return an empty page rather than an error.



# List slash commands
Source: https://docs.lerian.studio/en/reference/platform/narya/list-slash-commands

/en/openapi/v3-current/narya.yaml get /v1/commands
Lists every command file that can be expanded for work in this repository — an installed package's declared commands, the person's own under $NARYA_HOME/commands and ~/.claude/commands, and, only in a trusted repository, the project's own .claude/commands and .narya/commands. Name, description, argument hint, and where the file came from; never the body, which expandCommand is for. Notices carries the loaders' own complaints.



# List the decision audit
Source: https://docs.lerian.studio/en/reference/platform/narya/list-the-decision-audit

/en/openapi/v3-current/narya.yaml get /v1/permissions/decisions
Cursor-paginated audit of every permission decision ever taken on this host — by a human or by policy, including denials during unattended work. Every decision is recorded and reviewable afterwards.



# List the environments this host holds
Source: https://docs.lerian.studio/en/reference/platform/narya/list-the-environments-this-host-holds

/en/openapi/v3-current/narya.yaml get /v1/environments
Environments in creation order, each with the image digest it actually runs and what its setup script did. This host's own machine is not one of them: it is what a session gets by naming nothing, and it has no lifecycle to list.



# List the questions waiting on a person
Source: https://docs.lerian.studio/en/reference/platform/narya/list-the-questions-waiting-on-a-person

/en/openapi/v3-current/narya.yaml get /v1/questions
The questions the agent has asked and nobody has answered yet — the recovery road for a client that was not attached when `question-asked` went out.

It is the road `listPermissions` already is for the other kind of ask, and it exists for the same reason: a question is durable state on the host and the event announcing it is long past by the time a client attaches, which reads the transcript and then subscribes after the position that read returned. A question is not a transcript entry, so a client with no retained event cursor has nothing else to reconstruct it from.

ONLY PENDING QUESTIONS, and there is no status filter. An answered question is retired by `tool-call-finished` for the call it was blocking, and the decision audit never carries a question, so the only thing there is to list is what somebody still has to answer.



# List the repositories this organisation selected on GitHub
Source: https://docs.lerian.studio/en/reference/platform/narya/list-the-repositories-this-organisation-selected-on-github

/en/openapi/v3-current/narya.yaml get /v1/github/repositories
The repositories this organisation's installation of the Narya GitHub App carries, which is the set a person may name when creating an environment. **Served straight from GitHub on every request**, never from a copy narya keeps: the set is the customer's to change on GitHub at any moment, and a cache would drift from what they selected the instant they changed it.

An organisation that has connected no GitHub is answered with an **empty page carrying a notice** naming the gesture that connects one, rather than an error or a bare empty list — having connected nothing is a state with a remedy, not a failure. Every other cause fails closed: a host that cannot read what its organisation applies, and a GitHub that refuses, are both refusals naming what could not be done.



# List the schedules this host's clock owes
Source: https://docs.lerian.studio/en/reference/platform/narya/list-the-schedules-this-host-s-clock-owes

/en/openapi/v3-current/narya.yaml get /v1/schedules
Cursor-paginated list of every schedule on this host, newest first, cancelled and completed ones included. What a schedule is owed and when is on the row: nextRunAt is the instant the clock is working towards, and lastSkippedAt with lastSkipReason is why a due fire was turned down.



# List the session's running monitors
Source: https://docs.lerian.studio/en/reference/platform/narya/list-the-session-s-running-monitors

/en/openapi/v3-current/narya.yaml get /v1/sessions/{sessionId}/monitors
Every watcher this session is running right now, in the order they were started, each saying what it runs and who turned it on. This is what a status line counts and a session panel lists; a client that has been watching the event stream already knows, and this read is how one that just attached catches up.



# List the shared sessions this home holds
Source: https://docs.lerian.studio/en/reference/platform/narya/list-the-shared-sessions-this-home-holds

/en/openapi/v3-current/narya.yaml get /v1/shares
The RECIPIENT's end of publishing: the conversations colleagues have published to this home, newest first.
IT IS ADDRESSED BY SHARE ID AND NOT BY SESSION ID, here and on every road of this group. A published copy is not a session at this home: the entries arrived redacted from somebody else's machine and no session of that id exists here, by design. The session id a row reports is provenance about the machine it came from, and asking this host about it answers nothing.
WHO MAY SEE WHAT IS DECIDED HERE AND NOT BY A CLIENT. A share published to the whole organisation is readable by any member of it, which is every actor this home admits — one organisation is one home. A share naming colleagues is readable by exactly those colleagues and by whoever published it. This page is that rule asked once per row: the shares a caller may not read are simply absent, because a listing that refused would show a person nothing rather than their own.
A page can therefore come back shorter than its limit, and the cursor still leads where it led: a client pages until nextCursor is absent.
Shares whose expiry has passed and shares somebody revoked are not here. The conversation they carried has been deleted and the record survives only to say who had read it.



# List this home's registered extensions
Source: https://docs.lerian.studio/en/reference/platform/narya/list-this-home-s-registered-extensions

/en/openapi/v3-current/narya.yaml get /v1/extensions
Every extension this home has registered, in name order, with where it points, which points it sits on, which slots it claims, what was granted on it, whether it is enabled and who registered it when. **No response here ever carries a secret** — only the registration and the rotation that mint one do. Any member of the organisation may read this: the registry is what makes "what is reading our conversations" answerable, and one only its author could read would disclose nothing to the people whose prompts are crossing. An extension Lerian installed on a home it hosts is marked `installedByOperator`, which is how a customer learns it happened. Client-side extensions (pure TUI components) do not appear here — they live in the client binary.



# List what narya has been taught
Source: https://docs.lerian.studio/en/reference/platform/narya/list-what-narya-has-been-taught

/en/openapi/v3-current/narya.yaml get /v1/refinements
Cursor-paginated list of this owner's refinements, newest first, paged on (createdAt, id) — two facts consented in the same second would otherwise repeat one and lose the other across a page boundary. Rolled-back rows are in it: walking backwards from a strange behaviour to the fact that caused it is what the row is for.

Each row carries its provenance, its state, how often it has fired and — for a capability that executes — its script's HASH. Not the script's text, which is on getRefinement: a listing that carried every authored program's source is a listing nobody can page.



# List workflow runs
Source: https://docs.lerian.studio/en/reference/platform/narya/list-workflow-runs

/en/openapi/v3-current/narya.yaml get /v1/workflows/runs
Cursor-paginated list of workflow runs, filterable by status.



# Move a session to another directory
Source: https://docs.lerian.studio/en/reference/platform/narya/move-a-session-to-another-directory

/en/openapi/v3-current/narya.yaml put /v1/sessions/{sessionId}/repository
Points a live session at another directory. From the next turn onwards its tools are confined to the new root, its commands run there, and every surface that names the directory names this one. The CONVERSATION is untouched: not one entry is lost, and the move is written into it as a note saying where the session came from.
WHAT IT COSTS, and it is the one thing nobody can get back: the session's restore points are DROPPED. Every one of them named a saved working tree in a store keyed to the checkout the session is leaving, so after the move not one of them could put a file back — kept, they would go on offering a moment the host cannot honestly reach. Going back to an earlier point in the CONVERSATION still works, because the transcript is intact; going back to the files as they were before the move does not. A client offering this gesture has to be able to say so before it calls. The first tool that changes a file in the new directory takes a fresh baseline on its own, and until then the session offers no restore point at all.
Trust is asked about the destination exactly as at session open: an untrusted directory is not refused, it runs untrusted. What does not survive the move is a recorded HANDOVER — a session moved into a directory nobody has vouched for is taken back to `attended`, with the reason written into its conversation, because nobody being there in a directory nobody trusts is the hole this closes.
Refused with 409 while a turn is in flight, rather than raced: dropping the restore points under a tool part-way through writing files would throw away the one baseline that could put them back. Interrupt the turn and call again. Refused with 409 for an archived session, and with 422 for a destination that is not an absolute path to a directory, or whose own project configuration will not load.
Moving a session to the directory it already stands in is not an error: the state asked for holds, so nothing is appended, nothing is dropped, and no event is emitted.
The directory is a working-directory LABEL and re-homing a session moves nothing about who owns it: ownership is the identity the host authenticated at creation, and this operation cannot change it. On a host that names its own directories the destination resolves under that host's workspace root, and one outside it is refused with the same 422 sentence createSession refuses it with.



# Open a lane
Source: https://docs.lerian.studio/en/reference/platform/narya/open-a-lane

/en/openapi/v3-current/narya.yaml post /v1/sessions/{sessionId}/lanes
Opens a parallel track inside the session. kind side opens a side conversation that runs without pausing or contaminating the main work; kind subagent delegates to the named agent recipe, running concurrently with other delegated work. The initial message starts the lane's first turn; its results stream over the event stream.
A session holds at most one OPEN side conversation. A side conversation is a conversation, so a follow-up question belongs in the lane that already has one rather than in a new lane that never saw the exchange: list the session's lanes, find the side lane whose status is not closed, and submit the question to it (createLaneMessage). Asking for a second one answers 409 and names the lane that holds it. Closing the open one and opening another is how a fresh side conversation is started.



# Publish this session to the organisation's home
Source: https://docs.lerian.studio/en/reference/platform/narya/publish-this-session-to-the-organisation-s-home

/en/openapi/v3-current/narya.yaml post /v1/sessions/{sessionId}/share
Copies this session, already redacted, to the organisation's home, where the team reads it. The developer's home is where the work happens and the organisation's is where it is read, so this is a one-way copy addressed by a share id and never a synchronisation of two equal stores.
Read `GET /v1/sessions/{sessionId}/share/preview` first and show a person the document: it is the last moment before the bytes leave their machine.
THE MODE IS WHERE THE PUBLISH STOPS, and there are two. `once` copies the entries that exist and is finished. `sync` leaves the share subscribed, so entries said afterwards ride the same queue — one road with two stopping rules rather than a streaming mechanism beside a batch one.
THE SHARE ID IS DRAWN AND CARRIES NOTHING. It is unrelated to the session id by construction, so a share link that leaks says nothing about the machine it came from.
Publishing the same session twice creates a second share with its own id; a revoked share is never resumed, and re-sharing after a revocation is always a new one.
AN UNREACHABLE ORGANISATION'S HOME IS 503 NRY-0029 AND IS NOT A FAILURE. The share is recorded and every entry is owed on disk before anything is sent, so an unreachable organisation's home means the work is queued: a later drain carries it, complete and in order, and the message names the share. Nothing about local work is blocked by it.



# Re-point, re-order, re-grant or disable a registered extension
Source: https://docs.lerian.studio/en/reference/platform/narya/re-point-re-order-re-grant-or-disable-a-registered-extension

/en/openapi/v3-current/narya.yaml patch /v1/extensions/{publisher}/{name}
Changes the endpoint, the points, the slots, the position, the grants or the enabled flag. Requires `extensions:manage`. **Widening a grant additionally requires the caller to hold that permission themselves**, so nobody hands an extension reach they do not have; narrowing one never does.

**Four things here can reach the extension, and a disable outranks all four.** A moved `endpoint`, an explicit `refreshModels`, a `tool-server` slot this update claims that the row did not already hold, and — belonging to that slot alone — an `enabled` going from `false` to `true` on a row that already holds it. And then only for what the row has to answer for. A moved `endpoint` reads BOTH, the model list if the row claims `model-supplier` and the tool listing if it claims `tool-server`, because a new address is a new answer to both questions; `refreshModels` reads the model list alone; a newly-claimed `tool-server` slot, or an enable of a row already holding it, reads the tool listing alone — an enable being the moment this home starts serving that registration's tools, and the one road onto that which nothing else here checks. **Claiming `model-supplier` reaches it not at all by itself**: the claim alone stores that slot claimed and unserved, and `refreshModels` is what reads its catalogue, so an extension that verifies signatures is never called under a secret it does not hold yet. Everything else — a narrowed grant, a moved position, a changed point list, another slot, the switch itself — is a write against this home's own row that completes whether or not anything answers there.

**Each of those reads FAILS CLOSED.** A model list or a tool listing this host asked for and could not read — a refused connection, a timeout, a non-`200`, a body that does not parse — answers `422` and changes nothing, rather than storing a claim it could not check. Either way, check the endpoint answers `/tools` — or `/models` for a supplier — under the secret it holds, then make the write again.

**Carry `refreshModels: true` in the same body to claim the supplier slot and read its catalogue in one write**, so long as the row that update produces remains enabled. The flag outranks every other field the body carries but never the switch, so `{"slots": ["model-supplier"], "refreshModels": true}` does call the endpoint — the shortest correct road once the far side already holds the secret — while that same body carrying `"enabled": false` calls nothing at all and stores the claim unserved. Where the read does happen it is all or nothing: if it fails, the whole update answers 422 and **nothing is stored**, so the slot is never left claimed behind a read that did not happen.

**When the row this update produces is switched off, nothing is asked of that address, however the body is written.** `{"enabled": false, "refreshModels": true}` and a disable that also moves the endpoint store the change and call nothing: the moment an owner most needs to disable an extension is the moment it has stopped answering, and a veto its subject can refuse by going quiet is not one. What such a body asked for is stored rather than performed — the new address and the newly claimed slot are on the row — and **re-enabling does not read the model list either**, because switching a row back on says nothing about what that address now serves. Send `refreshModels: true`, with the enable or after it, to read the list at the address the row now carries. The tool listing is the exception: an enable of a row holding `tool-server` reads it, as above.

On a row Lerian installed (`installedByOperator`), `enabled` is the only field this may touch, in both directions. Off is the owner's standing veto and on again is allowed because re-enabling Lerian's own endpoint discloses nothing that was not disclosed when Lerian installed it. Every other field is refused: an owner who could re-point that endpoint could aim an operator-marked, Lerian-audited registration at an address of their own.



# Read a session's transcript
Source: https://docs.lerian.studio/en/reference/platform/narya/read-a-session-s-transcript

/en/openapi/v3-current/narya.yaml get /v1/sessions/{sessionId}/entries
One page of the session's transcript, oldest first: the questions a person asked, the answers, and the tool calls and results between them. This is how a client that did not watch a session happen shows its conversation — a tab opening a session created hours ago, a switcher moving into another one. Replaying the event stream is not a substitute for it: entry-appended carries identity and nothing else, so a client reconstructing a conversation from events alone renders every answer with none of the questions.
Each page carries lastEventId, the event-stream position it was read at. A client pages to the end and then subscribes to GET /v1/events for this session with Last-Event-ID set to the LAST page's value: every entry committed at or before that read is already in hand, every event after it arrives on the stream, and nothing is delivered twice. Entries and that position are read from one database snapshot, so no entry can slip between the two.
A turn still in flight is deliberately not in it. The fragments of a message that has not committed as an entry are not transcript yet — a client attaching mid-turn receives the rest of that turn on the stream, and reads the entry the turn commits when it ends by asking for the entries after the last sequence it holds.
nextCursor is always present: a transcript is append-only, so the cursor is a resume position rather than a promise that more exists already. hasMore is what says whether more exists right now.
An assistant round's reasoning blocks are not served here, and neither are their signatures. They are the model's own scratchpad — rendering them in the assistant's voice claims the model said what it only considered — and each signature is opaque provider material that never leaves the host. What the entry DOES carry is a summary of the run (Entry.reasoning): what the model called it, how many blocks it took and how long it ran. Those are facts about the thinking rather than any of it, and they are what lets a client reading a session back draw the one collapsed line the live client draws, in the place the thinking happened. An entry that held nothing else is still listed, carrying no text, so a transcript's sequence numbering stays honest.



# Read a shared session's copied entries
Source: https://docs.lerian.studio/en/reference/platform/narya/read-a-shared-session-s-copied-entries

/en/openapi/v3-current/narya.yaml get /v1/shares/{shareId}/entries
The conversation itself, as this home holds it: the redacted entries that crossed, in the order they were said.
ALREADY REDACTED, AND THE ORIGINAL NEVER EXISTED HERE. Every rule ran at the home the entries were published from, which is the only place a *before* exists. Nothing at this end can widen what was sent, and nothing at this end is asked to.
THE SAME AUDIENCE RULE THE LISTING APPLIES, and a share this caller may not read answers 404 NRY-0015 rather than 403 — the same answer a share id this home has never seen gets, so the two cannot be compared to learn that somebody's conversation is here. A revoked share and one whose expiry has passed answer identically, for the same reason.
EVERY SERVED READ IS RECORDED, unless the reader is the person who published it. The disclosure entry is written before a byte is served and a read whose record cannot be written is not served at all, which is what makes "who opened this" a trustworthy answer rather than a best-effort one.
Cursor pagination, oldest first, on the publishing home's own numbering — a conversation is read forwards.



# Read one file a transcript row carried
Source: https://docs.lerian.studio/en/reference/platform/narya/read-one-file-a-transcript-row-carried

/en/openapi/v3-current/narya.yaml get /v1/sessions/{sessionId}/media/{mediaKey}
The bytes of one picture or converted document a session's transcript names, addressed by the mediaKey on an Entry.attachments record. This is the ONLY road to them: the transcript read carries what a picture IS and never any of it, so a client that wants to draw one asks here.
It serves bytes rather than a path on purpose. The client may be on another machine than the engine, where a path names nothing — and even on one machine a path would invite a client to read a directory the host owns.
The key is resolved through the TRANSCRIPT that names it, not by joining it onto a directory. So a key this session's conversation does not carry is a 404 whether or not a file of that name exists: one conversation's picture is not another's, and a home holds every session's media beside the database. The refusal says nothing else — there is no distinction to draw between "no such file" and "not yours", and drawing one would answer questions nobody may ask.
Immutable once written, so the response may be cached for as long as the client likes. narya session purge destroys a conversation's media with it, after which its own keys answer 404.



# Read one registered extension
Source: https://docs.lerian.studio/en/reference/platform/narya/read-one-registered-extension

/en/openapi/v3-current/narya.yaml get /v1/extensions/{publisher}/{name}
One registration, never its secret. Readable by any member, for the listing's reason.



# Read one shared session's record
Source: https://docs.lerian.studio/en/reference/platform/narya/read-one-shared-session-s-record

/en/openapi/v3-current/narya.yaml get /v1/shares/{shareId}
One share this home holds, as a recipient sees it: who published it, which session on which machine it came from, how far the copy reaches and when it stops.
It is the same audience rule, the same 404 and the same disclosure record as the entries beside it. Reading the record of a published conversation is a read of that conversation's existence, and at this home its existence is the thing a share id would otherwise confirm.
WHO ELSE A SHARE NAMES IS NOT REPORTED HERE. The list of recipients is a statement about people rather than about the work: whoever published it holds it at their own home, and who has actually opened the copy is the disclosure audit's answer.



# Read the branched family a session belongs to
Source: https://docs.lerian.studio/en/reference/platform/narya/read-the-branched-family-a-session-belongs-to

/en/openapi/v3-current/narya.yaml get /v1/sessions/{sessionId}/tree
Every session joined to this one by branch provenance, root first, each node carrying the entry it branched at. A branch IS a session, so this is the shape listSessions cannot show: that flat list says which conversations exist and never that one continues another.
It returns the WHOLE family, not the subtree below the named session. A person navigating a tree is standing on a branch, and the thing they most often want is the sibling they walked away from — which a subtree rooted where they stand would not contain.
Each node carries the first and last thing said in it. That is how an unsummarised branch is recognised on sight, which is the point: no summary is ever produced because a branch was abandoned, so recognition has to work without one. Asking for a summary (summarizeSession) is one command away when it does not.
A node whose parentSessionId is absent is a root. That includes a branch whose origin was purged: the provenance link is cleared rather than the branch taken away, so an orphaned branch becomes a root of its own family and stays fully readable.
The label filter keeps a session carrying that label AND every ancestor of one, whether the ancestor carries it or not. A tree with holes in the middle is not a tree — dropping an unlabelled parent would draw its child hanging off a branch point that never existed.
A family whose branch provenance runs deeper than the walk allows is refused (409) rather than answered with a tree that quietly stops partway. A truncated tree presented as whole would be missing exactly the branch the person is standing on.



# Read the exact system prompt this session's next turn will send
Source: https://docs.lerian.studio/en/reference/platform/narya/read-the-exact-system-prompt-this-session-s-next-turn-will-send

/en/openapi/v3-current/narya.yaml get /v1/sessions/{sessionId}/prompt
The assembled system prompt, verbatim, plus the ledger's accounting beside it: which learned facts fired into it, and which the budget for this model's context window could not fit. It exists so a person debugging a strange behaviour can read what the model is actually being told instead of reasoning about it.

HOW THE PROMPT IS COMPOSED IS NOT ON THIS SURFACE, and the omission is deliberate rather than an oversight: no combinator order, no wrapper template, no budget formula and no selection rule. A client renders what it is given and never recomputes it.



# Read the provider's sign-in in flight
Source: https://docs.lerian.studio/en/reference/platform/narya/read-the-provider-s-sign-in-in-flight

/en/openapi/v3-current/narya.yaml get /v1/providers/{name}/auth
The state of the sign-in startProviderAuth last began for this provider: still pending with the URL to open, complete, or failed with the reason. This is how a client learns the outcome of a browser or device-code flow the host is driving on its behalf — the provider's own authState says whether a credential exists, this says what happened to the last attempt to get one. 404 when this host has no attempt on record for the provider.



# Read what a session changed on disk
Source: https://docs.lerian.studio/en/reference/platform/narya/read-what-a-session-changed-on-disk

/en/openapi/v3-current/narya.yaml get /v1/sessions/{sessionId}/changes
The files this session's write, edit and delete tools changed, each with what it did to the file, how many lines moved, and the content the file held before the session first touched it. It is what a diff view of a session's own work stands on, and what a touched-files list shows counts from.
Every row is measured from FIRST touch. A file the session edited five times is one row comparing what it held before edit one against what is on disk now — not five rows, and not the last edit's delta. That is also why a file put back the way it was is absent from the answer: it changed nothing, and reporting it at zero lines either way would claim otherwise.
The current content is deliberately not served. The host and its clients share a filesystem, so a client reads the file itself and gets the version it is about to let somebody edit, rather than a copy that was already stale when it was sent. What only the host has is the before side.
Both sides are bounded at 1 MiB (1048576 bytes). Past that nothing was kept, and the row says so through beforeState rather than serving an empty file or a truncated one: beforeBytes still carries the real size, so a client can say how large the file it cannot diff is. linesAdded and linesRemoved are then absent, because a count nobody could compute is not zero.



# Read what one conversation cost, broken down by model
Source: https://docs.lerian.studio/en/reference/platform/narya/read-what-one-conversation-cost-broken-down-by-model

/en/openapi/v3-current/narya.yaml get /v1/sessions/{sessionId}/usage
What this conversation has spent, one row per model it was billed under. The session resource already reports the same money as two scalars — `usage.costUsd` over the whole conversation, and `cacheSpend`, which DECOMPOSES part of that same figure rather than adding to it. This is the third view of those same dollars and adds nothing to them either: a conversation that ran on three models reports one number there and says which model spent it here, and the rows sum to that number.
The model is the one a round was BILLED under, which is the model that answered and not the one that was asked for. A round this host cannot price contributes its tokens and no dollars, so its group reports costComplete false and its costUsd is a floor.
A colleague refused the transcript is refused this.



# Read whether a repository's instruction files may be loaded
Source: https://docs.lerian.studio/en/reference/platform/narya/read-whether-a-repository-s-instruction-files-may-be-loaded

/en/openapi/v3-current/narya.yaml get /v1/repository-trust
Reports the one answer stored for repo: whether its own instruction files (AGENTS.md, or CLAUDE.md when there is no AGENTS.md, plus docs/PROJECT_RULES.md) may enter the system prompt, together with which of those files the repository actually carries right now. `unknown` means nobody has been asked — an interactive client asks once and records the answer here; a non-interactive run loads nothing and says so. Both `unknown` and `refused` keep every repository-supplied file out of the prompt: a repository somebody cloned does not get to write into the model's instructions unasked. The answer is stored per canonical repository path and by that path alone — a worktree, or a subdirectory opened as its own session, answers for itself.



# Record a repository's instruction-file answer
Source: https://docs.lerian.studio/en/reference/platform/narya/record-a-repository-s-instruction-file-answer

/en/openapi/v3-current/narya.yaml put /v1/repository-trust
Stores the answer a person gave for repo, replacing any earlier one. Only a real answer may be written: `unknown` is the absence of an answer, and recording it would be a claim nobody made. Trusting takes effect on the next turn — instruction files are read as each turn is built, so nothing needs restarting. A `trusted` answer is REFUSED, and nothing is stored, when the repository's own `.narya/config.toml` will not load, declares a rule that would grant what this machine's owner denied, or names an instruction file the repository does not carry: 422, with the path in the message. Those are the refusals opening a session in that directory already makes, made here because this answer is what arms the file — and because a stored answer can only be replaced, never withdrawn. A `refused` answer arms nothing.



# Record that a reader has looked at this session
Source: https://docs.lerian.studio/en/reference/platform/narya/record-that-a-reader-has-looked-at-this-session

/en/openapi/v3-current/narya.yaml put /v1/sessions/{sessionId}/viewed
Stamps the moment a reader had this session in front of them. It is the watermark "what happened while you were away" is measured from: read against the session's updatedAt, it answers whether anything has happened here since somebody looked.
The fact lives on the host rather than in the client that called this, which is the whole point of the operation. Two windows open on one session then agree about what has been seen, and a client that quits and comes back reads the same answer instead of starting from zero — the failure that closes is a background conversation which finished overnight and showed nothing the next morning.
It takes no body and is idempotent: a client acknowledges every time it brings a conversation to the front, so saying it twice is the ordinary case. The stamp is the host's own clock, never a time the caller names — a client with a skewed clock would otherwise be able to declare activity read before it happened. An archived session is accepted: a conversation somebody retired and then read must be able to stop claiming news. Nothing else about the session moves, updatedAt included — a viewing is not something the conversation did, and bumping it would mark the session unread by the act of reading it.



# Register an extension
Source: https://docs.lerian.studio/en/reference/platform/narya/register-an-extension

/en/openapi/v3-current/narya.yaml post /v1/extensions
Makes a program at an HTTPS address a principal of this home: it may then observe the event stream, transform what the agent assembles, and occupy the slots it claims. **This response carries the registration's secret**, and it is not stored anywhere a read can reach — a caller that loses it rotates rather than re-reads. Requires `extensions:manage`, which is what "the home's owner" means in the mechanism; an ordinary member is answered 403 NRY-0028.

The endpoint must be `https://` with no exception, loopback included, and the address it resolves to is judged before anything is stored: a loopback or private address is refused unless an operator wrote that range into this host's configuration, and a link-local, metadata, unspecified, multicast or NAT64-wrapped address is refused with no configuration able to admit it. A second claimant on an exclusive slot is answered 409 NRY-0006 naming the one that already holds it — **unless this host's `[extensions] prefer` configuration already names one of the two contesting registrations as that slot's winner.** That entry is the explicit tie-break, and it is the only thing that admits a second claimant here: without it, no winner may be picked implicitly, so the registration is refused. Where it is present the second registration is stored, the named registration occupies the slot, and the other one stays registered, stays enabled, keeps every other slot it claims and simply stops occupying the contested one. Revoking the occupant returns the slot to the survivor.

**A slot this write claims is stored CLAIMED AND UNSERVED (a `model-supplier` given `models` in this body serves them already), and this write reaches the endpoint NOT AT ALL.** A discovery call made here would be signed under the secret this response has not handed over yet. Register in ONE write, take the secret from this response, configure the far side with it, and send `refreshModels: true`. On an enabled row — which is what this write leaves behind unless it asked for otherwise — that update reads `/models` under a secret both sides hold by then, and is the same road that re-reads the list afterwards.

**Until that read the slot is claimed and offers no model.** It is in `slots`, `models` is ABSENT — the property is omitted from the response rather than served as an empty array — and no picker, no turn and no spend ceiling can select anything from it: the catalogue skips a claimed-and-unserved row exactly as it skips a disabled one, so nothing half-registered is selectable. What this write still decides is everything this home can decide alone — the arity above, and a 409 for a supplier whose models would answer under a provider name this host's catalogue already carries. Stating `models` on this write is the one way to register a supplier already serving, because those are on the row rather than at the far side.

**A `tool-server` slot is stored the same way, for the same reason.** The `/tools` listing a tool name is judged against would be signed under that same unhanded secret, so it is not read here either. The listing is read on the first write that follows under a secret both sides hold — a change whose resulting row is enabled and that moves the `endpoint` or claims the slot — and on the tool sweep's own clock regardless. Until a list is read this home serves none of that registration's tools, and a name it would contest is refused on the write that reads it rather than on this one.

An operator install rides this same operation under the plane's operator credential rather than a token carrying `extensions:manage`. A home holding no operator credential — every BYOC and every local deployment — cannot authenticate such a caller at all.



# Remove a package
Source: https://docs.lerian.studio/en/reference/platform/narya/remove-a-package

/en/openapi/v3-current/narya.yaml delete /v1/packages/{name}
Removes an installed package. Removing a code-carrying package triggers a rebuild, so the response is 202 with a job; resource-only removals complete immediately with the job already done. A failed rebuild leaves the previous binary — including the package — in place.



# Report consumption over a period
Source: https://docs.lerian.studio/en/reference/platform/narya/report-consumption-over-a-period

/en/openapi/v3-current/narya.yaml get /v1/records/usage
Token and cost consumption between two instants, over the whole home, grouped by the dimension you ask for. Every member of the organisation reads the same total, including the rounds of conversations their owners marked private: what the organisation spends on its own tools is not the content of a conversation, so no clause narrows these rows the way the search and file reads on this tag are narrowed. The parts add up to the whole.
Marking a conversation private hides its words, not its money. Its rounds are in this report, under their owner's line, for every member. A person choosing that mark is entitled to know exactly what it does and does not cover.
A person is named by the opaque subject the identity provider issued, never an email address and never a display name.
Grouping by repository is the one dimension whose key could be content: a repository name belongs to the conversation that ran in it. So every conversation the caller may not read lands in ONE group keyed `private`, which is a real line with real money in it and no name. Nothing is dropped, so the parts still sum to the whole. Ids are not content, so the conversation and person dimensions carry their real keys.
It reports the usage rows this home still holds. Those rows ride their conversation, so purging a conversation takes its cost out of every total computed afterwards. Warming charges and schedule-fire amounts are separate ledgers and are not in this figure.
PAGING IS OPT-IN ON THIS OPERATION, which is the one place the shared `limit` parameter's own default of 25 does not apply. Send neither `cursor` nor `limit` and the answer carries every group and no `nextCursor` — the whole period, as this report has always answered. Name either one and paging applies, with 25 as the default size. The exception exists because a total silently cut at a page is a bill that reads as complete and is not.



# Resume a workflow run
Source: https://docs.lerian.studio/en/reference/platform/narya/resume-a-workflow-run

/en/openapi/v3-current/narya.yaml post /v1/workflows/runs/{runId}/resume
Resumes a run that failed or was stopped, carrying on from the step it died on. The script is re-executed from the top — a program has no continuation to restore across a process death — but every step the run already settled answers from the record instead of running again, so a run that died at step 14 of 21 pays only for the steps that are left and writes the same step structure an uninterrupted run would have written. Completed and failed steps both answer from the record; a step that was merely interrupted holds no settled answer and runs. The source re-executed is the source stored when the run started, never a file on disk, so editing the script between attempts cannot change the structure. Only failed and stopped runs are resumable: resuming a pending, running or completed run is a conflict.



# Revoke a registered extension
Source: https://docs.lerian.studio/en/reference/platform/narya/revoke-a-registered-extension

/en/openapi/v3-current/narya.yaml delete /v1/extensions/{publisher}/{name}
Takes the registration away with everything on it, including the models a picker was offering. Requires `extensions:manage`. It takes effect on the next transformation rather than at the next restart, so an owner can stop a misbehaving extension while a turn is waiting on it. The audit rows stay: a registry that cannot say who installed what is a registry nobody can be accountable for.

**A row Lerian installed cannot be revoked here.** The owner's power over it is the standing veto — `enabled: false` through the update operation.



# Revoke every share of this session, deleting what was copied
Source: https://docs.lerian.studio/en/reference/platform/narya/revoke-every-share-of-this-session-deleting-what-was-copied

/en/openapi/v3-current/narya.yaml delete /v1/sessions/{sessionId}/share
Stops sharing this session and DELETES what was copied to the organisation's home. Not a flag that hides it there, and not a client that stops drawing it: the copied entries are removed from the organisation's store.
IT ANSWERS AFTER THE DELETION HAS HAPPENED, not after accepting a request to perform one. A revocation that is queued is a revocation that has not occurred yet, and the person asking for one is usually in a hurry. So 204 means the data is gone; 503 NRY-0029 means the organisation's home did not answer, this machine has stopped sending anything more for the share, and the copy is still there until the request is repeated.
THE SHARE RECORD SURVIVES AS A TOMBSTONE, and only the record: it carries the disclosure history, which is the one thing that has to outlive the data it describes. It also makes the revocation win against work queued before it — entries offered for a tombstoned share are refused 410 NRY-0031 forever, so a developer who was offline for a week cannot replay a conversation into a share somebody revoked on Tuesday.
EVERY SHARE OF THE SESSION STOPS. Publishing twice creates two shares, and a person revoking a conversation means the conversation.
RE-SHARING AFTERWARDS IS A NEW SHARE ID. A revoked id is never reused, because an id that came back to life would make the audit ambiguous about which disclosure it is recording.
Revoking twice is not an error, and neither is revoking a session nobody published: the state asked for is the state it is in. The instant recorded stays that of the first revocation.



# Rotate a registered extension's secret
Source: https://docs.lerian.studio/en/reference/platform/narya/rotate-a-registered-extension-s-secret

/en/openapi/v3-current/narya.yaml post /v1/extensions/{publisher}/{name}/secret
Mints a new secret and returns it once. The response names when the old one stops being accepted. Requires `extensions:manage`.

**A row Lerian installed cannot be rotated here**, for the reason it cannot be revoked: the secret is what Lerian authenticates with, and the owner's power over such a row is the standing veto.



# Save the repository's composer draft
Source: https://docs.lerian.studio/en/reference/platform/narya/save-the-repository-s-composer-draft

/en/openapi/v3-current/narya.yaml put /v1/drafts
Upserts the live draft text for repo's composer. Called debounced on every edit; the client also calls this with an empty string on submit, so nothing is left behind for a message that was actually sent. The same repository open in two windows shares this one row — the later save always wins, and neither window's draft is migrated or erased by the other opening. A clearing write names the content it expects to be clearing via ifMatchesSha256, so a submit in one window can never erase text another window typed into the same repository.



# Say what a source is, and whether installing it needs trust
Source: https://docs.lerian.studio/en/reference/platform/narya/say-what-a-source-is-and-whether-installing-it-needs-trust

/en/openapi/v3-current/narya.yaml get /v1/packages/classification
Reads a source off the host's disk — a directory, a single .go file or a Go module reference — and reports what kind of package it is and whether installing it needs an acknowledgement. Nothing is installed, nothing is written, and a module reference is NOT downloaded: nothing may fetch a package's code in order to decide whether to ask permission to fetch its code, so a reference is reported as unread rather than described.
It exists because the decision belongs to the host and the QUESTION belongs to a surface. A client has to know whether to ask before it can ask. installPackage still enforces the same rule server-side regardless of what any caller did with this answer.
A local path must be sent ABSOLUTE. A relative one resolves against the HOST's working directory, which is not the caller's, and the artifact the answer describes would not be the one the caller meant.



# Say what one fire of this schedule may spend
Source: https://docs.lerian.studio/en/reference/platform/narya/say-what-one-fire-of-this-schedule-may-spend

/en/openapi/v3-current/narya.yaml put /v1/schedules/{scheduleId}/budget
Records the dollars ONE fire of this schedule may spend. It is a hard stop rather than a price: the turn that fire opens carries this number, and it ends on the first supplier round that reaches it, keeping whatever text arrived and running none of the tool calls that round was still asking for. The honest limit is one supplier round of overshoot, because a round's price is known only once it has ended, and it bounds only what narya itself meters — a tool that reaches a paid service of its own bills somewhere this host never looks.
Zero is zero and never "unlimited": a schedule with nothing to spend does not fire, and records that on its own row rather than going quiet. The number takes effect on the NEXT fire; one already running keeps the ceiling it started under.
A second ceiling bounds what one owner's whole UTC day may be charged across every schedule they have. That one is operator configuration rather than part of any schedule, and either being reached stops the fire instead of warning about it.
Setting what a schedule already holds is not an error.



# Say whether this session pays to stay warm, and how much
Source: https://docs.lerian.studio/en/reference/platform/narya/say-whether-this-session-pays-to-stay-warm-and-how-much

/en/openapi/v3-current/narya.yaml put /v1/sessions/{sessionId}/warming
Records whether this session keeps its provider cache alive while nobody is using it, and the lifetime dollars it may spend doing so. Warming is off on every session until this is called: nothing enables it globally, and a daemon restart never enables, disables or changes what a session is allowed to spend.
A warmed session is sent a minimal request on a schedule so that the stable part of its prompt — the tool definitions and the system prompt — stays cached across an idle gap far longer than the five minutes a provider holds it for free. Nothing is appended to the conversation: the request carries one inert line, the answer is capped at a single token, and neither is stored. Resuming a warmed session therefore pays cache-read rates for its prefix rather than full input rates.
Two ceilings bound the spending and both STOP it rather than warn: the one named here, which is this session's lifetime allowance, and the store owner's allowance for the UTC day, which is operator configuration. Warming does not run at all until an operator has written the daily one — there is no number narya can pick about a bill it does not pay.
Setting what a session already holds is not an error.



# Search the sessions you can read
Source: https://docs.lerian.studio/en/reference/platform/narya/search-all-past-sessions

/en/openapi/v3-current/narya.yaml get /v1/records/search
Full-text search over three session kinds: the caller's own, the ones marked for the organisation, and — when the caller holds the read-private permission — every session this host has. A share adds none: a colleague named on a share of a private session may read that session's record and only the entries the share has delivered, up to its bound, while a hit here is an un-redacted excerpt from any matching entry and cannot honour that bound, so the session is left out. Results carry the session, an entry excerpt with the match, and its timestamp. A session outside the three kinds is absent rather than refused — it is not counted, and the page cursor does not step over it.



# Send a message to a session's inbox
Source: https://docs.lerian.studio/en/reference/platform/narya/send-a-message-to-a-session-s-inbox

/en/openapi/v3-current/narya.yaml post /v1/sessions/{sessionId}/inbox
Delivers a message from one session to another on the same machine. Delivery is guaranteed: a message to a busy session is queued and delivered when it becomes free, never lost, and delivery survives the recipient restarting. kind message is fire-and-forget with a delivery receipt; kind ask returns an askId whose answer is polled at GET /v1/asks/{askId} and also arrives on the event stream as an intercom-message event; kind answer resolves an earlier ask (askId required) and is posted to the ASKING session's inbox, which is the session that reads it. An ask carries a deadline it is refused at rather than waiting forever — the answerer is a program, and a blocking question between two programs with no deadline is a deadlock rather than somebody taking their time. An ask that would close a loop of sessions waiting on each other is refused at send (NRY-0025), naming both parties.



# Set aside this lane's old tool output
Source: https://docs.lerian.studio/en/reference/platform/narya/set-aside-this-lane-s-old-tool-output

/en/openapi/v3-current/narya.yaml post /v1/sessions/{sessionId}/lanes/{laneId}/prune
Takes the model-facing text of old tool results out of this lane's window — a file read from forty rounds ago that is re-sent verbatim on every round since. It sends no model round, so it costs nothing, and it summarises nothing away: the conversation keeps every word, the transcript keeps every result, and only what the model re-reads shrinks.
The cheap gesture of the pair, and the one to reach for first. What is set aside stays out of the window durably, so this is a decision rather than a hint the next round recomputes.
The newest results are never taken — an agent that loses the result it is about to act on has lost the plot — and neither is anything small enough that the trade is not worth a permanent hole in what the model remembers.
How many results were set aside travels on the `context-pruned` event, not in this response: a second client watching the same lane must learn the same fact through the same channel, whether the prune came from here or from the host's own threshold.
Answers 409 when a turn is running on the lane, and 409 when nothing in the window is eligible.



# Settle who a published share is for
Source: https://docs.lerian.studio/en/reference/platform/narya/settle-who-a-published-share-is-for

/en/openapi/v3-current/narya.yaml put /v1/shares/{shareId}/recipients
Changes who may read a conversation that has already been published, without republishing it. The share keeps its id, its expiry and its position: this is the audience and nothing else.
A REPLACEMENT, which is what makes adding and removing ONE act. The list sent is the list the share names afterwards, so a colleague added and a colleague dropped happen in one request and the two can never disagree about who is on it. Absent or empty hands the share back to the whole organisation, which is the ordinary publish.
WHOEVER ENTERS RECEIVES THE WHOLE CONVERSATION, from its first entry: the organisation's home holds the copy as it has been delivered, so a colleague added today opens everything sent before today. WHOEVER LEAVES LOSES IT AT ONCE — the next read answers 404 exactly as it answers a share id nobody minted, and the live view stops being written to them, because both ask the audience of the share as it stands rather than as it stood when they connected.
WHO MAY CHANGE IT: the person who published the share, or a member carrying `members:manage`. Everybody else is answered 403 NRY-0028, the holder of `sessions:read-private` included — being able to read a conversation is not being able to decide who else may.
A REVOKED OR EXPIRED SHARE IS OVER AND IS NOT RETARGETED. Its entries have been deleted, so an audience written onto it would describe a conversation that no longer exists.
IT TRAVELS TO THE ORGANISATION'S HOME AND ANSWERS AFTER IT HAS, for the reason a revocation does: the home that decides who opens the copy is the home that holds it, so a change recorded only here is a colleague still reading a conversation they were taken off. 503 NRY-0029 means the local record is settled and this machine has told nobody. Asking again re-attempts the organisation's home and is what completes it — the same request carrying the same list is sent on again rather than recognised as already done here, because what this home holds says nothing about what the other one holds. Served AT the organisation's home — which is where the copy is — it is the local write alone, and there is nowhere further for it to go.



# Sign out of a provider
Source: https://docs.lerian.studio/en/reference/platform/narya/sign-out-of-a-provider

/en/openapi/v3-current/narya.yaml delete /v1/providers/{name}/auth
Removes the provider's stored credential from this machine's keychain. Idempotent: a provider that holds no credential answers 204 too. An environment variable naming a key is never touched — nothing this operation can do removes it — so a provider covered by one goes on reading as authenticated afterwards.



# Start a monitor
Source: https://docs.lerian.studio/en/reference/platform/narya/start-a-monitor

/en/openapi/v3-current/narya.yaml post /v1/sessions/{sessionId}/monitors
Runs command under the session's repository and streams what it says into the conversation as it happens — batched on the pauses between bursts, so one test failure is one piece of news rather than forty lines. The monitor is announced in the transcript, listed until it is stopped, and killed with the host. A name already in use in this session is refused rather than replaced.



# Start a workflow run
Source: https://docs.lerian.studio/en/reference/platform/narya/start-a-workflow-run

/en/openapi/v3-current/narya.yaml post /v1/workflows/runs
Starts a deterministic orchestration of multiple agents from a script — by path or inline source — with arguments. The script runs in the host's confined runtime: no filesystem, no network, no module loading; only the agent API the host provides. Script validation failures return 422 NRY-0010 before anything executes. Progress streams as workflow-progress events.



# Start provider sign-in
Source: https://docs.lerian.studio/en/reference/platform/narya/start-provider-sign-in

/en/openapi/v3-current/narya.yaml post /v1/providers/{name}/auth
Starts the provider's sign-in flow. For browser-based providers the response carries a URL for the client to open; completion is reported on the returned auth session status and reflected in the provider's authState. Credentials are stored so another user on the machine cannot read them. Expired credentials prompt re-authorisation via this same operation — they never silently fail.

The body chooses between the two methods. `key` carries a key the person typed and answers once the host has probed it against the provider's own API — so this call is as slow as that probe, and a rejected key is never stored. `subscription` runs the provider's OAuth flow inside the host and answers as soon as there is a URL to open, leaving the flow running; the client polls getProviderAuth for its outcome. A sign-in already in flight for this provider is never started a second time: a `subscription` request is answered with the attempt as it stands, and a `key` request is refused with 409 — its outcome would otherwise overwrite the running flow's record.

A sign-in that FAILED is a 202 whose status is `failed`, not an error response: the request was served, the sign-in was not.



# Stop a monitor
Source: https://docs.lerian.studio/en/reference/platform/narya/stop-a-monitor

/en/openapi/v3-current/narya.yaml delete /v1/sessions/{sessionId}/monitors/{name}
Ends the named watcher's whole process tree and records the stop in the transcript. Returns once the process is gone.



# Stop a workflow run
Source: https://docs.lerian.studio/en/reference/platform/narya/stop-a-workflow-run

/en/openapi/v3-current/narya.yaml post /v1/workflows/runs/{runId}/stop
Stops a run mid-flight. The response reports what completed before the stop: finished steps keep their results, running steps are marked stopped, unstarted steps are marked skipped. Stopping an already-finished run is a conflict.



# Stop waiting on a delegated lane
Source: https://docs.lerian.studio/en/reference/platform/narya/stop-waiting-on-a-delegated-lane

/en/openapi/v3-current/narya.yaml post /v1/sessions/{sessionId}/lanes/{laneId}/promote
Releases the delegation that is waiting on this lane, without stopping the work. The agent that asked for the delegate carries on immediately; the delegate keeps running and its report is delivered into the conversation when it finishes. Answers 409 when nothing is waiting on the lane — the delegation was started in the background, or it has already reported back.



# Stream events (SSE)
Source: https://docs.lerian.studio/en/reference/platform/narya/stream-events-sse

/en/openapi/v3-current/narya.yaml get /v1/events
The global event firehose as server-sent events (text/event-stream). Every client consumes this one stream; events are encoded once per update and fanned out per connection, and a slow client is dropped rather than blocking the others. Filter to one session with the sessionId query parameter. Each SSE frame's id field carries the event id; on reconnect, send it in the Last-Event-ID request header to resume from the first event after it — delivery survives client restarts. Event ids are monotonic integers. The data field of each frame is one JSON Event envelope, discriminated by its type property.
A REPLAY MAY BE SERVED IN BLOCKS. When the backlog past Last-Event-ID is long, the server writes a bounded block of frames and then ends the connection rather than materialising the whole backlog onto it. The block-end is an ordinary end of connection carrying no marker: a client resumes as it would from any drop, sending the last id it received as Last-Event-ID, and continues from exactly there. Nothing is lost and nothing is duplicated — a client that already skips ids at or below the last one it delivered needs no change at all, and a replay short enough to fit in one block is served exactly as before.
A CURSOR THIS STORE CANNOT HONOUR IS REFUSED, not served. A Last-Event-ID naming an event newer than anything the store holds gets 409 (NRY-0026) instead of an open stream: the replay past it is empty by definition and every live event is below it, so a 200 there is a connection that can never carry a frame — silent for the life of the process, with nothing timing out to say so. It is what a client holds after the store underneath it was replaced. The remedy is to resume with no Last-Event-ID, never to retry the same cursor.



# Submit a message to a lane
Source: https://docs.lerian.studio/en/reference/platform/narya/submit-a-message-to-a-lane

/en/openapi/v3-current/narya.yaml post /v1/sessions/{sessionId}/lanes/{laneId}/messages
Submits a message into a specific lane — the side conversation, or a subagent lane. Same 202 contract as the session-level message: a turn is accepted and its results stream over events, never on this response. One case answers 204 instead: a lane STOPPED on a question takes the message as the answer to that question, which unblocks the agent already running on it and opens no turn of its own.



# Submit a user message
Source: https://docs.lerian.studio/en/reference/platform/narya/submit-a-user-message

/en/openapi/v3-current/narya.yaml post /v1/sessions/{sessionId}/messages
Submits a message into the session's main lane. The response is 202 with a turn id only: results never arrive on this response — deltas, tool activity and completion stream over GET /v1/events. Steering is this same operation: a message posted while the session is running is steering by default, queued and taken into account between complete tool batches without discarding work already done; queueKind follow-up instead starts a fresh turn after turn-finished. Entry admission and its queue operation record commit atomically before anything executes.



# Summarise this conversation, on demand
Source: https://docs.lerian.studio/en/reference/platform/narya/summarise-this-conversation-on-demand

/en/openapi/v3-current/narya.yaml post /v1/sessions/{sessionId}/summary
Asks a model what this conversation set out to do, what it established, and where it stopped, and stores the answer on the session. It is what makes an abandoned branch's value survive without reading it again.
It happens ONLY when somebody asks. Nothing summarises a branch because a rewind moved away from it: an automatic summary spends tokens on a timeline the person may be about to walk straight back into, at the exact moment they are trying to get somewhere else. Until they ask, a branch is recognised by its first and last message, which getSessionTree carries for exactly that reason.
It costs tokens, on the model the session is pointed at, and the call is recorded in the session's usage like any turn. Asking twice overwrites and re-stamps: summaryAt is the answer to "was this written before the last thing that happened here", read against updatedAt.
A conversation with no answer in it yet is refused rather than sent to a model with nothing to summarise. An archived session may be summarised — that is the case this exists for.
One round at a time per session: asked again while a round is still running, this answers 409 rather than starting a second one. The two would read the same conversation and only the later answer would survive, so the duplicate is a model paid for nothing. Asking again after the first has RETURNED is allowed and overwrites, as above.



# Summarise this lane's conversation now
Source: https://docs.lerian.studio/en/reference/platform/narya/summarise-this-lane-s-conversation-now

/en/openapi/v3-current/narya.yaml post /v1/sessions/{sessionId}/lanes/{laneId}/compact
Summarises the older part of this lane's conversation on demand, instead of waiting for the host to decide the next round no longer fits. It is the same summarisation the automatic path runs, so it costs one model round and the `compaction` event it publishes carries the reason `manual`.
Lane-scoped because a window belongs to a lane: the conversation and each delegation beside it carry their own, and the host has no opinion about which of them a session-wide gesture would mean.
The paid gesture of the pair. `prune` frees old tool output for nothing and destroys no reasoning; this one throws conversation away and pays a round to do it, so a client offering both should offer pruning first.
Answers 409 when a turn is running on the lane — rebuilding the window under a round in flight would race the turn that owns it — and 409 when there is nothing left to summarise. The token figure a client is showing goes UNKNOWN rather than moving: nobody can say what the rebuilt window costs until a provider counts it, so the meter refills on the next metered round.



# Take a batch of a shared session's entries
Source: https://docs.lerian.studio/en/reference/platform/narya/take-a-batch-of-a-shared-session-s-entries

/en/openapi/v3-current/narya.yaml post /v1/shares/{shareId}/entries
The INWARD half of publishing, served by the organisation's home and called by a developer's. It takes redacted entries for one share and is the only way anything of a shared session arrives here.
IT IS THIS CONTRACT AND NOT A SECOND PROTOCOL. The organisation's home is a narya host, so a publish is an operation on the contract this product already serves, authenticated by the same bearer on the same terms as every other. A caller reaches it with the publishing person's own token: the owner recorded here is that verified actor and never a field in this body.
IDEMPOTENT PER ENTRY ID. A sending home cannot tell a delivery whose answer was lost from one that never happened, so it re-offers everything it has not seen acknowledged; an entry id this share already holds is taken as already held rather than written twice. A retry after a partial failure therefore completes rather than duplicating, and it may safely re-send the whole batch.
THE FIRST DELIVERY IS WHAT ANNOUNCES THE SHARE. There is no earlier registration and deliberately no second operation for one, which is why the body carries the session the entries came from and the mode the publish is in alongside them.
A REVOKED SHARE IS 410 NRY-0031, TERMINALLY. Its entries were deleted at somebody's request and the row survives only as a tombstone, so work queued before the revocation and offered after it is refused rather than accepted — a delivery that succeeded here would undo a deletion. The refusal is answered identically forever and a caller drops the work rather than retrying it.
The redaction happened at the home the entries came from, which is the only place a *before* exists. Nothing here can widen what was sent, and nothing here is asked to.



# Take who the copy of a share is for
Source: https://docs.lerian.studio/en/reference/platform/narya/take-who-the-copy-of-a-share-is-for

/en/openapi/v3-current/narya.yaml put /v1/shares/{shareId}/audience
The INWARD half of settling a share's audience, served by the organisation's home and called by a developer's — the twin of the entries and revoke operations beside it, and for their reason: the organisation's home is a narya host, so this is one more operation on this contract rather than a second protocol.
IT IS ITS OWN OPERATION AND NOT THE ONE A PERSON USES. A home serving this writes the list and stops, because it holds the copy and has no far end of its own to tell. One road serving both halves would make a home that is both ends of a publish have to recognise its own call, and by the time that call arrives the list is identical on both sides of it — so the only fact available to recognise it by is the one fact that says nothing.
SETTLING THE SAME LIST TWICE IS NOT AN ERROR, and it is not skipped either: a home repeating this is a home whose first attempt it cannot know the fate of, and the state asked for is the state it gets.
WHO MAY CALL IT is who may change an audience anywhere — the person who published the share, or a member carrying `members:manage` — and the call travels as the person ASKING rather than as the person who published. That is what lets a departed colleague's conversation be narrowed at all: nobody holds a credential for somebody who has left, so a call that had to travel as the author would wait for a sign-in that never comes.
A share this home holds no copy of answers 404, and so does a revoked or expired one: there is no audience here for the list to apply to, which is the state the caller asked for.



# The live shares of this session, and who each one is for
Source: https://docs.lerian.studio/en/reference/platform/narya/the-live-shares-of-this-session-and-who-each-one-is-for

/en/openapi/v3-current/narya.yaml get /v1/sessions/{sessionId}/share
What this session has been published as, from the publishing end: one row per share that is still live, carrying who it is for.
IT IS THE WAY IN TO CHANGING THAT AUDIENCE. A share is retargeted by its id (`PUT /v1/shares/{shareId}/recipients`) and a person has a conversation rather than a 26-character id, so this is where a client learns which shares exist and what each one currently names. A client holds no share id of its own between runs and derives nothing.
REVOKED AND EXPIRED SHARES ARE NOT HERE. Their entries have been deleted and their audience can never change again, so a row for one would be an offer to retarget a conversation that no longer exists.
WHO MAY READ IT is narrower than who may read the session: whoever opened the session, or a member carrying `members:manage`. A colleague who may read the conversation may not read the list of the colleagues it was addressed to — that list is a statement about people rather than about the work, which is the line the disclosure audit beside it already holds and the reason a recipient's own read of a copy never reports who else was named. A caller who may not is answered 403 NRY-0028.
A SHARE THIS CALLER MAY NOT CHANGE IS NOT HERE EITHER, so no row is ever offered that `PUT /v1/shares/{shareId}/recipients` would refuse. The rows are the shares this caller may settle: their own, and every one of them for a member carrying `members:manage`. A session somebody ELSE published — which an unmarked session allows, since it is the organisation's already — therefore lists nothing for the person whose session it is, rather than a row naming the colleagues another member addressed their work to. An empty list is "nothing here for you to change" and not "this was never published".



# What publishing this session would send, and what it would hold back
Source: https://docs.lerian.studio/en/reference/platform/narya/what-publishing-this-session-would-send-and-what-it-would-hold-back

/en/openapi/v3-current/narya.yaml get /v1/sessions/{sessionId}/share/preview
Exactly what would leave this machine if the session were published to the organisation's home, computed before anything leaves it. The entries carry the text as it would be sent — already redacted — and withheld names every place a rule held something back, so a person decides against the document rather than against a promise.
A MATCHED RULE REDACTS IN PLACE AND NEVER DROPS. A withheld span is replaced by a marker naming the rule that took it, and the entry keeps its id, its kind and its place in the transcript — a reader can tell a withheld line from a line nobody wrote, which a gap in the sequence cannot say.
The rules are the host's, configured under [sharing.redaction], and every one of them is on unless somebody turned it off. A client computes none of it and holds no rule of its own.



# Who has opened this shared copy, and when
Source: https://docs.lerian.studio/en/reference/platform/narya/who-has-opened-this-shared-copy-and-when

/en/openapi/v3-current/narya.yaml get /v1/shares/{shareId}/disclosures
The disclosure audit at the home where the shared copy lives, addressed by the share id its reads are addressed by.
IT IS THE SAME AUDIT the session-addressed operation serves, asked from the receiving end. A copy here has no session row to ask about, so a read of it is recorded against the share and read back by it.
THE PAGE IS THIS COPY'S ALONE and carries no access to any other, which is where it differs from the session-addressed road: who may read a copy here is decided against the share the caller named, so the page is keyed by that same share. A home holding two copies of one conversation keeps two audits, and reading one says nothing about the other.
WHO MAY READ IT IS NARROWER THAN WHO MAY READ THE CONVERSATION. Whoever published the share reads the list, and so does a member administering the organisation; everybody else is refused, the holder of sessions:read-private included, because a list of everyone who has read a conversation is a statement about people rather than about the work.
A REVOKED SHARE STILL ANSWERS, which is what the tombstone is for: revoking deletes the conversation and leaves standing the history of who had read it. No retention window reaches these rows.
Reading the audit is not itself recorded.



# Who has opened this shared session, and when
Source: https://docs.lerian.studio/en/reference/platform/narya/who-has-opened-this-shared-session-and-when

/en/openapi/v3-current/narya.yaml get /v1/sessions/{sessionId}/share/disclosures
The disclosure audit: the recorded reads of this session by somebody other than its owner, newest first. It is what answers "who read this conversation" after the fact, and it is the one part of a share that outlives the data — revoking a share deletes what was copied and leaves this history standing, because an audit that went with the conversation could not say who had already read it.
WHAT IS IN IT, AND WHAT DELIBERATELY IS NOT. A member's reads of their OWN sessions are not recorded: logging them would make this the largest thing in the store and would answer a question nobody asked. Reads of a session nobody published are not recorded either — there is no share for them to be recorded against.
The entry names what was reached in the words of the road that served it — the session itself, an entry page, one media key — so a picture fetched out of a transcript is its own line rather than being folded into the conversation it came from. Reading this audit is NOT itself recorded: this list is about who opened the conversation, and mixing reads of the list into it would answer a second question in the same column.
WHO MAY READ IT is narrower than who may read the session: its owner, or a member carrying `members:manage`. A colleague who may read the conversation may not read the list of everyone who has — that list is a statement about people rather than about the work, and the permission that governs who belongs to the organisation is the one that governs it. The private mark is deliberately not consulted here, for the reason marking one is not: somebody auditing who read a departed colleague's private session must not have to be able to read the conversation first, which is exactly the case the permission exists for. A caller who may not audit is answered 403 for every session that exists and 404 for one that does not, which is the pair every read of a session already answers.



# January 2026
Source: https://docs.lerian.studio/en/news/2026/2026-01

Documentation updates and release notes published in January 2026 for Midaz, plugins, and platform tools, grouped by required customer action.

Updates are grouped by required customer action. Product filters show only the areas that affect your integration. See [News](/en/news/news) for impact definitions.

## Action required

***

**January 21st, 2026**

### [Helm v5.x documentation update](/en/news/2026/january/helm-v5-documentation-update)

**What changed**

Helm deployment documentation now reflects Midaz Helm Chart v5.x, including the unified Ledger service, integrated CRM, dependency changes, and migration guidance.

**Who is affected**

Teams deploying or upgrading Midaz with Helm.

**What you need to do**

Review the Helm v5.x migration guidance before your next Midaz deployment or upgrade.

## Review recommended

***

**January 30th, 2026**

### [Introducing Tracer](/en/news/2026/january/tracer-documentation)

**What changed**

Tracer documentation is now available for real-time transaction validation, rules, spending limits, and audit trails.

**Who is affected**

Teams evaluating or integrating transaction validation and spending controls.

**What you need to do**

Review the Tracer overview and getting started guides before planning a Tracer integration.

**January 16th, 2026**

### [Introducing Lerian Console](/en/news/2026/january/lerian-console-launch)

**What changed**

Lerian Console is now documented as the unified platform replacing the standalone Midaz Console for new product UI workflows.

**Who is affected**

Teams using the standalone Midaz Console or planning web-based operations across Lerian products.

**What you need to do**

Review Lerian Console documentation before planning new Console workflows.

## No action

***

**January 19th, 2026**

### [2026 release schedule published](/en/news/2026/january/release-schedule-2026)

**What changed**

The 2026 release schedule was published with planned release cycles and stages.

**Who is affected**

Teams planning work around Lerian release cycles.

**What you need to do**

No integration change is required. Use the schedule for planning.

## Product index

***

| Product area | January updates |
| - | - |
| **Console** | Lerian Console introduced as the unified UI platform. |
| **Midaz** | Helm v5.x documentation updated for Midaz deployments. |
| **Platform** | 2026 release schedule published. |
| **Tracer** | Tracer documentation introduced. |


# February 2026
Source: https://docs.lerian.studio/en/news/2026/2026-02

Documentation updates and release notes published in February 2026 for Midaz, plugins, and platform tools, grouped by required customer action.

Updates are grouped by required customer action. Product filters show only the areas that affect your integration. See [News](/en/news/news) for impact definitions.

## Action required

***

**February 20th, 2026**

### [Midaz v2 documentation removed](/en/news/2026/february/midaz-v2-documentation-removed)

**What changed**

Midaz v2.x documentation was removed from the public documentation portal.

**Who is affected**

Teams still using Midaz v2 documentation or planning upgrades from Midaz v2.

**What you need to do**

Use current Midaz documentation and Helm upgrade guidance when planning a move to v3.x or later.

## Review recommended

***

**February 3rd, 2026**

### [Introducing Matcher](/en/news/2026/february/matcher-documentation)

**What changed**

Matcher documentation is now available for automated transaction reconciliation, matching rules, exception management, reporting, and audit trails.

**Who is affected**

Teams evaluating or integrating automated transaction reconciliation.

**What you need to do**

Review the Matcher overview, quick start, and API reference before planning reconciliation workflows.

## No action

***

**February 11th, 2026**

### [Documentation now available in Portuguese](/en/news/2026/february/portuguese-documentation)

**What changed**

The documentation portal is now available in Brazilian Portuguese.

**Who is affected**

Portuguese-speaking teams using Lerian documentation.

**What you need to do**

No integration change is required. Use the Portuguese documentation experience if it better fits your team.

## Product index

***

| Product area | February updates |
| - | - |
| **Documentation** | Brazilian Portuguese documentation became available. |
| **Matcher** | Matcher documentation introduced. |
| **Midaz** | Midaz v2 documentation removed from the portal. |


# March 2026
Source: https://docs.lerian.studio/en/news/2026/2026-03

Documentation updates and release notes published in March 2026 for Midaz, plugins, and platform tools, grouped by required customer action.

Updates are grouped by required customer action. Product filters show only the areas that affect your integration. See [News](/en/news/news) for impact definitions.

## Action required

***

**March 30th, 2026**

### [Midaz Cycle 6 API updates](/en/news/2026/march/midaz-cycle-6-api-updates)

**What changed**

Midaz documentation was updated for Cycle 6, including Ledger Settings, Balance History, Transaction Routing, filters, and error codes.

**Who is affected**

Teams using affected Midaz APIs or planning Cycle 6 integration changes.

**What you need to do**

Review the updated Midaz API documentation before your next related integration change.

**March 27th, 2026**

### [Pix Switch: unified Pix architecture](/en/news/2026/march/pix-switch-unified-architecture)

**What changed**

Direct Pix and Indirect Pix documentation were consolidated into the Pix Switch architecture.

**Who is affected**

Teams evaluating Pix Direct, Pix Indirect, or Pix Switch implementation paths.

**What you need to do**

Use Pix Switch as the starting point for Pix implementation planning.

## Review recommended

***

**March 27th, 2026**

### [Partners Hub improvements](/en/news/2026/march/partners-hub-improvements)

**What changed**

Partners Hub documentation was restructured and expanded with improved guides, operations references, and error documentation.

**Who is affected**

Teams using Partners Hub documentation.

**What you need to do**

Review the updated navigation and references before using Partners Hub implementation guidance.

**March 25th, 2026**

### [Pix reconciliation with Matcher](/en/news/2026/march/pix-reconciliation-matcher)

**What changed**

A complete use case guide was published for reconciling Pix transactions using Matcher.

**Who is affected**

Teams reconciling Pix transactions with Matcher.

**What you need to do**

Review the use case before configuring sources, field maps, and match rules for Pix flows.

**March 23rd, 2026**

### [Matcher module in Lerian Console](/en/news/2026/march/matcher-console-module)

**What changed**

Matcher module documentation was added for Lerian Console workflows.

**Who is affected**

Teams using Matcher through Lerian Console.

**What you need to do**

Review the Console documentation before using Matcher management, Studio configuration, or Workbench review flows.

**March 16th, 2026**

### [Idempotency guide rewritten](/en/news/2026/march/idempotency-guide-rewrite)

**What changed**

Retries and idempotency documentation was rewritten with clearer endpoint scope, key behavior, error handling, and examples.

**Who is affected**

Teams implementing retries and idempotency for transaction endpoints.

**What you need to do**

Review the clarified idempotency scope and retry behavior before changing transaction retry logic.

**March 16th, 2026**

### [TED plugin documentation expansion](/en/news/2026/march/ted-plugin-documentation-expansion)

**What changed**

TED plugin documentation was expanded with localization, product guides, glossary updates, navigation changes, and error list alignment.

**Who is affected**

Teams using TED plugin documentation.

**What you need to do**

Review the updated TED guides, glossary, error list, and localized documentation where relevant.

**March 9th, 2026**

### [CRM standalone migration guide](/en/news/2026/march/crm-migration-guide)

**What changed**

A migration guide was published for moving from standalone CRM plugin deployment to CRM embedded in Midaz.

**Who is affected**

Teams operating or planning CRM deployment changes.

**What you need to do**

Review the guide before planning CRM deployment changes.

**March 4th, 2026**

### [Matcher documentation update](/en/news/2026/march/matcher-documentation-update)

**What changed**

Matcher API reference coverage was expanded and aligned more closely with the codebase.

**Who is affected**

Teams using the Matcher API reference.

**What you need to do**

Review the expanded reference before building new Matcher integrations.

## No action

***

**March 11th, 2026**

### [Use cases reorganized](/en/news/2026/march/midaz-use-cases-reorganization)

**What changed**

Midaz Core use cases were separated from plugin-specific use cases.

**Who is affected**

Teams browsing Midaz and plugin use case documentation.

**What you need to do**

No migration is required. Use the new locations when looking for examples.

**March 5th, 2026**

### [Deployment models: SaaS and BYOC](/en/news/2026/march/deployment-models)

**What changed**

A Deployment Models page was added for SaaS and BYOC.

**Who is affected**

Teams choosing between SaaS and BYOC deployment models.

**What you need to do**

No migration is required. Use the page when comparing deployment options.

## Product index

***

| Product area | March updates |
| - | - |
| **CRM** | Standalone CRM migration guide published. |
| **Matcher** | Pix reconciliation use case, Console module docs, and API reference updates. |
| **Midaz** | Cycle 6 API updates, idempotency rewrite, and use case reorganization. |
| **Pix** | Pix Switch unified architecture published. |
| **Platform** | Partners Hub improvements and deployment model documentation. |
| **TED** | TED plugin documentation expansion. |


# April 2026
Source: https://docs.lerian.studio/en/news/2026/2026-04

Documentation updates and release notes published in April 2026 for Midaz, plugins, and platform tools, grouped by required customer action.

Updates are grouped by required customer action. Product filters show only the areas that affect your integration. See [News](/en/news/news) for impact definitions.

## Action required

***

**April 30th, 2026**

### [Balance Overdraft documentation](/en/news/2026/april/balance-overdraft-documentation)

**What changed**

Balance Overdraft documentation was added for Midaz, including configuration, settlement behavior, operational guidance, and error codes.

**Who is affected**

Teams configuring or reviewing overdraft behavior in Midaz.

**What you need to do**

Review the guide before enabling or changing overdraft behavior.

## Review recommended

***

**April 30th, 2026**

### [APIX 001 and APIX 002 templates in Reporter](/en/news/2026/april/reporter-apix-templates)

**What changed**

Reporter documentation now covers BACEN APIX 001 and APIX 002 templates.

**Who is affected**

Teams using Reporter for BACEN APIX regulatory templates.

**What you need to do**

Review the APIX template documentation before configuring Reporter submissions.

**April 28th, 2026**

### [Matcher documentation refresh](/en/news/2026/april/matcher-documentation-refresh)

**What changed**

Matcher documentation was refreshed across guides, API reference, and Console integration.

**Who is affected**

Teams using Matcher guides, API reference, or Console documentation.

**What you need to do**

Review the refreshed documentation before planning new Matcher implementation work.

**April 23rd, 2026**

### [Flowker module documentation](/en/news/2026/april/flowker-console-module)

**What changed**

Flowker module documentation in Lerian Console is now available.

**Who is affected**

Teams using Flowker through Lerian Console.

**What you need to do**

Review the Flowker Console module documentation before using workflow design, provider management, or execution monitoring.

**April 22nd, 2026**

### [Flowker documentation](/en/news/2026/april/flowker-documentation)

**What changed**

Flowker documentation now includes guides, API reference, and product behavior coverage.

**Who is affected**

Teams using Flowker guides or API reference.

**What you need to do**

Review the Flowker documentation before building or updating workflow orchestration integrations.

**April 16th, 2026**

### [Ledger settings via Console](/en/news/2026/april/ledger-settings-console)

**What changed**

Ledger Settings can now be configured directly through Console.

**Who is affected**

Teams configuring Ledger Settings in Midaz.

**What you need to do**

Review the Console-based Ledger Settings flow before changing account type or transaction route validation configuration.

**April 14th, 2026**

### [Billing in Fees Engine](/en/news/2026/april/fees-engine-billing)

**What changed**

Fees Engine documentation now covers Billing Packages and Billing Calculation.

**Who is affected**

Teams using Fees Engine billing packages or billing calculation.

**What you need to do**

Review the billing documentation before configuring recurring billing models.

**April 13th, 2026**

### [Reporter via Lerian Console](/en/news/2026/april/reporter-console-module)

**What changed**

Reporter module documentation in Lerian Console was expanded and aligned with current product behavior.

**Who is affected**

Teams using Reporter through Lerian Console.

**What you need to do**

Review the Reporter Console documentation before using Data Sources, Template Builder, dashboard, or report generation workflows.

**April 10th, 2026**

### [Helm documentation improvement](/en/news/2026/april/helm-platform-documentation)

**What changed**

Helm documentation moved to the Platform tab and was reorganized into product-specific references.

**Who is affected**

Teams using Helm deployment documentation.

**What you need to do**

Use the product-organized Helm documentation when planning installation, upgrade, migration, troubleshooting, or production configuration.

## No action

***

No April updates are classified as no action.

## Product index

***

| Product area | April updates |
| - | - |
| **Flowker** | Flowker docs and Console module documentation. |
| **Matcher** | Matcher documentation refresh. |
| **Midaz** | Balance Overdraft and Ledger Settings via Console. |
| **Platform** | Helm documentation moved and reorganized. |
| **Plugin Fees** | Billing Packages and Billing Calculation documentation. |
| **Reporter** | APIX templates and Reporter Console module documentation. |


# May 2026
Source: https://docs.lerian.studio/en/news/2026/2026-05

Documentation updates and release notes published in May 2026 for Midaz, plugins, and platform tools, grouped by required customer action and product area.

Updates are grouped by required customer action. Product filters show only the areas that affect your integration. See [News](/en/news/news) for impact definitions.

## Action required

***

**May 6th, 2026**

### [TED: documentation aligned with v2.4.0](/en/news/2026/may/ted-v240-docs)

**What changed**

The public TED documentation now reflects version `2.4.0`, including transfer fields, webhooks, configuration, and error references.

**Who is affected**

Teams integrating with the TED plugin, especially teams creating transfer requests.

**What you need to do**

Review `InitiateTransferRequest` and make sure transfer creation payloads include the required `purpose` field.

## Review recommended

***

**May 8th, 2026**

### [Matcher: API reference aligned with v2.1.1](/en/news/2026/may/matcher-api-reference-v211)

**What changed**

The public Matcher API reference now reflects the released `v2.1.1` binary and Go DTOs, including fee-rule routes, schema names, fields, and error references.

**Who is affected**

Teams using Matcher API documentation to implement or review integrations.

**What you need to do**

Review the updated documentation before your next Matcher integration change. No product behavior changed in this documentation update.

**May 5th, 2026**

### [Flowker: v1 endpoints registered in the public reference](/en/news/2026/may/flowker-api-reference-cleanup)

**What changed**

Seven existing v1 endpoints are now visible in the documentation portal.

**Who is affected**

Teams using Flowker documentation for API discovery or AI-assisted documentation search.

**What you need to do**

Review the newly visible v1 endpoints if you use Flowker.

**May 4th, 2026**

### [Access Manager: MFA and Provider documentation update](/en/news/2026/may/access-manager-api-reference-audit)

**What changed**

The public Access Manager API reference now includes missing MFA, Provider, and application-provider pages.

**Who is affected**

Teams using Access Manager MFA, provider configuration, or application-provider links.

**What you need to do**

Review the new Access Manager pages if those capabilities are part of your roadmap. Existing integrations do not need a migration from this documentation update alone.

**May 4th, 2026**

### [Midaz: ledger list filters documented](/en/news/2026/may/midaz-ledger-reference-filters)

**What changed**

The public Midaz Ledger API reference now shows previously missing filters for accounts, organizations, and account types.

**Who is affected**

Teams querying Midaz accounts, organizations, or account types.

**What you need to do**

Review the updated list filters if your integration uses those endpoints. Existing integrations do not need a migration from this documentation update alone.

**May 4th, 2026**

### [CRM: identity reference context updated](/en/news/2026/may/crm-identity-reference-context)

**What changed**

CRM-related identity documentation context was updated as part of the May API reference audit.

**Who is affected**

Teams reading CRM documentation alongside identity-related API reference pages.

**What you need to do**

Review CRM together with the updated identity reference pages if your implementation depends on both areas. No CRM runtime behavior changed.

## No action

***

**May 26th, 2026**

### [Reporter Console: operational guides and field references](/en/news/2026/may/reporter-console-operational-guides)

**What changed**

Reporter Console documentation now has clearer operational guides, field references, Data Source journey guidance, API reference links, and aligned EN/ES/PT structure.

**Who is affected**

Operators, administrators, implementation teams, and integrators using Reporter through Lerian Console.

**What you need to do**

No migration is required. Review the updated Reporter Console documentation before onboarding operators or reviewing Reporter workflows.

**May 22nd, 2026**

### [Lerian Console: Midaz Module documentation clarity](/en/news/2026/may/console-midaz-module-docs-clarity)

**What changed**

The Lerian Console documentation now has clearer Midaz Module navigation, an explicit setup path, sharper plugin and Fees Engine guidance, and aligned EN/ES/PT structure.

**Who is affected**

Operators, administrators, implementation teams, and developers using Lerian Console to operate Midaz.

**What you need to do**

No migration is required. Review the updated Lerian Console documentation if you operate or onboard operators to the Midaz Module.

**May 19th, 2026**

### [Midaz: account statement guide](/en/news/2026/may/midaz-account-statement-guide)

**What changed**

A new Midaz guide explains how to transform account operations into customer-facing account statements.

**Who is affected**

Teams building statement experiences with Midaz account operations.

**What you need to do**

No migration is required. Use the new guide when designing, implementing, or reviewing account statement views.

**May 14th, 2026**

### [Tracer: spending limit documentation update](/en/news/2026/may/tracer-spending-limit-docs)

**What changed**

The public Tracer documentation now explains the full spending limit model, including periods, scheduling fields, amount format, and validation timing.

**Who is affected**

Teams reading Tracer documentation to understand spending limit configuration or validation behavior.

**What you need to do**

No migration is required. Use the updated documentation when configuring or reviewing Tracer limits.

**May 14th, 2026**

### [Matcher: source documentation field correction](/en/news/2026/may/matcher-source-documentation-fields)

**What changed**

The public Matcher documentation now shows source payloads without `feeScheduleId`.

**Who is affected**

Teams reading Matcher documentation to configure reconciliation sources.

**What you need to do**

No migration is required if your integration already works. Use Matcher fee rules for fee behavior instead of source fields.

**May 11th, 2026**

### [Flowker: operational endpoints removed from public reference](/en/news/2026/may/flowker-operational-endpoints-removed)

**What changed**

Flowker health and version endpoints no longer appear in the public API reference.

**Who is affected**

Teams reading the public Flowker API reference.

**What you need to do**

No product behavior changed. Keep operational monitoring tied to internal runbooks or deployment documentation.

**May 11th, 2026**

### [Matcher: operational endpoints removed from public reference](/en/news/2026/may/matcher-operational-endpoints-removed)

**What changed**

Matcher health, version, and readiness endpoints no longer appear in the public API reference.

**Who is affected**

Teams reading the public Matcher API reference.

**What you need to do**

No product behavior changed. Keep operational monitoring tied to internal runbooks or deployment documentation.

**May 11th, 2026**

### [Tracer: operational endpoints removed from public reference](/en/news/2026/may/tracer-operational-endpoints-removed)

**What changed**

Tracer health, version, and readiness endpoints no longer appear in the public API reference.

**Who is affected**

Teams reading the public Tracer API reference.

**What you need to do**

No product behavior changed. Keep operational monitoring tied to internal runbooks or deployment documentation.

**May 11th, 2026**

### [TED: operational endpoints removed from public reference](/en/news/2026/may/ted-operational-endpoints-removed)

**What changed**

TED liveness and readiness endpoints no longer appear in the public API reference.

**Who is affected**

Teams reading the public TED API reference.

**What you need to do**

No product behavior changed. Keep operational monitoring tied to internal runbooks or deployment documentation.

## Product index

***

| Product area | May updates |
| - | - |
| **Access Manager** | MFA, Providers, Application-Provider links, and Auth MFA login-flow documentation were expanded. |
| **Console** | Lerian Console documentation clarified for the Midaz Module, including setup path, plugin settings, Fees Engine package creation, and EN/ES/PT navigation parity. |
| **CRM** | CRM-related identity documentation context updated. |
| **Flowker** | v1 endpoint registration and operational endpoints removed from the public reference. |
| **Matcher** | API reference alignment with released `v2.1.1` behavior, source field correction, and operational endpoints removed from the public reference. |
| **Midaz** | Missing query parameters documented on ledger list endpoints and a new account statement guide published. |
| **Reporter** | Reporter Console documentation updated with operational guides, field references, Data Source journey guidance, API reference links, and EN/ES/PT language parity. |
| **TED** | Plugin documentation aligned with `2.4.0` and operational endpoints removed from the public reference. |
| **Tracer** | Full spending limit model added and operational endpoints removed from the public reference. |


# June 2026
Source: https://docs.lerian.studio/en/news/2026/2026-06

Documentation updates and release notes published in June 2026 for Midaz, plugins, and platform tools, grouped by required customer action.

Updates are grouped by required customer action. Product filters show only the areas that affect your integration. See [News](/en/news/news) for impact definitions.

## Review recommended

***

**June 26th, 2026**

### [Pix Indirect (BTG): documentation now public](/en/news/2026/june/pix-indirect-docs-public)

**What changed**

The complete Pix Indirect (BTG) documentation set and the full Indirect Pix API reference are now available. The set covers the overview, DICT operations, transfers, QR codes, collections, refunds, MED 2.0 funds recovery, intra-PSP transfers, webhooks, and integration.

**Who is affected**

Teams evaluating or building Pix Indirect (BTG) on Midaz: institutions that connect to BACEN's Pix infrastructure as indirect participants through BTG Pactual's BaaS offering. Anyone integrating Pix transfers, DICT, QR codes, collections, refunds, or dispute flows is also affected.

**What you need to do**

No migration is required. No product behavior, endpoint, or API contract changed. This is a documentation availability change only. Start with the overview to understand the indirect-participant model, then reference the individual guides and API reference as needed.

**June 12th, 2026**

### [Accounting: Accounting Routes terminology, Overdraft scenario, and navigation update](/en/news/2026/june/accounting-console-routes-overdraft-navigation)

**What changed**

The Accounting module documentation now uses **Accounting Routes** as the standard term (replacing "Transaction Routing/Routes"), adds a dedicated **Overdraft** scenario, and reorganizes the module navigation, in EN, ES, and PT.

**Who is affected**

Anyone reading the Accounting module documentation in the Console, including teams configuring routing rules between accounts and reviewing accounting scenarios.

**What you need to do**

This update is documentation-only, and no runtime behavior changed. Update internal references from "Transaction Routing/Routes" to "Accounting Routes", review the new Overdraft scenario, and re-check bookmarks against the reorganized navigation.

**June 5th, 2026**

### [BR Bank Transfer: webhook API reference and signature documentation update](/en/news/2026/june/br-bank-transfer-webhook-api-docs)

**What changed**

The API reference now documents the webhook self-service API (register, rotate signing secret, list event types), and corrects the webhook signature format and the event names.

**Who is affected**

Teams integrating BR Bank Transfer webhooks, and anyone using the BR Bank Transfer API reference.

**What you need to do**

This update is documentation-only, and no runtime behavior changed. If you validate webhook signatures or subscribe to event names, review them against the corrected documentation: the signature is now `v1,sha256=` computed over `v1:` + timestamp + body, and non-existent event names (`transfer.failed`, `transfer.cancelled`) were removed.

## No action

***

**June 19th, 2026**

### [Fundamentals: Accounting series](/en/news/2026/june/fundamentals-accounting-series)

**What changed**

The **Fundamentals** tab adds an **Accounting** series covering accounting end to end: what accounting is and why it matters, assets/liabilities/equity, debits and credits, double-entry bookkeeping, chart of accounts, financial statements, journal entries, revenue and expenses, accrual vs. cash accounting, the accounting cycle, and Accounting in Lerian (bridge to Midaz). The two series are cross-linked, Mermaid diagrams were added, and duplicated content was removed.

**Who is affected**

Anyone wanting to understand the accounting principles behind a ledger: engineers, finance and product teams, and implementation partners working with Midaz.

**What you need to do**

No migration is required. Read the Accounting series for accounting fundamentals, and finish with Accounting in Lerian to connect the concepts to Midaz.

**June 10th, 2026**

### [Fundamentals: Core Banking series](/en/news/2026/june/fundamentals-core-banking-series)

**What changed**

A new **Fundamentals** tab introduces the **Core Banking** series, a progressive path from concepts to a practical ledger plan: what core banking is, double-entry, building blocks (ledgers, accounts, portfolios, assets), how money moves, holders/accounts/aliases, external accounts and reconciliation, routes and fees, designing your ledger plan, and where to go next.

**Who is affected**

Anyone learning how Lerian's ledger works from first principles: engineers, product teams, and implementation partners onboarding to Midaz.

**What you need to do**

No migration is required. Read the series as foundational, conceptual material before reading product-specific documentation.

**June 5th, 2026**

### [BR Bank Transfer: operator guides in Lerian Console](/en/news/2026/june/br-bank-transfer-console-guides)

**What changed**

The BR Bank Transfer plugin now has operator documentation in Lerian Console, covering the dashboard, transfers, reconciliation, and the six settings sections, available in EN, ES, and PT.

**Who is affected**

Operators, administrators, and implementation teams using the BR Bank Transfer plugin through Lerian Console.

**What you need to do**

No migration is required. Review the new BR Bank Transfer Console documentation when onboarding operators or configuring the JD SPB integration.

**June 1st, 2026**

### [Documentation update: product source availability](/en/news/2026/june/documentation-product-source-availability)

**What changed**

The documentation now describes source availability per product. Midaz and Fetcher remain source-available; other Lerian products are available to licensed customers, with repositories maintained internally.

**Who is affected**

Customers and teams reading Lerian documentation to understand how each product's source code is distributed.

**What you need to do**

No migration is required. No product behavior, licensing term, or access level changed. Update internal materials only if they describe the full portfolio as source-available.

## Product index

***

| Product area | June updates |
| - | - |
| **Pix Indirect** | The full Pix Indirect (BTG) documentation set is now public: overview, DICT operations, transfers, QR codes, collections, refunds, MED 2.0 funds recovery, intra-PSP transfers, webhooks, and integration guides, plus the complete Indirect Pix API reference. Previously access-restricted; no product behavior changed. |
| **Fundamentals** | A new Fundamentals tab introduces the Core Banking series (core banking, double-entry, building blocks, money movement, holders/accounts/aliases, external accounts and reconciliation, routes and fees, designing your ledger plan) and an Accounting series (accounting principles, debits and credits, double-entry, chart of accounts, financial statements, journal entries, revenue and expenses, accrual vs. cash, the accounting cycle, and Accounting in Lerian). The two series are cross-linked, with Mermaid diagrams added and duplicated content removed. |
| **Accounting** | Accounting module documentation adopts "Accounting Routes" as the standard term, adds an Overdraft scenario, and reorganizes the module navigation (concepts, setup, and a Managing Accounting Routes subgroup), in EN, ES, and PT. |
| **BR Bank Transfer** | Webhook self-service API documented in the reference; webhook signature format and event names corrected; API reference and configuration aligned with the platform. New operator guides published in Lerian Console (dashboard, transfers, reconciliation, and settings) in EN, ES, and PT. |
| **General** | Documentation clarified to describe source availability per product: Midaz and Fetcher remain source-available, while other products are available to licensed customers with internally maintained repositories. |


# July 2026
Source: https://docs.lerian.studio/en/news/2026/2026-07

Documentation updates and release notes published in July 2026 for Midaz, plugins, and platform tools, grouped by required customer action.

Updates are grouped by required customer action. Product filters show only the areas that affect your integration. See [News](/en/news/news) for impact definitions.

## No action

***

**July 7th, 2026**

### [Matcher v4.3.0: AI-assisted ingestion, discovery connectors, and Console rebrand](/en/news/2026/july/matcher-v430)

**What changed**

Matcher adds AI-assisted document extraction, field-mapping proposals, and match-rule suggestions. Each has a human-in-the-loop review step before anything is applied. A new discovery-connector platform onboards sources from aggregators (Pluggy, Belvo), file formats (CNAB240, CNAB400, OFX, camt.053 preview), and SFTP. API error responses are now a consistent problem shape (`type`, `title`, `status`, `detail`). The Console adopts the new ink-blue theme with refreshed navigation and breadcrumbs. Seven customer-facing reliability fixes are included.

**Who is affected**

Teams using Matcher for reconciliation: operators uploading and mapping statements, teams building match rules, and integrations that parse Matcher API error responses.

**What you need to do**

Review the new AI extraction, mapping, and rule-suggestion flows and assign an owner to the approval step. Explore the discovery connectors if you onboard sources via aggregators or files. Confirm that any code parsing Matcher error responses handles the new problem shape. No migration is required for existing integrations.

**July 7th, 2026**

### [New reference: Receiving Midaz events through RabbitMQ or Streaming Hub](/en/news/2026/july/receiving-midaz-events-guide)

**What changed**

A new reference guide, Receiving events from Midaz, documents the two supported ways to consume the Midaz event stream. The first way is to bind your own queue directly to Midaz's RabbitMQ (AMQP 0-9-1) topic exchanges. The second way is to subscribe through Lerian's managed Streaming Hub (Webhook, Pull, SQS, RabbitMQ, or EventBridge). The guide includes a side-by-side comparison to help you choose.

**Who is affected**

Teams integrating with Midaz that react to ledger events (reconciliation, notifications, downstream projections, and analytics) instead of polling the REST API. This includes both self-hosted deployments and external / SaaS integrators.

**What you need to do**

No migration is required. No endpoints, event schemas, or delivery behavior changed. Self-hosted teams should review the RabbitMQ direct section and self-hosted environment flags; external consumers should review the Streaming Hub section and pick a delivery transport.

**July 9th, 2026**

### [New documentation structure: journey-first navigation](/en/news/2026/july/documentation-information-architecture)

**What changed**

The documentation portal moves to a journey-first information architecture. Tabs now follow how you work (Fundamentals, Guides, API Reference, Platform, and Lerian Console) rather than splitting by product first. API Reference is regrouped by product, and product guides now cross-link to their matching API reference so you can move between a concept and its endpoints in one step. Every previous URL kept working through redirects until September 10, 2026, when [page URLs moved to their navigation paths](/en/news/2026/september/page-urls-mirror-navigation) and the redirects were removed.

**Who is affected**

Anyone using the Lerian documentation portal. There are no product, API, or runtime behavior changes.

**What you need to do**

Nothing at the time. Old links redirected to their new locations until September 10, 2026; since then a saved link needs the address the navigation shows (see [Page URLs now mirror the navigation](/en/news/2026/september/page-urls-mirror-navigation)).

**July 9th, 2026**

### [Expanded API Reference: Pix Direct via JD, the Midaz ledger, and Pix Automático](/en/reference/introduction)

**What changed**

The API Reference gains substantial new coverage, all of it documentation, with no product, endpoint, or runtime behavior change:

* **Pix Direct via JD** is published for the first time, with 97 operations rendered end to end.
* The **Midaz ledger** reference is expanded with the holders and billing domains (31 additional operations).
* **Pix Automático** payer-side operations are added to the **Pix Indirect via BTG** reference.
* The former **CRM** reference is retired into the Midaz ledger section, where holders and related parties now live. Previous CRM reference links redirected automatically until September 10, 2026.
* The **Reporter**, database connections, **Access Manager**, and **Tracer** references are refreshed to match their current operations.

**Who is affected**

Anyone browsing the Lerian API Reference. In particular, teams integrating Pix via JD or BTG, teams working with Midaz holders and billing, and anyone who had bookmarked CRM reference pages. These operations were already part of the products; the reference now renders them.

**What you need to do**

Nothing. No endpoints, request or response schemas, authentication, or delivery behavior changed. These are documentation-only updates, so there is nothing to change in your integration. Old CRM reference URLs redirected to their new Midaz ledger locations until September 10, 2026; update saved bookmarks to the current addresses.

## Product index

***

| Product area | July updates |
| - | - |
| **Matcher** | v4.3.0 adds AI-assisted document extraction, mapping proposals, and match-rule suggestions (all with human-in-the-loop review), a new discovery-connector platform (Pluggy, Belvo, CNAB240/400, OFX, SFTP, camt.053 preview), standardized API error responses, an ink-blue Console rebrand with refreshed navigation, and seven reliability fixes. |
| **Midaz** | A new reference guide, Receiving events from Midaz, explains the two supported ways to consume Midaz ledger events and how to choose between them. The two ways are direct RabbitMQ (AMQP) exchange binding for self-hosted deployments and the managed Streaming Hub for external / SaaS integrators. The ledger API reference is also expanded with the holders and billing domains (31 additional operations). The former CRM reference is retired into the Midaz ledger section (holders and related parties). Old CRM links redirected automatically until September 10, 2026. |
| **Pix** | The Pix Direct via JD API reference is published for the first time (97 operations). Pix Automático payer-side operations are added to the Pix Indirect via BTG reference. These updates are documentation only. No product or endpoint behavior changed. |
| **Platform** | The documentation portal moves to a journey-first information architecture. Tabs are organized by how you work, and the API Reference is regrouped by product. Redirects kept every previous URL working until September 10, 2026. The database connections and Access Manager API references are also refreshed to match their current operations. |
| **Reporter** | The API reference is refreshed with the template-builder and deadline-notification operations. |
| **Tracer** | The API reference is refreshed with its reservation operations. |


# August 2026
Source: https://docs.lerian.studio/en/news/2026/2026-08

Documentation updates published in August 2026 for Matcher, Flowker, Pix, Lerian Console, and Platform, grouped by required customer action.

Updates are grouped by required customer action. Product filters show only the areas that affect your integration. See [News](/en/news/news) for impact definitions.

## Review recommended

***

**August 31, 2026**

### [Matcher actor-mapping permission names](/en/news/2026/august/matcher-auth-and-actor-mapping-contract)

The documentation changed how it writes the actor-mapping permission names, for example `actor-mappings-read`.

**August 31, 2026**

### [STA TLS trust configuration](/en/news/2026/august/sta-tls-trust-configuration)

STA uses system roots for BACEN TLS and does not use tenant trust-store configuration or a client certificate.

**August 31, 2026**

### [Midaz holder-account listing scope](/en/news/2026/august/midaz-holder-account-listing-scope)

Holder-account listings span the Organization unless you filter with `ledger_id`.

**August 31, 2026**

### [Flowker HTTP content-digest pin](/en/news/2026/august/flowker-http-content-digest-pin)

The generic HTTP executor can pin content with a SHA-256 digest and fails closed on a mismatch.

**August 31, 2026**

### [Platform Helm version and configuration guidance](/en/news/2026/august/platform-helm-version-and-configuration-guidance)

Helm guidance now reflects supported chart values, dependencies, components, and deployment prerequisites.

**August 31, 2026**

### [Streaming catalog contract corrections](/en/news/2026/august/streaming-catalog-contract-corrections)

Consignado, Lender, and Midaz event references now reflect their current streaming catalogs.

**August 29, 2026**

### [Streaming integration contract corrections](/en/news/2026/august/streaming-integration-contract-corrections)

Event, queue, and delivery contracts across streaming integrations are now explicit.

**August 29, 2026**

### [Helm package version and Console prerequisites](/en/news/2026/august/helm-package-version-console-prerequisites)

Lerian Helm chart packages use plain semantic versions, and Console compatibility guidance is updated.

**August 28, 2026**

### [Midaz transaction lifecycle streaming](/en/news/2026/august/midaz-transaction-lifecycle-streaming)

Midaz transaction lifecycle facts use the Kafka-compatible streaming surface, not the retired RabbitMQ event exchange.

**August 28, 2026**

### [Tracer CORS default](/en/news/2026/august/tracer-cors-default)

An unset or empty `CORS_ALLOWED_ORIGINS` allows every origin; configure an explicit allow-list in production.

**August 28, 2026**

### [Matcher callback-provided SLA dates](/en/news/2026/august/matcher-callback-provided-sla-dates)

Matcher stores SLA dates supplied by inbound callbacks; severity does not create a deadline.

**August 28, 2026**

### [Lender assignment-set discard](/en/news/2026/august/lender-assignment-set-discard)

Operators can discard an unsold assignment set while preserving its evidence and audit trail.

**August 28, 2026**

### [Access Manager Pix Lerian M2M applications](/en/news/2026/august/access-manager-pix-lerian-m2m-applications)

Access Manager now documents the Pix Lerian SPI, DICT, and COB application names for M2M setup.

**August 27, 2026**

### [Matcher event streaming contract](/en/news/2026/august/matcher-event-streaming-contract)

Matcher’s public CloudEvents, delivery policies, and manifest boundary are now documented in full.

**August 27, 2026**

### [Midaz event streaming contract](/en/news/2026/august/midaz-event-streaming-contract)

Midaz’s public Ledger-event payloads, manifest boundary, and delivery semantics are now explicit.

**August 27, 2026**

### [Reporter event streaming contract](/en/news/2026/august/reporter-event-streaming-contract)

Reporter’s 12 emitted CloudEvents now have complete delivery and payload contracts.

**August 27, 2026**

### [Tracer event producer boundary](/en/news/2026/august/tracer-event-producer-boundary)

The standalone Tracer service and the Tracer component embedded in Midaz have different event contracts.

**August 27, 2026**

### [Fetcher event routing and envelope contract](/en/news/2026/august/fetcher-event-routing-and-envelope-contract)

Fetcher event routing, DLQ keys, and legacy/current job identifiers are now documented.

**August 27, 2026**

### [Kafka topic auto-provisioning](/en/news/2026/august/kafka-topic-auto-provisioning)

Kafka-based streaming producers try to create fact and dead-letter topics by default at startup.

**August 27, 2026**

### [Midaz account-deletion balance contract](/en/news/2026/august/midaz-account-deletion-balance-contract)

Account deletion requires zero available and on-hold balance; an in-progress transaction is not an independent blocker.

**August 26, 2026**

### [Platform Helm deployment prerequisites](/en/news/2026/august/platform-helm-deployment-prerequisites)

Component-specific Kubernetes API baselines now guide Helm deployment planning.

**August 26, 2026**

### [Tracer authentication and validation-history contract](/en/news/2026/august/tracer-auth-and-validation-history-contract)

Authentication precedence and the scope of stored validation history are now explicit.

**August 26, 2026**

### [Lender streaming and portability contract](/en/news/2026/august/lender-streaming-and-portability-contract)

The streaming catalog and M011 portability-discovery prerequisites are documented.

**August 25th, 2026**

### [Matcher consent, audit, and fee contracts](/en/news/2026/august/matcher-consent-audit-and-fee-contracts)

Aggregator connections can await consent, audit checks can resume with `fromSeq`, and rate-shaped fee expressions are limited to `0..1`. Documentation correction; no runtime release is announced.

**August 25th, 2026**

### [Tracer rule identity and permission declaration](/en/news/2026/august/tracer-rule-identity-and-permission-declaration)

Rule names are case-sensitive and preserve internal whitespace. Optional identity permission declaration is fail-open. Documentation correction; no runtime release is announced.

**August 25th, 2026**

### [Platform Helm availability and prerequisites](/en/news/2026/august/platform-helm-availability-and-prerequisites)

Helm prerequisites, available charts, Console values, and compatibility guidance now reflect the supported inventory. Documentation correction; no runtime release is announced.

**August 24th, 2026**

### [Lender collection and Consignado event contract](/en/news/2026/august/lender-collection-and-consignado-event-contract)

Lender now documents `collection.instruction.issued` and four configuration-gated portability and refinance outcome consumers. The current Consignado gateway contract includes the two portability outcomes, which are emitted only when the outcome consumer is enabled and the deployed gateway manifest declares the event; it does not declare the two refinance outcomes. Review event routing and feature flags before enabling affected integrations. Documentation correction; no runtime release is announced.

**August 23rd, 2026**

### [Consignado API and streaming contracts](/en/news/2026/august/streaming-catalog-scope-and-delivery-recovery)

The Consignado reference and guide now cover the client-facing API surface. v3 streaming contracts clarify application-topic routing, the public Midaz manifest boundary, operational portability proposals, and Fetcher terminal-event recovery. Review integrations before the next deployment. Documentation correction; no runtime release is announced.

**August 21st, 2026**

### [Matcher error catalog](/en/news/2026/august/matcher-servicenow-connector-and-error-catalog)

Matcher documentation now covers the public error catalog and corrected source, rule, and priority guidance. Review client error handling. Documentation update; no new runtime release is announced.

**August 17th, 2026**

### [Fetcher direct-mode integrity contract](/en/news/2026/august/fetcher-direct-mode-integrity-contract)

Direct-mode SHA-256 detects accidental corruption but does not authenticate payloads against tampering. Review security controls that rely on the digest.

**August 17th, 2026**

### [Lender assignment of receivables guide](/en/news/2026/august/lender-assignment-of-receivables-guide)

The new guide separates a receivables assignment's fund, eligibility, approval, file-exchange, and external-evidence lifecycle stages. Review operating controls before using the flow.

**August 17th, 2026**

### [SPI DICT discovery and inventory configuration](/en/news/2026/august/spi-dict-discovery-and-inventory-configuration)

DICT workers have independent controls, defaults, and readiness thresholds; several are enabled by default. Review your SPI environment configuration and monitoring.

**August 13th, 2026**

### [Reporter data-source support and deletion contract](/en/news/2026/august/reporter-data-source-contract)

**What changed**

Reporter supports PostgreSQL and MongoDB Data Sources only. PostgreSQL connections can specify schemas; MongoDB connections cannot. Reporter also refuses to delete a Data Source while a live Template references it.

**Who is affected**

Teams that configure Reporter Data Sources or retire a database connection used by Templates.

**What you need to do**

Confirm that configured external Data Sources use PostgreSQL or MongoDB. Before retiring a connection, update or delete every live Template that references it.

**August 13th, 2026**

### [Lender authentication configuration contract](/en/news/2026/august/lender-auth-configuration-contract)

**What changed**

Lender configures authentication with `PLUGIN_AUTH_ENABLED` and `PLUGIN_AUTH_HOST`. `AUTH_REQUIRED` is not a Lender configuration variable and is no longer listed in the prerequisites or deployment checklist.

**Who is affected**

Teams that configure Lender route authorization.

**What you need to do**

Remove reliance on `AUTH_REQUIRED` from Lender deployment templates and runbooks. Configure the two documented authentication variables and verify identity-provider reachability.

**August 11th, 2026**

### [Access Manager SSO preflight and fixed-organization setup](/en/news/2026/august/access-manager-sso-preflight-static-organization)

**What changed**

Access Manager documentation now covers non-mutating SSO provider preflight validation and `PLUGIN_AUTH_SSO_STATIC_ORGANIZATION` for a fixed-organization single-tenant BYOC deployment. Do not set the variable with `MULTI_TENANT_ENABLED=true`.

**Who is affected**

Teams that configure Access Manager SSO, especially single-tenant BYOC deployments.

**What you need to do**

Use preflight before saving an SSO provider. Evaluate the static-organization option only for a fixed-organization single-tenant deployment.

**August 11th, 2026**

### [Flowker workflow execution and observability model](/en/news/2026/august/flowker-workflow-execution-observability)

**What changed**

Flowker documentation now distinguishes workflow-graph execution, recorded processing nodes, and opt-in telemetry. Trigger nodes do not create step records, and the documentation no longer claims a Console execution dashboard.

**Who is affected**

Teams that operate workflows or consume Flowker execution history and telemetry.

**What you need to do**

Review runbooks and execution-history consumers. Enable and connect a telemetry backend if you need OpenTelemetry data.

**August 11th, 2026**

### [Tracer rule-engine performance claim removed](/en/news/2026/august/tracer-rule-engine-performance-contract)

**What changed**

Tracer documentation no longer presents an unverified guarantee that compiled CEL expressions evaluate in under one millisecond.

**Who is affected**

Teams that used the prior statement for Tracer performance planning or commitments.

**What you need to do**

Review sizing and latency commitments. Measure rule evaluation under your own rule sets and load.

**August 10th, 2026**

### [Lerian Console deletion contract](/en/news/2026/august/console-deletion-contract)

**What changed**

The documentation now correctly states that deleting a Console user or application permanently removes it and cannot be undone. Application details show the name, description, ClientId, and ClientSecret; they do not show scopes or redirect URIs.

**Who is affected**

Teams that administer users or applications in Lerian Console.

**What you need to do**

Review access-management runbooks before your next deletion. Do not rely on application details as a source of scope or redirect URI data.

**August 10th, 2026**

### [Helm chart coverage for BYOC deployments](/en/news/2026/august/helm-chart-coverage)

**What changed**

Deployment documentation now correctly states that official Helm charts are available for the products and platform components supported through Lerian’s Helm repository; it no longer states that every product has an official chart.

**Who is affected**

Teams planning or operating BYOC deployments with Helm.

**What you need to do**

Confirm chart availability for your target product or platform component before planning a BYOC deployment.

**August 12th, 2026**

### [Double-entry consistency guidance](/en/news/2026/august/double-entry-consistency-guidance)

**What changed**

The double-entry guide now states that matching the source total, destination total, and sent value in Midaz is an amount-consistency control. It does not itself prove authorization, classification, or completeness. The debit/source and credit/destination explanation applies to the illustrated transfer, not every account type.

**Who is affected**

Teams using the guide for Midaz control design, audit evidence, or training.

**What you need to do**

Review material that treated double-entry balancing as proof that other financial controls passed, and keep those controls separate.

## Action required

***

**August 31, 2026**

### [Pix and TED streaming delivery configuration](/en/news/2026/august/pix-and-ted-streaming-delivery-configuration)

Pix Switch uses its fixed CloudEvents source, and TED RabbitMQ lifecycle delivery requires streaming.

**August 31, 2026**

### [Reporter Data Source configuration and worker bootstrap](/en/news/2026/august/reporter-data-source-configuration-and-worker-bootstrap)

Reporter Data Source configuration, encryption, schema overrides, and worker RabbitMQ requirements are clarified.

**August 31, 2026**

### [Lender M2M custody and ledger provisioning](/en/news/2026/august/lender-m2m-custody-and-ledger-provisioning)

Lender supports Vault KV v2 for M2M credentials and provisions Midaz ledger accounts by default.

**August 31, 2026**

### [SILOC MQ activation contract](/en/news/2026/august/siloc-mq-activation-contract)

SILOC inbound SFN processing is controlled by its MQ connection descriptor, not `SFN_INGEST_ENABLED`.

**August 29, 2026**

### [Midaz Billing v2 ledger scope](/en/news/2026/august/midaz-billing-v2-scope)

Billing packages and calculations use ledger-scoped v2 routes; the URL is the only ledger input.

**August 29, 2026**

### [Reporter Data Source probe contract](/en/news/2026/august/reporter-data-source-probe-contract)

Reporter probes Data Sources by `dataSourceId`; retrieve schema through a separate operation.

**August 29, 2026**

### [SPI settlement streaming configuration](/en/news/2026/august/spi-settlement-streaming-configuration)

SPI requires streaming brokers at startup and its BR Code settlement consumer runs unconditionally.

**August 28, 2026**

### [Reporter Data Source deletion path](/en/news/2026/august/reporter-data-source-deletion-path)

Reporter Data Source deletion uses `dataSourceId`, not the former `connectionId` path parameter.

**August 27, 2026**

### [Consignado sandbox server endpoint](/en/news/2026/august/consignado-sandbox-server-endpoint)

Use the served Consignado sandbox host; the former hostname fails before HTTP.

**August 27, 2026**

### [Consignado streaming and replay contracts](/en/news/2026/august/consignado-streaming-and-replay-contracts)

Consignado event, command-gating, and redirection-replay behavior are now explicit.

**August 27, 2026**

### [Reporter template and data-source contracts](/en/news/2026/august/reporter-template-and-data-source-contracts)

Reporter no longer claims unsupported regulatory mappings, and template uploads are limited to 1 MiB.

**August 26, 2026**

### [Platform IP allowlist enforcement contract](/en/news/2026/august/platform-ip-allowlist-enforcement-contract)

Configure the trusted-proxy boundary before relying on an IP allowlist.

**August 26, 2026**

### [Reporter CCS encoding and data-source contract](/en/news/2026/august/reporter-ccs-encoding-and-data-source-contract)

CCS templates require UTF-16BE output, and multi-tenant data sources use the API.

**August 26, 2026**

### [Midaz route validation contract](/en/news/2026/august/midaz-route-validation-contract)

Enable route validation before using Accounting Routes as transaction controls.

**August 25th, 2026**

### [Event streaming configuration and STA outcome contracts](/en/news/2026/august/event-streaming-configuration-and-sta-outcomes)

Lender TLS certificates must be base64-encoded PEM, Consignado manifests use `/v1/streaming/manifest`, and Streaming Hub catalog matching uses `resourceType` and `eventType`. Review event and STA integrations before deployment. Documentation correction; no runtime release is announced.

**August 25th, 2026**

### [Midaz fee asset contract](/en/news/2026/august/midaz-fee-asset-contract)

Fee requests require a non-empty `send.asset`; `DEFAULT_CURRENCY` is not a fallback. Update fee clients and deployment templates. Documentation correction; no runtime release is announced.

**August 25th, 2026**

### [Reporter data-source and preview contracts](/en/news/2026/august/reporter-data-source-and-preview-contracts)

Reporter data sources use an API-managed encrypted registry, reports use cursors, and exhausted template-preview capacity returns `429` / `RPT-0108`. Update clients and configuration. Documentation correction; no runtime release is announced.

**August 25th, 2026**

### [SILOC CloudEvents source identity](/en/news/2026/august/siloc-cloud-events-source-identity)

SILOC now validates `STREAMING_CLOUDEVENTS_SOURCE` against the identity in the current Lerian deployment package; another value or surrounding whitespace prevents startup. Documentation correction; no runtime release is announced.

**August 24th, 2026**

### [TED OUT completion and rail event contracts](/en/news/2026/august/ted-out-completion-and-rail-event-contracts)

TED OUT exposes `COMPLETED` through its transfer and reconciliation APIs but does not emit `transfer.completed` yet. Do not use that event as a TED OUT completion signal; update completion handling before your next deployment. SPI now documents the mandate-resolution consumer, STA documents its effective defaults and inbound ZIP bounds, and Consignado exposes its streaming manifest endpoint. Documentation correction; no runtime release is announced.

**August 21st, 2026**

### [Tracer asset field contract](/en/news/2026/august/tracer-asset-field-contract)

Tracer uses `asset`, not `currency`, in limit and validation requests, rule inputs, returned validation context, and Console terminology. Replace the former field in payload builders, rules, and client models. Documentation correction; no runtime release is announced.

**August 21st, 2026**

### [Flowker webhook and external API header contract](/en/news/2026/august/flowker-webhook-and-external-api-header-contract)

Webhook `accepted_headers` and `_webhook.headers` ingestion rules are documented. External OpenAPI integrations support static headers and fail closed on missing required inputs. Review affected workflows before deployment. Documentation correction; no runtime release is announced.

**August 21st, 2026**

### [Lender migration and Consignado command contract](/en/news/2026/august/lender-migration-and-consignado-command-contract)

Migration directories are fixed in the service image; remove retired `MIGRATIONS_PATH` from deployment configuration. `consignado.margin.requested` was retired later; only the exclusion and redirection commands remain. Documentation correction; no runtime release is announced.

**August 20th, 2026**

### [Event streaming v3 application contract](/en/news/2026/august/event-streaming-v3-application-contract)

v3 uses application topics, fixed producer sources, and source-qualified CloudEvents types. Matcher-to-Lender handoff is live when both runtimes are enabled; Reporter manifests use event keys without per-event topic fields. Review routing and configuration before deployment. Documentation correction; no runtime release is announced.

**August 20th, 2026**

### [Event streaming integration contracts](/en/news/2026/august/event-streaming-integration-contracts)

**What changed**

The event-streaming documentation now corrects Lender topic and retry semantics, Reporter delivery boundaries and identifier scope, and Midaz event payload and CRM topic conventions. It also documents streaming configuration requirements for Lender, Pix Switch, Boleto, and SLC.

**Who is affected**

Teams that consume Lender, Midaz, or Reporter events, or operate the documented streaming integrations.

**What you need to do**

Review subscriptions, event parsers, retry controls, and deployment configuration before the next deployment. This is a documentation correction; it does not announce a runtime release.

**August 18th, 2026**

### [Event streaming identity and delivery contracts](/en/news/2026/august/event-streaming-contracts)

Deduplicate CloudEvents by `(ce-source, ce-id)` rather than `ce-id` alone. Use the documented event-type tokens and review Streaming Hub tenant and EventBridge routing before the next deployment.

**August 18th, 2026**

### [Matcher duplicate-ingestion contract](/en/news/2026/august/matcher-duplicate-ingestion-contract)

Sources can define a mapped composite duplicate key, and the default duplicate policy is `FLAG_AS_EXCEPTION`. Review import configuration and exception handling before the next reconciliation run.

**August 18th, 2026**

### [SILOC ingress routing contract](/en/news/2026/august/siloc-ingress-routing-contract)

SILOC uses a closed SFN product-message routing policy and deduplicates relayed funding by `BCMSG.NUOp`. Update settlement-ingress operating controls.

**August 18th, 2026**

### [Access Manager SSO tenant validation](/en/news/2026/august/access-manager-sso-tenant-validation)

Auth rejects an SSO callback when its email is missing or resolves to another tenant. Verify identity-provider claims and tenant mappings.

**August 17th, 2026**

### [Midaz CRM and Fees Engine integration contract](/en/news/2026/august/midaz-crm-fees-integration-contract)

Create holder-owned accounts with `POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/holders/{id}/accounts`. CRM and Fees Engine are integrated Midaz components; configure fees in Midaz, not as a plugin.

**August 17th, 2026**

### [Access Manager SSO and Helm configuration](/en/news/2026/august/access-manager-sso-and-helm-configuration)

Pre-login SSO matching uses `domain:`. Set `disablePasswordLogin` explicitly when required, and review chart `8.6.0` with Auth and Identity `3.1.0` before upgrading.

**August 17th, 2026**

### [Reporter trial-balance classification contract](/en/news/2026/august/reporter-trial-balance-classification-contract)

Use rubric codes in `accountingEntries` and each operation's `routeCode` for new report classifications. Do not use deprecated `OperationRoute.code` as the source.

**August 17th, 2026**

### [Flowker environment-label contract](/en/news/2026/august/flowker-environment-label-contract)

`prod` and `production` both require production authentication guards. With the Tenant Manager secrets backend, set a non-empty `ENV_NAME`.

**August 17th, 2026**

### [Lender full-settlement prepayment event](/en/news/2026/august/lender-full-settlement-prepayment-event)

Process `lender.prepayment_quote.created` only as a full-settlement prepayment-quote event; it does not cover every prepayment quote.

**August 13th, 2026**

### [Midaz customer-closure v2 routes](/en/news/2026/august/midaz-customer-closure-v2-routes)

**What changed**

The customer-account closure guide now uses the current `/v2` Holder and Instrument routes for listing, updating, and archiving the Holder and its instruments. Only the CRM Holder and Instrument routes changed to `/v2`. The documented Ledger Balance and Ledger Account routes remain on `/v1`.

**Who is affected**

Teams automating the Midaz customer-account closure flow.

**What you need to do**

Replace the former CRM Holder and Instrument `/v1` paths in closure automation with the documented `/v2` equivalents, then test the complete flow before your next production closure.

**August 12th, 2026**

### [Lender Consignado API and event contract](/en/news/2026/august/lender-consignado-api-and-event-contract)

**What changed**

The Consignado API replaces `PUT /v1/credentials/dataprev/taxa-mensal` with `PUT /v1/credentials/dataprev/portal-base-url`. The Lender reference adds nine Consignado contract-divergence and compensating-adjustment operations, documents `lender.loan_account.debt_balance_changed`, and corrects guarantee recovery to `lender.guarantee_recovery_cash.allocated`. `CONSIGNADO_ENABLED` now documents its remaining legacy rejected-averbação handling only.

**Who is affected**

Teams integrating with the Lender Consignado API, consuming its events, or operating the Consignado configuration.

**What you need to do**

Replace calls to the retired monthly-rate endpoint, validate portal URLs before sending them, update guarantee-recovery subscriptions, and review `CONSIGNADO_ENABLED` runbooks before the next deployment.

**August 11th, 2026**

### [CADOC 4111 Reporter template contract](/en/news/2026/august/reporter-cadoc-4111-template-contract)

**What changed**

The CADOC 4111 guide now matches the tested `registros/registro` XML layout, `YYYY/MM/dd` date format, and balance selection from the latest operation for each account-and-route pair.

**Who is affected**

Teams using the Reporter CADOC 4111 template or a custom template derived from the previous guide.

**What you need to do**

Update and validate the template before your next CADOC 4111 submission. Do not sum every historical operation.

**August 10th, 2026**

### [Matcher error and idempotency contract](/en/news/2026/august/matcher-error-and-idempotency-contract)

**What changed**

The documentation now correctly describes Matcher’s RFC 9457 error envelope and idempotency-key constraints and retry behavior. Runtime behavior did not change.

**Who is affected**

Teams integrating with the Matcher API.

**What you need to do**

Align error parsing and generated idempotency keys with the documented contract before your next client release.

**August 10th, 2026**

### [SPI operations PII startup configuration](/en/news/2026/august/spi-operations-pii-startup-configuration)

**What changed**

The documentation now correctly states that the SPI service requires `SPI_OPERATIONS_PII_ENCRYPTION_KEY` to be a valid AES-256 key and `SPI_OPERATIONS_BLIND_INDEX_PEPPER` to contain at least 32 characters in every environment. Missing, malformed, or too-short values prevent the service from starting.

**Who is affected**

Teams deploying or operating the SPI service for Pix operations.

**What you need to do**

Before the next SPI start or redeployment, verify that both values are supplied through your secret manager and meet the documented requirements. Do not commit or log either value.

**August 10th, 2026**

### [Flowker scheduler Redis isolation configuration](/en/news/2026/august/flowker-scheduler-redis-isolation)

**What changed**

The documentation now correctly states that the Flowker scheduler has its own Redis configuration, but startup does not enforce isolation from the Redis used for tenant lifecycle events. Operators must provide a dedicated Redis instance or, when sharing an instance, a different logical database index.

**Who is affected**

Teams running Flowker workers with scheduled workflows enabled.

**What you need to do**

Verify the scheduler Redis settings before enabling or continuing to run scheduled workflows. Point the scheduler to a dedicated Redis instance, or configure a logical database index that tenant lifecycle events do not use.

## Product index

***

**August 26 additions:** Platform IP allowlists enforce the configured trusted-proxy boundary; Reporter CCS templates require UTF-16BE output; Midaz validates direct transactions against route rules only when route validation is enabled; Helm guidance now identifies component-specific Kubernetes API baselines; Tracer documents authentication precedence and stored validation-history scope; and Lender documents its streaming catalog and M011 portability prerequisites. These are documentation corrections, not runtime-release announcements.

| Product area | August updates |
| - | - |
| **Fetcher** | Direct-mode SHA-256 detects accidental corruption but does not authenticate payloads against tampering. Review any security control that treats the digest as authentication. Terminal events persist their terminal state and a pending marker before a separate durable-outbox insert; a repair loop re-emits the stable CloudEvents ID until delivery clears. Documentation corrections only. Runtime behavior did not change. |
| **Access Manager** | SSO provider preflight validates configuration without mutation. `PLUGIN_AUTH_SSO_STATIC_ORGANIZATION` is for fixed-organization single-tenant BYOC only and must not be set with multi-tenancy. Documentation update; no runtime change announced. Pre-login matching now uses `domain:`, password login is explicitly controlled, and chart `8.6.0` carries Auth and Identity `3.1.0`. The SSO callback also requires an email that resolves to the tenant that initiated the flow. |
| **Midaz** | Double-entry balancing validates recorded amount consistency; it is not proof of authorization, classification, or completeness. The debit/source and credit/destination wording is scoped to the illustrated transfer. The customer-account closure guide now uses current v2 Holder and Instrument routes for listing, updating, and archiving; the documented Ledger Balance and Ledger Account v1 routes remain unchanged. Replace former Holder and Instrument v1 paths in closure automation before the next production closure. Documentation corrections only. Account composition uses the CRM `/v2` Holder-account route; CRM and Fees Engine are integrated components, and fee setup is not a plugin workflow. The streaming manifest covers public JSON business events; the former separate internal billing stream is retired. Accounting Routes validate direct transactions only when route validation is enabled for the Ledger; cancellation is source-only. |
| **Reporter** | CADOC 4111 now documents the tested `registros/registro` layout, `YYYY/MM/dd` date format, and latest-operation-per-account-and-route balance selection. Data Sources support PostgreSQL and MongoDB only, schema selection applies only to PostgreSQL, and Reporter refuses to delete a Data Source while a live Template references it. Update custom templates and review connection-retirement procedures. Documentation corrections only. Trial-balance classifications now use `accountingEntries` rubric codes and each operation `routeCode`, not `OperationRoute.code`. Reporter event streams use the `reporter` source and manifest event keys; do not derive per-event or dead-letter topics from the manifest. ACCS001, ACCS005, and ACCS010 templates require UTF-16BE output; multi-tenant data sources use the Reporter API. |
| **Tracer** | The unverified sub-millisecond CEL evaluation claim was removed. Do not treat the prior statement as an SLA or capacity guarantee. Tracer uses `asset`, not `currency`, in limit and validation contracts; update integration payloads and rules. Plugin authentication takes precedence where both plugin and API-key authentication are enabled, except on API-key-only endpoints. Validation records are stored history, not an immutable audit log. Documentation corrections only. |
| **Matcher** | The error reference now correctly documents the RFC 9457 envelope (`title`, `status`, `detail`, `code`, and optional `errors`) and idempotency-key constraints and retry behavior. Sources can define mapped composite duplicate keys; the default policy is `FLAG_AS_EXCEPTION`. Update client handling before the next integration release. Documentation update; no runtime release announced. The public documentation now also covers the error catalog. |
| **Flowker** | Workflow execution follows a graph of nodes and edges. Executed processing nodes create records; trigger nodes do not. Telemetry is opt-in, and the documentation does not claim a Console execution dashboard. Documentation correction only. Runtime behavior did not change. Scheduler Redis isolation remains an operator configuration requirement: use a dedicated Redis instance or a logical database index separate from tenant lifecycle events. Both `prod` and `production` enable production guards; Tenant Manager deployments require a non-empty `ENV_NAME`. Webhook accepted-header and external API static-header requirements now fail closed when their documented contract is not met. |
| **Pix** | SPI operations PII requires a valid AES-256 key and a blind-index pepper with at least 32 characters in every environment; missing or invalid values prevent startup. Documentation correction only. Runtime behavior did not change. DICT discovery and inventory workers have independent controls, defaults, and readiness thresholds. SILOC applies a closed SFN routing policy and relayed funding is deduplicated by `BCMSG.NUOp`. BR Code also consumes `spi.mandate.resolved` to move a Pix Automático mandate out of `CRIADA`. |
| **TED** | TED OUT makes `COMPLETED` available through its transfer and reconciliation APIs but does not emit `transfer.completed` yet. Do not use that webhook as a TED OUT completion signal. Documentation correction only. No runtime release is announced. |
| **STA** | STA defaults `SERVER_ADDRESS` to `:4028` and its streaming-only tenant fallback to `11111111-1111-1111-1111-111111111111`. Inbound transfer extraction defaults to one 5 GiB ZIP entry with a maximum 100:1 expansion ratio; review overrides where those limits do not fit your operating environment. Documentation correction only. No runtime release is announced. |
| **Streaming Hub** | Consumers deduplicate CloudEvents by `(ce-source, ce-id)`, not `ce-id` alone. Published event types use the documented underscore tokens; review tenant resolution and EventBridge routing before the next deployment. Documentation correction only. No runtime release announced. |
| **Lerian Console** | User and application deletion is permanent and irreversible; application details show name, description, ClientId, and ClientSecret, not scopes or redirect URIs. Documentation correction only. |
| **Platform** | Official Helm charts cover products and platform components supported through Lerian’s Helm repository, not every product. Console supports Kubernetes 1.20+, while Access Manager and infrastructure charts require Kubernetes 1.23+. IP allowlists trust `X-Forwarded-For` only from configured direct proxy CIDRs. A non-empty list is enforced only for selected `console` or `api` scopes, and unresolved clients are permitted when the transport peer is in `PLATFORM_INTERNAL_CIDRS`. Documentation corrections only. |
| **Lender** | Consignado now documents nine contract-divergence and compensating-adjustment operations. Replace the retired monthly-rate endpoint with the HTTPS worker-portal URL endpoint, update guarantee-recovery subscriptions to `lender.guarantee_recovery_cash.allocated`, and review the narrowed `CONSIGNADO_ENABLED` gate. Authentication uses `PLUGIN_AUTH_ENABLED` and `PLUGIN_AUTH_HOST`; `AUTH_REQUIRED` is not a Lender setting. Documentation updates; no runtime release announced. The new assignment guide separates lifecycle evidence stages, and `lender.prepayment_quote.created` is limited to immutable full-settlement quotes. Migration directories are fixed in the service image, and the dormant `consignado.margin.requested` command has been removed. The client-facing Consignado reference now covers 55 operations and the guide covers setup, margin, auctions, registration, servicing, portability, guarantees, reconciliation, operations, and configuration. `consignado.portability_proposal.received` is operational when the scheduled portability-discovery poller finds a live M011 offer. `collection.instruction.issued` is emitted, while portability and refinance outcome listeners remain configuration-gated; the gateway contract includes the two portability outcomes, which are emitted only when the outcome consumer is enabled and the deployed manifest declares the event, but not the two refinance outcomes. Its wired streaming manifest is available at `GET /api/v1/streaming/manifest`. The catalog has 35 definitions (33 fact definitions and two commands), with production callers for 31 definitions (29 facts and both commands); M011 discovery is independently controlled by `LEILAO_PORTABILITY_ENABLED`. |

## No action

***

**August 27, 2026**

### [OpenAPI specification downloads](/en/news/2026/august/openapi-specification-downloads)

API Reference now provides direct YAML downloads for every rendered specification.

## Deprecation

***

**August 27, 2026**

### [Lender streaming command deprecation](/en/news/2026/august/lender-streaming-command-deprecation)

Lender no longer exposes the dormant `consignado.margin.requested` command.


# September 2026
Source: https://docs.lerian.studio/en/news/2026/2026-09

Documentation updates published in September 2026, grouped by required customer action.

Updates are grouped by required customer action. Product filters show only the areas that affect your integration. See [News](/en/news/news) for impact definitions.

## Action required

***

**September 30, 2026**

### [Lerian SPI API contract changes](/en/news/2026/september/spi-api-contract-changes)

Lerian SPI 1.0.0, released on September 29, 2026, changed the idempotency header to `X-Idempotency`, moved the received Pix list and person statistics to `POST`, removed the Core MED case routes, and moved the direct participant to its own route.

**September 20, 2026**

### [Lender API and event contract](/en/news/2026/september/lender-api-and-event-contract)

**What changed**

The Lender reference publishes 122 operations instead of 52, including the whole assignment-of-receivables family, returned-payment receivables, version promotion, document templates and the accrual-run retry. The event catalog holds 37 definitions with three new ones; the dormant Consignado margin and proposal events are retired. The documented idempotency contract now covers 27 operations and is fail-closed, not fail-open.

**Who is affected**

Teams integrating with the Lender API, consuming its events, or relying on the previously documented idempotency behaviour.

**What you need to do**

Review idempotency handling against the corrected fail-closed contract, send `X-Idempotency` under that exact spelling, and drop subscriptions to the retired Consignado events.

**September 20, 2026**

### [Lender guides updated for scheduled jobs and new refusals](/en/news/2026/september/lender-guides-2026-09)

Accrual closes a calendar month rather than a loan anniversary, two background jobs ship enabled, loan-application writes require an idempotency key, and origination refuses a product that is not active.

**September 10, 2026**

### [Page URLs now mirror the navigation](/en/news/2026/september/page-urls-mirror-navigation)

Every page and API operation on docs.lerian.studio moved to the path its navigation position names: `/en/<tab>/<anchor>/<page>`, so a product page now sits under `/en/products/<product>/`. The old URLs are not redirected. Update saved links, product-console links, and any URL embedded in an API description or error payload.

**September 3, 2026**

### [Midaz v4 API and deployment model](/en/news/2026/september/midaz-v4-api-and-deployment-model)

Ledger `/v2` is the current Core, CRM, and Fees API; CRM and Fees deploy with Midaz, while Tracer remains separately deployed.

**September 3, 2026**

### [Streaming Hub multi-tenant configuration](/en/news/2026/september/streaming-hub-multi-tenant-configuration)

Multi-tenant deployments use Tenant Manager, Redis, and deployment-level Kafka credentials; Secrets Manager remains for producer-manifest credentials.

**September 3, 2026**

### [SISBAJUD KMS and credential configuration](/en/news/2026/september/sisbajud-kms-and-credential-configuration)

SISBAJUD now documents the supported KMS selection path and sealed per-institution credentials.

**September 2, 2026**

### [Consignado gateway API contract update](/en/news/2026/september/consignado-gateway-api-contract-sweep)

Three new operations, an optional formalization portal, a narrowed refinancing reversal without `dataRefinanciamento`, and error codes moving from `MYS-` to `CLT-`.

**September 1, 2026**

### [Platform Helm deployment and upgrade references](/en/news/2026/september/platform-helm-deployment-references)

Platform Helm documentation now identifies the supported CRM deployment model, Reporter chart reference, and upgrade value behavior.

**September 1, 2026**

### [Reporter template authoring and report filters](/en/news/2026/september/reporter-template-authoring-and-report-filters)

Reporter PDF templates use HTML source, report filters use operator objects, and `date_time` uses the runtime local time zone.

**September 1, 2026**

### [Midaz pending-transaction overdraft behavior](/en/news/2026/september/midaz-pending-transaction-overdraft-behavior)

A pending transaction creates a hold rather than drawing overdraft; a hold that exceeds Available is rejected with `0018`.

## Review recommended

***

**September 8, 2026**

### [Documentation site: API error references and rebuilt sections](/en/news/2026/september/api-error-references-and-rebuilt-sections)

Twenty API reference sections list their error responses; Solutions, Platform, and the Console pages are rebuilt, and Narya is documented.

**September 5, 2026**

### [Documentation site: new structure](/en/news/2026/september/documentation-site-new-structure)

The site now has nine tabs, new Solutions and Interfaces sections, an API Reference rendered from the OpenAPI specifications, and, at the time, English-only content.

**September 3, 2026**

### [Tracer v4 integration and authentication](/en/news/2026/september/tracer-v4-integration-and-authentication)

Tracer v4 guidance clarifies its separate deployment, reservation integration, and API authentication examples.

**September 3, 2026**

### [Midaz noted transaction status](/en/news/2026/september/midaz-noted-transaction-status)

`NOTED` is annotation-only: it does not change balances.

**September 3, 2026**

### [Reporter API error catalog](/en/news/2026/september/reporter-error-catalog)

The error reference now reflects active 400, 409, and 412 API responses and removes retired `RPT-0033`.

**September 3, 2026**

### [SPB message-log and frame access](/en/news/2026/september/spb-message-log-and-frame-access)

Message logs return structured data; retained signed frames require their dedicated authorized route.

**September 2, 2026**

### [Platform Helm deployment configuration](/en/news/2026/september/platform-helm-deployment-configuration)

Platform Helm examples now use the current Reporter values and show the required OpenTelemetry Collector values file.

**September 2, 2026**

### [Tracer CORS and service-discovery configuration](/en/news/2026/september/tracer-cors-and-service-discovery-configuration)

Empty CORS origins block cross-origin requests, and enabled service discovery requires an advertised address with a static fallback.

**September 2, 2026**

### [SLC recovery and parked-operation handling](/en/news/2026/september/slc-recovery-and-parked-operation-handling)

Parked outbound operations use `attempt_budget_exhausted`, and un-parking resets the transmit-attempt budget.

**September 2, 2026**

### [Narya developer-tool integration model](/en/news/2026/september/narya-developer-tool-integration-model)

Narya is documented as an in-development Developer Tool with public HTTP integration over its local Unix socket.

**September 1, 2026**

### [SPB electronic-money advice event](/en/news/2026/september/spb-electronic-money-advice-event)

SPB documents `str.emoney.transferAdvised`, including payload fields and the deduplication key for streaming and webhook consumers.

## No action

***

**September 16, 2026**

### [Documentation in Portuguese and Spanish](/en/news/2026/september/documentation-in-portuguese-and-spanish)

Every page now has a Brazilian Portuguese edition and a Spanish edition, derived from the English source, at the same path with the `/pt/` or `/es/` prefix.


# October 2026
Source: https://docs.lerian.studio/en/news/2026/2026-10

Documentation updates published in October 2026, grouped by required customer action.

This page groups the updates by the action they require. Product filters show only the areas that affect your integration. See [News](/en/news/news) for impact definitions.

## Action required

***

**October 22, 2026**

### [Payments BTG v1.0.2 payer lookup](/en/interfaces/payments-btg/boleto-environment-variables)

The Payments BTG pages moved to v1.0.2. Bill and DARF payments now read the payer from CRM endpoints served by `MIDAZ_LEDGER_URL` at `/v2`, and `MIDAZ_CRM_URL` no longer configures that lookup. Before you upgrade, make sure that the Midaz ledger URL serves CRM endpoints at `/v2`.

**October 18, 2026**

### [Lerian SISBAJUD in two components](/en/rails/sisbajud/what-is-lerian-sisbajud)

The Lerian SISBAJUD pages moved to two releases: the Lerian SISBAJUD Mensageria v1.0.0 and the Lerian SISBAJUD executor v1.0.0. The Mensageria receives the orders as files through Lerian STA and writes the response files. The executor runs the orders on Midaz and needs its own PostgreSQL database. Each component has its own environment variables: see the [Mensageria](/en/rails/sisbajud/sisbajud-environment-variables) and [executor](/en/rails/sisbajud/sisbajud-executor-environment-variables) pages. The API reference has one section for each component, and the operation URLs changed. Before you move to these releases, register each institution on both components with the same `institutionId` and `enabled` set to `true`.

**October 18, 2026**

### [Lifecycle Management through the Lerian BYOC agent](/en/platform/lifecycle-management)

Lifecycle Management moved from the Lifecycle dashboard to the Lerian BYOC agent, and Lerian retired the dashboard. Lerian installs, upgrades, rolls back, and removes products in your cluster through the agent, at your request. To use Lifecycle Management, ask Lerian support for the agent credential and the control-plane address. Then install the agent with its chart.

**October 13, 2026**

### [Payments BTG v1.0.1 license variables](/en/interfaces/payments-btg/boleto-environment-variables)

The Payments BTG pages moved to release v1.0.1, which validates its license when it starts. In v1.0.1, every pod, the worker included, needs `LICENSE_KEY` and `ORGANIZATION_IDS` in every environment. The value of `ORGANIZATION_IDS` is `global` or a comma-separated list of lowercase organization UUIDs. A license refusal carries an `LCS` code. The API operations did not change. Before you upgrade, set both variables on every pod, and open the outbound rule that [License Manager](/en/platform/licensing/license-manager) describes.

**October 13, 2026**

### [Bank Transfer v3.1.0 deductible TED OUT fees](/en/products/midaz/fees/fees-migration-guide)

Bank Transfer v3.1.0 refuses a TED OUT with `422` `BTF-3002` when the fee package that matches it has a fee with `isDeductibleFrom: true`. The refusal applies in `native` mode, and in `legacy` mode with `BTF_FEE_ENABLED=true`. For TED OUT and P2P, the `totalAmount` is the amount that Bank Transfer debits from the sender, and usage limits count that amount. Transfer reads carry `organizationId` and `ledgerId`, [List Transfers](/en/reference/interfaces/ted-jd/list-transfers) takes a `ledgerId` filter, and the API reference added `422` `BTF-2004` and `BTF-2005`. Bank Transfer asks Midaz to create a transaction metadata index, which needs the Midaz `settings` `post` permission in both fee modes. Before you upgrade, make sure that no plugin-fees package that a TED OUT can match has a fee with `isDeductibleFrom: true`.

**October 13, 2026**

### [Pix JD v1.2.4 English field names and key lookup](/en/interfaces/pix-jd/direct-pix-via-jd)

The Pix JD pages and API reference moved to v1.2.4, where the key lookup takes an optional `indirectId` for a payment through an indirect participant. Pix JD adds English names for some fields of MED 2.0, Pix Automático, and the key lookup. Where a field has an English name, the Portuguese name still works and is deprecated, and two different values for one field answer `400` `PIX-0148`. Two MED routes have English paths that need the same permission as the Portuguese ones. As the [environment variables](/en/interfaces/pix-jd/pix-jd-environment-variables) page says, the rail no longer reads `MULTI_TENANT_ALLOW_INSECURE_HTTP` from 1.2.1. In multi-tenant mode with an `http://` Tenant Manager, set `ALLOW_INSECURE_TLS=true` on the API and the worker before that upgrade, or the service does not start.

**October 11, 2026**

### [Bank Transfer v3.1.0 fee mode](/en/products/midaz/fees/fees-migration-guide)

Bank Transfer v3.1.0, the TED JD plugin, can charge fees through the Midaz Fees Engine. [`MIDAZ_FEE_MODE`](/en/interfaces/ted-jd/ted-environment-variables) selects `legacy` (plugin-fees, `/v1`) or `native` (Midaz, `/v2`), and the default `auto` selects `native` on Midaz 4.1.0 or later. Under `auto`, if your fee packages are still in plugin-fees, transfers carry no fee once Midaz runs 4.1.0 or later. `native` needs the Midaz permissions `packages` `get` and `estimates` `post`, an explicit `native` also needs `organizations` `get`, and `BTF_FEE_ENABLED` applies to `legacy` only. Set `MIDAZ_FEE_MODE=legacy` before you upgrade, then move your packages as the migration guide describes. Switch to `native` only when every Bank Transfer pod runs 3.1.0 or later and the packages exist in Midaz.

**October 8, 2026**

### [Matcher v5.0.0 idempotency header and auto-confirmation](/en/products/matcher/what-is-matcher)

The Matcher pages and API reference moved to Matcher v5.0.0, where a `DATE_LAG` match goes to review and the default duplicate policy is `FLAG_AS_EXCEPTION`. Matcher v5.0.0 reads an idempotency key only from the `X-Idempotency` header, and it does not use a key in `Idempotency-Key` or `X-Idempotency-Key`. Send idempotency keys in `X-Idempotency`, and review the matches that your process expects to confirm automatically.

**October 8, 2026**

### [Access Manager v3.10.0 MFA code and partners](/en/platform/access-manager/features/mfa/api)

In Access Manager v3.10.0, a user who turns off MFA on their own account must send a code. The partner pages and the partner operations left the site. If your application lets users turn off MFA or remove a method on their own account, collect the code and send it in the request.

**October 8, 2026**

### [Pix JD v1.2.0](/en/interfaces/pix-jd/pix-jd-environment-variables)

The Pix JD pages and API reference moved to plugin release v1.2.0, which adds an asynchronous account validation for JD. In v1.2.0, a route claims Pix Automático recurrences on JD Courier. Before you upgrade, follow the 1.2.0 upgrade step on the environment variables page.

**October 8, 2026**

### [CCS license variables](/en/rails/ccs/ccs-environment-variables)

The CCS environment variables page changed `LICENSE_KEY` and `ORGANIZATION_IDS` from required in production to required in every environment. Set both variables in every environment, development included.

**October 8, 2026**

### [Payments BTG guarantor and payment lookup](/en/interfaces/payments-btg/boleto-and-bill-payment)

The Payments BTG API reference removed the guarantor from boleto issuance, and a request that sends one answers `400` `PBP-0001`. The Boletos & Bill Payment page added how to find a payment by its `Idempotency-Key` when a creation request ends without a payment id. Remove the guarantor from your boleto requests, and after an error, resend under the same `Idempotency-Key` before you look up the payment.

**October 8, 2026**

### [JD Courier v1.1.0 rail activation](/en/interfaces/jd-courier/jd-courier-deployment)

The JD Courier pages and API reference moved to v1.1.0 and added the activation and suspension of a rail. In v1.1.0, the Courier delivers no message of a rail to the engines until an operator activates the rail. Activate each rail as the deployment page describes.

**October 6, 2026**

### [Tracer reservations use gRPC only in Midaz 4.2.0](/en/products/tracer/integration-guide)

In Midaz 4.2.0, the Ledger reaches Tracer for reservations over gRPC only, on port 4021 by default. The REST reservation operations left the Tracer API reference. Deploy Tracer before the Ledger, and do not roll Tracer back below 4.2.0 while a 4.2.0 Ledger runs.

**October 6, 2026**

### [Pix JD v1.0.0 configuration and upgrade](/en/interfaces/pix-jd/pix-jd-environment-variables)

The Pix JD pages moved to plugin release v1.0.0. In v1.0.0, the Midaz organization, ledger, asset and clearing account come from the systemplane binding and two `tenant_policy/midaz.*` keys, and payments and devoluções require `X-Idempotency`. Follow the new upgrade steps: write the `tenant_policy/midaz.*` keys first, then remove the retired `MIDAZ_*` identity variables.

**October 6, 2026**

### [Payments BTG bill payment flow and consult](/en/interfaces/payments-btg/boleto-and-bill-payment)

The Payments BTG pages added the steps of a bill payment: the ledger reserves the funds before BTG receives the payment. An unknown outcome answers `202` with status `UNCONFIRMED`, the reference added a bill consult operation, and the error list added seven codes and removed `PBP-0209`. Do not resend an `UNCONFIRMED` payment under a new `Idempotency-Key`, and set `CONSULT_AUDIT_HMAC_KEY`: a pod that serves the payment API does not start without it.

**October 6, 2026**

### [TED JD v3.0.1 error format](/en/reference/interfaces/ted-jd/ted-error-list)

In TED JD v3.0.1, every error is an RFC 9457 problem document on `application/problem+json`, and a JD SPB code is on `upstream.code`. Update the error parsing of your integration.

**October 6, 2026**

### [SISBAJUD v1.2.0 license variables](/en/rails/sisbajud/sisbajud-environment-variables)

Lerian SISBAJUD v1.2.0 needs `LICENSE_KEY` and `ORGANIZATION_IDS` in every environment. Set both variables.

**October 6, 2026**

### [Access Manager chart environment name](https://github.com/LerianStudio/helm/tree/main/charts/plugin-access-manager)

The Access Manager Helm page added the environment name. The chart default is `development`. For any environment other than development, staging or local, expose Caradhras over https with a certificate from a public certificate authority. Then point Auth and Identity at that https address.

**October 6, 2026**

### [Streaming Hub v2.3.0 refusals](/en/reference/platform/streaming-hub/streaming-hub-error-list)

In Streaming Hub v2.3.0, a `401` or `403` refusal is a problem document with code `unauthorized` or `forbidden`. The hub answers `503` when Access Manager returns no verdict. Update the error parsing of your integration.

**October 6, 2026**

### [Lerian Console v2.6.0 pages](/en/platform/console/managing-applications)

The Console pages changed to match Lerian Console v2.6.0. The update added pages for Reporter Institutions, TED IN operations, TED JD Accounting Routes and Pix BTG refunds, and covered report parameters and the `Partial failure` status. The update removed the BC Correios Console pages. The Console shows an application's client secret once, when you create the application. Store it then.

## Review recommended

***

**October 18, 2026**

### [Lerian SRC](/en/rails/src/what-is-lerian-src)

The Brazil Rails tab and the API Reference added Lerian SRC. Lerian SRC sends restriction consultations to BACEN's BC Protege+ before your institution opens an account or changes the ownership of an existing relationship. It records BACEN's verdict for each consultation and keeps an evidence trail.

**October 18, 2026**

### [Lerian BC Correios](/en/rails/bc-correios/what-is-lerian-bc-correios)

The Brazil Rails tab and the API Reference added Lerian BC Correios. Lerian BC Correios collects your institution's BC Correio mail from BACEN, stores it with an audit trail, and sends messages to BACEN departments.

**October 15, 2026**

### [Access Manager startup guidance](/en/platform/access-manager/am-lifecycle-stages)

The Access Manager lifecycle guidance no longer treats PostgreSQL, Valkey, or Caradhras reachability as a service-start prerequisite. Use the health checks to confirm readiness before you enable access enforcement in a product.

**October 15, 2026**

### [SLC clearing events in integration diagrams](/en/diagrams/native-rails/receive-receivables-at-domicile)

The SLC integration diagrams now identify the events for preview positions, settled credits, and returned credits. Review your subscriptions and operational runbooks against the revised journeys.

**October 15, 2026**

### [Midaz account and balance model](/en/products/midaz/accounts)

The Midaz account and balance guidance now distinguishes a customer's separate accounts from multiple balances within one account. Review your account model and balance-level controls against the current guidance.

**October 13, 2026**

### [Lerian Console v2.13.0 pages](/en/platform/console/about-lerian-console)

The Console pages changed to match Lerian Console v2.13.0, and [Product versions](/en/platform/console/about-lerian-console#product-versions) lists the product version that some screens need. When a product runs an earlier version, a notice such as *Requires Bank Transfer 3.1.0 or later* replaces that part of the screen. The Tracer module opens on its dashboard with Tracer 4.1.0 or later, and the Console no longer reads `NEXT_PUBLIC_TRACER_DASHBOARD_ENABLED`. In Bank Transfer, the Transfers list and the Recent Transfers card show the transfers of the selected ledger. For TED Out and P2P, Total shows the amount debited from the sender, and the Fee Policy settings apply only in the `legacy` fee mode. A new page describes [Environments](/en/platform/console/environments), the screen that lists the environments where you have an account and lets you choose your default one.

**October 13, 2026**

### [Access Manager v3.11.1 and partners](/en/platform/access-manager/using-access-manager)

The Access Manager pages and the Auth and Identity API references moved to Access Manager v3.11.1. The Auth reference added the SSO discover and start operations, and the Identity reference added the partner, scope catalog and own tenant operations. The partner guides returned, with an overview, a Console guide and an API guide. You can give a partner permissions only on a product that accepts partners, and the [overview](/en/platform/access-manager/features/partners/overview) says how to find those products in your deployment. A request to delete a group that has members or subgroups now answers `409` with `IDE-1058` or `IDE-1059`. The [error list](/en/reference/platform/access-manager/access-manager-error-list) also added `AUT-0033`, `AUT-1011`, `AUT-1012`, `IDE-0064`, `IDE-0065` and `IDE-0066`, and the Tenant Manager automatic provisioning page left the site.

**October 8, 2026**

### [Matcher module of Lerian Console](/en/products/matcher/ui/matcher-ui-overview)

The Matcher UI pages changed to describe the Matcher module of Lerian Console v2.12.0.

**October 8, 2026**

### [Lerian Console v2.12.0 pages](/en/platform/console/about-settings)

The Console pages changed to match Lerian Console v2.12.0. In v2.12.0, you open Authorization from the Settings sidebar or the gear menu, and the application list has a Description column. The Products page added Matcher.

**October 8, 2026**

### [Integration Diagrams journeys](/en/diagrams/introduction)

The Integration Diagrams tab has four sections: Lerian Products, Native rails, Partner interfaces and Market infrastructures. Native rails has the SLC, SILOC and STR journeys for secured credit and daily settlement, with a Lerian column that shows the endpoint or the event of each step between your institution and Lerian, and marks the steps that are still pending. The other sections are in construction. A message index lists each code and its journeys. On rail pages, the official manuals prevail over the diagrams.

**October 8, 2026**

### [Tab layout and Integration Diagrams](/en/diagrams/introduction)

The site regrouped its tabs and removed the Solutions tab and its pages. Platform became a section of Lerian Products, and Interfaces became a section of Brazil Rails, with no change to the addresses of their pages. The site added an Integration Diagrams tab before API Reference.

**October 6, 2026**

### [JD Courier](/en/interfaces/jd-courier/what-is-jd-courier)

The Interfaces tab and the API Reference added JD Courier. JD Courier lets two or more core banking engines share one JD channel and one ISPB on SPB (TED) and Pix. It runs in BYOC and on Lerian Cloud.

**October 6, 2026**

### [Fee debt in Midaz 4.2.0](/en/products/midaz/fees/fee-debt)

In Midaz 4.2.0, the unpaid part of a deferrable fee on a `/v2` direct transaction can become a fee debt that later `/v2` credits settle, oldest first. Fee debt is off by default, and Valkey must persist its keys.

**October 6, 2026**

### [Access Manager Identity API reference](/en/reference/platform/access-manager/am-identity-apis)

The Identity API reference dropped the partner, scope catalog and user tenant operations. The Access Manager error list added `IDE-0038`.

**October 6, 2026**

### [Consignado v3.7.0](/en/rails/consignado/how-consignado-works)

The Consignado API reference added an operation that reads the cadastro stored with an averbação, and the events reference changed to match what v3.7.0 emits. In Lerian Consignado v3.7.0, the saldo devedor sent to Dataprev is the present value of the unpaid installments.

## No action

***

**October 13, 2026**

### [Midaz v4.2.2](/en/products/midaz/about-midaz)

The Midaz pages and the Ledger and Tracer API references moved to Midaz v4.2.2. The API operations did not change.

**October 6, 2026**

### [SPI environment variables](/en/rails/spi/spi-environment-variables)

The SPI environment variables page dropped `BACEN_SPI_SIGNING_KEY_FILE`.


# Latest news
Source: https://docs.lerian.studio/en/news/latest-news



***

**October 22, 2026**

### [Payments BTG v1.0.2 payer lookup](/en/interfaces/payments-btg/boleto-environment-variables)

The Payments BTG pages moved to v1.0.2. Bill and DARF payments now read the payer from CRM endpoints served by `MIDAZ_LEDGER_URL` at `/v2`, and `MIDAZ_CRM_URL` no longer configures that lookup. Before you upgrade, make sure that the Midaz ledger URL serves CRM endpoints at `/v2`.

**October 18, 2026**

### [Lerian STA v1.1.0](/en/rails/sta/sta-environment-variables)

The Lerian STA pages moved to Lerian STA v1.1.0. Lerian STA v1.1.0 can read its license from a signed license file that Lerian issues. Set the path of the file in `LICENSE_FILE_PATH`. With a license file, Lerian STA verifies the license locally and does not call the license service. When `LICENSE_FILE_PATH` is set, Lerian STA ignores `LICENSE_KEY`. Every environment needs `LICENSE_FILE_PATH` or `LICENSE_KEY`, and `ORGANIZATION_IDS`.

**October 18, 2026**

### [Lerian SRC](/en/rails/src/what-is-lerian-src)

The Brazil Rails tab and the API Reference added Lerian SRC. Lerian SRC sends restriction consultations to BACEN's BC Protege+ before your institution opens an account or changes the ownership of an existing relationship. It records BACEN's verdict for each consultation and keeps an evidence trail.

**October 18, 2026**

### [Lerian SISBAJUD in two components](/en/rails/sisbajud/what-is-lerian-sisbajud)

The Lerian SISBAJUD pages moved to two releases: the Lerian SISBAJUD Mensageria v1.0.0 and the Lerian SISBAJUD executor v1.0.0. The Mensageria receives the orders as files through Lerian STA and writes the response files. The executor runs the orders on Midaz and needs its own PostgreSQL database. Each component has its own environment variables: see the [Mensageria](/en/rails/sisbajud/sisbajud-environment-variables) and [executor](/en/rails/sisbajud/sisbajud-executor-environment-variables) pages. The API reference has one section for each component, and the operation URLs changed. Before you move to these releases, register each institution on both components with the same `institutionId` and `enabled` set to `true`.

**October 18, 2026**

### [Lerian BC Correios](/en/rails/bc-correios/what-is-lerian-bc-correios)

The Brazil Rails tab and the API Reference added Lerian BC Correios. Lerian BC Correios collects your institution's BC Correio mail from BACEN, stores it with an audit trail, and sends messages to BACEN departments.

**October 18, 2026**

### [Lifecycle Management through the Lerian BYOC agent](/en/platform/lifecycle-management)

Lifecycle Management moved from the Lifecycle dashboard to the Lerian BYOC agent, and Lerian retired the dashboard. Lerian installs, upgrades, rolls back, and removes products in your cluster through the agent, at your request. To use Lifecycle Management, ask Lerian support for the agent credential and the control-plane address. Then install the agent with its chart.

**October 15, 2026**

### [Access Manager startup guidance](/en/platform/access-manager/am-lifecycle-stages)

The Access Manager lifecycle guidance no longer treats PostgreSQL, Valkey, or Caradhras reachability as a service-start prerequisite. Use the health checks to confirm readiness before you enable access enforcement in a product.

**October 15, 2026**

### [SLC clearing events in integration diagrams](/en/diagrams/native-rails/receive-receivables-at-domicile)

The SLC integration diagrams now identify the events for preview positions, settled credits, and returned credits. Review your subscriptions and operational runbooks against the revised journeys.

**October 15, 2026**

### [Midaz account and balance model](/en/products/midaz/accounts)

The Midaz account and balance guidance now distinguishes a customer's separate accounts from multiple balances within one account. Review your account model and balance-level controls against the current guidance.

**October 13, 2026**

### [Payments BTG v1.0.1 license variables](/en/interfaces/payments-btg/boleto-environment-variables)

The Payments BTG pages moved to release v1.0.1, which validates its license when it starts. In v1.0.1, every pod, the worker included, needs `LICENSE_KEY` and `ORGANIZATION_IDS` in every environment. The value of `ORGANIZATION_IDS` is `global` or a comma-separated list of lowercase organization UUIDs. A license refusal carries an `LCS` code. The API operations did not change. Before you upgrade, set both variables on every pod, and open the outbound rule that [License Manager](/en/platform/licensing/license-manager) describes.

**October 13, 2026**

### [Bank Transfer v3.1.0 deductible TED OUT fees](/en/products/midaz/fees/fees-migration-guide)

Bank Transfer v3.1.0 refuses a TED OUT with `422` `BTF-3002` when the fee package that matches it has a fee with `isDeductibleFrom: true`. The refusal applies in `native` mode, and in `legacy` mode with `BTF_FEE_ENABLED=true`. For TED OUT and P2P, the `totalAmount` is the amount that Bank Transfer debits from the sender, and usage limits count that amount. Transfer reads carry `organizationId` and `ledgerId`, [List Transfers](/en/reference/interfaces/ted-jd/list-transfers) takes a `ledgerId` filter, and the API reference added `422` `BTF-2004` and `BTF-2005`. Bank Transfer asks Midaz to create a transaction metadata index, which needs the Midaz `settings` `post` permission in both fee modes. Before you upgrade, make sure that no plugin-fees package that a TED OUT can match has a fee with `isDeductibleFrom: true`.

**October 13, 2026**

### [Pix JD v1.2.4 English field names and key lookup](/en/interfaces/pix-jd/direct-pix-via-jd)

The Pix JD pages and API reference moved to v1.2.4, where the key lookup takes an optional `indirectId` for a payment through an indirect participant. Pix JD adds English names for some fields of MED 2.0, Pix Automático, and the key lookup. Where a field has an English name, the Portuguese name still works and is deprecated, and two different values for one field answer `400` `PIX-0148`. Two MED routes have English paths that need the same permission as the Portuguese ones. As the [environment variables](/en/interfaces/pix-jd/pix-jd-environment-variables) page says, the rail no longer reads `MULTI_TENANT_ALLOW_INSECURE_HTTP` from 1.2.1. In multi-tenant mode with an `http://` Tenant Manager, set `ALLOW_INSECURE_TLS=true` on the API and the worker before that upgrade, or the service does not start.

**October 13, 2026**

### [Lerian Console v2.13.0 pages](/en/platform/console/about-lerian-console)

The Console pages changed to match Lerian Console v2.13.0, and [Product versions](/en/platform/console/about-lerian-console#product-versions) lists the product version that some screens need. When a product runs an earlier version, a notice such as *Requires Bank Transfer 3.1.0 or later* replaces that part of the screen. The Tracer module opens on its dashboard with Tracer 4.1.0 or later, and the Console no longer reads `NEXT_PUBLIC_TRACER_DASHBOARD_ENABLED`. In Bank Transfer, the Transfers list and the Recent Transfers card show the transfers of the selected ledger. For TED Out and P2P, Total shows the amount debited from the sender, and the Fee Policy settings apply only in the `legacy` fee mode. A new page describes [Environments](/en/platform/console/environments), the screen that lists the environments where you have an account and lets you choose your default one.

**October 13, 2026**

### [Access Manager v3.11.1 and partners](/en/platform/access-manager/using-access-manager)

The Access Manager pages and the Auth and Identity API references moved to Access Manager v3.11.1. The Auth reference added the SSO discover and start operations, and the Identity reference added the partner, scope catalog and own tenant operations. The partner guides returned, with an overview, a Console guide and an API guide. You can give a partner permissions only on a product that accepts partners, and the [overview](/en/platform/access-manager/features/partners/overview) says how to find those products in your deployment. A request to delete a group that has members or subgroups now answers `409` with `IDE-1058` or `IDE-1059`. The [error list](/en/reference/platform/access-manager/access-manager-error-list) also added `AUT-0033`, `AUT-1011`, `AUT-1012`, `IDE-0064`, `IDE-0065` and `IDE-0066`, and the Tenant Manager automatic provisioning page left the site.

**October 13, 2026**

### [Midaz v4.2.2](/en/products/midaz/about-midaz)

The Midaz pages and the Ledger and Tracer API references moved to Midaz v4.2.2. The API operations did not change.

**October 11, 2026**

### [Bank Transfer v3.1.0 fee mode](/en/products/midaz/fees/fees-migration-guide)

Bank Transfer v3.1.0, the TED JD plugin, can charge fees through the Midaz Fees Engine. [`MIDAZ_FEE_MODE`](/en/interfaces/ted-jd/ted-environment-variables) selects `legacy` (plugin-fees, `/v1`) or `native` (Midaz, `/v2`), and the default `auto` selects `native` on Midaz 4.1.0 or later. Under `auto`, if your fee packages are still in plugin-fees, transfers carry no fee once Midaz runs 4.1.0 or later. `native` needs the Midaz permissions `packages` `get` and `estimates` `post`, an explicit `native` also needs `organizations` `get`, and `BTF_FEE_ENABLED` applies to `legacy` only. Set `MIDAZ_FEE_MODE=legacy` before you upgrade, then move your packages as the migration guide describes. Switch to `native` only when every Bank Transfer pod runs 3.1.0 or later and the packages exist in Midaz.

**October 8, 2026**

### [Matcher v5.0.0 idempotency header and auto-confirmation](/en/products/matcher/what-is-matcher)

The Matcher pages and API reference moved to Matcher v5.0.0, where a `DATE_LAG` match goes to review and the default duplicate policy is `FLAG_AS_EXCEPTION`. Matcher v5.0.0 reads an idempotency key only from the `X-Idempotency` header, and it does not use a key in `Idempotency-Key` or `X-Idempotency-Key`. Send idempotency keys in `X-Idempotency`, and review the matches that your process expects to confirm automatically.

**October 8, 2026**

### [Access Manager v3.10.0 MFA code and partners](/en/platform/access-manager/features/mfa/api)

In Access Manager v3.10.0, a user who turns off MFA on their own account must send a code. The partner pages and the partner operations left the site. If your application lets users turn off MFA or remove a method on their own account, collect the code and send it in the request.

**October 8, 2026**

### [Pix JD v1.2.0](/en/interfaces/pix-jd/pix-jd-environment-variables)

The Pix JD pages and API reference moved to plugin release v1.2.0, which adds an asynchronous account validation for JD. In v1.2.0, a route claims Pix Automático recurrences on JD Courier. Before you upgrade, follow the 1.2.0 upgrade step on the environment variables page.

**October 8, 2026**

### [CCS license variables](/en/rails/ccs/ccs-environment-variables)

The CCS environment variables page changed `LICENSE_KEY` and `ORGANIZATION_IDS` from required in production to required in every environment. Set both variables in every environment, development included.

**October 8, 2026**

### [Payments BTG guarantor and payment lookup](/en/interfaces/payments-btg/boleto-and-bill-payment)

The Payments BTG API reference removed the guarantor from boleto issuance, and a request that sends one answers `400` `PBP-0001`. The Boletos & Bill Payment page added how to find a payment by its `Idempotency-Key` when a creation request ends without a payment id. Remove the guarantor from your boleto requests, and after an error, resend under the same `Idempotency-Key` before you look up the payment.

**October 8, 2026**

### [JD Courier v1.1.0 rail activation](/en/interfaces/jd-courier/jd-courier-deployment)

The JD Courier pages and API reference moved to v1.1.0 and added the activation and suspension of a rail. In v1.1.0, the Courier delivers no message of a rail to the engines until an operator activates the rail. Activate each rail as the deployment page describes.

**October 8, 2026**

### [Matcher module of Lerian Console](/en/products/matcher/ui/matcher-ui-overview)

The Matcher UI pages changed to describe the Matcher module of Lerian Console v2.12.0.

**October 8, 2026**

### [Lerian Console v2.12.0 pages](/en/platform/console/about-settings)

The Console pages changed to match Lerian Console v2.12.0. In v2.12.0, you open Authorization from the Settings sidebar or the gear menu, and the application list has a Description column. The Products page added Matcher.

**October 8, 2026**

### [Integration Diagrams journeys](/en/diagrams/introduction)

The Integration Diagrams tab has four sections: Lerian Products, Native rails, Partner interfaces and Market infrastructures. Native rails has the SLC, SILOC and STR journeys for secured credit and daily settlement, with a Lerian column that shows the endpoint or the event of each step between your institution and Lerian, and marks the steps that are still pending. The other sections are in construction. A message index lists each code and its journeys. On rail pages, the official manuals prevail over the diagrams.

**October 8, 2026**

### [Tab layout and Integration Diagrams](/en/diagrams/introduction)

The site regrouped its tabs and removed the Solutions tab and its pages. Platform became a section of Lerian Products, and Interfaces became a section of Brazil Rails, with no change to the addresses of their pages. The site added an Integration Diagrams tab before API Reference.

**October 6, 2026**

### [Tracer reservations use gRPC only in Midaz 4.2.0](/en/products/tracer/integration-guide)

In Midaz 4.2.0, the Ledger reaches Tracer for reservations over gRPC only, on port 4021 by default. The REST reservation operations left the Tracer API reference. Deploy Tracer before the Ledger, and do not roll Tracer back below 4.2.0 while a 4.2.0 Ledger runs.

**October 6, 2026**

### [Pix JD v1.0.0 configuration and upgrade](/en/interfaces/pix-jd/pix-jd-environment-variables)

The Pix JD pages moved to plugin release v1.0.0. In v1.0.0, the Midaz organization, ledger, asset and clearing account come from the systemplane binding and two `tenant_policy/midaz.*` keys, and payments and devoluções require `X-Idempotency`. Follow the new upgrade steps: write the `tenant_policy/midaz.*` keys first, then remove the retired `MIDAZ_*` identity variables.

**October 6, 2026**

### [Payments BTG bill payment flow and consult](/en/interfaces/payments-btg/boleto-and-bill-payment)

The Payments BTG pages added the steps of a bill payment: the ledger reserves the funds before BTG receives the payment. An unknown outcome answers `202` with status `UNCONFIRMED`, the reference added a bill consult operation, and the error list added seven codes and removed `PBP-0209`. Do not resend an `UNCONFIRMED` payment under a new `Idempotency-Key`, and set `CONSULT_AUDIT_HMAC_KEY`: a pod that serves the payment API does not start without it.

**October 6, 2026**

### [TED JD v3.0.1 error format](/en/reference/interfaces/ted-jd/ted-error-list)

In TED JD v3.0.1, every error is an RFC 9457 problem document on `application/problem+json`, and a JD SPB code is on `upstream.code`. Update the error parsing of your integration.

**October 6, 2026**

### [SISBAJUD v1.2.0 license variables](/en/rails/sisbajud/sisbajud-environment-variables)

Lerian SISBAJUD v1.2.0 needs `LICENSE_KEY` and `ORGANIZATION_IDS` in every environment. Set both variables.

**October 6, 2026**

### [Access Manager chart environment name](https://github.com/LerianStudio/helm/tree/main/charts/plugin-access-manager)

The Access Manager Helm page added the environment name. The chart default is `development`. For any environment other than development, staging or local, expose Caradhras over https with a certificate from a public certificate authority. Then point Auth and Identity at that https address.

**October 6, 2026**

### [Streaming Hub v2.3.0 refusals](/en/reference/platform/streaming-hub/streaming-hub-error-list)

In Streaming Hub v2.3.0, a `401` or `403` refusal is a problem document with code `unauthorized` or `forbidden`. The hub answers `503` when Access Manager returns no verdict. Update the error parsing of your integration.

**October 6, 2026**

### [Lerian Console v2.6.0 pages](/en/platform/console/managing-applications)

The Console pages changed to match Lerian Console v2.6.0. The update added pages for Reporter Institutions, TED IN operations, TED JD Accounting Routes and Pix BTG refunds, and covered report parameters and the `Partial failure` status. The update removed the BC Correios Console pages. The Console shows an application's client secret once, when you create the application. Store it then.

**October 6, 2026**

### [JD Courier](/en/interfaces/jd-courier/what-is-jd-courier)

The Interfaces tab and the API Reference added JD Courier. JD Courier lets two or more core banking engines share one JD channel and one ISPB on SPB (TED) and Pix. It runs in BYOC and on Lerian Cloud.

**October 6, 2026**

### [Fee debt in Midaz 4.2.0](/en/products/midaz/fees/fee-debt)

In Midaz 4.2.0, the unpaid part of a deferrable fee on a `/v2` direct transaction can become a fee debt that later `/v2` credits settle, oldest first. Fee debt is off by default, and Valkey must persist its keys.

**October 6, 2026**

### [Access Manager Identity API reference](/en/reference/platform/access-manager/am-identity-apis)

The Identity API reference dropped the partner, scope catalog and user tenant operations. The Access Manager error list added `IDE-0038`.

**October 6, 2026**

### [Consignado v3.7.0](/en/rails/consignado/how-consignado-works)

The Consignado API reference added an operation that reads the cadastro stored with an averbação, and the events reference changed to match what v3.7.0 emits. In Lerian Consignado v3.7.0, the saldo devedor sent to Dataprev is the present value of the unpaid installments.

**October 6, 2026**

### [SPI environment variables](/en/rails/spi/spi-environment-variables)

The SPI environment variables page dropped `BACEN_SPI_SIGNING_KEY_FILE`.

> [!TIP]
>
> For older updates, browse the full archive by year in the Archived section.


# News overview
Source: https://docs.lerian.studio/en/news/news

Latest updates to Lerian products, documentation, and APIs, with release cadence, impact definitions, product filters, and links to the full archive.

Updates to Lerian products, documentation, and APIs. We publish here whenever we close a release cycle, change an API, or ship a documentation update worth flagging.

## Release cadence

***

We deliver continuously, with planning and reviews on a weekly rhythm. **Production releases** are consolidated and rolled out periodically for Lerian Cloud, and we announce each one here as it happens.

We're currently refining this cadence, so timing may change as the process evolves.

## How to read updates

***

Monthly pages are organized by customer impact first. Start with the section that matches your urgency, then use product filters to narrow the list to the products and plugins you use.

| Impact | What it means |
| - | - |
| **Action required** | Your team should update integration code, configuration, validation, tests, or an operational workflow. |
| **Review recommended** | The update can affect how teams understand or use the product, but no immediate migration is required. |
| **No action** | Informational update, documentation cleanup, or public reference correction. |
| **Deprecation** | A capability is being removed or replaced. Plan the migration before the deadline. |

## Product filters

***

Entry tags are reserved for product and plugin names, such as **Midaz**, **Matcher**, **Flowker**, **Tracer**, **TED**, **Pix**, and **Access Manager**.

Use filters to answer "does this affect a product I use?". Use the monthly section headings to answer "do I need to act?".

## API reference updates

***

When a release note reports an API reference update, the default assumption is that the documentation changed and product behavior did not. We call out product behavior changes separately in the impact section and in the "What you need to do" guidance.


# 2024 in review
Source: https://docs.lerian.studio/en/news/releases-2024

Full archive of Lerian product and documentation release notes published throughout 2024, organized by month with links to each release and update.

**November 6th, 2024**

### [New Documentation Release: Portfolios Domain](/en/news/2024/new-documentation-release-portfolios-domain)

The documentation for the **Portfolios Domain** is now live. It provides a complete overview and detailed guides for managing portfolios within Midaz.


# 2025 in review
Source: https://docs.lerian.studio/en/news/releases-2025

Full archive of Lerian product and documentation release notes published throughout 2025, organized by month with links to each release and update.

**September 19, 2025**

### [Midaz Release – Cycle 3](/en/news/2025/midaz-cycle-3)

On September 19, 2025, we released **Cycle 3 of Midaz**, introducing new capabilities across Transactions and Reporter.

**August 7th, 2025**

### Deprecation Notice

As of August 5th, 2025, Midaz v2.x has entered **maintenance mode** and is now officially **deprecated**.

**July 28th, 2025**

### [Documentation Update #3: End of Release Cycle](/en/news/2025/documentation-update-3)

We’ve closed the latest release cycle with a major round of updates across the Lerian documentation. In this version, flexible routing rules, smarter plugin workflows, and a more intuitive site structure make it easier to build, test, and grow with confidence.

**July 4th, 2025**

### [Smart Templates: new CADOC examples available](/en/news/2025/smart-templates-new-cadoc-examples-available)

We’ve expanded our documentation with detailed examples on how to generate **CADOC 4010**, **4016**, and **4111** reports using the [**Reporter**](/en/products/reporter/what-is-reporter).

**June 2nd, 2025**

### [Midaz Ledger and Console: Unified Installation](/en/news/2025/midaz-ledger-and-console-unified-installation)

Starting May 30, 2025, **Midaz Ledger** and **Midaz Console** are now part of the same repository. This means a single installation process for both components, which saves you time and simplifies setup.

**May 30th, 2025**

### [Documentation Update #2: End of Release Cycle](/en/news/2025/documentation-update-end-of-release-cycle)

We’ve wrapped up the release cycle with a fresh batch of documentation updates. The updates bring something new for building integrations, deploying infrastructure, and getting started with Midaz.

**May 2nd, 2025**

### [Midaz API Updates](/en/news/2025/midaz-api-updates)

A few changes just landed in the Midaz API:

**May 2nd, 2025**

### [Managing Transactions in Midaz Console](/en/news/2025/managing-transactions-in-midaz-console)

We’ve just updated the Midaz Console documentation with a set of user guides to help you manage Transactions.

**April 26th, 2025**

### [Documentation Update #1: Midaz Console](/en/news/2025/documentation-update-midaz-console)

We’ve refreshed the documentation to reflect recent changes in the Console interface:

**April 14th, 2025**

### [Fee Engine documentation](/en/news/2025/fee-engine-documentation)

We’ve just released the first version of the Fee Engine documentation. This plugin helps you calculate and apply fees based on rules you can fully customize.

**April 9th, 2025**

### [Access Manager documentation](/en/news/2025/access-manager-documentation)

We’ve just released the first version of the Access Manager documentation. It covers the Auth and Identity plugins, usage guides, and the Auth and Identity API references.

**April 4th, 2025**

### [How to Update Midaz](/en/news/2025/how-to-update-midaz)

We've just added a new page to the documentation with instructions for updating Midaz, both locally and via Helm.

**March 24th, 2025**

### [Authentication Change](/en/news/2025/authentication-change)

Starting from **Midaz v1.49**, authentication is **no longer required in the Community version**. You can make requests to the Midaz APIs directly.

**February 24th, 2025**

### [Our Documentation Hub Just Got an Upgrade.](/en/news/2025/our-documentation-hub-just-got-an-upgrade)

Today we launch a new version of our documentation portal. This update improves how you access, navigate, and interact with our documentation.

**January 31st, 2025**

### [Product -> Segment](/en/news/2025/product-segment)

To make our structure easier to understand, we rename what was previously called Products in Midaz.

**January 7th, 2025**

### [New Documentation Structure](/en/news/2025/new-documentation-structure)

**Introducing Our New Documentation Structure**


# Answer one round of proposed refinements
Source: https://docs.lerian.studio/en/reference/platform/narya/answer-one-round-of-proposed-refinements

/en/openapi/v3-current/narya.yaml post /v1/refinements/rounds/{roundId}/answer
Records what a person decided about one round and writes what they allowed. The consent unit is the ROUND — the whole proposed diff, with per-item marks inside it — because one ask per item at volume is reflex approval and makes the gate decorative.

The marks name items by INDEX, into the item list exactly as the round sent it. The engine ordered those items, so a client that reordered them would post somebody's approval onto a different edit with a straight face — `answerQuestion`'s own indexing rule, for the same reason. `accept-round` carries no marks at all: saying "all of it" must not require enumerating the round back.

A rejection writes no refinement, and the message a person types is not decoration: it reaches the next review as a correction, so the same fact is not proposed again tomorrow night.



# Ask to widen what a fact applies to
Source: https://docs.lerian.studio/en/reference/platform/narya/ask-to-widen-what-a-fact-applies-to

/en/openapi/v3-current/narya.yaml post /v1/refinements/{refinementId}/promote
Asks a person to widen one repository-scoped fact to everywhere this owner works, and WRITES NOTHING. A fact was allowed in one checkout; "everywhere I work" is a different claim, so it is put to a person again with the fact's own text, its provenance, its citations and — for a capability that executes — its program and the hash it was allowed under.

It answers 202 with the round that is now standing, exactly as `proposeRefinement` does, and the widening happens when somebody answers that round through `answerRefinementRound`. There is no destination to name: the ledger keeps two scopes, so widening has one direction.

Its sibling `demoteRefinement` is the other direction and does not ask, because a restriction composes where a permission never does.



# List the calls Lerian's platform made to this home
Source: https://docs.lerian.studio/en/reference/platform/narya/every-time-lerian-s-platform-reached-this-home

/en/openapi/v3-current/narya.yaml get /v1/platform/accesses
The calls Lerian's control plane made to this home on its own credential, as this home recorded them, newest first. Each row names the operation, when it ran, who the plane said it was, and how it ended. A row carries no session, repository, title or argument.

Any member of this home may read this list, and no permission is needed. Lerian's platform credential cannot read it.



# Narya host API error list
Source: https://docs.lerian.studio/en/reference/platform/narya/host-api-error-list

Every error code the Narya host answers, over HTTP or on a finished turn: when the host writes it, and what to do next.

The host answers one error envelope: `code`, `title` and `message`. Codes are `NRY-` and four digits. Quote the code when you report a problem. The [host API overview](/en/reference/platform/narya/host-api-overview) describes the transport these answers arrive on.

```json theme={null}
{ "code": "<code>", "title": "<title>", "message": "<message>" }
```

## Codes the host answers

***

The `message` always names the specific thing that failed. Read it before you act on the row below.

| Code | HTTP status | When the host answers it | What to do |
| :- | :- | :- | :- |
| NRY-0000 | 400 | The request is malformed. The body is not valid JSON, or a value does not bind to its declared type. | Correct the request encoding. The message names the part that failed to bind. |
| NRY-0001 | 422 | A request body failed validation. | Correct the properties the message names, then send the request again. |
| NRY-0002 | 404 | No session on this host carries the `sessionId` in the request. | List sessions to get a valid id. |
| NRY-0003 | 409 | The target session is archived. An archived session accepts no new work. | Branch the session at an entry to continue from its transcript, or address an active session. |
| NRY-0004 | 409 | The target cannot accept the request in its current state. | Read the message and resolve the conflict it describes. |
| NRY-0006 | 409 | Two packages claim the same replaceable slot. Nothing was installed. A package job that fails this way carries the code in its `error` field. | Remove or disable one claimant, then install again. The message names both. |
| NRY-0007 | 409 | A package build failed. The binary that was already serving is intact. A package job that fails this way carries the code in its `error` field. | Read the job's error, correct or remove the package, then install again. |
| NRY-0009 | 404 | The addressed peer session is gone from this host. | List peers to refresh the set of addressable sessions, then send the message again. |
| NRY-0010 | 422 | A workflow script failed validation before the run started. | Correct the script errors the message names, then start the run again. |
| NRY-0011 | 401 | The request carries no valid token. | Sign in with `narya login`, then send the request again. A host with no identity provider refuses every token, and the message names the settings to add. |
| NRY-0012 | 500 | The local store is unavailable, or it failed its integrity check. The host refuses writes rather than work on a damaged store. | Check disk space and store integrity, correct the cause, then restart the host. |
| NRY-0013 | 404 | This home has no enabled extension with that name, or the extension does not expose the operation. | List this home's extensions, and ask the extension's author which operations it exposes. |
| NRY-0015 | 404 | The named resource does not exist on this host. Packages, package jobs, agent recipes, skills, commands, lanes, monitors, providers, schedules, workflow runs, inter-session asks and transcript entries all answer with this code. | List the collection the resource belongs to, and use a name or id from it. |
| NRY-0016 | 409 | A package with this name is already installed. | Remove the installed package first, or install under another name. |
| NRY-0017 | 409 | An enable or a disable swapped the binary, and then failed to confirm the package row. | The change already applies to the binary that runs now. Send the request again, or restart the host so start-up reconciliation confirms the row. |
| NRY-0020 | 412 | A conditional write carried an `ifMatchesSha256` that the stored value no longer hashes to. Another client wrote the row first, and nothing was written. | Read the resource again to see what it holds now. A client that clears a draft it sent can treat this as success. |
| NRY-0021 | 500 | The host could not carry out the request on this machine. A process it had to start did not start, or an operation failed for a reason with no more exact code. | Nothing about the request was wrong, so send it again. |
| NRY-0022 | 500 | A rewind that restores named files stopped part-way. Some files are back and the rest are untouched. | Read the message for the files that moved. The working tree as it stood before the attempt is kept as a restore point. |
| NRY-0023 | 500 | A rewind of the conversation and the files branched the conversation, and then failed to restore the files. The branch is real. | Continue in the session the message names, then rewind the files alone from the original session at the same moment. |
| NRY-0024 | 413 | A transcript import ran past a size ceiling. | Read the message for the ceiling it names, then send a smaller transcript. |
| NRY-0025 | 409 | A blocking ask between sessions was refused, because granting it would close a loop of sessions that wait on each other. | Answer or expire the ask already in flight, or send a one-way message instead. The message names both sessions. |
| NRY-0026 | 409 | A stream resumed from a `Last-Event-ID` that names an event newer than anything this store holds. | Resume with no `Last-Event-ID`, then read state again through the `GET` operations. |
| NRY-0027 | 413 | The files on one message weigh more together than one supplier request can carry. Nothing was written. | Send fewer files on the message, or smaller ones. The message names the ceiling in bytes. |
| NRY-0028 | 403 | The caller is signed in and the request is refused. When the operation needs a permission, the message names it. | For a named permission, an administrator grants it on your role in Access Manager, and it takes effect on your next token. If the message says the host could not reach Access Manager, send the request again shortly. |
| NRY-0029 | 503 | The organisation's home did not answer. | Read the message: it says whether the work is queued or whether to send the request again. Publishing the same session again creates a second share. |
| NRY-0030 | 403 | The token names an organisation that this home does not serve. | Point `NARYA_HOME` at your organisation's home, or sign in to this home with `narya login`. |
| NRY-0031 | 410 | The share was revoked. | Publish the session again to create a new share. A revoked share is never resumed. |

## Codes a failed turn carries

***

A turn that fails ends with a `turn-finished` event. Its `payload.error` carries the same envelope as an HTTP error. Three codes arrive that way, and the host never answers them as an HTTP status.

| Code | Event | When the host writes it | What to do |
| :- | :- | :- | :- |
| NRY-0008 | `turn-finished` | The model supplier the turn needed has no usable credential. It is missing, expired or refused, or the keyring is unavailable. | Sign in with `narya auth login <provider>`, then send the message again. The message names the remedy that fits. |
| NRY-0018 | `turn-finished` | The turn could reach no model supplier. The session names no provider, or it names one this host has no record of. | Sign in with `narya auth login <provider>`, or set `default_model` in the host's `config.toml`, then send the message again. `narya providers` lists what this machine can use. |
| NRY-0019 | `turn-finished` | The turn failed for a reason with no more specific code. The message carries the cause. Narya removes known credential shapes and URL secrets from it, and replaces your home directory with `~`. | Read the message. |


# List the rounds waiting on a person
Source: https://docs.lerian.studio/en/reference/platform/narya/list-the-rounds-waiting-on-a-person

/en/openapi/v3-current/narya.yaml get /v1/refinements/rounds
The rounds standing on the consent surface, newest first. It is the recovery road for a client that was not attached when `refinement-proposed` went out — a round proposed by last night's scheduled fire is answered the next morning, and an announcement nobody heard must not be the only way to find it.

A round is NEVER expired by the boot-recovery pass, unlike a permission or a question: nothing is blocked behind it, so a host restarting leaves it exactly where it was.



# Narrow a fact to one checkout
Source: https://docs.lerian.studio/en/reference/platform/narya/narrow-a-fact-to-one-checkout

/en/openapi/v3-current/narya.yaml post /v1/refinements/{refinementId}/demote
Narrows one of this owner's global facts to the single repository it should keep applying in, and does it ON THE SPOT: nothing is asked, because narrowing what narya may do is never the dangerous direction and making cleanup expensive is how a ledger nobody prunes gets built. The log is the undo.

IT IS ALSO HOW A WIDENING IS UNDONE, in one gesture rather than two: the general row narrows back, the row it superseded stays exactly where it is, and the ledger keeps saying where the fact was first learned. Rolling the row back instead takes the fact away entirely, which is the delete.

It answers 200 with the row as the narrowing left it rather than 204, so `narya learned demote --json` has something to print.



# Read one refinement whole
Source: https://docs.lerian.studio/en/reference/platform/narya/read-one-refinement-whole

/en/openapi/v3-current/narya.yaml get /v1/refinements/{refinementId}
The whole row: its text, its citations, the authored script IN FULL where there is one, and the append-only log of everything that has happened to it. The log is what answers "who taught narya this and who took it away" — nothing in it is ever rewritten.



# Read one round whole, to answer it
Source: https://docs.lerian.studio/en/reference/platform/narya/read-one-round-whole-to-answer-it

/en/openapi/v3-current/narya.yaml get /v1/refinements/rounds/{roundId}
Every item of one round, at the indices an answer names them by: the kind, the reach it asks for, the title, the body IN FULL, the turns it stands on, the definition it would replace, and — where narya authored a program — that program IN FULL.

NOTHING HERE IS ELIDED, and that is the operation's whole reason. An authored script must be shown to be READ rather than only named: a person cannot consent to what they were not shown, and what they consent to is what the confined runtime later runs, byte for byte. A client that drew a digest, a length or a "show more" would be offering approval over text nobody read.

An item's `kind`, `scope` and `action` are the MODEL's own words and are deliberately not the ledger's enums: the review keeps them untyped, and they become typed at the moment a person's answer turns a proposal into a row. A client displays them and never resolves them.



# Teach narya something, and ask a person to allow it
Source: https://docs.lerian.studio/en/reference/platform/narya/teach-narya-something-and-ask-a-person-to-allow-it

/en/openapi/v3-current/narya.yaml post /v1/refinements
Proposes ONE refinement. It creates a pending item — a one-item round on the consent surface, provenance `api` and the calling actor beside it — and it activates nothing at all. The prompt this host assembles is byte-identical before and after this call, and that rule is pinned by a test rather than stated here.

SEEDING IS NEVER ACTIVATING, and this operation is the one that must never become a back door: what a client proposes passes exactly the human consent anything the loop proposes passes. A person answers it in a client through `POST /v1/refinements/rounds/{roundId}/answer`, and the round the answer names is the one this call returns.

At least one citation is required. An edit citing no turn never becomes a row — evidence is a structural control and not a request for good behaviour.



# Undo what narya learned
Source: https://docs.lerian.studio/en/reference/platform/narya/undo-what-narya-learned

/en/openapi/v3-current/narya.yaml post /v1/refinements/{refinementId}/rollback
Undoes a refinement and records that it did. THIS IS ALSO THE DELETE: "archive, never destroy" holds here, so the row stops firing, keeps its provenance and its evidence, and stays in the listing — walking backwards from a strange behaviour to the fact that caused it is exactly what the row is for.

With no `toEventId` the whole history is inverted, back to the creation, and the row lands in `rolled-back`. Naming an event undoes down to and including that event, which is also how a rollback is itself undone: undo and redo are one verb aimed at different events.

It answers 200 with the row as the rollback left it rather than 204, so `narya learned rollback --json` has something to print.