Skip to main content
Agent tokens let an agent pay from a budget the card owner approved once, instead of asking for approval on every purchase. The owner creates a mandate (amd_*) on the dashboard for one of their saved cards. 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. Use agent tokens when the user can’t approve each purchase, or when the checkout encrypts the card in the browser so browser tokens can’t pay. See choose a method. Agent tokens are for agents: call them with an agent key and the X-Instance-ID header. Support for Natural-issued cards is coming soon.

​
Permissions

Using agent tokens needs saved_cards.use, along with the scopes below. When the agent acts for a customer, the customer grants them by approving the connection. saved_cards.use appears there as Use saved cards. Without saved_cards.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, the owner creates one on the dashboard and verifies it with their card issuer. Repeat the card lookup after approval.
  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 /card-external-accounts 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. 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.
  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 dashboard login or approval. If the card lookup returns no usable mandate, check the agent’s saved_cards.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.