allowedHosts, resends them through the proxy and hands the response back to the page. Everything else, including the merchant’s own pages, stays on Browser Use’s proxy.
You need:
- A Natural agent key with
wallets.read,payments.read,payments.createandsaved_cards.use - A Browser Use API key in
BROWSER_USE_API_KEY - Python with
playwright,httpxandcertifi(pip install playwright httpx certifi). No local browser download is needed.
How it fits together
- Shop. The agent browses in a Browser Use browser 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. - Route the card request. Your backend connects to the browser’s
cdpUrland routes requests toallowedHoststhrough Natural’s proxy. - Pay. The agent fills in the stand-in card and submits.
1. Shop
Create a browser, or use the one your V4 agent run is already using. Both have acdpUrl:
cdpUrl as a credential: anyone who has it can control the browser.
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. Do a dry run of the checkout with DevTools open, or log the checkout’s POST requests over CDP, and look for 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’t swap it in: see when the proxy can’t reach the checkout.
2. Open a session and wait for approval
claimExpiresAt: 10 minutes after you open it. Open the session when the agent is at the payment step, not earlier.
3. Claim and build a proxy client
4. Route the card request
Register the routes on the browser context, not a page, so cross-origin iframes such as hosted card fields are covered too:time.sleep, the paused requests never go out.
The card request leaves from Natural’s proxy instead of Browser Use’s residential IP. That’s normal for a payment processor’s API, but if the allowed host is the merchant’s own domain behind bot protection, it may block the request.
5. Check the route, then pay
Send one request to each allowed host throughrelay first. A 4xx from the host itself is fine: api.stripe.com/ answers 404. A proxy or TLS error means the route doesn’t work.
6. Clean up
Thefinally block removes the routes, closes the proxy client and disconnects from the browser. Disconnecting doesn’t stop a Browser Use browser: stop it with PATCH /api/v4/browsers/{id} and {"action": "stop"} when the agent is done. 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.
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 and the proxy login stay in your backend. Browser Use never sees the proxy login.