How the plugin works

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 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)
• Calculates and applies fees before the customer confirms
• 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

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)

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

​

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.

​

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 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 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.

​

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.