> ## 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.

# Cards overview

> USD virtual and disposable cards — what they are, the nine states they move through, and the two objects that describe their activity.

A **card** is a USD Mastercard your business issues to one of its customers. It carries its own balance, funded from one of your accounts, and it spends at merchants like any other card.

Everything here is USD. There is no other card currency, and no physical card.

<Warning>
  **A business client cannot currently issue a card through this API.** A `customerId` is required, and that customer must be at tier 2 — but [every customer is created at tier 1 and nothing raises it](/services/customers/identity-and-verification#tiers). Every issuance attempt ends in `404 card_holder_not_found`. The rest of this service is documented as built; read the issuance pages as a specification of intent rather than something you can exercise today.
</Warning>

## Two types

| | `virtual` | `disposable` |
| - | - | - |
| Reusable | Yes | No — moves to `used` after its first payment |
| Spending controls | Supported | **Rejected** at creation |
| Typical use | A subscription card, a team card | A single online purchase |

## The object

```json theme={null}
{
  "id": "01K2Z3AB4S5T6V7W8XYZABCDEF",
  "label": "Ada travel card",
  "type": "virtual",
  "brand": "mastercard",
  "currency": "USD",
  "status": "active",
  "maskedPan": "•••• •••• •••• 4242",
  "expiryMonth": 8,
  "expiryYear": 2028,
  "holder": { "type": "customer", "id": "01K2Z3AB4C5D6E7F8G9HJKMNPQ", "name": "Ada Okafor" },
  "balance": "5000",
  "balanceFormatted": "50.00",
  "spendingControls": { "transactionAmountLimit": "2000", "dailyAmountLimit": "5000", "dailyTransactionCount": 10 },
  "operations": []
}
```

`balance` is USD minor units as a string — `"5000"` is \$50.00. Cards expire two years after issuance.

## Statuses

```mermaid theme={null}
stateDiagram-v2
    [*] --> creating: POST /v1/cards
    creating --> active: provider issued and funded
    creating --> failed: issuance failed
    creating --> funding_failed: issued, funding failed
    active --> frozen: freeze
    frozen --> active: unfreeze
    active --> used: disposable card spent
    active --> terminating: terminate
    frozen --> terminating: terminate
    terminating --> terminated: balance swept
    active --> fraud: platform
```

| Status | Can spend | Can fund or withdraw | Terminal |
| - | - | - | - |
| `creating` | No | No | No |
| `active` | Yes | Yes | No |
| `frozen` | No | **Yes** | No |
| `funding_failed` | No | No | No — retry issuance |
| `used` | No | No | Yes |
| `terminating` | No | No | Yes |
| `terminated` | No | No | Yes |
| `failed` | No | No | Yes |
| `fraud` | No | No | Yes |

The row worth noticing is `frozen`: a frozen card refuses merchants but still accepts funding and withdrawal. Freezing is a spending control, not a lock on the money.

## Operations and payments

Two different records, easily confused.

| | **Operation** | **Payment** |
| - | - | - |
| What | Something *you* did to the card | Something the *card* did at a merchant |
| Kinds | `issuance`, `funding`, `withdrawal`, `termination` | A purchase, refund, or reversal |
| Where | `operations` on the card, from `GET /v1/cards/{cardId}` | `GET /v1/cards/{cardId}/transactions` |
| Statuses | `created`, `submitting`, `pending`, `completed`, `failed` | `pending`, `completed`, `failed`, `reversed`, `refunded` |

Operations are how you track your own instructions asynchronously. Payments are the card's spending history.

## The hidden account

Every card gets its own USD balance account, opened by Sakawave and marked invisible. It will never appear in `GET /v1/accounts`, and you cannot transfer to or from it directly — funding and withdrawal are the only doors.

That is why a card balance is read from the card, not from the accounts service.

## Events

| Event | When |
| - | - |
| `card.created` | A card was issued |
| `card.updated` | Its status or controls changed |
| `card.transaction.created` | A payment was authorised |
| `card.transaction.completed` | A payment settled |
| `card.transaction.failed` | A payment failed |
| `card.transaction.reversed` | An authorisation was reversed |

## Next

<CardGroup cols={2}>
  <Card title="Introduction" icon="book-open" href="/services/cards/introduction">
    What cards are for, and the tier gates in front of them.
  </Card>

  <Card title="Get started" icon="play" href="/services/cards/get-started">
    Issue, fund, and read a card.
  </Card>

  <Card title="Setup and configuration" icon="sliders" href="/services/cards/setup-and-configuration">
    Feature gates, limits, and idempotency.
  </Card>

  <Card title="Card programs and PAN handling" icon="shield" href="/services/cards/card-programs-and-pan-handling">
    Spending controls, credentials, and what never to store.
  </Card>
</CardGroup>


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