Skip to main content
POST

Autorizações

​
Authorization
string
header
obrigatório

JWT Bearer token authentication. The tenantId is derived from the bearer token or authenticated request context and is not supplied through X-Organization-Id.

Cabeçalhos

​
X-Organization-Id
string<uuid>
obrigatório

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.

​
X-Idempotency
string
obrigatório

Required idempotency key for safe retries. Use a UUID v4 or unique business identifier. 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.

Maximum string length: 255

Corpo

application/json
​
senderAccountId
string<uuid>
obrigatório

The Midaz account ID of the sender.

Exemplo:

"019c96a0-0c0c-7221-8cf3-13313fb60081"

​
recipient
object
obrigatório
​
amount
number<decimal>
obrigatório

The transfer amount in BRL.

Intervalo obrigatório: 0.01 <= x <= 999999.99
Exemplo:

1000.5

​
purpose
string
obrigatório

BACEN SPB FinlddCli code identifying the transfer purpose. Must be 1–4 ASCII digits.

Common FinlddCli codes:

  • 1 — Pagamento de Impostos, Tributos e Taxas
  • 3 — Pagamentos de Dividendos
  • 10 — Crédito em Conta
  • 100 — 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.

Maximum string length: 4
Pattern: ^[0-9]{1,4}$
Exemplo:

"10"

​
description
string

A free-text description of the transfer.

Maximum string length: 140
Exemplo:

"Payment for services"

​
metadata
object

Custom metadata as key-value pairs.

Exemplo:

Resposta

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.

​
initiationId
string<uuid>
obrigatório

The unique initiation ID. Use this value in the Process Transfer endpoint to confirm the transfer.

Exemplo:

"019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b"

​
feeAmount
number<decimal>
obrigatório

The calculated fee amount. Returns 0.00 if fees are disabled for this organization.

Exemplo:

1.5

​
totalAmount
number<decimal>
obrigatório

The total amount, calculated as the transfer amount plus the fee.

Exemplo:

1002

​
estimatedCompletionAt
string<date-time>
obrigatório

The estimated time when the transfer will be completed.

Exemplo:

"2026-02-01T18:00:00-03:00"

​
expiresAt
string<date-time>
obrigatório

The time when this initiation expires, 24 hours after creation.

Exemplo:

"2026-02-02T15:30:00-03:00"

​
status
enum<string>
obrigatório

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.

Opções disponíveis:
PENDING_CONFIRMATION,
PROCESSED,
EXPIRED
Exemplo:

"PENDING_CONFIRMATION"

​
feeEntries
object[]

Itemized fee breakdown. Each entry corresponds to one fee charged during the transfer.

​
packageAppliedId
string<uuid> | null

ID of the fee package applied to this transfer, if any.

Exemplo:

"019c96a0-ad10-7fab-c1d2-3b4c5d6e7f8a"