> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jointransfer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Browser checkout with Codex

> Let an agent shop and submit supported purchases within owner-set limits.

The default **Copy for Codex** setup now installs a small card-details worker:
Codex can retrieve the assigned number and expiry and type them through its
existing browser. This intentionally exposes the details to model context and
browser arguments. See [Connect your agent](/guides/connect-agent) for that simpler
flow.

This guide describes the separate browser companion, for integrations that keep
the card number outside the conversation and enforce Transfer purchase intents.
Existing companion installations remain available; the default card-details
worker does not install Chromium or provide these companion tools. A trusted
integration with an existing browser would need the same private-entry and
submission protections described below.

The companion runs a visible, isolated browser with public HTTPS websites;
checkout layouts that cannot be identified confidently need the owner.

## Set it up

1. Link the agent's virtual card in your dashboard.
2. Open **Companion limits**, choose a payment currency and limits per purchase
   and calendar month, then select **Enable automatic purchases**. This permits
   submission within those limits without another Transfer approval each time.
   Automatic purchases are off by default. These limits apply to this companion;
   your issuing bank's controls remain separate.
3. Use a separately configured companion connection. The default **Copy for
   Codex** flow uses card-details mode instead and does not enable this browser.
   Companion deployments require the local companion runtime, MCP SDK, Zod and
   Playwright with Chromium, plus their own private version 2 companion
   configuration. A restart may be needed. Setup itself makes no purchase.
4. Ask Codex to inspect its assigned card with `get_agent_card`, then give it the
   website, item and exact maximum amount you intend to spend. It can shop in an
   existing browser and use the companion when payment needs the trusted bridge.

This browser starts without your usual cookies or saved passwords. Enter login
details directly in its visible window when needed. Do not send your card
number, CVC or password to the conversation. Moving checkout from another browser
may require recreating the cart or signing in again; cookies and login state are
not copied automatically.

## Purchase flow

The agent can open the website, inspect filtered page text and ordinary controls,
and enter shopping or shipping details. Input values, card fields and screenshots
are not exposed. Generic browser actions cannot enter card details or click the
final payment button.

For the final action, `checkout_purchase` receives one stable `request_id`, the
exact expected amount in cents and payment currency. The companion identifies
the checkout fields, total, merchant and payment control, checks them against
the request, and obtains a server-side purchase intent under your current limits.
It fills the assigned card privately, records submission before clicking once,
and clears payment fields after the attempt. Ambiguous totals, required missing
fields or unsupported controls return `requires_action` instead of guessing.

If CVC is required, enter it directly at the merchant before the agent resumes
the pending preparation. The companion checks only whether that field is filled
and valid; it does not read or store its value. Login, CAPTCHA and 3D Secure also
require your action in the visible browser.

After any card-entry attempt, the browser stays private to the owner. Agent page
inspection, navigation and ordinary actions remain locked until that browser is
closed; clearing known fields cannot prove that merchant scripts discarded card
data. `get_checkout_status` returns only a filtered outcome. Open a fresh isolated
browser for further shopping.

## Pending or uncertain payments

After a payment has been submitted, use `get_checkout_status` to check a receipt
or finish bank authentication. This tool never submits payment again. A merchant
receipt is not independent confirmation of bank settlement.

If the result is `unknown`, `submitting` or a submitted `requires_action`, new
automatic purchases remain paused. Check the merchant and your bank. In
**Companion limits**, use **I checked: paid** or **I checked: not charged** only
after checking the result. Submitted amounts remain counted against the current
monthly limit even when recorded as failed; this prevents uncertain retries from
silently restoring spending allowance. Limits use one configured currency, with
no automatic currency conversion.

Opening another browser, restarting the companion or inventing a new request ID
does not clear an unresolved payment. Never retry an uncertain purchase with a
new ID.

## Available local tools

| Tool | Purpose |
| - | - |
| `open_checkout_browser` | Open a visible isolated browser at a public HTTPS URL. |
| `inspect_checkout_browser` | Read filtered page text and fresh control references. |
| `checkout_browser_action` | Navigate or use ordinary shopping and shipping controls. |
| `checkout_purchase` | Attempt one authorized purchase with an exact expected total. |
| `get_checkout_status` | Reconcile a previous attempt without another payment click. |
| `close_checkout_browser` | Close the browser and discard its session. |

The companion also proxies `get_agent_card`, `get_payment_card` and
`list_agent_transactions` for its one assigned agent. Manual remote HTTP MCP
connections provide those three card tools; they do not install the local
browser companion. Transfer does not have a bank balance or transaction feed,
and bank-side limits still apply.

## Integrating another browser

A trusted browser adapter must hold the agent credential outside model context,
redeem the short-lived token with that same credential, and deliver PAN and expiry
directly to protected card fields. `get_payment_card` itself never returns the
card number, and an opaque token cannot be typed into a merchant card field.

The adapter must also validate merchant, exact total and currency; obtain a
purchase intent under current owner limits; record `submitting` before its one
payment click; and finalize or reconcile the durable result without retrying an
uncertain payment. CVC and bank authentication remain owner actions. Card entry
must keep the browser private from agent inspection afterward, including merchant
copies of the data. Reopening a browser or changing the request ID cannot bypass
an unresolved payment.

Transfer's `fillAssignedCard` helper and `executeCheckout` engine demonstrate
the private injection and authorized submission flow. Adapting them to another
browser requires a trusted integration with those capabilities; configuring a
normal browser tool alone does not add them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.