How AgentPay works

One prepaid wallet, cards minted at the moment of payment, a real browser that clears the bank's check, and merchant logins the agent keeps. The model behind every endpoint.

The shape

AgentPay is the payment layer between your agent and any merchant. Your agent never holds money, a card number or a password. It holds an API key, and the key is tied to one account with one wallet.

Text

your agent  ->  AgentPay API  ->  wallet  ->  card  ->  merchant
                                    |
                                    +-> checkout engine (real browser, 3DS, merchant logins)

Two ways to pay, same wallet:

	Issue a card	Complete a checkout
Who types the card	Your agent, on the merchant site	AgentPay, in its own browser
When the card exists	When you call `POST /v1/cards`	At the final review, for the real total plus a small margin, never above your cap
Who clears 3DS	AgentPay, on its own	AgentPay, on its own
What you get back	A real card number, once, via `GET /v1/cards/{id}`	A `checkout_id` to poll, then the order id and total
Best for	Sites your agent already drives	Everything else

The wallet

The wallet is a prepaid balance in US dollars, read with GET /v1/wallet.

Field	What it is
`balance`	Everything in the wallet.
`reserved`	Money sitting on open cards. A card's cap is reserved the moment it is issued.
`available`	`balance` minus `reserved`. What a new card can be capped at.
`pending`	A declared bank transfer that has not landed. Not spendable.
`cards_ready`	Open single-use cards that were never charged. A checkout whose total fits one of them pays with it, with no new card.
`charges_in_flight`	Charges authorized and waiting for the network to clear, usually by the next day. The card holding them stays reserved until then.

Issuing a card reserves its cap. A charge clearing spends from the balance. Closing a card releases whatever reserve is left. Money enters only through a Stripe top-up (card or stablecoin), a bank transfer, or a signup gift.

Cards

POST /v1/cards mints a Visa or Mastercard virtual card capped at amount, dedicated to one merchant. A single-use card (the default) freezes itself after its first charge, so it can never be reused or over-spent. A multi-use card keeps taking charges until its cap is reached or you close it.

The per-card ceiling is 5,000 dollars. Your plan sets how many cards a month you can issue; past that, POST /v1/cards and POST /v1/checkout answer 402 plan_limit.

The card number is returned only by GET /v1/cards/{id}, and AgentPay never logs it. Reveal at the moment of use, never store it.

The checkout engine

POST /v1/checkout hands AgentPay a task, a merchant and a cap. The engine:

Opens the merchant in its own browser, signed in through a connection when the account has one for that merchant.
Puts the right items in the basket and walks to the final review. A choice the task does not settle (a size, a delivery slot) becomes one short question to the account owner in the console; the run shows needs_answer while it waits.
At the review, mints a single-use card for the real total plus a small margin, never above the cap. If an open, never-charged card already covers the total, it pays with that one instead.
Pays and clears the bank's 3DS check itself. Nothing is asked of your agent or of the person.
Reports submitted with the merchant's order_id and order_total.

Two modes

confirm_pay on the checkout decides who says yes at the review.

`confirm_pay`	What happens at the review
`false` (default)	The run stops at `awaiting_approval`. The account owner approves in the console, on any device.
`true`	The run pays on its own, up to the cap.

The agent's own approval mode, set in the console, can only make this stricter, never looser. The response's confirm_pay says what was granted.

The person's own card

An account can also connect the person's own credit or debit card, behind a passkey on their phone. A checkout on it stops at the review with needs_card_approval until the cardholder approves on that phone. Nothing is issued, nothing is prepaid, and the bank's check on that card is theirs to clear. See the person's own card.

Connections and the AgentPay passkey

Many merchants need an account. A connection is the person's signed-in session at one merchant, created once at a connect_url where they type their password on the merchant's own page. AgentPay never sees it.

On merchants that take passkeys, AgentPay adds its own passkey to the person's account the next time a checkout runs there. From then on the engine signs in by itself, even after the merchant expires the session. The connection's layer says passkey once that happened, session before. A checkout's login_layer says which one signed in.

What the person sees

Everything your agent does shows up in the console: every card, every run with its steps and screenshots, every approval request, every charge in Activity. The console is where the owner funds the wallet, approves a review in ask mode, answers a run's question, and connects merchants.

Limits and rules

One card is dedicated to one purchase. A single-use card locks after its first charge.
The cap is the ceiling. The engine never spends above it, and a card never takes a charge above its limit.
Only the AgentPay card issued for a run, or a connected own card the person approved, is used. A card saved on the merchant account is never used.
The agent never empties the basket. A run that ended with its own items in the basket can be continued with resume_of.
There is no test mode. Every call is live and every card is real. Use a small cap to try things.