Iniciar uma Transferência
Use este endpoint para iniciar uma transferência validando os dados do remetente, verificando horários de funcionamento e limites de uso, detectando duplicatas e calculando a tarifa. Nenhum fundo é retido nesta etapa. O initiationId retornado é válido por 24 horas e deve ser confirmado através do endpoint Processar Transferência. Use o cabeçalho X-Idempotency para garantir a deduplicação.
Autorizações
Autenticação por token JWT Bearer. O tenantId é derivado do token bearer ou do contexto de requisição autenticado e não é fornecido por meio do X-Organization-Id.
Cabeçalhos
Escopo da organização Midaz para a requisição, usado para chamadas downstream ao CRM, Fees e Midaz. Obrigatório nas rotas de transferência com escopo de organização em todos os modos de implantação; um valor ausente ou que não seja UUID retorna 400. Este não é o identificador do tenant — o tenantId é derivado do JWT bearer ou do contexto autenticado, nunca deste cabeçalho. Workers em segundo plano (poller de TED IN, conciliação) não possuem cabeçalho de requisição e, no modo single-tenant, recorrem à variável de ambiente ORGANIZATION_ID da implantação.
Chave de idempotência obrigatória para tentativas seguras. Use um UUID v4 ou identificador de negócio único. Se a mesma chave for enviada novamente e a solicitação original já tiver sido processada, a resposta em cache será retornada.
Consulte Tentativas e idempotência para detalhes.
255Corpo
O ID da conta Midaz do remetente.
"019c96a0-0c0c-7221-8cf3-13313fb60081"
O valor da transferência em BRL.
0.01 <= x <= 999999.991000.5
Código FinlddCli do SPB do BACEN que identifica a finalidade da transferência. Deve conter entre 1 e 4 dígitos ASCII.
Códigos FinlddCli comuns:
1— Pagamento de Impostos, Tributos e Taxas3— Pagamentos de Dividendos10— Crédito em Conta100— Depósito Judicial
Consulte o Dicionário de Domínios (FinlddCli) do BACEN para a tabela completa de códigos ativos.
Nota: o plugin atualmente aceita valores de FinlddCli de até 4 dígitos. Códigos de 5 dígitos do catálogo BACEN (como 99999 — Outros) ainda não são suportados e retornarão um erro de validação.
4^[0-9]{1,4}$"10"
Descrição em texto livre da transferência.
140"Payment for services"
Metadados personalizados como pares chave-valor.
Resposta
Indica que a transferência foi iniciada com sucesso e está aguardando confirmação.
Chamadas repetidas com a mesma chave X-Idempotency reproduzem a resposta em cache.
Consulte Tentativas e idempotência para mais detalhes.
O ID de iniciação único. Use este valor no endpoint Processar Transferência para confirmar a transferência.
"019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b"
O valor da tarifa calculada. Retorna 0.00 se as tarifas estiverem desabilitadas para esta organização.
1.5
O valor total, calculado como o valor da transferência mais a tarifa.
1002
O horário estimado de conclusão da transferência.
"2026-02-01T18:00:00-03:00"
O horário em que esta iniciação expira, 24 horas após a criação.
"2026-02-02T15:30:00-03:00"
O status da iniciação. PENDING_CONFIRMATION indica que a iniciação está aguardando confirmação através do endpoint Processar Transferência. PROCESSED indica que uma transferência foi criada. EXPIRED indica que a iniciação expirou após 24 horas.
PENDING_CONFIRMATION, PROCESSED, EXPIRED "PENDING_CONFIRMATION"
Detalhamento das tarifas cobradas. Cada entrada corresponde a uma tarifa aplicada durante a transferência.
ID do pacote de tarifas aplicado a esta transferência, se houver.
"019c96a0-ad10-7fab-c1d2-3b4c5d6e7f8a"