Skip to main content
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.
Don’t put Natural’s proxy in Browser Use’s customProxy. It can’t connect, and the browser fails with ERR_TUNNEL_CONNECTION_FAILED or hangs before the page loads:
  • Natural’s proxy only accepts TLS connections (protocol: "https", port 443). customProxy has no protocol field and connects over plain HTTP.
  • The proxy password from a claim is about 900 characters. customProxy accepts up to 255.
  • The browser has to trust Natural’s proxy certificate for the allowed hosts. customProxy has no way to add a CA, and ignoreCertErrors turns off certificate checks for every site.
Instead, keep the browser on Browser Use’s residential proxy and have your backend send only the card request through Natural’s proxy. Your backend connects to the browser over CDP, pauses requests to 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.create and saved_cards.use
  • A Browser Use API key in BROWSER_USE_API_KEY
  • Python with playwright, httpx and certifi (pip install playwright httpx certifi). No local browser download is needed.

How it fits together

  1. Shop. The agent browses in a Browser Use browser 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. Route the card request. Your backend connects to the browser’s cdpUrl and routes requests to allowedHosts through Natural’s proxy.
  5. 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 a cdpUrl:
Treat 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

The user has to approve, and you have to claim, before the session’s 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

Build a new client for every claim. The host and login differ between claims. The CA bundle keeps the system certificates and adds Natural’s proxy certificate, so certificate checks stay on.

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:
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. 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 through relay 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.
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 request bodies your handler resends, the proxy URL, the cardholder name and the billing address.

6. Clean up

The finally 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, 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 and the proxy login stay in your backend. Browser Use never sees the proxy login.