Pular para o conteúdo principal
Este guia cobre as principais decisões que seu time precisa tomar ao integrar o Bank Transfer, e as boas práticas para garantir uma experiência confiável e em conformidade para seus clientes.

​
Decisões de produto

Estas são escolhas que seu time de produto faz na experiência voltada ao cliente. Elas afetam diretamente a satisfação do cliente e o volume de suporte.

​
Exiba a tarifa antes do cliente confirmar

O fluxo de duas etapas (initiate → process) foi projetado para isso: seu sistema recebe o valor da tarifa antes de qualquer movimentação de fundos. Use esse intervalo para exibir uma tela de confirmação clara: 
Confirmar transferência

Destinatário: Maria Silva — Bradesco (237)

Valor:    R$ 1.000,00
Tarifa:       R$ 1,50
─────────────────────
Total:    R$ 1.001,50

[ Cancelar ]        [ Confirmar ]
Isso reduz reclamações e cancelamentos de clientes surpreendidos com tarifas após a conclusão.

​
Trate os horários de funcionamento com clareza

O TED OUT está disponível de segunda a sexta-feira, das 06:30 às 17:00 (horário de Brasília). Quando um cliente tentar iniciar uma transferência fora desse horário, não exiba apenas um erro — informe quando ele poderá tentar novamente: 
Transferências TED estão disponíveis de segunda a sexta-feira, das 06:30 às 17:00.
Próximo horário disponível: segunda-feira às 06:30.
Para evitar chamadas desnecessárias, valide os horários de funcionamento no lado do cliente antes de chamar a API. Não é necessário manter sua própria lista de feriados — o plugin já bloqueia automaticamente fins de semana e feriados do BACEN. A fonte da verdade em runtime é a tabela bacen_holidays, com seed para 2026–2099. O refresher diário roda por padrão e reaplica a seed embutida; ele não busca dados em tempo real da ANBIMA, porque a ANBIMA só publica uma planilha legada não legível por máquina — a seed é a fonte autoritativa até que isso mude. Se uma transferência for rejeitada por feriado, exponha esse motivo ao cliente. Em vez de replicar o calendário no cliente, confie no plugin como fonte da verdade para evitar inconsistências ao longo do tempo.

​
Comunique os limites de transferência antes que os clientes os atinjam

Exiba o limite diário restante do cliente em sua interface de transferência — antes que ele tente uma transferência que será rejeitada. Por exemplo: 
Limite diário: R$ 50.000,00
Utilizado hoje: R$ 45.000,00
Disponível:    R$ 5.000,00

​
Exiba comprovantes após a conclusão

Após a conclusão de uma transferência TED OUT ou P2P, exiba — ou ofereça para download — um comprovante com:
  • Data e hora da transferência
  • Dados do remetente e destinatário
  • Valor, tarifa e total
  • confirmationNumber (sua referência interna)
  • controlNumber (referência JD SPB, somente para TED OUT)
Fornecer essas informações proativamente reduz contatos de suporte do tipo “minha transferência foi concluída?”.

​
Mantenha os clientes informados em tempo real

Use webhooks para enviar atualizações de status da transferência para sua interface assim que elas acontecem. Não faça os clientes atualizarem a página ou se perguntarem se a transferência foi concluída. Consulte Webhooks do TED para configuração.

​
Decisões de conformidade

Estes são requisitos que se aplicam à sua integração independentemente das suas escolhas de produto.

​
LGPD e dados pessoais

Os registros de transferência contêm dados pessoais — nomes de clientes, CPF/CNPJ e dados bancários. Certifique-se de que sua política de privacidade cubra explicitamente os dados de transações financeiras. Evite registrar CPF/CNPJ em texto simples; mascare-os nas interfaces como ***.***.***-00. Um endpoint dedicado de anonimização para solicitações de direito ao esquecimento da LGPD está planejado para uma versão futura. Até lá, coordene as solicitações de anonimização com sua equipe de administração de banco de dados.

​
Retenção de dados

Os dados de transferência devem ser retidos por 5 anos conforme a Resolução 4.753/2019 do BACEN. Isso não é configurável e não pode ser reduzido.
Tipo de dadoPeríodo de retenção
Registros de transação5 anos (requisito BACEN)
Logs de aplicação90 dias
Dados de auditoria5 anos (anonimizados após 2 anos)

