Realizar Repasse (Funds out)

Utilize o endpoint abaixo para realizar um repasse para uma conta externa. Caso ainda não tenha associado uma conta destino externa ao Profile, utilize o Assosciar Conta destino. Vale ressaltar que é necessário que a conta destino seja de mesma titularidade para o sucesso da transação.

POST /v1/marketplaces/{marketplace_id}/profiles/{profile_id}/accounts/{account_id}/transfers/funds-out

{
  "amount": 12000
}

Response 202:

{
"transfer_id": "3f2a1c9e-8b4d-4f61-9a02-5c7d1e6b0a34",
"status": "ACCEPTED"
}

Possíveis status: ACCEPTED → PROCESSING → SUCCEEDED | FAILED | REVERSED.

Webhooks

Quando a transação tem sucesso, o marketplace recebe o webhook XXXXX:

{
  "type": "transfer.succeeded",
  "resource": "event",
  "payload": {
    "object": {
      "transfer_id": "3f2a1c9e-8b4d-4f61-9a02-5c7d1e6b0a34",
      "profile_id": "85b00690-...",
      "kind": "FUNDS_OUT",
      "status": "SUCCEEDED",
      "amount": 12000,
      "source_account_id": "8ac1f0d2-77b4-4e19-9d3a-1c2e4f5a6b70",
      "destination": {
        "bank_code": "341",
        "agency_number": "3000",
        "account_number": "600000",
        "account_type": "CHECKING"
      },
      "created_at": "2026-10-14T12:00:00Z",
      "updated_at": "2026-10-14T12:00:04Z",
      "end_to_end_id": "E2E..."
    }
  }
}

Quando a transação tem falha, o marketplace recebe o webhook XXXXX:

{
  "type": "transfer.succeeded",
  "resource": "event",
  "payload": {
    "object": {
      "transfer_id": "3f2a1c9e-8b4d-4f61-9a02-5c7d1e6b0a34",
      "profile_id": "85b00690-...",
      "kind": "FUNDS_OUT",
      "status": "FAILED",
      "amount": 12000,
      "failure_reason": "FAILED",
      "source_account_id": "8ac1f0d2-77b4-4e19-9d3a-1c2e4f5a6b70",
      "destination": {
        "bank_code": "341",
        "agency_number": "3000",
        "account_number": "600000",
        "account_type": "CHECKING"
      },
      "created_at": "2026-10-14T12:00:00Z",
      "updated_at": "2026-10-14T12:00:04Z",
    }
  }
}

⚠️ Erros comuns no funds out

Erro	Causa	Correção
`400`	`INVALID_PAYLOAD`	Header `X-Idempotency-Key` ausente ou payload inválido
`404`	`PROFILE_NOT_FOUND`	Profile não encontrado
`404`	`TRANSFER_ACCOUNT_NOT_OWNED`	Conta não pertence ao seller
`422`	`TRANSFER_ACCOUNT_NOT_VALIDATED`	Conta de destino ainda não validada
`404`	`TRANSFER_NOT_FOUND`	Transferência não encontrada (consulta)