Skip to main content
Browser tokens are in early access and subject to change. To request Browser tokens access, contact hi@natural.com.
Browser tokens let an agent pay with a card without ever seeing the real card number (PAN), by checking out through a browser proxy. In the API, each browser token is a card session. Each card session (csn_*) covers one purchase, or one card action with no purchase, such as saving the card on file at a merchant. The agent gets a stand-in card number and a proxy login, fills in the merchant’s checkout with the stand-in, and routes its browser through the proxy. When the checkout sends the card to one of the session’s allowed hosts, the proxy swaps in the real card on the way. Anywhere else, or after the session expires, the stand-in is useless. Browser tokens are for agents: call them with an agent key, or with the OAuth token of a partner app Natural has approved, which acts as one of your agents. Creating and claiming a session also needs the X-Instance-ID header. Other apps connected through Natural OAuth, such as MCP clients, can’t open sessions on saved cards. Browser tokens work with external cards. Support for Natural-issued cards is coming soon.

Permissions

The agent needs these scopes. When it acts for a customer, the customer grants them by approving the connection. savedCards.use appears there as Use saved cards. Without savedCards.use, opening a session with a saved card returns 403 card.useNotPermitted. If the scope is removed after approval, the claim returns 409 card.notActive.

Flow

  1. Find a card. GET /external-cards lists the user’s saved cards (eac_*), with brand and last four digits.
  2. Open a session. POST /card-sessions with the cardId, the purchase (merchant name, amount, currency, and an optional description for the user) and the allowedHosts that may receive the real card. See what the user approves. For a saved card, the response includes an approvalUrl. Send it to the user. Pass an Idempotency-Key header so you can retry a create whose response you lost: the same key and body return the original session and approvalUrl, and the same key with a different body returns 409 idempotencyKeyReused. Without a key, the approvalUrl is returned only once. Set returnUrl (an https page, or sms: with your phone number) to send the user back to your product once they answer.
  3. Wait for approval. The user opens the link, checks the purchase and approves it with Face ID if they saved the code, with no sign-in. Otherwise they sign in to Natural if they’re signed out and approve with the card’s security code. Poll GET /card-sessions/{sessionId} until status is approved. A declined or expired session is over: open a new one. A session expires when it’s still pending at approvalExpiresAt, or approved but unclaimed at claimExpiresAt.
  4. Claim. POST /card-sessions/{sessionId}/claim returns the stand-in card, the cardholder name and billing address, and the proxy login. It succeeds once. Send an Idempotency-Key header so you can retry it (see Retrying a claim); without one, the credential can’t be fetched again.
  5. Check out. Fill in the merchant’s checkout with the stand-in card and send the payment request to an allowed host through the proxy, trusting the proxy’s root certificate at caBundleUrl.

What the user approves

The approval page shows the user merchantName, amount, description, the card, its billing ZIP, and allowedHosts. They approve what you describe.
  • merchantName, amount and description are shown, not enforced. Natural doesn’t cap the charge at amount or lock the card to the merchant. Your agent can pick the merchant and the final price later, within what it described. Write the description so the user knows what they’re agreeing to, such as Flowers for tomorrow morning, up to $200.
  • allowedHosts is enforced. The proxy puts the real card only in requests to these hosts. If you don’t know the merchant yet, list the processor API hosts your agent may need, such as api.stripe.com. If the checkout sends the card to a host you didn’t list, such as a processor’s card-token API, don’t enter the card: open a new session with that host added and a new Idempotency-Key. For a card the user added, they approve again.
  • description is optional plain text, up to 140 characters. Leading and trailing spaces are trimmed, and an empty one returns 422. It’s returned on the session as purchase.description.

Approve now, pay later

The user has 24 hours to approve, and your agent’s claim window starts when they do.
  1. Set claimWindowSeconds (up to 86400, 24 hours) so your agent can claim later than 10 minutes after the user approves.
  2. Claim right before your agent enters the card. The claimed card and proxy login last ttlSeconds (600 by default, up to 900).
  3. There’s no renewal under the same approval. If the credential expires mid-checkout, open a new session and ask the user to approve again.
