Confirm the cart
The model setsconfirm 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
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 apurchase.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 theorder_placed message, message.order.orderId:
orders.ts
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.updatedthe 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.updatedwith the order’sshipments, and a cancellation by the store arrives asorder.updatedwithstatus: "canceled".order.confirmedcarries 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_atshows when Agentcard last read it.
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, anderror.body.merchants lists the stores:
error.body.merchants named:
orders.ts
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 answersplacing 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.
placing and reply, tells the shopper their rule is paying, and never asks for an approval. reply reads:
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’sreply 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":
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:
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 answersneeds_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 readsplacing 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
Check it with live credentials
The sandbox stops before payment. A confirm there endsdeclined: 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.
- Ask for the item, pick a product, and say yes to the cart.
- Check that the approval link arrives alone, with one short line that names the amount, and that the model’s reply holds no link.
- Approve with your passkey. Check that “order placed” arrives in the chat with nothing typed after the tap.
- Ask for the item again, say yes, and decline the approval. Check that no charge appears and the cart is still there.