Saltar al contenido principal
Esta guía cubre las decisiones clave que toma tu equipo cuando integras Bank Transfer. También da las mejores prácticas para una experiencia de cliente confiable y conforme a la normativa.

​
Decisiones de producto

Estas son elecciones que tu equipo de producto toma en la experiencia de cara al cliente. Afectan de forma directa la satisfacción del cliente y el volumen de soporte.

​
Muestra la comisión antes de que el cliente confirme

El paso initiate devuelve el monto de la comisión antes de que se mueva cualquier fondo. Usa esa ventana para mostrar una pantalla de confirmación clara:
Esto reduce los reclamos y las cancelaciones de clientes sorprendidos por comisiones después del hecho.

​
Maneja el horario de operación con cuidado

TED OUT está disponible de lunes a viernes, 06:30–17:00 (hora de Brasilia) de forma predeterminada. Cuando un cliente empieza una transferencia fuera de ese horario, no muestres solo un error. Dile cuándo puede intentarlo de nuevo:
Para evitar viajes de ida y vuelta innecesarios, valida el horario de operación del lado del cliente antes de llamar a la API. No necesitas mantener tu propia lista de feriados. El plugin bloquea los fines de semana y los feriados de BACEN de forma automática, a partir de su calendario de feriados incorporado para 2026 a 2028. Cuando un feriado rechaza una transferencia, muestra ese motivo al cliente. No repliques el calendario del lado del cliente. Confía en el plugin como fuente de verdad para evitar inconsistencias con el tiempo.

​
Comunica los límites de transferencia antes de que los clientes los alcancen

Muestra el límite diario restante del cliente en tu interfaz de transferencias. Muéstralo antes de que intente una transferencia que el plugin rechaza. El plugin cuenta el monto debitado del remitente (totalAmount), y el día cambia a las 00:00 UTC (21:00 hora de Brasilia). Por ejemplo:

​
Muestra comprobantes de confirmación después de completarse

Después de que una transferencia TED OUT o P2P se completa, muestra (u ofrece descargar) un comprobante con:
  • Fecha y hora de la transferencia
  • Datos del emisor y del receptor
  • Monto, comisión y total
  • confirmationNumber (referencia de cara al cliente)
  • controlNumber (referencia de JD SPB, para TED OUT y TED IN)
Cuando das esta información temprano, reduces los contactos de soporte del tipo “¿se hizo mi transferencia?”.

​
Mantén a los clientes informados en tiempo real

Usa webhooks para enviar las actualizaciones de estado de la transferencia a tu interfaz a medida que ocurren. No hagas que los clientes actualicen la página o se pregunten si su transferencia se hizo. Consulta webhooks de TED para la configuración.

​
Decisiones de cumplimiento

Estos son requisitos que se aplican a tu integración sin importar tus elecciones de producto.

​
LGPD y datos personales

Los registros de transferencia contienen datos personales: nombres de clientes, CPF/CNPJ y datos bancarios. Confirma que tu política de privacidad cubra de forma explícita los datos de transacciones financieras. No registres el CPF/CNPJ en texto plano. Enmascáralo en las interfaces como ***.***.***-00. El plugin no tiene un endpoint para las solicitudes de derecho al olvido de la LGPD.

​
Retención de datos

El plugin nunca borra ni hace expirar los registros de transferencia, así que su retención es tuya. Conserva los datos de transferencias y de auditoría durante al menos 5 años, según los requisitos de conservación de registros de BACEN para instituciones financieras.

​
Registro de auditoría y conciliación

Cada transferencia genera dos números de referencia que debes almacenar: Guarda el transferId y el confirmationNumber en tus propios registros para la conciliación. Para TED OUT y TED IN, almacena también el controlNumber.

​
Horario de operación

BACEN exige que TED opere de lunes a viernes, 06:30–17:00 (hora de Brasilia, UTC-3). El plugin aplica esa ventana de forma predeterminada. Un operador puede cambiar la ventana en tiempo de ejecución a través de la clave del systemplane operating_hours.window. Toma 06:30–17:00 como la norma y construye tu experiencia de usuario alrededor de ella. Consulta Maneja el horario de operación con cuidado más arriba.
Las transferencias P2P no están sujetas a restricciones de horario de operación y funcionan 24/7.

​
Lista de verificación de la integración

Antes de salir a producción, verifica lo siguiente:
  • Claves de idempotencia en todas las operaciones de escritura: envía un encabezado X-Idempotency con un UUID v4 en cada llamada a initiate, process y cancel. Esto evita transferencias duplicadas por reintentos o dobles clics.
  • Endpoint de webhook activo antes del lanzamiento: despliega tu endpoint de webhook y hazlo alcanzable antes de salir a producción. Los eventos de transferencia empiezan a dispararse de inmediato en la primera transacción real.
  • Expiración manejada: una transferencia iniciada expira en expiresAt: después de 24 horas o, para TED OUT, al cierre de la ventana de operación de ese día. Si tu flujo permite que un cliente empiece una transferencia y vuelva más tarde, maneja el caso de expiración de forma explícita.
  • Lee antes de reintentar un 5xx: un 5xx deja el resultado desconocido. Lee primero la transferencia y reintenta con backoff (por ejemplo, 2s, 4s, 8s) con una nueva clave X-Idempotency solo si la operación no ocurrió. La indisponibilidad de JD SPB se expresa como 503 con BTF-1000 o BTF-1003. La indisponibilidad del ledger de Midaz se expresa como BTF-2000. No reintentes de inmediato en un bucle.
  • Horario de operación validado del lado del cliente: revisa el horario en la interfaz antes de llamar a la API. Esto reduce las llamadas fallidas a la API y da una mejor experiencia al cliente.
  • transferId y confirmationNumber almacenados: obligatorios para la conciliación y la auditoría. Para TED OUT y TED IN, almacena también el controlNumber.

​
Manejo de errores

Usa estos escenarios de error para asignar los errores de la API a mensajes claros para el cliente y definir la ruta de recuperación correcta. Para la lista completa de códigos de error y sus significados, consulta la lista de errores de TED.