# `Weavr.Accounts`
[🔗](https://github.com/iamkanishka/weavr/blob/main/lib/weavr/resources/accounts.ex#L1)

Managed Accounts — financial instruments that hold funds for their owner.

All paths and operations in this module are verified against
`weavr-multi-api.redoc.ly` and `api.weavr.io/products/multi/openapi/`.

## Confirmed endpoints

  * `GET    /managed_accounts` — list all accounts for the identity
  * `POST   /managed_accounts` — create a new managed account
  * `GET    /managed_accounts/{id}` — get a single account
  * `PATCH  /managed_accounts/{id}` — update account details (e.g. `friendlyName`, `tag`)
  * `POST   /managed_accounts/{id}/iban` — assign an IBAN (may be async, check `state`)
  * `GET    /managed_accounts/{id}/iban` — fetch the IBAN details
  * `POST   /managed_accounts/{id}/block` — temporarily block (supports `idempotency-ref`)
  * `POST   /managed_accounts/{id}/unblock` — unblock (supports `idempotency-ref`)
  * `GET    /managed_accounts/{id}/statement` — transaction history
  * `DELETE /managed_accounts/{id}` — destroy the account

## List query parameters (confirmed from curl examples)

  * `offset`, `limit`
  * `profileId`, `friendlyName`, `currency`, `tag`
  * `state` — `"ACTIVE"`, `"BLOCKED"`, `"DESTROYED"`
  * `state.blockedReason` — `"USER"`, `"SYSTEM"`
  * `state.destroyedReason` — `"SYSTEM"`
  * `createdFrom`, `createdTo` — epoch milliseconds

## Statement query parameters (confirmed from curl examples)

  * `offset`, `limit`
  * `orderByTimestamp` — `"ASC"` or `"DESC"`
  * `fromTimestamp`, `toTimestamp` — epoch milliseconds
  * `showFundMovementsOnly` — boolean
  * `singleEntryPerTransaction` — boolean

## Important notes

  * Creating a managed account requires the end-user's auth_token to be
    **stepped-up** (the user must have completed 2FA at least once since
    registration).
  * `"profileId"` is required when creating — find it in Multi Portal > API Credentials.
  * Amounts throughout Weavr are in **minor units** (e.g. 1000 = £10.00).
  * An account blocked by `"SYSTEM"` cannot be unblocked by users — only
    those with `blockedReason: "USER"` can be unblocked via the API.

# `assign_iban`

```elixir
@spec assign_iban(Weavr.Config.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Weavr.Error.t()}
```

Assigns an IBAN to a managed account, enabling wire transfers.

`POST /managed_accounts/{id}/iban` — may be async; check the returned
`ManagedAccountIBAN.state` field. It may be `"PENDING_ALLOCATION"` until
bank details are ready.

# `block`

```elixir
@spec block(Weavr.Config.t(), String.t(), keyword()) ::
  :ok | {:error, Weavr.Error.t()}
```

Temporarily blocks a managed account.

`POST /managed_accounts/{id}/block` — supports `idempotency-ref`. Sets
`state.blockedReason` to `"USER"`, which means it can be unblocked later.

# `create`

```elixir
@spec create(Weavr.Config.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Weavr.Error.t()}
```

Creates a new managed account.

`POST /managed_accounts` — requires a stepped-up `auth_token`.

Required fields in `attrs`:
- `"profileId"` — from Multi Portal > API Credentials
- `"friendlyName"` — a display name for the account
- `"currency"` — ISO 4217 code

Optional: `"tag"` (custom searchable field).

# `destroy`

```elixir
@spec destroy(Weavr.Config.t(), String.t(), keyword()) ::
  :ok | {:error, Weavr.Error.t()}
```

Destroys (permanently deletes) a managed account.

`DELETE /managed_accounts/{id}` — irreversible. The account must have a
zero balance before it can be destroyed.

# `get`

```elixir
@spec get(Weavr.Config.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Weavr.Error.t()}
```

Fetches a managed account by id. `GET /managed_accounts/{id}`.

# `get_iban`

```elixir
@spec get_iban(Weavr.Config.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Weavr.Error.t()}
```

Fetches the IBAN details for a managed account. `GET /managed_accounts/{id}/iban`.

# `list`

```elixir
@spec list(
  Weavr.Config.t(),
  keyword()
) :: {:ok, map()} | {:error, Weavr.Error.t()}
```

Lists all managed accounts for the authenticated identity.

`GET /managed_accounts` — pass filter options in `opts[:filters]`.

# `statement`

```elixir
@spec statement(Weavr.Config.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, Weavr.Error.t()}
```

Returns the transaction statement for a managed account.

`GET /managed_accounts/{id}/statement` — see module doc for query params.
Pass them via `opts[:filters]`.

# `unblock`

```elixir
@spec unblock(Weavr.Config.t(), String.t(), keyword()) ::
  :ok | {:error, Weavr.Error.t()}
```

Unblocks a managed account.

`POST /managed_accounts/{id}/unblock` — only works when `state.blockedReason`
is `"USER"`. Accounts blocked by `"SYSTEM"` cannot be unblocked via the API.

# `update`

```elixir
@spec update(Weavr.Config.t(), String.t(), map(), keyword()) ::
  {:ok, map()} | {:error, Weavr.Error.t()}
```

Updates a managed account's details.

`PATCH /managed_accounts/{id}` — updatable fields include `"friendlyName"` and `"tag"`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*