Skip to main content
This guide covers the key decisions your team needs to make when integrating Bank Transfer, and the best practices to ensure a reliable, compliant experience for your customers.

​
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 two-step flow (initiate → process) is designed for this: your system receives the fee amount before any funds move. Use that 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–Friday, 06:30–17:00 (Brasília time). When a customer tries to initiate outside those hours, don’t just surface 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 calling the API. There’s no need to maintain your own holiday list — the plugin already blocks weekends and BACEN holidays automatically. The runtime source of truth is the bacen_holidays table, seeded for 2026–2099. The daily refresher runs by default and re-applies the built-in seed; it does not fetch live from ANBIMA, because ANBIMA only publishes a legacy non-machine-readable spreadsheet — the seed is the authoritative source until that changes. If a transfer is rejected due to a holiday, surface that reason to the customer. Instead of replicating the calendar on the client, rely on 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 — before they attempt a transfer that will be rejected. 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 (your internal reference)
  • controlNumber (JD SPB reference, for TED OUT only)
Providing this information proactively reduces “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. Don’t make customers refresh or wonder if their transfer went through. See 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. Ensure your privacy policy explicitly covers financial transaction data. Avoid logging CPF/CNPJ in plain text; mask it in interfaces as ***.***.***-00. A dedicated anonymization endpoint for LGPD right-to-erasure requests is planned for a future release. Until then, coordinate anonymization requests with your database administration team.

​
Data retention

Transfer data must be retained for 5 years per BACEN Resolution 4.753/2019. This is not configurable and cannot be shortened.
Data typeRetention period
Transaction records5 years (BACEN requirement)
Application logs90 days
Audit data5 years (anonymized after 2 years)

​
Audit trail and reconciliation

Every transfer generates two reference numbers you must store:
FieldWhat it isWhen to use
transferIdInternal Lerian identifierAPI lookups, support cases
confirmationNumberUser-readable referenceReceipts, customer communication
controlNumberJD SPB reference (TED OUT only)BACEN audit trail, regulatory reporting
Keep both the transferId and confirmationNumber in your own records for reconciliation. For TED OUT, also store the controlNumber.

​
Operating hours

BACEN mandates that TED operates Monday–Friday, 06:30–17:00 (Brasília time, UTC-3). The plugin enforces this window by default; the open/close times are operator-adjustable at runtime (within BACEN limits) via systemplane, but treat 06:30–17:00 as the norm. Build your UX around it — see Handle operating hours gracefully above.
P2P transfers are not subject to operating hour restrictions and work 24/7.

​
Integration checklist

Before going 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 — Your webhook endpoint must be deployed and reachable before you go live. Transfer events start firing immediately on the first real transaction.
  • 24-hour expiry handled — An initiated transfer expires if not confirmed within 24 hours. If your flow allows a customer to start a transfer and return later, handle the expiry case explicitly.
  • Exponential backoff on 5xx errors — Implement retry with backoff (e.g., 2s, 4s, 8s) when the response is 503 or 500. JD SPB unavailability surfaces as 503 with a raw JD vendor code (TRANSPORT, ACE95, …); 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 calling the API. Reduces unnecessary failed API calls and gives a better customer experience.
  • Both transferId and confirmationNumber stored — Required for reconciliation and audit. For TED OUT, also store controlNumber.

​
Error handling

Use these error scenarios to map API errors to customer-friendly messages and define the correct recovery path.
ScenarioCustomer-facing messageRecovery
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)“Your account doesn’t have enough balance for this transfer.”Recoverable — customer adds funds or reduces the amount
Daily limit reached (BTF-0011)“You’ve reached your daily transfer limit of R$ [X]. Limit resets at midnight.”Recoverable — wait for reset
Invalid recipient (BTF-0500)“Destination account not found. Please check the account details and try again.”Recoverable — customer corrects details
Service unavailable (TRANSPORT, HTTP 503, raw JD code)“Transfer service is temporarily unavailable. Please try again in a few minutes.”Recoverable — retry with backoff
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.