Skip to main content
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 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

Response: the updated wallet (status: "DISABLED", walVersion incremented, new updatedAt). Effect on in-flight orders: The transition is a soft freeze — existing commitments honor through; new commitments are blocked.

​
DISABLED → 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

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

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.