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

Managed Cards — virtual and physical payment cards.

All paths and operations are verified against Weavr's published docs.

## Confirmed endpoints

  * `GET    /managed_cards` — list all cards
  * `POST   /managed_cards` — create a card
  * `GET    /managed_cards/{id}` — get a card
  * `PATCH  /managed_cards/{id}` — update card details
  * `POST   /managed_cards/{id}/block` — block a card
  * `POST   /managed_cards/{id}/unblock` — unblock a card
  * `DELETE /managed_cards/{id}` — destroy a card
  * `POST   /managed_cards/{id}/physical` — upgrade to physical card
  * `GET    /managed_cards/{id}/statement` — card transaction statement
  * `GET    /managed_cards/{id}/spend_rules` — get spend rules
  * `POST   /managed_cards/{id}/spend_rules` — create spend rules
  * `PUT    /managed_cards/{id}/spend_rules` — update spend rules
  * `DELETE /managed_cards/{id}/spend_rules` — remove spend rules

## Card modes

  * **Prepaid** — the card has its own balance; fund it via transfers.
  * **Debit** — taps into the balance of a linked parent managed account
    (set `"parentManagedAccountId"` at creation).

## Physical card fulfilment states (via webhook)

`"REQUESTED"` → `"SENT_FOR_FULFILLMENT"` → `"DISPATCHED"` → `"DELIVERED"`

These are reported via the `managed_cards_physical_cards_upgrade_watch` webhook.

## List query parameters

  * `offset`, `limit`, `profileId`, `friendlyName`, `currency`, `tag`
  * `state` — `"ACTIVE"`, `"MANAGED"`, `"DESTROYED"`
  * `state.blockedReason` — `"USER"`, `"SYSTEM"`
  * `type` — `"VIRTUAL"`, `"PHYSICAL"`
  * `mode` — `"PREPAID"`, `"DEBIT"`
  * `renewalType` — `"RENEW"`, `"NO_RENEW"`
  * `createdFrom`, `createdTo` — epoch milliseconds

## Important notes

  * Amounts in **minor units** (1000 = £10.00).
  * Use `"userId"` (not the deprecated `"linkedUserId"` inside
    `threeDSecureAuthConfig`) to assign a card to a specific user at creation.

# `block`

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

Blocks a managed card.

`POST /managed_cards/{id}/block` — sets `state.blockedReason` to `"USER"`,
which can be reversed by `unblock/3`.

# `create`

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

Creates a new managed card.

`POST /managed_cards`

Required fields in `attrs`:
- `"profileId"` — from Multi Portal > API Credentials
- `"friendlyName"` — display name
- `"currency"` — ISO 4217 code
- `"cardholderMobileNumber"` — object with `"countryCode"` and `"number"`
- for debit mode: `"parentManagedAccountId"`, `"cardLevelClassification": "DEBIT"`

Optional: `"nameOnCard"`, `"tag"`, `"userId"` (assign to a specific user),
`"threeDSecureAuthConfig"`, `"renewalType"`.

# `create_spend_rules`

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

Creates spend rules for a managed card. `POST /managed_cards/{id}/spend_rules`.

# `delete_spend_rules`

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

Removes all spend rules from a managed card. `DELETE /managed_cards/{id}/spend_rules`.

# `destroy`

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

Destroys (permanently removes) a managed card.

`DELETE /managed_cards/{id}` — irreversible.

# `get`

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

Fetches a managed card by id. `GET /managed_cards/{id}`.

# `get_spend_rules`

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

Gets the spend rules for a managed card. `GET /managed_cards/{id}/spend_rules`.

# `list`

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

Lists all managed cards for the authenticated identity.

`GET /managed_cards` — pass filters in `opts[:filters]`.

# `manufacturing_states`

```elixir
@spec manufacturing_states() :: [String.t()]
```

The confirmed physical card fulfilment states.

# `statement`

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

Returns the transaction statement for a managed card.

`GET /managed_cards/{id}/statement` — pass filters in `opts[:filters]`.
Supports `offset`, `limit`, `orderByTimestamp`, `fromTimestamp`, `toTimestamp`,
`showFundMovementsOnly`, `singleEntryPerTransaction`.

# `unblock`

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

Unblocks a managed card. `POST /managed_cards/{id}/unblock`.

# `update`

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

Updates a managed card's details. `PATCH /managed_cards/{id}`.

# `update_spend_rules`

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

Updates individual spend rules for a managed card. `PUT /managed_cards/{id}/spend_rules`.

# `upgrade_to_physical`

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

Upgrades a virtual card to a physical card, triggering fulfilment.

`POST /managed_cards/{id}/physical` — fulfilment state changes are
reported via the `managed_cards_physical_cards_upgrade_watch` webhook.
Pass delivery address and other physical card config in `attrs`.

---

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