Browser tokens are in early access and subject to change. To request Browser tokens access,
contact hi@natural.com.
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
- Find a card.
GET /external-cardslists the user’s saved cards (eac_*), with brand and last four digits. - Open a session.
POST /card-sessionswith thecardId, thepurchase(merchant name, amount, currency, and an optionaldescriptionfor the user) and theallowedHoststhat may receive the real card. See what the user approves. For a saved card, the response includes anapprovalUrl. Send it to the user. Pass anIdempotency-Keyheader so you can retry a create whose response you lost: the same key and body return the original session andapprovalUrl, and the same key with a different body returns409idempotencyKeyReused. Without a key, theapprovalUrlis returned only once. SetreturnUrl(anhttpspage, orsms:with your phone number) to send the user back to your product once they answer. - 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}untilstatusisapproved. Adeclinedorexpiredsession is over: open a new one. A session expires when it’s still pending atapprovalExpiresAt, or approved but unclaimed atclaimExpiresAt. - Claim.
POST /card-sessions/{sessionId}/claimreturns the stand-in card, the cardholder name and billing address, and the proxy login. It succeeds once. Send anIdempotency-Keyheader so you can retry it (see Retrying a claim); without one, the credential can’t be fetched again. - 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 usermerchantName, amount, description, the card, its billing ZIP, and allowedHosts. They approve what you describe.
merchantName,amountanddescriptionare shown, not enforced. Natural doesn’t cap the charge atamountor 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 asFlowers for tomorrow morning, up to $200.allowedHostsis 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 asapi.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 newIdempotency-Key. For a card the user added, they approve again.descriptionis optional plain text, up to 140 characters. Leading and trailing spaces are trimmed, and an empty one returns422. It’s returned on the session aspurchase.description.
Approve now, pay later
The user has 24 hours to approve, and your agent’s claim window starts when they do.- Set
claimWindowSeconds(up to 86400, 24 hours) so your agent can claim later than 10 minutes after the user approves. - Claim right before your agent enters the card. The claimed card and proxy login last
ttlSeconds(600 by default, up to 900). - 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.
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, setamount to 0 and say what your agent will do in description:
- 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.
requestAgentTokenisn’t available withamount: 0. It returns400.
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). SetrequestAgentToken: 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 thatmandateId(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.- Request the scopes in the invitation. Offer your agent
savedCards.usewhen you invite the customer. A new invitation doesn’t addsavedCards.useto an existing connection: the customer has to disconnect, then accept a fresh invitation. - Pass
customerPartyIdon every call. Use the customer’s party ID (pty_*) as thecustomerPartyIdquery parameter onGET /external-cards,GET /card-sessions/{sessionId}andPOST /card-sessions/{sessionId}/claim, and indata.attributesonPOST /card-sessions. - 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
Setreference 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 sameIdempotency-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 sameexpiresAt: 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
409card.notActive. - A claim with no key, a different key, or after
expiresAtreturns409cardSession.alreadyClaimed. - Natural never stores the credential. For a saved card, it keeps the encrypted security code until
expiresAtwhen 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,usernameandpasswordcome from each claim; the host can differ between claims. - What the proxy enforces: only
allowedHostsandexpiresAt. 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 untilexpiresAt. On checkouts the proxy handles itself (encrypted card fields), the card goes out once: after the processor answers, approved or declined, the login returns409card_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 toallowedHosts(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.purchaseis 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
409card.notActive. - An agent acting for a customer passes the same
customerPartyIdit used to create the card. - The proxy login stops working when the card expires, even if
ttlSecondsasks 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, setclaimWindowSecondswhen you open the session, from 600 to 86400 (24 hours). Until the user approves,claimExpiresAtshows the latest it could be. - For a saved card, Natural holds the encrypted security code until the claim, or until
claimExpiresAtif 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: trueto 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=trueon the card link.