Skip to main content
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.

​
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 the bacen_holidays calendar (static seed for 2026–2028, live ANBIMA refresher pending)
  • Signs messages with your institution’s digital certificate, as BACEN requires
  • Retries failed operations automatically
  • 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

Endpoint: POST /v1/transfers/initiate
1
Your system calls the plugin with the transfer details: amount, recipient, and sender account.
2
The plugin validates the sender account, checks operating hours, and runs duplicate detection.
3
The plugin calculates the fee and returns an initiationId with the calculated amounts.
4
Your system shows the fee to the customer for confirmation.
The initiation is valid for 24 hours. If the customer does not confirm within that window, it expires.

​
Step 2 — Prepare signing (optional)

Endpoint: POST /v1/transfers/signing/prepare
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

Endpoint: POST /v1/transfers/process
1
Your system calls the plugin with the initiationId to confirm.
2
The plugin checks the daily and monthly limits and the available balance.
3
The plugin reserves funds in Midaz (a hold) and sends the signed message to JD Consultores.
4
JD routes the transfer to the destination bank over the SPB network.
5
The plugin receives the settlement confirmation from JD and finalizes the records.
6
Your system receives a webhook with the final status.

​
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.
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 organization. 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 supports two deployment models. The DEPLOYMENT_MODE environment variable selects the model.

​
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. In saas mode, the plugin runs as a multi-tenant service. The multi-tenancy platform service resolves the tenant identity, JD credentials, webhook secrets, and selected settings at runtime. This mode requires the MULTI_TENANT_* variables and AWS_REGION, and the plugin uses them actively.

​
BYOC (bring your own credentials)

In BYOC deployments, your institution provides the JD Consultores credentials and the RSA private key that signs messages. Your DevOps team sets these values through environment variables. You keep full control of the JD connection, and the plugin runs entirely in your own infrastructure. BYOC is the default deployment mode (byoc). The plugin loads all configuration from environment variables at startup, including JD credentials, webhook secrets, and fee settings.

​
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. For these, the plugin falls back to the ORGANIZATION_ID environment variable.
In byoc mode, the plugin ignores the multi-tenancy variables (MULTI_TENANT_*) and AWS_REGION.
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 after JD validates and confirms the transfer.
  • P2P — a single Midaz transaction debits the sender and credits the recipient atomically.
Every transfer maps to one transaction record in your Midaz ledger. 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.
Ted Architectural Pattern

​
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 with a configurable TTL (default 300 seconds, set by DUPLICATE_GUARD_TTL_SEC). 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.

​
Multi-tenant data isolation

Tenant isolation comes from per-tenant database resolution in the multi-tenancy platform. 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 (tenant:{tenantId}:{key}). Business tables use the Midaz organization fields only for business-scope authorization inside the resolved tenant.

​
Observability

The plugin exposes Prometheus metrics, structured JSON logs, and OpenTelemetry traces. It also exposes unauthenticated liveness and readiness probes for Kubernetes orchestration. These probes matter mainly for BYOC deployments.
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.