Skip to main content
The TED plugin is a self-contained service that handles all communication with Brazil’s SPB network (via JD Consultores). It manages the full transfer lifecycle — from fee calculation to settlement confirmation — so your team doesn’t need to interact with JD directly.

​
What the plugin handles for you

  • Sends outgoing TEDs to any Brazilian bank (TED OUT)
  • Receives and credits incoming TEDs automatically (TED IN)
  • Processes instant internal transfers between accounts (P2P)
  • Calculates and applies fees automatically before the customer confirms
  • Detects and prevents duplicate transfers within a configurable window
  • Signs messages with your institution’s digital certificate, as required by BACEN
  • Retries failed operations automatically
  • Notifies your system via webhooks in real time on every status change

​
How TED OUT works

TED OUT uses a two-step flow so the customer can review the fee before confirming.

​
Step 1 — Initiate

Endpoint: POST /v1/transfers/initiate
1
Your system calls the plugin with the transfer details (amount, recipient, 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 doesn’t confirm within that window, it expires automatically.

​
Step 2 — Process

Endpoint: POST /v1/transfers/process
1
Your system calls the plugin with the initiationId to confirm.
2
The plugin checks daily and monthly limits and verifies available balance.
3
The plugin reserves funds in Midaz (hold) and sends the signed message to JD Consultores.
4
JD routes the transfer to the destination bank via 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 via JD Consultores.
  2. The plugin polls JD every 30 seconds 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 confirming the credit.
TED IN receiving is disabled by default. Enable it per organization via the Admin API once your JD credentials and polling worker are configured.

​
How P2P works

P2P transfers move funds between two accounts within the same organization, without going through the SPB network. Settlement is instant.
  1. Your system calls the plugin with sender account, recipient account, and amount.
  2. The plugin calculates the fee (if configured) and presents it for confirmation.
  3. Upon confirmation, the plugin executes the transfer in Midaz.
  4. Both accounts are updated immediately. Your system receives a webhook.

​
Deployment models

SaaS (managed by Lerian) Lerian maintains the JD Consultores connection and certificate. You configure your organization’s settings — limits, fees, webhooks — via the Admin API. No infrastructure work required. BYOC (bring your own credentials) Your institution provides JD Consultores credentials and the RSA private key for message signing. DevOps configures these via environment variables. You have full control over the JD connection and can run the plugin in your own infrastructure. See TED configuration for the full list of environment variables.

​
Integration with Midaz

All financial movements go through the Midaz ledger. The plugin creates transactions in Midaz for every transfer:
  • TED OUT — funds are held when the transfer is confirmed (process step, via pending: true), then debited upon settlement confirmation.
  • TED IN — funds are credited after the transfer is validated and confirmed by JD.
  • P2P — a single Midaz transaction debits the sender and credits the recipient atomically.
This means every transfer is fully reflected in your Midaz ledger with a corresponding transaction record. See TED data and reporting for the fields available for reconciliation.

​
For developers

​
Architecture

The plugin uses Hexagonal (Ports and Adapters) architecture combined with CQRS. Business logic is isolated from infrastructure, making it straightforward to add new adapters (e.g., a different SPB provider) without changing core behavior.
Ted Architectural Pattern

​
Duplicate detection

The plugin generates an idempotency key from SHA256(organizationId + senderAccountId + recipient + amount) and stores it in Redis with a configurable TTL (default: 60 seconds). Duplicate requests within the window are rejected with 409 Conflict and error code BTF-0012.

​
Multi-tenant data isolation

All database queries are filtered by organization_id. Redis cache uses per-tenant key prefixes (tenant:{tenantId}:{key}) to prevent data leakage across organizations. The tenantId is extracted from the JWT claim and validated against the X-Tenant-Id HTTP header on every request.

​
Observability

The plugin exposes Prometheus metrics, structured JSON logs, and OpenTelemetry traces. Health endpoints (GET /health/live, GET /health/ready) are available unauthenticated for Kubernetes liveness and readiness probes. These are primarily relevant for BYOC deployments.
Health endpoints are unauthenticated by design (for K8s probe compatibility). In BYOC deployments, restrict access to these endpoints at the network level (e.g., via ingress rules or security groups) to prevent exposing internal dependency status to the public internet.