Skip to main content
POST
/
v1
/
transfers
/
initiate
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-Tenant-Id: <x-tenant-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"
  }
}
'
{
  "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-Tenant-Id header.

Headers

​
X-Tenant-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
​
amount
number<decimal>
required

The transfer amount in BRL.

Required range: 0.01 <= x <= 999999.99
Example:

1000.5

​
description
string

A description of the transfer purpose.

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

Indicates that the transfer was initiated successfully and is awaiting confirmation.

The response includes the X-Idempotency-Replayed header.

If the value is false, the transaction was just processed. If the value is true, the response is a replay of a previously processed request.

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.

​
packageAppliedId
string<uuid> | null

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

Example:

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