user_id, read the number at the checkout, and close the card when it’s done.
To let your agent create cards itself, see the MCP server.
Your credential decides the mode: sandbox credentials issue test cards no real merchant accepts, production credentials issue real ones.
The user has to be connected first, or created by your company with POST /api/v2/users. In production they also need to pass identity verification.
The card object
The card object never carries the number or CVC. Read the credentials for those.
Fund a card
Your company’s funding setting decides where the money comes from. It applies to every card and can’t be set per card, so sendingfunds_source answers 400 funds_source_not_supported. GET /api/v2/company_wallet returns it as default_funds_source.
Check what your company can spend with the company wallet. Fund a user’s own balance with
POST /api/v2/wallet/fund. Sandbox company-funded cards skip identity verification, so test the kyc_required answer in production.
Use your company’s token
Every endpoint here takes your platform token and names the user withuser_id. A user’s connection token is refused:
Retry safely
Send anIdempotency-Key on every create. A retry with the same key collects the same card and spends once. 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. After a timeout, retry with the same key too, so you never issue a second card.
Retry a basket on the same single-use card
A single-use card closes at its first approved charge. When the merchant then voids that authorization and nothing else counts against the limit, the card opens again under the sameid, with its limit back and a new number, so a retry goes on the card you already hold instead of a second one. A card.updated event carries the new last4 and reason: reissued_after_void; read the number again from GET /cards/:id/credentials, which always answers with the live card.
A card that closed for any other reason stays closed: its limit spent, a merchant that only partly reversed the charge, an expiry, or a close you asked for.
Set spending controls
Cap what a multi-use card spends on one charge and over a day, a week, a month or a year, and choose the merchant categories it can be charged at. Sendspending_controls with type: multi_use when you create the card:
Every amount is an integer in cents, at least 100. A card takes
allowed_mccs or blocked_mccs, not both:
allowed_mccs and nothing else. It closes after its first approved charge, so a cap has nothing left to hold. A card created with scope_preset takes no controls at all, because the preset already fixes its merchants. Either one answers 400 with spending_controls_unsupported:
Choose where a single-use card can be charged
Sendallowed_mccs with type: single_use, and the card network itself declines a charge at any other merchant:
GET:
PATCH answers 400 with spending_controls_unsupported, and a new card is the way to change it.
Change the controls
Sendspending_controls to PATCH /api/v2/cards/{card_id}. A field you leave out keeps its value, null removes it, and a value replaces it. To swap the allow list above for a block list:
per_authorization_cents and limits, and the next charge is checked against the new list. Sending null for every field removes the controls.
A PATCH that sends spend_limit_cents and spending_controls together applies both or neither: when the new limit is refused, the controls stay as they were. When two updates to the same card’s controls cross, the one that lands second answers 409 with policy_changed and applies nothing. Read the card and send your change again:
Add controls to a card with a preset
A card that already carries rules of its own keeps them.spending_controls reads and changes only the controls you set through it, and the card’s rules stay in their mode. On a card whose preset is in Watch mode, a charge that breaks a control goes through, the card stays open, and the owner is told every control the charge broke.
A card that follows a preset other cards share, such as a saved preset or a company preset, takes no controls: changing them would change that preset for every card on it. The update answers 409 with spending_controls_shared_preset and changes nothing:
spending_controls to cap that spend instead:
What a refusal says
Where each control is checked
On a multi-use card the card network declines any charge pastspend_limit_cents, the card’s total, and that total is the only control the network checks before it approves a charge. A single-use card’s allowed_mccs sit with the network too, so it declines a charge outside them before it approves one.
Agentcard checks a multi-use card’s spending controls on each charge after the card network has approved it. A charge that breaks a control still goes through, and the card is paused, so every charge after it is declined. The card’s status reads pausing, then paused.
Each charge counts once toward each rolling cap, through its authorization, its clearing and any redelivery. A reversed charge stops counting. A rolling cap counts this card’s charges alone. An increase to a charge the network already authorized is not checked again, and counts toward the rolling caps from then on.
To make sure no single charge can go past an amount, set that amount as the card’s total with amount_cents. Resume a paused card with POST /api/v2/cards/{card_id}/resume after you have looked at the charge.