> ## Documentation Index
> Fetch the complete documentation index at: https://developers.bloobank.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallet lifecycle

> The wallet state machine — ACTIVE, DISABLED, and the transitions between them.

Every wallet is in one of two operational states. The state machine is intentionally simple — the entire surface area is two states and one bi-directional transition.

## States

| State      | Created via                                                                   | Effect                                                                                                         |
| ---------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `ACTIVE`   | `POST /wallets` (default), `PUT /wallets/{wallet}` with `{"status":"ACTIVE"}` | Wallet accepts all operations: balance queries, inbound and outbound payment orders, approvals, cancellations. |
| `DISABLED` | `PUT /wallets/{wallet}` with `{"status":"DISABLED"}`                          | New payment orders are rejected. Existing in-flight orders complete normally. Balance queries still work.      |

## State diagram

```mermaid theme={"dark"}
stateDiagram-v2
    [*] --> ACTIVE: POST /wallets
    ACTIVE --> DISABLED: PUT {"status":"DISABLED"}
    DISABLED --> ACTIVE: PUT {"status":"ACTIVE"}

    note right of ACTIVE
      Normal operation:
      ✓ Read balance
      ✓ Create payment orders
      ✓ Approve outbound orders
      ✓ Cancel outbound orders
    end note

    note right of DISABLED
      Frozen for new operations:
      ✓ Read balance
      ✓ Existing orders complete
      ✗ Create new payment orders
    end note
```

There are no terminal states — `DISABLED` is reversible. There is no `DELETED` state; wallets persist for audit purposes even when no longer in use.

## When to use `DISABLED`

* **Suspected compromise** of the credential that operates the wallet — disable while you investigate, re-enable after rotation.
* **Operational pause** — e.g., during reconciliation cutover, year-end balance freeze.
* **Decommissioning** a wallet that no longer corresponds to an active business line. The wallet stays available for historical queries; new operations are explicitly blocked.

## Transitions in detail

### `ACTIVE` → `DISABLED`

```http theme={"dark"}
PUT /wallets/production-main HTTP/1.1
Content-Type: application/json

{ "status": "DISABLED" }
```

Response: the updated wallet (`status: "DISABLED"`, `walVersion` incremented, new `updatedAt`).

**Effect on in-flight orders:**

| Order state at transition time |                          Continues normally?                         |
| ------------------------------ | :------------------------------------------------------------------: |
| `AWAITING_APPROVAL`            | ✅ — can still be approved or canceled. New orders cannot be created. |
| `PENDING` / `PROCESSING`       |             ✅ — runs to completion. Webhooks still fire.             |
| Any final state                |                        N/A — already terminal.                       |

The transition is a **soft freeze** — existing commitments honor through; new commitments are blocked.

### `DISABLED` → `ACTIVE`

```http theme={"dark"}
PUT /wallets/production-main HTTP/1.1
Content-Type: application/json

{ "status": "ACTIVE" }
```

Response: the updated wallet (`status: "ACTIVE"`, `walVersion` incremented).

Resumes acceptance of new payment orders immediately. No backfill or replay of orders attempted during the disabled window.

## What you cannot change

| Field       | Why immutable                                                                                           |
| ----------- | ------------------------------------------------------------------------------------------------------- |
| `name`      | Used as URL path segment; changing would break links and references. Attempts return `LABEL_IMMUTABLE`. |
| `id`        | Database key; never changes.                                                                            |
| `kind`      | Derived from resource type.                                                                             |
| `createdAt` | Audit log.                                                                                              |
| `selfName`  | Derived from `name`.                                                                                    |

To "rename" a wallet, you must create a new wallet with the new name and migrate balance/state externally. There is no in-place rename — that is intentional.

## Operational considerations

### Effect on webhooks

Disabling a wallet does **not** affect webhook delivery — events for in-flight orders continue to fire as their states transition. Your webhook consumer should not assume the wallet is `ACTIVE` when an event arrives.

### Concurrent disable + create

There is no race protection between `PUT .../status=DISABLED` and a concurrent `POST .../paymentOrders`. The concrete outcomes:

* If `POST` arrives before `PUT` commits: order is created. The disable transition does not roll back already-accepted orders.
* If `POST` arrives after `PUT` commits: order is rejected (server-side state check).

If you need strict serialization, coordinate at the application level (e.g., a lock around state transitions).

### Disable during outage recovery

If an outbound provider is unavailable, you may see a backlog of `PENDING` orders. **Disabling the wallet does not cancel them** — they remain pending until the provider responds. To clear a backlog, cancel each outbound order in `AWAITING_APPROVAL` (those that have not yet been submitted to the provider) and wait for the rest to settle naturally.

## What `DISABLED` does not protect against

| Concern                                               |                      Wallet status helps?                      |
| ----------------------------------------------------- | :------------------------------------------------------------: |
| Stolen credential creating new wallets in your tenant | ❌ — disable scope is per-wallet; revoke the credential instead |
| In-flight orders completing after disable             |                   ❌ — those run to completion                  |
| Past orders being visible                             |                  ❌ — `GET` still returns them                  |
| Historical balance discrepancy                        |                  ❌ — `GET balance` still works                 |

For credential-level kill-switch behavior, request revocation of the Access Key from your account team.

## Next

<CardGroup cols={2}>
  <Card title="Wallet overview" icon="wallet" href="/get-started/wallets/overview">
    Anatomy, identifiers, balances.
  </Card>

  <Card title="Update wallet" icon="pen" href="/api-reference/wallets/update">
    The endpoint that changes status.
  </Card>
</CardGroup>