Skip to main content

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.

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

StateCreated viaEffect
ACTIVEPOST /wallets (default), PUT /wallets/{wallet} with {"status":"ACTIVE"}Wallet accepts all operations: balance queries, inbound and outbound payment orders, approvals, cancellations.
DISABLEDPUT /wallets/{wallet} with {"status":"DISABLED"}New payment orders are rejected. Existing in-flight orders complete normally. Balance queries still work.

​
State diagram

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

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 timeContinues normally?
AWAITING_APPROVAL✅ — can still be approved or canceled. New orders cannot be created.
PENDING / PROCESSING✅ — runs to completion. Webhooks still fire.
Any final stateN/A — already terminal.
The transition is a soft freeze — existing commitments honor through; new commitments are blocked.

​
DISABLED → ACTIVE

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

FieldWhy immutable
nameUsed as URL path segment; changing would break links and references. Attempts return LABEL_IMMUTABLE.
idDatabase key; never changes.
kindDerived from resource type.
createdAtAudit log.
selfNameDerived 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

ConcernWallet 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

Wallet overview

Anatomy, identifiers, balances.

Update wallet

The endpoint that changes status.