​
Trilha de auditoria e reconciliação

Cada transferência gera dois números de referência que você deve armazenar:
CampoO que éQuando usar
transferIdIdentificador interno LerianConsultas na API, casos de suporte
confirmationNumberReferência legível pelo usuárioComprovantes, comunicação com o cliente
controlNumberReferência JD SPB (só TED OUT)Trilha de auditoria BACEN, reportes regulatórios
Mantenha tanto o transferId quanto o confirmationNumber em seus próprios registros para reconciliação. Para TED OUT, armazene também o controlNumber.

​
Horários de funcionamento

O BACEN determina que o TED opera de segunda a sexta-feira, das 06:30 às 17:00 (horário de Brasília, UTC-3). O plugin impõe essa janela por padrão; os horários de abertura/fechamento são ajustáveis pelo operador em runtime (dentro dos limites do BACEN) via systemplane, mas trate 06:30–17:00 como a norma. Construa sua UX em torno dela — consulte Trate os horários de funcionamento com clareza acima.
Transferências P2P não estão sujeitas a restrições de horário de funcionamento e funcionam 24/7.

​
Checklist de integração

Antes de entrar em produção, verifique o seguinte:
  • Chaves de idempotência em todas as operações de escrita — Envie um UUID v4 X-Idempotency em cada chamada para initiate, process e cancel. Isso evita transferências duplicadas por tentativas de retry ou duplo clique.
  • Endpoint de webhook ativo antes do lançamento — Seu endpoint de webhook deve estar implantado e acessível antes de entrar em produção. Os eventos de transferência começam a disparar imediatamente na primeira transação real.
  • Expiração de 24 horas tratada — Uma transferência iniciada expira se não for confirmada em 24 horas. Se seu fluxo permite que um cliente inicie uma transferência e retorne depois, trate o caso de expiração explicitamente.
  • Backoff exponencial em erros 5xx — Implemente retry com backoff (ex: 2s, 4s, 8s) quando a resposta for 503 ou 500. A indisponibilidade do JD SPB aparece como 503 com o código de fornecedor JD sem transformação (TRANSPORT, ACE95, …); a indisponibilidade do ledger Midaz aparece como BTF-2000. Não tente novamente imediatamente em loop.
  • Horários de funcionamento validados no lado do cliente — Verifique os horários na interface antes de chamar a API. Reduz chamadas de API desnecessárias e proporciona uma melhor experiência ao cliente.
  • Tanto transferId quanto confirmationNumber armazenados — Necessários para reconciliação e auditoria. Para TED OUT, armazene também o controlNumber.

​
Tratamento de erros

Use estes cenários de erro para mapear erros da API para mensagens amigáveis ao cliente e definir o caminho de recuperação correto.
CenárioMensagem ao clienteRecuperação
Fora do horário de funcionamento (BTF-0010)“Transferências TED estão disponíveis de segunda a sexta, das 06:30 às 17:00. Próximo horário: [data/hora].”Recuperável — aguarde a próxima janela
Saldo insuficiente (BTF-2003, HTTP 422)“Sua conta não tem saldo suficiente para esta transferência.”Recuperável — o cliente adiciona fundos ou reduz o valor
Limite diário atingido (BTF-0011)“Você atingiu seu limite diário de transferências de R$ [X]. O limite é resetado à meia-noite.”Recuperável — aguarde o reset
Destinatário inválido (BTF-0500)“Conta de destino não encontrada. Verifique os dados da conta e tente novamente.”Recuperável — o cliente corrige os dados
Serviço indisponível (TRANSPORT, HTTP 503, código JD sem transformação)“Serviço de transferência temporariamente indisponível. Tente novamente em alguns minutos.”Recuperável — retry com backoff
Transferência duplicada (BTF-0012)“Uma transferência idêntica foi enviada recentemente. Se foi intencional, aguarde um momento e tente novamente.”Condicional — aguarde a janela de deduplicação encerrar
Para a lista completa de códigos de erro e seus significados, consulte a lista de erros do TED.