Skip to main content
Agent tokens are in early access and subject to change. To request Agent tokens access, contact hi@natural.com.
Agent tokens let an agent pay from a budget the card owner approved once, instead of asking for approval on every purchase. The owner approves a mandate (amd_*) on one of their external cards while approving a purchase you asked for with an agent token: see when the proxy can’t reach the checkout. A mandate is a budget for that card: a total amount, a per-purchase limit and an expiry. Agents with access to the card spend under its mandates. For each purchase, the agent claims a tokenized card issued against the mandate. It isn’t the saved card’s number, so the agent stays out of PCI scope. Browser tokens are the default. Agent tokens are a backup for checkouts where the proxy can’t swap in the card. See choose a method. Agent tokens are for agents: call them with an agent key, or a partner app’s OAuth token, and the X-Instance-ID header. Support for Natural-issued cards is coming soon.

Permissions

Agent tokens need only savedCards.use. When the agent acts for a customer, the customer grants them by approving the connection. savedCards.use appears there as Use saved cards. Without savedCards.use, the mandate list comes back empty instead of returning an error, and creating a purchase returns 403. If an agent sees no mandates, check this scope first.

Flow

  1. Find the requested card’s mandate. Follow the card lookup below. Require an enabled payment method, then use an existing mandate with status active, an expiry in the future, and enough available budget and perPurchaseLimit for the checkout total.
  2. Get approved if needed. If that card has no usable mandate, open a browser token session with requestAgentToken: true. Once the user approves it, agentToken.mandateId names the mandate to use. If it’s still null after status is approved, setting up the mandate failed, which is expected for most cards. The approval still stands: claim the session and try the proxy. If the checkout can’t take the stand-in card, tell the user this checkout isn’t supported with this card.
  3. Create a purchase. POST /agentic-payments/purchases with the mandateId, the amount, the merchant (name, https URL and country code) and a ttlSeconds of 60 to 600. This reserves the amount from the mandate. Send an Idempotency-Key, and retry with the same key.
  4. Claim. POST /agentic-payments/purchases/{purchaseId}/claim returns the card number, expiry and CVC for this purchase. It succeeds once; the credential can’t be fetched again. Don’t log or store it.
  5. Check out. Enter the card details in the merchant’s checkout before expiresAt.
If the agent won’t check out, cancel the purchase before claiming it to release the reserved budget. A claimed purchase still counts against the mandate, even if no order was placed.

Find the requested card’s mandate

When the user names a card by its last four digits:
  1. Call GET /external-cards and match attributes.lastFour and, when supplied, attributes.brand. Follow pagination if needed. Use the matching active card’s id (eac_*). If more than one card matches, ask the user which card to use.
  2. Call GET /agentic-payments/cards/{cardId} with that eac_* ID. If enabled is false, agent tokens aren’t available on this card for you. Either you can’t use the card: check savedCards.use and the customer connection, which a browser token needs too. Or agent payments aren’t available in this environment: pay through the proxy. Otherwise the response contains paymentMethod.cardId, paymentMethod.id (apm_*) and mandates. Require a non-null paymentMethod with status enabled. An agent sees active, unexpired mandates for that card, but their presence does not mean the payment method is enabled. If it is suspended or still awaiting enrollment, ask the owner to resolve that state before purchasing. A null paymentMethod means the card isn’t set up for agent payments yet: the owner sets it up when approving a session with requestAgentToken: true.
  3. Choose a returned mandate whose available and perPurchaseLimit cover the total, including tax and shipping. Use its id (amd_*) as mandateId when creating the purchase.
For a connected customer, pass the same customerPartyId on the saved-card lookup, card lookup and purchase request. The mandate list spans cards and returns paymentMethodId, not the card’s last four digits. Use the card-specific lookup to establish the connection; do not guess from list order, descriptions or ID timestamps. An existing usable mandate does not require another approval. If the card lookup returns no usable mandate, check the agent’s savedCards.use scope and customer connection before asking the owner to set one up. Do not switch to another card without the user’s authorization.

Limits

  • A purchase covers one checkout. For another checkout, create a new purchase.
  • amount can’t exceed the mandate’s perPurchaseLimit or its available budget. Amounts are in USD minor units.
  • The credential stops working at expiresAt, or when the mandate expires or is revoked, whichever comes first.