Iniciar una Transferencia
Utilice este endpoint para iniciar una transferencia validando los datos del remitente, verificando el horario de operación y los límites de uso, detectando duplicados y calculando la tarifa. No se retienen fondos en este paso. El initiationId devuelto es válido por 24 horas y debe confirmarse a través del endpoint Procesar Transferencia. Utilice el encabezado X-Idempotency para deduplicación garantizada.
Autorizaciones
Autenticación mediante token JWT Bearer. El tenantId se deriva del token bearer o del contexto autenticado de la solicitud y no se proporciona a través de X-Organization-Id.
Encabezados
Alcance de organización Midaz para la solicitud, utilizado para las llamadas posteriores a CRM, Fees y Midaz. Es obligatorio en las rutas de transferencia con alcance de organización en todos los modos de despliegue; un valor faltante o que no sea un UUID devuelve 400. Este no es el identificador del tenant — el tenantId se deriva del JWT bearer o del contexto autenticado, nunca de este header. Los workers en segundo plano (poller de TED IN, conciliación) no tienen header de solicitud y, en modo single-tenant, recurren a la variable de entorno ORGANIZATION_ID del despliegue.
Clave de idempotencia requerida para reintentos seguros. Utilice un UUID v4 o un identificador de negocio único. Si se envía la misma clave nuevamente y la solicitud original ya fue procesada, se devuelve la respuesta almacenada en caché.
Consulte Reintentos e idempotencia para más detalles.
255Cuerpo
El ID de cuenta Midaz del remitente.
"019c96a0-0c0c-7221-8cf3-13313fb60081"
El monto de la transferencia en BRL.
0.01 <= x <= 999999.991000.5
Código FinlddCli del SPB BACEN que identifica el propósito de la transferencia. Debe contener entre 1 y 4 dígitos ASCII.
Códigos FinlddCli comunes:
1— Pagamento de Impostos, Tributos e Taxas3— Pagamentos de Dividendos10— Crédito em Conta100— Depósito Judicial
Consulte el Dicionário de Domínios (FinlddCli) del BACEN para la tabla completa de códigos activos.
Nota: el plugin acepta actualmente valores de FinlddCli de hasta 4 dígitos. Códigos de 5 dígitos del catálogo BACEN (como 99999 — Outros) aún no están soportados y devolverán un error de validación.
4^[0-9]{1,4}$"10"
Descripción en texto libre de la transferencia.
140"Payment for services"
Metadatos personalizados como pares clave-valor.
Respuesta
Indica que la transferencia fue iniciada exitosamente y está esperando confirmación.
Las llamadas repetidas con la misma clave X-Idempotency reproducen la respuesta en caché.
Consulte Reintentos e idempotencia para más detalles.
El ID de iniciación único. Utilice este valor en el endpoint Procesar Transferencia para confirmar la transferencia.
"019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b"
El monto de la tarifa calculada. Devuelve 0.00 si las tarifas están deshabilitadas para esta organización.
1.5
El monto total, calculado como el monto de la transferencia más la tarifa.
1002
El tiempo estimado en que la transferencia será completada.
"2026-02-01T18:00:00-03:00"
El momento en que esta iniciación expira, 24 horas después de su creación.
"2026-02-02T15:30:00-03:00"
El estado de la iniciación. PENDING_CONFIRMATION indica que la iniciación está esperando confirmación a través del endpoint Procesar Transferencia. PROCESSED indica que se creó una transferencia. EXPIRED indica que la iniciación expiró después de 24 horas.
PENDING_CONFIRMATION, PROCESSED, EXPIRED "PENDING_CONFIRMATION"
Desglose detallado de comisiones. Cada entrada corresponde a una comisión cobrada durante la transferencia.
ID del paquete de comisiones aplicado a esta transferencia, si corresponde.
"019c96a0-ad10-7fab-c1d2-3b4c5d6e7f8a"