buy_checkout

Connect to https://mcp.agentcard.sh/mcp with the user’s connection token (or a buy_token for org-owned accounts). Behavior: destructive.

Not in the default tools/list. It is still callable by exact name, and appears when the client sends the x-expert-tools: 1 header.

What it does

DESTRUCTIVE: place + pay for the current cart. Runs the spend gate, creates a one-time card sized to the cart total, tokenizes at the merchant, and places the order. Confirm the cart total with the user first. Returns needs_approval if a spend approval is required. May also return denied with an account gate — kyc_required (run start_kyc), user_info_required (run submit_user_info), wallet_funding_required (run add_funds) — each reply names the tool to run before retrying with the same idempotency_key. To make retries SAFE (e.g. after a timeout), pass the SAME idempotency_key on every retry of one purchase — the backend then reuses the single reservation/card instead of charging twice. Use a fresh key only for a genuinely new purchase.

Inputs

Field	Type	Description
`merchant` (required)	string
`expected_total_cents`	number	the FINAL total in cents you showed the user and they confirmed — cart total PLUS any tip_cents you pass. The server re-reads the live cart and rejects the checkout (409 cart_total_changed) if it no longer adds up, so an amount the user never saw can never be charged. Always pass it when you showed a total.
`expected_address_id`	string	the id (from buy_addresses / the one you passed to buy_set_default_address) of the delivery address the user confirmed. The server re-asserts it as the merchant default and rejects the checkout (409 address_changed) if it can’t, so the order can never ship to a stale/other address. Always pass it once a delivery address is set.
`tip_cents`	number	optional Dasher tip in cents; added to the charge and the created card size
`delivery_time`	string	optional ISO-8601 time to SCHEDULE delivery for (e.g. “2026-06-17T23:00:00Z”); omit for ASAP
`approval_id`	string	a previously-issued spend approval id, if checkout returned needs_approval
`idempotency_key`	string	a stable key for this purchase; reuse it on every retry so a timed-out/retried call never double-charges
`cart_rebuilt`	boolean	pass true ONLY after a pos_cart_validation rejection AND after you actually re-added the item with corrected option selections — it overrides the server’s block on re-checking-out a cart it saw the restaurant’s register reject. Never pass it on a cart you haven’t changed.

Returns

None.

Example call

{
  "tool": "buy_checkout",
  "arguments": {
    "merchant": "\u2026"
  }
}

MCP

Organization tools

User tools

What it does

Inputs

Returns

Example call

​What it does

​Inputs

​Returns

​Example call

What it does

Inputs

Returns

Example call