A claim retry with the same Idempotency-Key is for a claim response you lost. It returns a new login that still ends at the first claim’s expiresAt. It doesn’t extend it. See Retrying a claim.

Card actions with no purchase

For an action that charges nothing, such as saving the card on file at a merchant or replacing the card on a gym or SaaS account, set amount to 0 and say what your agent will do in description:
The approval page leads with your description, or “Save your card at Amazon” without one, and shows no price. Keep in mind:
  • The merchant gets the real card number and keeps it. Charges the merchant makes on its own later are outside Natural’s controls.
  • On checkouts the proxy handles itself (encrypted card fields: Adyen, CyberSource Flex Microform, Southwest), the proxy sends the card once. When the processor answers, approved or declined, the login stops putting the card in. If the merchant runs a $0 verification when it saves the card, that verification uses the login. To buy something after, open a new session.
  • requestAgentToken isn’t available with amount: 0. It returns 400.

Where the user approves

Approving happens on Natural’s site, with the user’s passkey or a Natural sign-in. A security code saved with Face ID is a passkey for natural.com: Natural checks it for each purchase, so that user approves with Face ID alone. Anyone else signs in on the device they approve from. A user who signed up by phone signs in with a code we text them: add ?signin=phone to the approvalUrl (card vault).

When the proxy can’t reach the checkout

The proxy is the default way to pay. It swaps in the real card only when the stand-in number appears in the checkout’s HTTP request. If the checkout doesn’t send the raw card number, because it encrypts the card in the browser or collects it in its own payment iframe, the proxy has nothing to swap and a browser token can’t pay, unless the processor is one the proxy re-encrypts for (encrypted card fields). Set requestAgentToken: true on POST /card-sessions only when you know the checkout works this way. It’s a backup, not a different flow: the user approves the purchase as usual, and on each approval Natural also tries to set up an agent token mandate on the card for this purchase. The card network may ask the user to confirm with a passkey or a one-time code. It works for saved cards and USD purchases up to $999,999.99. Expect the backup to fail often. Most cards don’t support agent payments yet, and that’s fine: the approval still stands either way. Once status is approved, read agentToken.mandateId:
  • A mandate ID (amd_*): the backup worked. Create an agentic purchase with that mandateId (POST /agentic-payments/purchases) and claim its credential.
  • null: the card couldn’t take agent payments. Claim the session and pay through the proxy. If the checkout really can’t take the stand-in, tell the user this checkout isn’t supported with this card.

Pay with a customer’s saved card

A Connect platform can pay with its customers’ saved cards. The customer approves the connection once, then approves each purchase.
  1. Request the scopes in the invitation. Offer your agent savedCards.use when you invite the customer. A new invitation doesn’t add savedCards.use to an existing connection: the customer has to disconnect, then accept a fresh invitation.
  2. Pass customerPartyId on every call. Use the customer’s party ID (pty_*) as the customerPartyId query parameter on GET /external-cards, GET /card-sessions/{sessionId} and POST /card-sessions/{sessionId}/claim, and in data.attributes on POST /card-sessions.
  3. Send the customer the approvalUrl. A signed-in user of the customer’s account approves the purchase and enters the card’s security code.
cURL

Finding sessions

Set reference when you open a session to tag it with your own ID, such as your checkout or task ID (up to 255 characters). It’s returned on the session and isn’t unique: use Idempotency-Key to avoid opening duplicates. GET /card-sessions lists the sessions the calling agent opened for the party it acts for, newest first, with cursor pagination. Filter by status or reference, and pass customerPartyId to list a customer’s sessions. It never includes card data, and note is always null in the list: get the session for it.

Retrying a claim

