# Card

URL: /business/nouns/card · Id: `noun:card`

> A Card is a payment credential a Startup issues to one Worker under one Mandate, with controls compiled from that Mandate.

A Card is a payment credential a [Startup](/business/nouns/startup) issues to one [Worker](/business/nouns/worker) under one [Mandate](/business/nouns/mandate), with controls compiled from that Mandate.

## Properties
| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `form` | `string` | Yes | `singleUse` pays one Task and closes; `merchant` pays one merchant until the Mandate ends; `physical` is for a Human only. |
| `status` | `string` | Yes | Follows its Mandate: frozen while the Mandate is paused, closed once it is revoked or a single-use Card has paid. |
| `merchants` | `string[]` | No | The merchants or merchant categories it may pay, compiled from the Mandate. |
| `limit` | [Limit](/business/nouns/limit) | Yes | The amount per charge and per period; every interval is set, so the rail’s default never decides. |
| `task` | [Task](/business/nouns/task) | No | For a `singleUse` Card: the Task it pays for, which also holds the receipt. |
| `last4` | `string` | No | The last four digits; the full number never leaves the rail. |

## Object
```json
{
  "$id": "https://api.sb/quietcopy.com/cards/card_1",
  "$type": "Card",
  "form": "singleUse",
  "status": "active",
  "merchants": [
    "advertising"
  ],
  "limit": "limit_1",
  "task": "task_1",
  "last4": "4242"
}
```

## Relationships
- <a id="rel-carried-by"></a>A Card **is carried by** one [Worker](/business/nouns/worker): a [Worker](/business/nouns/worker) carries the Cards issued for its [Mandates](/business/nouns/mandate); the cardholder on the rail is always the [Company](/business/nouns/company). `carriedBy`, inverse [`carries`](/business/nouns/worker#rel-carries).
- <a id="rel-funded-by"></a>A Card **is funded by** one [Mandate](/business/nouns/mandate): a [Mandate](/business/nouns/mandate) funds the Cards that spend under it; pausing it freezes them and revoking it closes them. `fundedBy`, inverse [`funds`](/business/nouns/mandate#rel-funds).

## Lifecycle

| State | Meaning | Moves to |
| --- | --- | --- |
| `active` (first) | It pays the merchants its Mandate allows, within its Limit. | `frozen` on [`Mandate.paused`](/business/events/Mandate.paused) when the Mandate is this Card’s; `closed` on [`Mandate.revoked`](/business/events/Mandate.revoked) when the Mandate is this Card’s; `closed` on [`Mandate.spent`](/business/events/Mandate.spent) when this Card is single-use and paid its Task |
| `frozen` | Its Mandate is paused, so every charge is declined. | `active` on [`Mandate.resumed`](/business/events/Mandate.resumed) when the Mandate is this Card’s; `closed` on [`Mandate.revoked`](/business/events/Mandate.revoked) when the Mandate is this Card’s |
| `closed` | Its Mandate is revoked or its single use is spent; the record and its charges stay. | None: it ends here. |

## Verbs
| Verb | Description | Subject | Event | Class |
| --- | --- | --- | --- | --- |
| [Card.issue](/business/nouns/card/issue) | Issue creates a Card under a Mandate once the Mandate check passes, with explicit limits on every interval. | [Treasurer](/agents/finance/treasurer) | [`Card.issued`](/business/events/Card.issued) | Two-way: `try`, `send`, `do` |
| <a id="get"></a>[Card.get](/business/nouns/card/get) | Returns one Card by id. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |
| <a id="list"></a>[Card.list](/business/nouns/card/list) | Returns Cards, newest first, one page at a time. Inherited from [Noun](/business/nouns/noun). | None. | None. | Read: `try`, `do` |

A Card is kept forever and never edited: it has no `update` or `delete`.

## Permissions
Which Access level may call each Verb. One-way Verbs wait their delay window.

| Operation | `owner` | `admin` | `member` | `viewer` |
| --- | --- | --- | --- | --- |
| `Card.get` | Yes | Yes | Yes | Yes |
| `Card.list` | Yes | Yes | Yes | Yes |
| `Card.issue` | Yes | Yes | Yes | No |

## Stripe
**Issuing Card** (`issuing.card`). The source of truth is db.sb, and Stripe holds a copy written from it.

| Property | Stripe field | Source of truth |
| --- | --- | --- |
| `status` | `status` | db.sb |
| `limit` | `spending_controls.spending_limits[]` | db.sb |
| `merchants` | `spending_controls.allowed_categories` | db.sb |
| `last4` | `last4` | Stripe |

## Call it

**Ask**

```text
Issue the latest card with a mandate.
```

**API**

```bash
curl -X POST https://api.sb/ledgerlark.com/cards/issue \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mandate":"mandate_1","form":"singleUse"}'
```

```json
{
  "api": "https://api.sb/ledgerlark.com",
  "card": {
    "$id": "https://api.sb/ledgerlark.com/cards/card_1",
    "$type": "Card",
    "form": "singleUse",
    "status": "active",
    "limit": "limit_1"
  },
  "action": {
    "$id": "https://api.sb/ledgerlark.com/actions/action_1",
    "operation": "Card.issue",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/ledgerlark.com/actions/action_1"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const card = await $.Card.issue({ mandate: 'mandate_1', form: 'singleUse' })
```

**CLI**

```bash
npx startup-builder do Card.issue --json '{"mandate":"mandate_1","form":"singleUse"}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "code": "return await $.Card.issue({ mandate: 'mandate_1', form: 'singleUse' })"
  }
}
```

## Example
The [Marketing Lead](/agents/marketing/marketing-lead) [Agent](/business/nouns/agent) at a sleep-tracking app holds two Cards under one Mandate. One is a `merchant` Card for its ad network at $2,000 a month; the other is a `singleUse` Card for a $450 design tool. Pausing the Mandate freezes both at once.