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:
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
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.ai_labs locks a multi_use card to AI-lab merchants (OpenAI, Anthropic, Gemini). Anything else declines at authorization.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: