Skip to main content
POST
/
v1
/
transfers
/
initiate
curl --request POST \
  --url https://plugin-br-bank-transfer-jd.sandbox.lerian.net/v1/transfers/initiate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --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"
  }
}
'
{
  "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-Key
string

Client-provided idempotency key for guaranteed deduplication. Submitting the same key within 24 hours returns the cached response. UUID v4 format is recommended. When omitted, an automatic 60-second duplicate detection window is applied.

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.

​
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"