Initiate a Transfer
Use this endpoint to initiate a transfer by validating sender data, checking operating hours and usage limits, detecting duplicates, and calculating the fee. No funds are held at this step. The returned initiationId is valid for 24 hours and must be confirmed via the Process Transfer endpoint. Use the X-Idempotency header for guaranteed deduplication.
Autorizaciones
JWT Bearer token authentication. The tenantId is derived from the bearer token or authenticated request context and is not supplied through X-Organization-Id.
Encabezados
Midaz organization scope for the request, used for downstream CRM, Fees, and Midaz calls. Required on org-scoped transfer routes in every deployment mode; a missing or non-UUID value returns 400. This is not the tenant identifier — tenantId is derived from the bearer JWT or authenticated context, never from this header. Background workers (TED IN poller, reconciliation) have no request header and, in single-tenant mode, fall back to the deployment's ORGANIZATION_ID env.
Required idempotency key for safe retries. Use a UUID v4 or a unique business identifier, made of letters, digits, ., _, and -. If the same key is sent again and the original request was already processed, the cached response is returned.
See Retries and idempotency for details.
255^[a-zA-Z0-9._-]+$Cuerpo
The Midaz account ID of the sender.
"019c96a0-0c0c-7221-8cf3-13313fb60081"
The transfer amount in BRL.
0.01 <= x <= 999999.991000.5
BACEN SPB FinlddCli code identifying the transfer purpose. Must be 1–4 ASCII digits.
Common FinlddCli codes:
1— Pagamento de Impostos, Tributos e Taxas3— Pagamentos de Dividendos10— Crédito em Conta100— Depósito Judicial
Refer to the BACEN Dicionário de Domínios (FinlddCli) for the full table of active codes.
Note: the plugin currently accepts FinlddCli values of up to 4 digits. 5-digit codes from the BACEN catalog (such as 99999 — Outros) are not yet supported and will return a validation error.
4^[0-9]{1,4}$"10"
A free-text description of the transfer.
140"Payment for services"
Custom metadata as key-value pairs.
A fee label that you choose. A fee package on the payer's ledger selects on it. The ledger postings of the transfer carry it. Between two ledgers, each ledger prices its own part. The label is accepted only when the ledger prices fees natively.
50^[a-z][a-z0-9_]{0,49}$"ted_salario"
Respuesta
Indicates that the transfer was initiated successfully and is awaiting confirmation.
Repeated calls with the same X-Idempotency key replay the cached response.
See Retries and idempotency for more details.
The unique initiation ID. Use this value in the Process Transfer endpoint to confirm the transfer.
"019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b"
The calculated fee amount. Returns 0.00 if fees are disabled for this organization.
1.5
The amount debited from the sender's account: the transfer amount plus any fee charged on top.
1002
The estimated time when the transfer will be completed.
"2026-02-01T18:00:00-03:00"
The time when this initiation expires, 24 hours after creation.
"2026-02-02T15:30:00-03:00"
The status of the initiation. PENDING_CONFIRMATION indicates the initiation is awaiting confirmation via the Process Transfer endpoint. PROCESSED indicates a transfer was created. EXPIRED indicates the initiation expired after 24 hours.
PENDING_CONFIRMATION, PROCESSED, EXPIRED "PENDING_CONFIRMATION"
Itemized fee breakdown. Each entry corresponds to one fee charged during the transfer.
ID of the fee package applied to this transfer, if any.
"019c96a0-ad10-7fab-c1d2-3b4c5d6e7f8a"
The recipient's Midaz ledger on a P2P between two ledgers of one organization. Absent on a P2P inside one ledger and on every TED.
"0190a0e2-7b1c-7d3e-9f40-5a6b7c8d9e03"