Skip to main content
Create a virtual card for a user from your server, with your org token and their user_id. The card can never spend more than the money behind it.

Fund the card

Every card draws on a balance, and your company’s funding setting says which one. It applies to every card and can’t be set per card. The company balance is the simpler start, because your server never waits on the user to pay. Live company-funded cards need an active subscription. GET /api/v2/company_wallet shows what’s free to spend. To have the user fund their own balance, verify their phone once, then create a link:
In production the user needs a verified identity before funding, or the request is refused with kyc_required. The last response then carries a checkout_url. The user opens it and pays in their own browser. In sandbox no one pays: the test money lands right away and the code is always 111111. The User balance reference has the details.

Create a card

The response never carries the card number. Read the credentials when your agent reaches the payment form.
string
required
The connected user the card is for.
number
required
What the card can spend, in cents. Minimum 100.
string
single_use (default) closes after the first approved charge. multi_use stays open until its limit is spent, for subscriptions or merchants that charge repeatedly. Optional expires_at closes it at that time.
string
ai_labs locks a multi_use card to AI-lab merchants (OpenAI, Anthropic, Gemini). Anything else declines at authorization.
Send an Idempotency-Key on every create. A retry with the same key returns the same card and spends once, so a timeout never buys two cards. In sandbox, a card funded from a user’s balance ignores the key, so each retry creates another test card. A company-funded card can take up to a minute to fund. Past that, the create answers 202 with funding_in_progress. Wait retry_after_seconds, then send the same request with the same key to collect the card. Every card arrives as a card.created webhook. The API reference lists every field.

Handle a refusal

Sandbox returns a test card immediately. In production a create can be refused first, and no money moves: A refusal looks like this:

Rules for your agent