Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt

Use this file to discover all available pages before exploring further.

TED IN allows your institution to receive transfers from any Brazilian bank automatically. No action is required from your team — the plugin handles detection, validation, and crediting. When a customer at another bank sends a TED to your institution, the funds appear in the recipient’s account within minutes.

​
How it works

  1. A customer at another bank initiates a TED transfer addressed to one of your institution’s accounts
  2. Every 30 seconds, the plugin polls the JD SPB network for new incoming transfers
  3. The recipient account is validated against your CRM using the document number in the transfer message
  4. The amount is credited to the recipient’s account automatically (minus the cashin fee, if configured)
TED IN flow diagram

​
Detection and processing timeline

What your customer experiences after the origin bank sends the transfer:
TimeWhat happens
T+0sOrigin bank submits the transfer to the BACEN network
T+30sPlugin detects the transfer; status moves to RECEIVED
T+32sRecipient account is looked up and confirmed; status moves to PROCESSING
T+35sAmount is credited to the recipient’s account; status moves to COMPLETED
T+36sWebhook notification is sent to your system
Typical SLA: Under 1 minute from the moment the origin bank sends the transfer.

​
Transfer states

StateWhat it means for the recipient
RECEIVEDTransfer detected on the network; being processed
PROCESSINGRecipient account confirmed; credit is being applied
COMPLETEDFunds have arrived in the recipient’s account
FAILEDRecipient could not be identified; funds returned to sender

​
Receiving fee (cashin)

Your organization can optionally charge a fee on incoming transfers. When enabled, the fee is deducted from the amount before it is credited — the recipient receives the net amount. The fee amount and configuration are set per organization via the Fees Engine. Formula: credited amount = transfer amount − fee Example: a R1,000.00transferwithaR1,000.00 transfer with a R2.50 fee results in R$997.50 credited to the recipient’s account. This is the opposite of TED OUT, where the fee is added on top and the sender pays more.

​
What happens when a recipient isn’t found

If the document number in the incoming transfer cannot be matched to an account in your CRM, the transfer is automatically returned to the origin bank. The sending customer receives their money back. No manual intervention is needed and no funds remain unaccounted for. The transfer record is marked as FAILED with the reason “Recipient account could not be identified.”

​
Querying received transfers

Use the List Transfers endpoint to retrieve all incoming transfers. Filter by type=TED_IN to view only received transfers. Endpoint: GET /v1/transfers Response (key fields): 
{
  "data": [
    {
      "transferId": "019c96a0-ab20-7def-a1b2-1f2a3b4c5d6e",
      "type": "TED_IN",
      "status": "COMPLETED",
      "amount": 5000.00,
      "feeAmount": 0.00,
      "totalAmount": 5000.00,
      "recipientHolderName": "Empresa ABC Ltda",
      "createdAt": "2026-01-21T10:15:00-03:00"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "totalCount": 150,
    "hasNextPage": true
  }
}
For full query parameter options, see the List Transfers reference.

​
Operational endpoints

Two operator endpoints control the TED IN polling loop. They are intended for scripts and runbooks, not for end-user traffic.
EndpointPurpose
POST /v1/transfers/ted-in/pollManually trigger the JD poller that normally runs on a 30s cron. Useful after an incident window or to validate JD connectivity. Does not require X-Organization-Id since it operates across the polling worker, not a tenant.
POST /v1/transfers/ted-in/replayReplay a previously fetched TED IN message that failed downstream credit processing. Requires X-Organization-Id and idempotency.
For request body, response, status codes, and error codes, see the TED OpenAPI specification (operations triggerTEDInPoller and replayTEDInPoller).

​
Three distinct dead-letter paths

The plugin uses three separate failure stores. They are not interchangeable and should be monitored independently:
  • JD parse failures — stored in jd_incoming_parse_failures. The message arrived from JD but could not be interpreted (malformed XML, unknown message type). Manual triage required.
  • Undeliverable inbound transfers — stored in undeliverable_incoming_transfers. Parsing succeeded, but the credit could not be applied (e.g., recipient account not found). May result in an automatic devolução to the origin bank.
  • Webhook DLQ — the retry queue for failed outbound webhook deliveries, exposed via /v1/transfers/webhooks/dlq. Unrelated to TED IN ingestion; this is the outbound event channel to integrating clients.

​
Webhooks

Configure a webhook to get real-time notifications when transfers arrive. The transfer.incoming.completed event fires as soon as a transfer is credited. See Webhooks for setup and event payload details.

​
Reconciliation

For accounting and finance reconciliation, each transfer record includes the following fields:
FieldUsage
controlNumberJD SPB control number — unique per transfer, used for interbank reconciliation
transferIdLerian internal identifier
createdAtTimestamp when the transfer was detected
completedAtTimestamp when funds were credited
Transfer history is retained for 5 years, as required by BACEN regulations.

​
Processing guarantees

The plugin is designed so that no transfer is lost and no transfer is credited twice:
  • No duplicate credits — each transfer message carries a unique sequence number; the plugin rejects any attempt to process the same message more than once
  • Automatic retry on failure — transient errors (such as a momentary service interruption) are retried with exponential backoff before any failure state is recorded
  • Dead-letter queue for unresolvable issues — if a transfer cannot be processed after all retries, it is moved to a dead-letter queue for manual review, ensuring nothing is silently dropped