Skip to main content
The shopper reads the cart and says yes. Your agent sends an approval link, and the shopper approves the payment on their phone with a passkey, which is Face ID or Touch ID on an iPhone. Agentcard places the order the moment they approve, and the chat reads “order placed” with nothing else to type. Two steps are the shopper’s own: the yes to the cart, and the approval. Your code never approves for them, and the model never places an order without the yes. The steps below cover the Vault’s approval. To let a shopper approve in their own Link wallet instead, see Paying with a Stripe Link wallet.

Confirm the cart

The model sets confirm to true only when the shopper said yes to the cart in the model’s last result, asks to check out or pay, says they added the card for a cart that waits, says they approved, or asks for the approval link again. The tool then confirms the cart Agentcard last showed, so you handle no cart hash and no conversation id. Show the shopper the cart before the model confirms it. “Showing the cart” renders it. When the confirm needs the shopper to approve, the answer carries these fields: The approval link works for about 15 minutes. The model asks the shopper for one thing, the approval, in one short line, such as “approve the payment to place your order (up to $19.02)”. The dollar amount in the parentheses is the cart’s max_charge, the most the shopper’s card can be held for. A store that prices its final total at checkout asks for more than the cart’s total, and a flight asks for exactly its total.
chat.ts
Show the cart’s approvedCeilingCents beside its total whenever the cart carries one. A shopper who sees only the total approves less than the card can be held for.

Place the order

The shopper taps the link, sees the store and the amount, and approves with their passkey. Agentcard places the order against that approval. Your server hears about it as a purchase.message, and the SDK hands you text ready to post: An order takes a few seconds to go through after the approval. A call that lands while Agentcard is still placing the order pauses once for 12 seconds and reads the conversation. The model then reads order_placed with the order number, or placing. A placing status means the order is going through, so the model never asks for another approval. A call that finds the order already placed reads it at once. When shopper_need_not_reply is true, a purchase.message will tell the shopper how the order went, and the model tells them they need not reply. Post that message into the chat when it arrives. The order events your company receives are documented in Order events.

Read where an order is

Ask Agentcard where an order is at any time, with the order number from the order_placed message, message.order.orderId:
orders.ts
The call is GET /buy/orders/{order_id}, with opts.merchant sent as ?merchant=. Agentcard answers from what it last read from the store, so the call returns at once and never calls the store. status is the stage the order has reached: placed, confirmed, courier_assigned, courier_at_store, ready_for_pickup, picked_up, arriving, delivered or canceled. tracking says whether Agentcard still follows the order, and checked_at says when it last asked the store. The answer also carries what the order holds, what it was sent with and where its packages are: A split retail order lists every package, and reads as far along as its slowest one.

Decide how often to read

Let order events tell you when an order changes, and read the order only to fill a screen, such as the first time a shopper opens their order:
  • DoorDash. Each stage arrives as order.updated the minute Agentcard reads it. If you read the order yourself, read it no more than once a minute: Agentcard refreshes it about once a minute, so a faster read returns the same answer.
  • Retail. Each stage arrives as order.updated with the order’s shipments, and a cancellation by the store arrives as order.updated with status: "canceled". order.confirmed carries the store’s order number and delivery window. Agentcard reads a retail order about every 45 minutes, so reading it more often returns nothing new. checked_at shows when Agentcard last read it.
Agentcard places a retail order from its own purchasing account, so the store’s confirmation and shipping emails never reach the shopper. Show the shopper the receipt from order.placed and order.confirmed, and the carrier’s tracking link from shipments. See Order events.

Pick between two orders with one number

Two stores can give the same order number. Agentcard then refuses the read, and error.body.merchants lists the stores:
Ask again with one of the stores error.body.merchants named:
orders.ts
Agentcard refuses an order number it does not hold for that shopper:

Let the shopper’s rule pay

When the shopper’s auto-approval rule, or your app’s permission from Enable auto-approval, pays for the order, the confirm answers placing with no approval link. Agentcard pays this way only when all of these are true:
  • The store’s processor fixes the amount: the checkout confirms a Stripe PaymentIntent with the card inside, whose amount Agentcard reads from Stripe, or its card request names the total the shopper confirmed, as Paysafe’s single-use payment handle does.
  • The checkout page is on the store whose cart the shopper said yes to.
  • The amount is within the rule’s limits, or within your app’s permission.
