Skip to main content
Natural works with two kinds of cards:
  • External cards: cards a user already has from their own bank, saved on the dashboard. In the API they’re saved cards (eac_*).
  • Natural-issued cards (coming soon): cards Natural issues to your wallet.
Either way, agents never handle the real card number (PAN), which keeps them out of PCI scope. Natural hands the agent a credential that only works for the purchase it was issued for.

​
When to use each

Use external cards when the agent is shopping for a person who wants to pay with a card they already have, and they can approve purchases as they happen. On cards that support it, they can instead approve a budget once with agent tokens. Use Natural-issued cards when the agent should spend without a person in the loop for each purchase, from funds and limits you control. To be notified when they’re available, contact hi@natural.com.

​
How agents pay

Browser tokens and agent tokens are for agents: call them with an agent key and the X-Instance-ID header. Paying with an external card needs the saved_cards.use scope. Each method’s page lists the scopes for every endpoint. Single-use virtual cards are card numbers drawn from a Natural-issued card that work for one purchase. They work only with Natural-issued cards.

​
Choose a method

Use browser tokens by default. Agent tokens are a backup for checkouts a browser token can’t complete. Most cards don’t support agent payments yet, so expect setting one up to fail. That’s fine: the agent still has the browser token. Browser tokens work at most checkouts, and the owner doesn’t need to set up a mandate first. Whether the user is needed depends on the card:
  • External cards: the user approves every purchase and types the card’s security code (CVV) each time. Only use a browser token when the user can respond during checkout.
  • Natural-issued cards (coming soon): no approval step for each purchase.
Agent tokens need a mandate the owner approved with their card network. The owner sets one up while approving a browser token session you opened with requestAgentToken: true. Once it’s active, the agent can pay within its budget. Use agent tokens when:
  • The checkout doesn’t send the raw card number. The proxy swaps in the real card only when the stand-in number appears in the checkout’s HTTP request. If the page encrypts or tokenizes the card in the browser first, such as inside a payment provider’s iframe, the swap can’t happen and a browser token can’t pay.
  • The user can’t approve each purchase while paying with an external card.
Before asking the owner to create a mandate, check the requested card. List saved cards, match the card’s brand and last four digits, then call GET /agentic-payments/cards/{cardId} with its eac_* ID. The response includes that card’s payment method and mandates. Require paymentMethod.status to be enabled before selecting a mandate. See find the requested card’s mandate. If that card has no usable mandate, open a browser token session with requestAgentToken: true. On approval, Natural also tries to set up a mandate and the session returns it. If it can’t, agentToken.mandateId is null and you still have the browser token: try the proxy, and if the checkout can’t take the stand-in card, tell the user this checkout isn’t supported with this card. See when the proxy can’t reach the checkout. Read more: Pay with external cards.