Iniciar una Transferencia

Utilice este endpoint para iniciar una transferencia validando los datos del remitente, verificando el horario de operación y los límites de uso, detectando duplicados y calculando la tarifa. No se retienen fondos en este paso. El initiationId devuelto es válido por 24 horas y debe confirmarse a través del endpoint Procesar Transferencia. Utilice el encabezado X-Idempotency para deduplicación garantizada.

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>' \
  --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"
}

Autorizaciones

Authorization · string · header · requerido

Autenticación mediante token JWT Bearer. El tenantId se deriva del token bearer o del contexto autenticado de la solicitud y no se proporciona a través de X-Organization-Id.

Encabezados

X-Organization-Id · string<uuid>

Alcance de organización Midaz para la solicitud. En despliegues multi-tenant este header es obligatorio. Este no es el identificador del tenant; el tenantId se deriva del JWT bearer o del contexto autenticado. En despliegues single-tenant los valores de X-Organization-Id proporcionados por el llamador son rechazados y la organización es proporcionada por SINGLE_TENANT_ORGANIZATION_ID.

X-Idempotency · string · requerido

Clave de idempotencia requerida para reintentos seguros. Utilice un UUID v4 o un identificador de negocio único. Si se envía la misma clave nuevamente y la solicitud original ya fue procesada, se devuelve la respuesta almacenada en caché.

Consulte Reintentos e idempotencia para más detalles.

Maximum string length: 255

Cuerpo

application/json

senderAccountId · string<uuid> · requerido

El ID de cuenta Midaz del remitente.

Ejemplo:

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

recipient · object · requerido

Show child attributes

amount · number<decimal> · requerido

El monto de la transferencia en BRL.

Rango requerido: 0.01 <= x <= 999999.99

Ejemplo:

1000.5

purpose · string · requerido

Código FinlddCli del SPB BACEN que identifica el propósito de la transferencia. Debe contener entre 1 y 4 dígitos ASCII.

Códigos FinlddCli comunes:

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

Consulte el Dicionário de Domínios (FinlddCli) del BACEN para la tabla completa de códigos activos.

Nota: el plugin acepta actualmente valores de FinlddCli de hasta 4 dígitos. Códigos de 5 dígitos del catálogo BACEN (como 99999 — Outros) aún no están soportados y devolverán un error de validación.

Maximum string length: 4

Pattern: ^[0-9]{1,4}$

Ejemplo:

"10"

description · string

Descripción en texto libre de la transferencia.

Maximum string length: 140

Ejemplo:

"Payment for services"

metadata · object

Metadatos personalizados como pares clave-valor.

Ejemplo:

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

Respuesta

200

application/json

Indica que la transferencia fue iniciada exitosamente y está esperando confirmación.

Las llamadas repetidas con la misma clave X-Idempotency reproducen la respuesta en caché.

Consulte Reintentos e idempotencia para más detalles.

initiationId · string<uuid> · requerido

El ID de iniciación único. Utilice este valor en el endpoint Procesar Transferencia para confirmar la transferencia.

Ejemplo:

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

feeAmount · number<decimal> · requerido

El monto de la tarifa calculada. Devuelve 0.00 si las tarifas están deshabilitadas para esta organización.

Ejemplo:

1.5

totalAmount · number<decimal> · requerido

El monto total, calculado como el monto de la transferencia más la tarifa.

Ejemplo:

1002

estimatedCompletionAt · string<date-time> · requerido

El tiempo estimado en que la transferencia será completada.

Ejemplo:

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

expiresAt · string<date-time> · requerido

El momento en que esta iniciación expira, 24 horas después de su creación.

Ejemplo:

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

status · enum<string> · requerido

El estado de la iniciación. PENDING_CONFIRMATION indica que la iniciación está esperando confirmación a través del endpoint Procesar Transferencia. PROCESSED indica que se creó una transferencia. EXPIRED indica que la iniciación expiró después de 24 horas.

Opciones disponibles: PENDING_CONFIRMATION, PROCESSED, EXPIRED

Ejemplo:

"PENDING_CONFIRMATION"

feeEntries · object[]

Desglose detallado de comisiones. Cada entrada corresponde a una comisión cobrada durante la transferencia.

Show child attributes

packageAppliedId · string<uuid> | null

ID del paquete de comisiones aplicado a esta transferencia, si corresponde.

Ejemplo:

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