The model reads placing and reply, tells the shopper their rule is paying, and never asks for an approval. reply reads:
Agentcard sends no purchase.message for an order the rule pays. The model’s next call reads order_placed with the order number, or placing while the order is still going through. When the shopper’s bank asks to check the payment, the rule can’t answer that check, so the order doesn’t go through and nothing is charged. The confirm answers declined with decline_code: bank_check_required, and reply reads:
Agentcard won’t start a second payment for the same item at that store until it resolves this one. The shopper can buy another item, or the same item at another store, in the meantime. Every other purchase sends the approval link, including one at a Shopify store. A store that turns the card into a token charges that token later for whatever its order says, so no rule’s limit can hold against the charge.

Wait for the bank’s approval

When the shopper’s bank asks them to approve a payment in their banking app, post Agentcard’s reply and wait. A payment the shopper approved with the approval link at a store’s own checkout page reaches the bank’s check, and Agentcard keeps that checkout open for 15 minutes while the shopper approves. When the shopper’s auto-approval rule pays, a bank’s check ends the purchase with bank_check_required instead, as Let the shopper’s rule pay says. Until the bank answers, a confirm of the same cart answers needs_input, with next_action: "bank_challenge" and decline_code: "bank_challenge_required":
Post reply as it is, and don’t ask for a new approval. A confirm of the same cart only reads where the payment stands, and Agentcard never charges twice. url is always null for now. Your server gets a bank_challenge message with the same text, then order_placed or order_failed once the bank answers and the store confirms. Post either the message or the reply from the confirm, not both: they say the same thing. The buy tool’s answer carries the same two fields: next_action reads bank_challenge, and bank_challenge holds the details above. bank_challenge.kind says what the bank asked for: A confirm of the same cart after a code challenge answers:
After a code challenge, your server gets order_placed or order_failed once the store answers.

Handle a refusal where it happens

The shopper declines or lets the approval expire

After a decline, the cart stays on the table. The shopper can say yes for a new approval link, or tell the agent what to change. approval_declined has advances set to true. Open buy.nextStep(message) as “Taking the next step once the shopper finishes outside the chat” shows, and the agent offers the next step without waiting for the shopper. Drop a message after its facts.validUntil: the link or window it names has closed. isStale(message) checks it, and listen and the webhook handler skip stale messages for you.

The cart changed

A cart changes when its price or contents drift after the shopper saw it. Agentcard refuses the confirm, and the tool answers needs_input with error_code: cart_changed and the cart as it stands now. The model shows the shopper the new total and asks again. Nothing is charged. The other refusals that still answer the shopper come back as needs_input with the reason in reply and the code in error_code:

A confirm that takes too long

A request that takes Agentcard more than 110 seconds comes back before its cart is ready. A confirm that takes that long returns the order it placed, sends the approval link it paused on, or reads placing while the order is still going through. A call that times out throws an AgentcardApiError with code: timeout. Whether the turn ran is then unknown, so read the conversation before you call again:
recover.ts
Call the tool again only once that read shows the turn did not finish, because a second call sends a second turn.

Check it with live credentials

The sandbox stops before payment. A confirm there ends declined: a paid purchase answers decline_code: sandbox_mode, and a table booking answers decline_code: sandbox_unavailable. Both mean the sandbox worked, and everything before the confirm ran for real. The approval link, the passkey tap, and the placed order exist only with live credentials. To check them end to end, switch to live credentials as the Quickstart describes, and buy one inexpensive item with your own card.
  1. Ask for the item, pick a product, and say yes to the cart.
  2. Check that the approval link arrives alone, with one short line that names the amount, and that the model’s reply holds no link.
  3. Approve with your passkey. Check that “order placed” arrives in the chat with nothing typed after the tap.
  4. Ask for the item again, say yes, and decline the approval. Check that no charge appears and the cart is still there.