Best practices

Apply proven patterns when integrating Bank Transfer — show fees before confirmation, handle settlement windows, and reduce customer complaints.

This guide covers the key decisions your team makes when you integrate Bank Transfer. It also gives the best practices for a reliable and compliant customer experience.

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 initiate step returns the fee amount before any funds move. Use this 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 to Friday, 06:30–17:00 (Brasília time). When a customer starts a transfer outside these hours, do not show only 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 you call the API.

You do not need to maintain your own holiday list. The plugin blocks weekends and BACEN holidays automatically. The runtime source of truth is the bacen_holidays table, which the plugin seeds for 2026–2028. The daily refresher runs by default and re-applies the built-in seed. It does not fetch live from ANBIMA, because ANBIMA publishes only a legacy spreadsheet that machines cannot read. The seed stays the authoritative source until that changes.

When a holiday rejects a transfer, show that reason to the customer. Do not replicate the calendar on the client. Trust 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. Show it before they attempt a transfer that the plugin rejects. 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 (customer-facing reference)
• controlNumber (JD SPB reference, for TED OUT only)

When you provide this information early, you reduce “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. Do not 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. Make sure your privacy policy explicitly covers financial transaction data. Do not log CPF/CNPJ in plain text. Mask it in interfaces as ***.***.***-00.

A dedicated anonymization endpoint for LGPD right-to-erasure requests will arrive in a future release. Until then, coordinate anonymization requests with your database administration team.

Data retention

The plugin never deletes or expires transfer records, so you own their retention. Retain transfer and audit data for at least 5 years, per BACEN record-keeping requirements for financial institutions.

Data type	Retention period
Transaction records	5 years (BACEN requirement)
Application logs	90 days
Audit data	5 years (anonymized after 2 years)

Audit trail and reconciliation

Every transfer generates two reference numbers you must store:

Field	What it is	When to use
transferId	Internal Lerian identifier	API lookups, support cases
confirmationNumber	User-readable reference	Receipts, customer communication
controlNumber	JD 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 to Friday, 06:30–17:00 (Brasília time, UTC-3). The plugin enforces this window by default. An operator can adjust the open and close times at runtime through systemplane, within BACEN limits. Treat 06:30–17:00 as the norm and 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 you go 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 — Deploy your webhook endpoint and make it reachable before you go live. Transfer events start firing immediately on the first real transaction.
• 24-hour expiry handled — An initiated transfer expires if the customer does not confirm it 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 you call the API. This reduces 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.

Scenario	Customer-facing message	Recovery
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.