Agent tokens are in early access and subject to change. To request Agent tokens access, contact
hi@natural.com.
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 onlysavedCards.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
- Find the requested card’s mandate. Follow the card lookup below. Require an enabled payment method, then use an existing mandate with
statusactive, an expiry in the future, and enoughavailablebudget andperPurchaseLimitfor the checkout total. - 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.mandateIdnames the mandate to use. If it’s stillnullafterstatusisapproved, 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. - Create a purchase.
POST /agentic-payments/purchaseswith themandateId, theamount, themerchant(name,httpsURL and country code) and attlSecondsof 60 to 600. This reserves the amount from the mandate. Send anIdempotency-Key, and retry with the same key. - Claim.
POST /agentic-payments/purchases/{purchaseId}/claimreturns 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. - Check out. Enter the card details in the merchant’s checkout before
expiresAt.
Find the requested card’s mandate
When the user names a card by its last four digits:- Call
GET /external-cardsand matchattributes.lastFourand, when supplied,attributes.brand. Follow pagination if needed. Use the matching active card’sid(eac_*). If more than one card matches, ask the user which card to use. - Call
GET /agentic-payments/cards/{cardId}with thateac_*ID. Ifenabledisfalse, agent tokens aren’t available on this card for you. Either you can’t use the card: checksavedCards.useand 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 containspaymentMethod.cardId,paymentMethod.id(apm_*) andmandates. Require a non-nullpaymentMethodwithstatusenabled. 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. AnullpaymentMethodmeans the card isn’t set up for agent payments yet: the owner sets it up when approving a session withrequestAgentToken: true. - Choose a returned mandate whose
availableandperPurchaseLimitcover the total, including tax and shipping. Use itsid(amd_*) asmandateIdwhen creating the purchase.
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.
amountcan’t exceed the mandate’sperPurchaseLimitor itsavailablebudget. Amounts are in USD minor units.- The credential stops working at
expiresAt, or when the mandate expires or is revoked, whichever comes first.