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

# Accounts overview

> What a Sakawave account is, the flags that govern it, and how funding destinations attach to it.

An **account** is a balance. It belongs either to your business or to one of your [customers](/services/customers/overview), holds exactly one asset, and is the only place money lives — customers, recipients, and transfers all resolve to accounts in the end.

An account is not reachable from the outside world when it is first opened. Money arrives through an **account detail**: a bank account number, a mobile-money handle, or an on-chain address, issued by a payment provider on request. An account with no detail can still hold and move value inside Sakawave; it just has no address anyone can pay into.

## The object

| Field group | Fields | Notes |
| - | - | - |
| Identity | `id`, `name`, `tag` | `name` is your label. `tag` is the platform-minted public handle — two letters and ten digits — that another Sakawave business can pay. |
| Classification | `type`, `category`, `currency` | `category` follows from `currency` and is never chosen. |
| Money | `balance`, `balanceFormatted` | `balance` is minor units as a string; use it for arithmetic. `balanceFormatted` is for display only. |
| State | `status`, `canDebit`, `canCredit`, `transferReady` | Four independent gates. See below. |
| Ownership | `isWalletAccount`, `customerId` | A wallet account belongs to a customer; everything else belongs to you. |
| Yours | `metadata` | Free-form JSON, stored and returned verbatim. |
| Closure | `closedAt`, `closureReason` | Both null until closed. |

## Four gates, not one

Whether an account can move money is the conjunction of four separate things. Reading only `status` will mislead you.

| Gate | Meaning |
| - | - |
| `status` | `active` is the only status that moves money. `inactive` is a reversible stop, `frozen` is a compliance or provider hold, `closed` is terminal. |
| `canDebit` | Money may leave. Held separately so an account can be stopped in one direction — a closing account can still take refunds. |
| `canCredit` | Money may arrive. |
| `transferReady` | The account is bound to a payment provider. **False until the first detail is issued**, and while false the account cannot send or receive externally. |

`transferReady` is the one that surprises people. A freshly opened account is `active`, `canDebit`, `canCredit` — and still cannot reach the outside world.

## Types

`operational` and `savings` are the only types you can open, and they behave **identically**: transactable, no interest, no lock. `savings` is a bucket you choose, not a different backend treatment.

The other types — `settlement`, `collection`, `fee`, `revenue`, `suspense` — describe the platform's own structure. You may see them on accounts Sakawave opened, so read `type` defensively, but you cannot ask for one.

## Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> active: POST /v1/accounts
    active --> active: POST /v1/accounts/{accountId}/details
    active --> inactive: platform
    inactive --> active: platform
    active --> frozen: compliance or provider hold
    frozen --> active: hold lifted
    active --> closed: dashboard only
    inactive --> closed: dashboard only
    note right of active
        transferReady flips to true when
        the first detail is issued.
    end note
    note right of closed
        Terminal. Details are retired
        and the balance must be zero.
    end note
```

<Warning>
  **There is no close endpoint on the Business API.** Closing an account is a dashboard action. Plan for it: any offboarding flow you build with this API stops one step short and has to be finished by a person.
</Warning>

A frozen account cannot be closed at all, even from the dashboard. The hold was put there by compliance or a provider, and lifting it comes first.

## Account details

A detail is how the outside world reaches the account.

| Field | Notes |
| - | - |
| `account` | The account this detail funds: its `id`, `currency` and `name`. |
| `beneficiary` | Who a payer is sending to, as the bank knows them: `name` and `address`. |
| `details.id`, `details.type` | The detail itself. `type` is `bank_account`, `mobile_money`, or `wallet_address`, and follows from the account's category. |
| `details.domestic` | What a payer in the account's own currency zone sends to: `accountNumber`, plus `routingNumber`, `sortCode`, `bankName` and `bankAddress` where the corridor uses them. This is what you publish. |
| `details.international` | What a payer abroad sends to: `iban`, `swiftCode` and the bank fields. `null` unless the account was issued an IBAN or SWIFT code. See [what a payer needs](/services/accounts/currencies-and-funding-rails#what-a-payer-needs). |
| `details.wallet` | The `chain` and `address` of an on-chain destination. `null` for a bank detail. |
| `details.paymentRails` | How the destination can be paid into, such as `ach_push` or `wire`. |
| `details.providerBacked` | Whether an integration issued it. Which integration stays private. |

Every block is always present. A block the destination does not offer is `null`, and so is a field inside a block that the corridor does not use. A GBP detail has a `sortCode` and a `null` `routingNumber`.

You cannot name your own account number. A destination is allocated by the provider — a business that could assert its own number could publish one it does not own and have its customers pay a stranger.

Issuance can complete asynchronously: `201` means issued, `202` means the provider is still working and you should poll.

## Events

| Event | When |
| - | - |
| `account.created` | An account was opened. |
| `account.updated` | The account was bound to a provider (`transferReady` became true), it was closed, or a provider reported a change. |
| `account.detail.created` | A destination was issued — including one that arrived after a `202`. |
| `account.detail.updated` | A provider reported a change to an existing destination. |

`account.updated` is the intended way to learn that `transferReady` flipped. Subscribe rather than poll.

## Next

<CardGroup cols={2}>
  <Card title="Introduction" icon="book-open" href="/services/accounts/introduction">
    Your money versus your customers' money.
  </Card>

  <Card title="Get started" icon="play" href="/services/accounts/get-started">
    Open an account and give it a payable destination.
  </Card>

  <Card title="Setup and configuration" icon="sliders" href="/services/accounts/setup-and-configuration">
    What is checked on opening and issuing details, rate limits, and webhooks.
  </Card>

  <Card title="Currencies and funding rails" icon="route" href="/services/accounts/currencies-and-funding-rails">
    What you may hold, and how each kind is funded.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.