codespar_issue

Issue and control payment cards for AI agents or end-users. Virtual and physical cards, freeze, unfreeze and cancel, through the card-issuing partner (pan-LATAM issuing). Creates spend instruments; it does not move money.

Buy-sideYour agent is the spender: money leaves the wallet it governs, under a signed mandate.

Spend cards bound to the same mandate governance.

tool codespar_issue4 actionsmoves no moneyalways required action

The agent-spend-card primitive (the Mesada use case). It creates spend instruments, distinct from codespar_pay and codespar_charge, which move money.

Actions

`action`	What it does	Money	Needs
`card-virtual` example below	Issue a virtual card, active immediately (the default action)	no	`cardholder_idprogram_id`
`card-physical`	Issue a physical card shipped to shipping_address	no	`cardholder_idprogram_idshipping_address`
`card-control`	Freeze, unfreeze or cancel an existing card	no	`card_idcontrol`
`card-get`	Read a card's status	no	`card_id`

Unknown action: refused; nothing is issued. Measured 2026-09-09.

Names come from the published tool document (/v1/meta-tools.json, the same list the MCP server answers to tools/list); the one-line summaries and the money class are kept in the docs repository and checked against it on every build.

Example

action: "card-virtual", the default: a virtual card, active immediately.

Call · tools/call

arguments

{
  "name": "codespar_issue",
  "arguments": {
    "action": "card-virtual",
    "cardholder_id": "cardholder_0000",
    "program_id": "program_0000"
  }
}

Result

Result shape: see runtime. The tool document says card-virtual returns a card that is active immediately and card-get reads a card's status; it names no result field (the earlier page used card_id from the result to freeze it). The published document is /v1/meta-tools.json.

When to use

An agent needs a card to spend at merchants that take cards: card-virtual, bound to a cardholder and a card program at the issuer.
A physical card: card-physical with a shipping_address.
Stop or resume spend: card-control with control: "freeze", "unfreeze" or "cancel", and a reason stamped on the action.
Check state: card-get.

Arguments

Field	Type	Required	Description
`action`	`string`	No	`card-virtual` (default) \| `card-physical` \| `card-control` \| `card-get`
`cardholder_id`	`string`	To issue	Cardholder id at the issuer
`program_id`	`string`	To issue	Card program / BIN (issuer affinity group)
`card_id`	`string`	For `card-control`, `card-get`	The card
`control`	`string`	For `card-control`	`freeze` \| `unfreeze` \| `cancel`
`reason`	`string`	No	Reason stamped on a control action
`shipping_address`	`object`	For `card-physical`	Where the physical card ships
`metadata`	`object`	No	Provider-specific overrides

Errors and what to do

Error	Cause	What to do
`invalid_args`	`card-physical` without `shipping_address`, a control or get without `card_id`, an unknown `action`. Nothing is issued.	Fix the call against the Arguments table.
`400 issuer_corridor_unsupported`	No enabled issuer serves the (country, currency) corridor on this deployment. Issuing is off by default and enabled per corridor by an `ISSUER_*_ENABLED` flag, no matter what the mandate or key says.	An operator decision: enable the corridor and seed its credentials in the vault (the service refuses to boot with the flag on and the secret missing). On CodeSpar's hosted production the Pomelo corridor is enabled.
`403 live_issuer_test_key` / `403 stage_issuer_live_key`	The lane is environment-bound in both directions: a deployment that issues real cards refuses a test-mode key, and one that issues stage cards refuses a live-mode key.	Use the key that matches the deployment.
`409 mandate_already_bound`	One card per mandate: a second mint against a mandate that already backs a card.	Reuse the existing card, or sign a new mandate.

Money and mandate

No money moves on this tool. A card is a spend instrument: the money moves later, when the card is used, and that spend runs under the same mandate governance as the wallet (spending limits and policy are described under Wallets). One mandate backs at most one card.

codespar_pay: move money (cards are an instrument, not a transfer)
codespar_wallet: the governed funds behind the card
Wallets: spending limits and policy on agent spend
Autonomous card payments: the mandate that authorizes card spend

Notes

Operator setup. The card-issuing partner uses an API key (api_key auth_type). The operator connects the issuing account in /dashboard/auth-configs; the cardholder and the program / BIN are provisioned at the issuer and referenced by id.

From the SDK. session.issue(args) is the typed wrapper; session.execute("codespar_issue", arguments) takes the same arguments as the MCP call.

On this page