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.

POST /v1/transfers/initiate

cURL

tedOut

curl --request POST \
  --url https://plugin-br-bank-transfer.sandbox.lerian.net/v1/transfers/initiate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --header 'X-Organization-Id: <x-organization-id>' \
  --data '
{
  "senderAccountId": "019c96a0-0c0c-7221-8cf3-13313fb60081",
  "recipient": {
    "ispb": "00000000",
    "branch": "0001",
    "account": "1234567890",
    "accountType": "CACC",
    "holderName": "João Silva",
    "holderDocument": "12345678901"
  },
  "amount": 1000.5,
  "description": "Payment for services",
  "metadata": {
    "invoiceId": "INV-2024-001"
  }
}
'

200

success

{
  "initiationId": "019c96a0-aa10-7abc-d1e2-8c9d0e1f2a3b",
  "feeAmount": 1.5,
  "totalAmount": 1002,
  "estimatedCompletionAt": "2026-02-01T18:00:00-03:00",
  "expiresAt": "2026-02-02T15:30:00-03:00",
  "status": "PENDING_CONFIRMATION"
}

Authorizations

Authorization · string · header · required

JWT Bearer token authentication. The token must include a tenantId claim that matches the X-Organization-Id header.

Headers

X-Organization-Id · string<uuid> · required

Organization ID used as the tenant identifier. All data is scoped to this organization. Must match the JWT tenantId claim when authentication is enabled.

X-Idempotency · string · required

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

Body

application/json

senderAccountId · string<uuid> · required

The Midaz account ID of the sender.

Example:

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

recipient · object · required

Show child attributes

amount · number<decimal> · required

The transfer amount in BRL.

Required range: 0.01 <= x <= 999999.99

Example:

1000.5

purpose · string · required

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}$

Example:

"10"

description · string

A free-text description of the transfer.

Maximum string length: 140

Example:

"Payment for services"

metadata · object

Custom metadata as key-value pairs.

Example:

{
  "invoiceId": "INV-2024-001",
  "orderId": "ORD-2024-123"
}

Response

200

application/json

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> · required

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

Example:

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

feeAmount · number<decimal> · required

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

Example:

1.5

totalAmount · number<decimal> · required

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

Example:

1002

estimatedCompletionAt · string<date-time> · required

The estimated time when the transfer will be completed.

Example:

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

expiresAt · string<date-time> · required

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

Example:

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

status · enum<string> · required

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.

Available options: PENDING_CONFIRMATION, PROCESSED, EXPIRED

Example:

"PENDING_CONFIRMATION"

feeEntries · object[]

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

Show child attributes

packageAppliedId · string<uuid> | null

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

Example:

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