Skip to main content
Esta guía cubre las decisiones clave que tu equipo toma al integrar Bank Transfer. También ofrece las buenas prácticas para una experiencia de cliente confiable y conforme.

​
Decisiones de producto

Estas son las decisiones que tu equipo de producto toma en la experiencia orientada al cliente. Afectan directamente la satisfacción del cliente y el volumen de soporte.

​
Muestra la tarifa antes de que el cliente confirme

El paso initiate devuelve el monto de la tarifa antes de que se muevan los fondos. Usa esta ventana para mostrar una pantalla de confirmación clara:
Esto reduce las reclamaciones y cancelaciones de clientes sorprendidos por las tarifas después del hecho.

​
Maneja el horario de funcionamiento con elegancia

TED OUT está disponible de lunes a viernes, de 06:30 a 17:00 (horario de Brasilia). Cuando un cliente inicia una transferencia fuera de ese horario, no muestres solo un error. Dile cuándo podrá intentarlo de nuevo:
Para evitar viajes de ida y vuelta innecesarios, valida el horario de funcionamiento en el lado del cliente antes de llamar a la API. No necesitas mantener tu propia lista de feriados. El plugin bloquea automáticamente fines de semana y feriados BACEN. La fuente de verdad en runtime es la tabla bacen_holidays, que el plugin puebla con seed para 2026–2028. El job de actualización diaria se ejecuta por defecto y reaplica el seed integrado. No consulta en vivo a ANBIMA, porque ANBIMA solo publica una hoja de cálculo legacy que las máquinas no pueden leer. El seed sigue siendo la fuente autoritativa hasta que eso cambie. Cuando un feriado rechaza una transferencia, comunica ese motivo al cliente. No repliques el calendario en el 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 transferencia. Muéstralo antes de que intente una transferencia que el plugin rechaza. Por ejemplo:

​
Muestra comprobantes de confirmación después de la finalización

Después de que se complete una transferencia TED OUT o P2P, muestra — u ofrece descargar — un comprobante con:
  • Fecha y hora de la transferencia
  • Datos del remitente y destinatario
  • Monto, tarifa y total
  • confirmationNumber (referencia visible para el cliente)
  • controlNumber (referencia JD SPB, solo para TED OUT)
Cuando proporcionas esta información de forma anticipada, reduces los contactos de soporte del tipo “¿se realizó mi transferencia?”.

​
Mantén a los clientes informados en tiempo real

Usa webhooks para enviar actualizaciones del estado de la transferencia a tu interfaz a medida que ocurren. No hagas que los clientes actualicen la página ni se pregunten si su transferencia fue procesada. Consulta Webhooks de Bank Transfer para la configuración.

​
Decisiones de cumplimiento

Estos son los requisitos que aplican a tu integración independientemente de tus decisiones de producto.

​
LGPD y datos personales

Los registros de transferencia contienen datos personales — nombres de clientes, CPF/CNPJ y datos bancarios. Asegúrate de que tu política de privacidad cubra explícitamente los datos de transacciones financieras. No registres CPF/CNPJ en texto claro. Enmascáralo en interfaces como ***.***.***-00. Un endpoint dedicado de anonimización para solicitudes de derecho al olvido de la LGPD llegará en una versión futura. Hasta entonces, coordina las solicitudes de anonimización con tu equipo de administración de base de datos.

​
Retención de datos

El plugin nunca elimina ni caduca los registros de transferencia, así que tú controlas su retención. Conserva los datos de transferencia y auditoría durante al menos 5 años, conforme a los requisitos de conservación de registros del BACEN para instituciones financieras.

​
Registro de auditoría y reconciliación

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

​
Horario de funcionamiento

El BACEN establece que TED opera de lunes a viernes, de 06:30 a 17:00 (horario de Brasilia, UTC-3). El plugin aplica esta ventana por defecto. Un operador puede ajustar los horarios de apertura y cierre en runtime a través de systemplane, dentro de los límites de BACEN. Trata 06:30–17:00 como la norma y construye tu UX en torno a ella. Consulta Maneja el horario de funcionamiento con elegancia arriba.
Las transferencias P2P no están sujetas a restricciones de horario de funcionamiento y funcionan 24/7.

​
Lista de verificación de integración

Antes de salir en producción, verifica lo siguiente:
  • Claves de idempotencia en todas las operaciones de escritura — Envía un header X-Idempotency 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 accesible antes de salir en producción. Los eventos de transferencia comienzan a dispararse inmediatamente en la primera transacción real.
  • Expiración de 24 horas manejada — Una transferencia iniciada expira si el cliente no la confirma dentro de las 24 horas. Si tu flujo permite que un cliente inicie una transferencia y regrese más tarde, gestiona el caso de expiración explícitamente.
  • Backoff exponencial en errores 5xx — Implementa reintentos con backoff (por ejemplo, 2s, 4s, 8s) cuando la respuesta sea 503 o 500. La indisponibilidad de JD SPB aparece como 503 con un código de proveedor JD sin transformar (TRANSPORT, ACE95, …). La indisponibilidad del ledger Midaz aparece como BTF-2000. No reintentes inmediatamente en un bucle.
  • Horario de funcionamiento validado en el lado del cliente — Verifica el horario en la interfaz antes de llamar a la API. Esto reduce llamadas fallidas a la API y brinda una mejor experiencia al cliente.
  • Ambos transferId y confirmationNumber almacenados — Requeridos para reconciliación y auditoría. Para TED OUT, también almacena controlNumber.

​
Manejo de errores

Usa estos escenarios de error para mapear errores de la API a mensajes amigables 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 Bank Transfer.