Browser tokens are in early access and subject to change. To request Browser tokens access,
contact hi@natural.com.
- A Natural agent key with
savedCards.use - A Browser Use API key in
BROWSER_USE_API_KEY, with Write onbrowsers - Python with
httpxandplaywright(pip install httpx playwright). No local browser download is needed.
How it fits together
- Shop. The agent browses in a Browser Use browser on its residential proxy and gets to the merchant’s payment step.
- Open a session. Your backend calls
POST /card-sessionswith the purchase and the processor host that receives the card, then sends the user theapprovalUrl. - Claim. Once the user approves,
POST /card-sessions/{sessionId}/claimreturns a stand-in card and a proxy login. - Swap the proxy. Switch the running browser onto Natural’s proxy with Browser Use’s update browser proxy endpoint.
- Pay. The agent fills in the stand-in card and submits, then the browser goes back to the residential proxy.
1. Shop
Create a standalone browser and drive it over itscdpUrl:
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:
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
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
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. A4xx 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:
5. Clean up
Thefinally 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’scdpUrl (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).
Route the card request over CDP
Route the card request over CDP
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, passcustomerPartyId 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.