If you lose a claim response, retry the claim with the same Idempotency-Key instead of opening a new session. The user doesn’t have to approve again.
  • A retry by the same agent with the same key, before the first claim’s expiresAt, returns a new stand-in card and proxy login. They expire at that same expiresAt: a retry never extends it. Use the values from the latest response.
  • Each retry checks the card and the agent’s access again, like the first claim. If either was lost, it returns 409 card.notActive.
  • A claim with no key, a different key, or after expiresAt returns 409 cardSession.alreadyClaimed.
  • Natural never stores the credential. For a saved card, it keeps the encrypted security code until expiresAt when the claim had a key, and deletes it at the claim when it didn’t.

Proxy details

  • Certificate: the proxy’s root certificate at caBundleUrl (https://ca.evervault.com) is the same for every claim, so you can trust it once when you set up the browser.
  • Connection: treat each claim as a new proxy. The host, port, username and password come from each claim; the host can differ between claims.
  • What the proxy enforces: only allowedHosts and expiresAt. It doesn’t check the merchant or amount; the user approving the purchase covers those. Through the browser proxy, the stand-in card can be used more than once until expiresAt. On checkouts the proxy handles itself (encrypted card fields), the card goes out once: after the processor answers, approved or declined, the login returns 409 card_proxy_card_already_used.
  • instructions: the claim returns the same setup steps every time: configure the proxy from the returned settings, trust the certificate, route requests to allowedHosts (including checkout iframes) through the proxy, test routing with a harmless request first, and stop rather than send card requests directly if the proxy fails.

Virtual cards (early access)

If your account has early access to virtual cards, an agent can open a session with a virtual card it holds (pcd_*) instead of a saved card: a single-use card it was issued, or a multi-use card an Owner or Admin gave it. Opening, reading, and claiming the session need cards.read on the card’s wallet instead of savedCards.use.
  • The session starts approved, so there’s no approval link. purchase is optional.
  • Only the agent that holds the card can use it, and only while the card is active. A card that was used up, expired, frozen or closed returns 409 card.notActive.
  • An agent acting for a customer passes the same customerPartyId it used to create the card.
  • The proxy login stops working when the card expires, even if ttlSeconds asks for longer.
  • The card’s own controls still apply: a single-use card approves one purchase, and a multi-use card approves purchases within its limits. If a session expires before the agent claims it, the agent can open a new one on the same card while it’s active.
  • The claim returns no cardholder name or billing address.

Allowed hosts

allowedHosts is required and has no default. Entries are exact hostnames, such as api.stripe.com. Wildcards, ports and paths aren’t accepted. Only requests to these hosts get the real card, so name the payment processor’s API host that receives the card, not the merchant’s website. The user sees the hosts on the approval page. Find the host before you open the session. Open the payment page and find the request that carries the card when the form is submitted (often sent from a processor’s card-field iframe) and list the host it goes to. If that isn’t clear, submit a fake card number that will fail and see which host receives it.

Limits

  • A session covers one purchase, or one card action with no purchase. For another, open a new session.
  • The user must approve before approvalExpiresAt: 24 hours after the session opens.
  • The agent must claim before claimExpiresAt: 10 minutes after the user approves by default. To approve now and pay later, set claimWindowSeconds when you open the session, from 600 to 86400 (24 hours). Until the user approves, claimExpiresAt shows the latest it could be.
  • For a saved card, Natural holds the encrypted security code until the claim, or until claimExpiresAt if nobody claims. Pick the shortest window that fits.
  • The stand-in card and proxy login stop working at the claim’s expiresAt (ttlSeconds, 600 by default, up to 900).
  • Checkouts that encrypt or tokenize the card in the browser before sending it only work where the proxy knows how to re-encrypt the card (see supported checkouts and encrypted card fields). Elsewhere the request never contains the stand-in number; set requestAgentToken: true to also try an agent token (see when the proxy can’t reach the checkout).
  • With a saved card, the user must approve each purchase and enter the card’s security code, or use Face ID if they saved it with passkeyApprovals=true on the card link.