Skip to main content
Browser tokens are in early access and subject to change. To request Browser tokens access, contact hi@natural.com.
Browser Use runs cloud browsers and browser agents. This guide shows how a Browser Use browser pays at a merchant’s checkout with a Natural browser token: the agent types a stand-in card, and Natural’s proxy swaps in the real card on the way to the payment processor. The real card number never reaches your agent, your servers or Browser Use. You need:
  • A Natural agent key with savedCards.use
  • A Browser Use API key in BROWSER_USE_API_KEY, with Write on browsers
  • Python with httpx and playwright (pip install httpx playwright). No local browser download is needed.

How it fits together

  1. Shop. The agent browses in a Browser Use browser on its residential proxy and gets to the merchant’s payment step.
  2. Open a session. Your backend calls POST /card-sessions with the purchase and the processor host that receives the card, then sends the user the approvalUrl.
  3. Claim. Once the user approves, POST /card-sessions/{sessionId}/claim returns a stand-in card and a proxy login.
  4. Swap the proxy. Switch the running browser onto Natural’s proxy with Browser Use’s update browser proxy endpoint.
  5. Pay. The agent fills in the stand-in card and submits, then the browser goes back to the residential proxy.
The browser doesn’t restart, so tabs, cookies, the cart and checkout state are kept.

1. Shop

Create a standalone browser and drive it over its cdpUrl:
Treat cdpUrl as a credential: anyone who has it can control the browser. Browser Use only changes the proxy of a standalone browser. A browser that belongs to a V4 agent run, or that has the agentic autofill extension, answers 409: for those, see agent run browsers.

Find the processor host

allowedHosts must name the host the checkout sends the card number to, not the merchant’s website. Wildcards aren’t accepted. To find it, watch the checkout’s requests:
Several hosts may show up. Do a dry run with a test card and pick the request whose body holds the card number. Common hosts include api.stripe.com, payments.braintree-api.com and pci-connect.squareup.com. If the payment form encrypts the card in the browser, the proxy can only swap it in for the processors listed under encrypted card fields; elsewhere it can’t: see when the proxy can’t reach the checkout.

2. Open a session and wait for approval

The user has to approve before the session’s approvalExpiresAt: 24 hours after you open it. You have to claim before claimExpiresAt: 10 minutes after the user approves, unless you set claimWindowSeconds (up to 86400, 24 hours). Claim right before the agent enters the card.

3. Claim and swap the proxy

Pass protocol and caBundleUrl. Natural’s proxy only accepts TLS connections, and Browser Use downloads the certificate at caBundleUrl so the browser trusts Natural’s proxy for the allowed hosts while every other site keeps full certificate checks. Don’t use ignoreCertErrors: it turns off certificate checks for every site, and the proxy swap doesn’t accept it. The swap takes about 5 seconds while the browser loads the certificate. Your CDP connection, open pages and their state stay as they are, but requests in flight during the swap may fail, so swap while the payment page is idle, before the agent fills in the card. Send one change at a time: a second change for the same browser answers 409 until the first one ends. If the payment form encrypts the card in the browser, reload the payment page after the swap so the proxy sees the page load: see encrypted card fields. While the browser is on Natural’s proxy, all of its traffic goes through it and leaves from Natural’s proxy instead of Browser Use’s residential IP. That’s normal for a payment processor’s API, but a merchant page behind bot protection may react to the new IP, so keep the swap to the payment step. Use the claim’s login for this swap only. The host and login differ between claims. If you lose the claim response, retry the claim with the same Idempotency-Key for a fresh login: see retrying a claim.

4. Check the route, then pay

Load every allowed host first. A 4xx from the host itself is fine: api.stripe.com/ answers 404. A network error, such as a tunnel or certificate error, or a 5xx means the route doesn’t work. Wrap the check and the payment in try/finally so the browser leaves Natural’s proxy even when either one fails:
If routing fails, stop. Never send the stand-in card around the proxy, and before retrying, check that the earlier attempt didn’t go through. Treat the claim as a secret: don’t log or store any of it, including the proxy login, the cardholder name and the billing address.

5. Clean up

The finally block switches the browser back to Browser Use’s residential proxy. The proxy login stops working at the claim’s expiresAt either way, 10 minutes after the claim by default. Set ttlSeconds on the session, up to 900, if checkout needs longer. Disconnecting CDP with await pw.stop() doesn’t stop a Browser Use browser: stop it with PATCH /api/v4/browsers/{id} and {"action": "stop"} when the agent is done.

Agent run browsers

Browser Use doesn’t change the proxy of a browser that belongs to a V4 agent run. For those, keep the browser on its residential proxy and have your backend send only the card request through Natural’s proxy: connect to the run browser’s cdpUrl (from GET /api/v4/browsers/{id}), pause requests to allowedHosts, resend them through the proxy and hand the response back to the page. This also needs certifi (pip install certifi).
Build a proxy client from the claim. The CA bundle keeps the system certificates and adds Natural’s proxy certificate, so certificate checks stay on:
Register the routes on the browser context, not a page, so cross-origin iframes such as hosted card fields are covered too:
Keep the asyncio event loop running for the rest of the checkout. If it’s blocked, for example by time.sleep, the paused requests never go out.Check each allowed host with await relay.get(f"https://{host}/") before the agent pays, the same way as above. Wrap the check and the payment in try/finally, and in the finally block context.unroute(...) each host and await relay.aclose(), so a failed checkout doesn’t leave the routes on. Don’t log the request bodies your handler resends or the proxy URL.

When the proxy can’t reach the checkout

Some checkouts encrypt the card in the browser or inside the processor’s own iframe, so the stand-in number never appears in a request the proxy can see. POST /card-sessions returns a warning when an allowed host is a checkout known to do this. For those, open the session with requestAgentToken: true. When the user approves, they can also set up agent payments on the card, and the session returns a mandateId. Then pay with an agent token: it’s a tokenized card the agent types in directly, with no proxy and no swap.

Customers’ cards

To pay with a Connect customer’s saved card, pass customerPartyId in data.attributes when you open the session, and as a query parameter when you get or claim it. See pay with a customer’s saved card.

What each party sees

Your Natural agent key stays in your backend. Browser Use only ever holds a proxy login for one purchase.