Pular para o conteúdo principal
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 do 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.

​
Mostre a tarifa antes de o cliente confirmar

A etapa initiate retorna o valor da tarifa antes de qualquer movimentação de recursos. Use essa janela para mostrar uma tela de confirmação clara:
Isso reduz reclamações e cancelamentos de clientes surpreendidos por tarifas depois do fato.

​
Trate o horário de funcionamento de forma amigável

A TED OUT está disponível de segunda a sexta, 06:30–17:00 (horário de Brasília) por padrão. Quando um cliente começa uma transferência fora desse horário, não mostre apenas um erro. Diga quando ele pode tentar de novo:
Para evitar idas e vindas desnecessárias, valide o horário 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 fins de semana e feriados do BACEN automaticamente, a partir do seu calendário de feriados embutido para 2026 a 2028. Quando um feriado rejeita uma transferência, mostre 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

Mostre o limite diário restante do cliente na sua interface de transferência. Mostre antes de ele tentar uma transferência que o plugin rejeita. O plugin conta o valor debitado do remetente (totalAmount), e o dia vira às 00:00 UTC (21:00 no horário de Brasília). Por exemplo:

​
Mostre comprovantes de confirmação após a conclusão

Depois que uma transferência TED OUT ou P2P é concluída, mostre (ou ofereça para baixar) um comprovante com:
  • Data e hora da transferência
  • Dados do remetente e do destinatário
  • Valor, tarifa e total
  • confirmationNumber (referência voltada ao cliente)
  • controlNumber (referência do JD SPB, para TED OUT e TED IN)
Quando você fornece essa informação cedo, reduz os contatos de suporte do tipo “minha transferência saiu?”.

​
Mantenha os clientes informados em tempo real

Use webhooks para enviar atualizações de status da transferência para sua interface conforme elas acontecem. Não faça os clientes atualizarem a tela nem ficarem em dúvida se a transferência deles saiu. Veja webhooks TED para a 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. Garanta que sua política de privacidade cubra explicitamente os dados de transações financeiras. Não registre CPF/CNPJ em texto claro nos logs. Mascare nas interfaces como ***.***.***-00. O plugin não tem endpoint para solicitações de direito ao apagamento da LGPD.

​
Retenção de dados

O plugin nunca apaga nem expira registros de transferência, então a retenção é sua responsabilidade. Retenha os dados de transferência e auditoria por pelo menos 5 anos, conforme os requisitos de guarda de registros do BACEN para instituições financeiras.

​
Trilha de auditoria e conciliação

Cada transferência gera dois números de referência que você deve armazenar: Mantenha o transferId e o confirmationNumber nos seus próprios registros para conciliação. Para TED OUT e TED IN, armazene também o controlNumber.

​
Horário de funcionamento

O BACEN determina que a TED opera de segunda a sexta, 06:30–17:00 (horário de Brasília, UTC-3). O plugin aplica essa janela por padrão. Um operador pode mudar a janela em tempo de execução pela chave do systemplane operating_hours.window. Trate 06:30–17:00 como a norma e construa sua UX em torno disso. Veja Trate o horário de funcionamento de forma amigável acima.
As 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 header X-Idempotency com UUID v4 em cada chamada a initiate, process e cancel. Isso evita transferências duplicadas por novas tentativas ou cliques duplos.
  • Endpoint de webhook no ar antes do lançamento: faça o deploy do seu endpoint de webhook e deixe-o acessível antes de entrar em produção. Os eventos de transferência começam a disparar de imediato na primeira transação real.
  • Expiração tratada: uma transferência iniciada expira em expiresAt: depois de 24 horas ou, para TED OUT, no fechamento da janela de operação daquele dia. Se o seu fluxo permitir que o cliente comece uma transferência e volte depois, trate o caso de expiração explicitamente.
  • Leia antes de tentar de novo após um 5xx: um 5xx deixa o resultado desconhecido. Leia a transferência primeiro e tente de novo com backoff (por exemplo, 2s, 4s, 8s) com uma nova chave X-Idempotency apenas se a operação não aconteceu. A indisponibilidade do JD SPB aparece como 503 com BTF-1000 ou BTF-1003. A indisponibilidade do ledger Midaz aparece como BTF-2000. Não repita a tentativa em loop de imediato.
  • Horário de funcionamento validado no cliente: verifique o horário na interface antes de chamar a API. Isso reduz chamadas de API com falha e dá uma experiência melhor ao cliente.
  • transferId e confirmationNumber armazenados: obrigatórios para conciliação e auditoria. Para TED OUT e TED IN, 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, veja a lista de erros TED.