Skip to main content
Este guia cobre as principais decisões que seu time toma ao integrar o Bank Transfer. Ele também traz as boas práticas para uma experiência de cliente confiável e em conformidade.

​
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 passo initiate retorna o valor da tarifa antes de qualquer movimentação de fundos. Use esse intervalo para exibir uma tela de confirmação clara:
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 inicia uma transferência fora desse horário, não exiba apenas um erro. Informe quando ele poderá tentar novamente:
Para evitar chamadas desnecessárias, valide os horários de funcionamento no lado do cliente antes de chamar a API. Você não precisa manter sua própria lista de feriados. O plugin bloqueia automaticamente fins de semana e feriados do BACEN. A fonte da verdade em runtime é a tabela bacen_holidays, que o plugin popula com seed para 2026–2028. 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 que máquinas não conseguem ler. A seed permanece a fonte autoritativa até que isso mude. Quando um feriado rejeita uma transferência, exponha esse motivo ao cliente. Não replique 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. Exiba-o antes que ele tente uma transferência que o plugin rejeita. Por exemplo:

​
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 (referência voltada ao cliente)
  • controlNumber (referência JD SPB, somente para TED OUT)
Quando você fornece essas informações antecipadamente, 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. Não registre 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 chegará em 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

O plugin nunca exclui nem expira os registros de transferência, então você controla a retenção deles. Retenha os dados de transferência e auditoria por pelo menos 5 anos, conforme os requisitos de conservação de registros do BACEN para instituições financeiras.

​
Trilha de auditoria e reconciliação

Cada transferência gera dois números de referência que você deve armazenar: 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. Um operador pode ajustar os horários de abertura e fechamento em runtime através do systemplane, dentro dos limites do BACEN. Trate 06:30–17:00 como a norma e 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 — Implante seu endpoint de webhook e torne-o 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 o cliente não a confirmar 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. Isso 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. Para a lista completa de códigos de erro e seus significados, consulte a lista de erros do TED.