Saltar al contenido principal
Esta guía cubre las decisiones clave que tu equipo debe tomar al integrar Bank Transfer, y las buenas prácticas para garantizar una experiencia confiable y conforme para tus clientes.

​
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 flujo de dos pasos (initiate → process) está diseñado para esto: tu sistema recibe el monto de la tarifa antes de que se muevan los fondos. Usa esa ventana para mostrar una pantalla de confirmación clara: 
Confirmar transferencia

Destinatario: Maria Silva — Bradesco (237)

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

[ Cancelar ]        [ Confirmar ]
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 intenta iniciar fuera de ese horario, no muestres solo un error — dile cuándo podrá intentarlo de nuevo: 
Las transferencias TED están disponibles de lunes a viernes, de 06:30 a 17:00.
Próximo horario disponible: lunes a las 06:30.
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 es necesario mantener tu propia lista de feriados — el plugin ya bloquea automáticamente fines de semana y feriados BACEN. La fuente de verdad en runtime es la tabla bacen_holidays, con seed para 2026–2099. 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 no legible por máquina — el seed es la fuente autoritativa hasta que eso cambie. Si una transferencia es rechazada por feriado, comunica ese motivo al cliente. En lugar de replicar 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 — antes de que intente una transferencia que será rechazada. Por ejemplo: 
Límite diario:  R$ 50.000,00
Utilizado hoy:  R$ 45.000,00
Disponible:      R$ 5.000,00

​
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 (tu referencia interna)
  • controlNumber (referencia JD SPB, solo para TED OUT)
Proporcionar esta información de forma proactiva reduce 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. Evita registrar CPF/CNPJ en texto claro; enmascara en interfaces como ***.***.***-00. Un endpoint dedicado de anonimización para solicitudes de derecho al olvido de la LGPD está planificado para 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

Los datos de transferencia deben conservarse durante 5 años conforme a la Resolución 4.753/2019 del BACEN. Esto no es configurable y no puede acortarse.
Tipo de datoPeríodo de retención
Registros de transacción5 años (requisito BACEN)
Logs de aplicación90 días
Datos de auditoría5 años (anonimizados después de 2 años)

​
Registro de auditoría y reconciliación

Cada transferencia genera dos números de referencia que debes almacenar:
CampoQué esCuándo usarlo
transferIdIdentificador interno de LerianConsultas a la API, casos de soporte
confirmationNumberReferencia legible para el usuarioComprobantes, comunicación con el cliente
controlNumberReferencia JD SPB (solo TED OUT)Registro de auditoría BACEN, reportes regulatorios
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; los horarios de apertura/cierre son ajustables por el operador en runtime (dentro de los límites de BACEN) vía systemplane, pero trata 06:30–17:00 como la norma. 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 — Tu endpoint de webhook debe estar desplegado y 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 no se 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. Reduce llamadas innecesarias a la API fallidas 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.
EscenarioMensaje para el clienteRecuperación
Fuera del horario operativo (BTF-0010)“Las transferencias TED están disponibles de lunes a viernes, de 06:30 a 17:00. Próximo horario: [fecha/hora].”Recuperable — espera la siguiente ventana
Saldo insuficiente (BTF-2003, HTTP 422)“Su cuenta no tiene saldo suficiente para esta transferencia.”Recuperable — el cliente agrega fondos o reduce el monto
Límite diario alcanzado (BTF-0011)“Ha alcanzado su límite diario de transferencias de R$ [X]. El límite se restablece a medianoche.”Recuperable — espera el restablecimiento
Destinatario inválido (BTF-0500)“Cuenta de destino no encontrada. Verifique los datos de la cuenta e intente nuevamente.”Recuperable — el cliente corrige los datos
Servicio no disponible (TRANSPORT, HTTP 503, código JD sin transformar)“El servicio de transferencias no está disponible temporalmente. Intente nuevamente en unos minutos.”Recuperable — reintenta con backoff
Transferencia duplicada (BTF-0012)“Una transferencia idéntica fue enviada recientemente. Si fue intencional, espere un momento e intente de nuevo.”Condicional — espera a que expire la ventana de deduplicación
Para la lista completa de códigos de error y sus significados, consulta la lista de errores de Bank Transfer.