---
title: codespar_issue
description: Issue and control payment cards for AI agents or end-users. Virtual + physical cards, freeze/unfreeze/cancel. Routes to our card-issuing partner (pan-LATAM issuing). Typed wrapper session.issue(args).
---

import { Callout } from "fumadocs-ui/components/callout";
import { Tabs, Tab } from "fumadocs-ui/components/tabs";

# codespar_issue

<Callout title="Meta-tool" type="info">
**Buy-side.** Your agent is the spender: money leaves the wallet/account your agent governs, under a signed mandate.

`codespar_issue` creates and controls **payment cards** — the agent-spend-card primitive. It creates *spend instruments*, distinct from [`codespar_pay`](/docs/concepts/meta-tools/pay) / [`codespar_charge`](/docs/concepts/meta-tools/charge), which move money. Routes to our card-issuing partner (pan-LATAM card issuing-as-a-service). Covered by the `session.issue(args)` typed wrapper.
</Callout>

## Actions

| `action` | Purpose |
|---|---|
| `card-virtual` *(default)* | Issue a virtual card (active immediately) |
| `card-physical` | Issue a physical card (needs `shipping_address`) |
| `card-control` | Freeze / unfreeze / cancel an existing card |
| `card-get` | Read a card's status |

## Typed wrapper

<Tabs items={["TypeScript", "Python"]}>

```ts tab="TypeScript"
// Issue a virtual card for an agent
const card = await session.issue({
  action: "card-virtual",
  cardholder_id: "<issuer-user-id>",
  program_id: "<issuer-card-program-id>",
});

// Freeze it
await session.issue({
  action: "card-control",
  card_id: card.card_id,
  control: "freeze",
  reason: "suspicious activity",
});
```

```python tab="Python"
card = session.issue({
    "action": "card-virtual",
    "cardholder_id": "<issuer-user-id>",
    "program_id": "<issuer-card-program-id>",
})
```

</Tabs>

## Direct execute

```ts
const status = await session.execute("codespar_issue", {
  action: "card-get",
  card_id: "<card-id>",
});
```

## Args shape

| Field | Type | Required | Description |
|---|---|---|---|
| `action` | `"card-virtual"` \| `"card-physical"` \| `"card-control"` \| `"card-get"` | No | Defaults to `"card-virtual"` |
| `cardholder_id` | `string` | issue | Issuer-side user the card belongs to |
| `program_id` | `string` | issue | Card program / BIN at the issuing partner |
| `card_id` | `string` | control, get | Card id — required for `card-control` and `card-get` |
| `control` | `"freeze"` \| `"unfreeze"` \| `"cancel"` | control | Control action |
| `reason` | `string` | No | Reason stamped on a control action |
| `shipping_address` | `object` | physical | Shipping address (`card-physical` only) |
| `metadata` | `object` | No | Provider-specific overrides |

## Operator setup

- **Card-issuing partner** — API key (`api_key` auth_type). The operator connects the issuing account in `/dashboard/auth-configs`; the cardholder and program/BIN are provisioned at the issuer and referenced by id.

## See also

- [codespar_pay](/docs/concepts/meta-tools/pay) — move money (cards are a spend *instrument*, not a transfer)
- [Wallets](/docs/concepts/wallets) — spending limits + policy on agent spend
- [Tools & meta-tools](/docs/concepts/tools) — full meta-tool list