Skip to main content
POST
Create a card
Issues a card to a connected user. Send an Idempotency-Key, and on a 202 or a timeout retry with the same key. See Retry safely. To cap a multi-use card per charge and per day, week, month or year, or to choose the merchant categories it can be charged at, send spending_controls. A single-use card takes allowed_mccs alone, and the card network declines a charge at any other merchant. See Set spending controls.

Authorizations

Authorization
string
header
required

A platform access token. Get one on the Create an access token endpoint by exchanging your client_id + client_secret, then send it as Authorization: Bearer <token>. Tokens live one hour.

Headers

Idempotency-Key
string

Your key for this card. Retry with the same one after a timeout or a 202.

Body

application/json
user_id
string
required

The connected user the card is for.

amount_cents
integer
required

What the card can spend, in cents. At least 100.

Required range: x >= 100
type
enum<string>
default:single_use

single_use closes after its first approved charge.

Available options:
single_use,
multi_use
expires_at
string<date-time>

Closes a multi_use card at this time, at most 365 days out.

scope_preset
enum<string>

Locks a multi_use card to AI-lab merchants.

Available options:
ai_labs
spending_controls
object

Caps and merchant categories. A multi_use card takes all of them; a single_use card takes allowed_mccs alone, which the card network declines against. Not with scope_preset.

Response

The card.

object
enum<string>
required

Always card.

Available options:
card
id
string
required

The card's id.

status
string
required

creating, open, in_use, paused, pausing, closing, or closed.

type
string
required

single_use or multi_use.

spend_limit_cents
integer
required

What the card can spend in all.

balance_cents
integer
required

What's left to spend.

last4
string
required

The last four digits.

expiry
string
required

MM/YY.

created_at
string<date-time>
required

When it was issued.

spending_controls
object

The card's caps and merchant categories. On a multi_use card Agentcard checks each charge against them once the card network has approved it, and pauses the card on a charge that breaks one; the card network declines only charges past spend_limit_cents. A single_use card carries allowed_mccs alone, and the card network declines a charge at any other merchant as it is authorized.

user_id
string | null

The user the card is for.

cardholder_name
string

The name the card was issued in, for the payment form.

billing_address
string

The billing address, for the payment form.

funds_source
string

On a new card: what funded it.

transfer_id
string

On a company-funded new card: the transfer that funded it.

closed_reason
string

Only when closed: used, canceled, expired, declined.

card_expires_at
string<date-time>

When a multi_use card closes itself.