Pular para o conteúdo principal
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-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"
}

Documentation Index

Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt

Use this file to discover all available pages before exploring further.

Autorizações

​
Authorization
string
header
obrigatório

Autenticação por token JWT Bearer. O token deve incluir uma claim tenantId que corresponda ao cabeçalho X-Organization-Id.

Cabeçalhos

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

ID da organização usado como identificador do tenant. Todos os dados são limitados a esta organização. Deve corresponder à claim tenantId do JWT quando a autenticação está habilitada.

​
X-Idempotency
string
obrigatório

Chave de idempotência obrigatória para tentativas seguras. Use um UUID v4 ou identificador de negócio único. Se a mesma chave for enviada novamente e a solicitação original já tiver sido processada, a resposta em cache será retornada.

Consulte Tentativas e idempotência para detalhes.

Maximum string length: 255

Corpo

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

O ID da conta Midaz do remetente.

Exemplo:

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

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

O valor da transferência em BRL.

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

1000.5

​
purpose
string
obrigatório

Código FinlddCli do SPB do BACEN que identifica a finalidade da transferência. Deve conter entre 1 e 4 dígitos ASCII.

Códigos FinlddCli comuns:

  • 1 — Pagamento de Impostos, Tributos e Taxas
  • 3 — Pagamentos de Dividendos
  • 10 — Crédito em Conta
  • 100 — Depósito Judicial

Consulte o Dicionário de Domínios (FinlddCli) do BACEN para a tabela completa de códigos ativos.

Nota: o plugin atualmente aceita valores de FinlddCli de até 4 dígitos. Códigos de 5 dígitos do catálogo BACEN (como 99999 — Outros) ainda não são suportados e retornarão um erro de validação.

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

"10"

​
description
string

Descrição em texto livre da transferência.

Maximum string length: 140
Exemplo:

"Payment for services"

​
metadata
object

Metadados personalizados como pares chave-valor.

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

Resposta

Indica que a transferência foi iniciada com sucesso e está aguardando confirmação.

Chamadas repetidas com a mesma chave X-Idempotency reproduzem a resposta em cache.

Consulte Tentativas e idempotência para mais detalhes.

​
initiationId
string<uuid>
obrigatório

O ID de iniciação único. Use este valor no endpoint Processar Transferência para confirmar a transferência.

Exemplo:

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

​
feeAmount
number<decimal>
obrigatório

O valor da tarifa calculada. Retorna 0.00 se as tarifas estiverem desabilitadas para esta organização.

Exemplo:

1.5

​
totalAmount
number<decimal>
obrigatório

O valor total, calculado como o valor da transferência mais a tarifa.

Exemplo:

1002

​
estimatedCompletionAt
string<date-time>
obrigatório

O horário estimado de conclusão da transferência.

Exemplo:

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

​
expiresAt
string<date-time>
obrigatório

O horário em que esta iniciação expira, 24 horas após a criação.

Exemplo:

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

​
status
enum<string>
obrigatório

O status da iniciação. PENDING_CONFIRMATION indica que a iniciação está aguardando confirmação através do endpoint Processar Transferência. PROCESSED indica que uma transferência foi criada. EXPIRED indica que a iniciação expirou após 24 horas.

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

"PENDING_CONFIRMATION"

​
feeEntries
object[]

Detalhamento das tarifas cobradas. Cada entrada corresponde a uma tarifa aplicada durante a transferência.

​
packageAppliedId
string<uuid> | null

ID do pacote de tarifas aplicado a esta transferência, se houver.

Exemplo:

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