Cards & Issuing

Issue virtual cards linked to Wallgent wallets with spending controls and real-time authorization.

Overview

Wallgent integrates with Stripe Issuing to let your AI agents create and use virtual cards. Cards are linked to wallets — spending draws from the wallet balance, and policies control how much and where the card can be used.

Card types:

Type	Description
`PERSISTENT`	Reusable card for ongoing subscriptions and purchases
`SINGLE_USE`	One-time card that is automatically cancelled after capture

Cardholders

Before issuing cards, create a cardholder to associate billing information.

Create a Cardholder

POST /v1/cards/cardholders

Request Body

Field	Type	Required	Description
`name`	`string`	Yes	Cardholder name
`email`	`string`	No	Contact email
`phone`	`string`	No	Contact phone
`billingAddress`	`object`	Yes	Billing address (see below)

Billing Address

Field	Type	Required	Description
`line1`	`string`	Yes	Street address
`line2`	`string`	No	Apartment, suite, etc.
`city`	`string`	Yes	City
`state`	`string`	Yes	State/province
`postalCode`	`string`	Yes	Postal code
`country`	`string`	Yes	ISO 3166-1 alpha-2 country code

{
  "name": "Research Agent Corp",
  "email": "agent@company.com",
  "billingAddress": {
    "line1": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94105",
    "country": "US"
  }
}

Issuing Cards

Create a Card

POST /v1/cards

Request Body

Field	Type	Required	Description
`walletId`	`string`	Yes	Wallet to fund the card from
`type`	`string`	Yes	`PERSISTENT` or `SINGLE_USE`
`spendingLimits`	`array`	No	Spending limit rules

Spending Limit Object

Field	Type	Required	Description
`amount`	`string`	Yes	Maximum spend for the interval
`interval`	`string`	Yes	`per_authorization`, `daily`, `weekly`, `monthly`, `yearly`, `all_time`
`categories`	`string[]`	No	Restrict to specific MCC categories

const card = await wg.cards.create({
  walletId: 'wal_01J...',
  type: 'PERSISTENT',
  spendingLimits: [
    { amount: '500.00', interval: 'monthly' },
    { amount: '100.00', interval: 'per_authorization' },
  ],
});

List Cards

GET /v1/cards?walletId=wal_01J...

Returns all cards for the organization, optionally filtered by wallet.

Get Card Details

GET /v1/cards/:id

Returns card metadata (last4, brand, status). Does not include the full card number or CVC.

Get Sensitive Card Details

GET /v1/cards/:id/details

Returns the full card number, CVC, and expiry. Requires the cards:sensitive_read permission. Every access is audit-logged for PCI-DSS compliance.

{
  "number": "4242424242424242",
  "cvc": "123",
  "expMonth": 12,
  "expYear": 2027
}

Card Management

Freeze / Unfreeze

PATCH /v1/cards/:id

{ "status": "INACTIVE" }

Set status to INACTIVE to freeze or ACTIVE to unfreeze.

Update Spending Limits

PATCH /v1/cards/:id

{
  "spendingLimits": [
    { "amount": "1000.00", "interval": "monthly" }
  ]
}

Cancel a Card

DELETE /v1/cards/:id

Permanently cancels the card. This cannot be undone.

Authorization Flow

When a card is used at a merchant, Stripe sends a real-time authorization request:

Stripe checks the card's spending limits and status
The authorization amount is held against the wallet balance
On capture, the hold is converted to a permanent debit
On reversal, the hold is released

List Authorizations

GET /v1/cards/:id/authorizations

Returns the authorization history for a card.

Webhook Events

Event	Description
`card.created`	Card was created
`card.updated`	Card status or limits changed
`card.cancelled`	Card was cancelled
`card.authorization.approved`	Authorization was approved
`card.authorization.declined`	Authorization was declined
`card.authorization.captured`	Authorization was captured (funds debited)
`card.authorization.reversed`	Authorization was reversed (hold released)
`card.refund.created`	Refund was issued to the card

MCP Tools

Tool	Description
`wallgent_create_card`	Create a virtual card linked to a wallet
`wallgent_list_cards`	List cards, optionally by wallet
`wallgent_freeze_card`	Freeze a card to stop spending
`wallgent_unfreeze_card`	Unfreeze a card to resume spending

Permissions

Permission	Required For
`payments:write`	Create cards, create cardholders, update/cancel cards
`payments:read`	List cards, get card details, list authorizations
`cards:sensitive_read`	Access full card number and CVC

On this page