Skip to main content

​
The complete_checkout tool

complete_checkout is the in-agent MCP tool that completes a purchase inside an existing conversation. One call gates on the buyer’s recorded consent, mints and renders the checkout that matches the conversation’s channel, and runs one bounded reconcile probe for a paid or failed outcome. It pairs with confirm_payment_mandate, the tool that records the consent the gate requires. This page is the tool contract for agent authors: what the call does, the two-phase consent flow, the channel map, the exact failure vocabulary, and what operators see in retry and sandbox contexts. For the consent model behind the gate, see Authorization mandates. For the commerce primitives the tool orchestrates, see Commerce checkout spine.

​
What one call does

The tool takes conversation_id (required). Two optional arguments: A call runs these steps in order and stops at the first failure:
  1. Resolve the conversation. The tool reads the conversation record to get its stored channel (WhatsApp, RCS, Apple Messages for Business, or web chat). It never re-detects the channel by any other means.
  2. Check that an active cart exists. The conversation must already carry a cart. If it does not, the tool returns no_active_cart and never creates a bare cart on the conversation.
  3. Gate on recorded consent. The tool requires a fresh consent receipt from confirm_payment_mandate for this conversation. Without one it returns not_confirmed and mints nothing.
  4. Mint and render the PaymentRequest. The tool mints a hosted PaymentRequest via POST /commerce/payment-request and renders it through the channel-specific adapter via /commerce/payment-request/render, so the buyer receives the native payload for their channel: an order details payload on WhatsApp, a hosted link on RCS, Apple Pay or a hosted link on Apple Messages for Business, or the embedded tokenized form on web chat. The tool returns the rendered payload to the agent, which relays it in the conversation.
  5. Run one bounded reconcile probe. The tool polls /commerce/payment-request/reconcile once every 5 seconds for up to 10 minutes, classifying each snapshot as completed, failed, or still pending (see Reading reconcile outcomes).
On a paid outcome the tool returns the order confirmation the agent relays to the customer:
On a terminal failure the tool returns the reconcile reason so the agent can offer to retry from the mint step. When the 10-minute window ends without a terminal state, the tool returns still_pending with the open checkout_link: the link is still valid, so the agent tells the buyer the link remains open instead of rendering a second checkout. complete_checkout never asks the buyer for consent itself and never infers it from conversation text. Consent is captured in a first phase by confirm_payment_mandate:
  1. The agent reads the cart back to the buyer verbatim: merchant, total amount, and currency.
  2. The buyer gives an explicit yes to exactly that amount and merchant.
  3. The agent calls confirm_payment_mandate with merchant, amount, currency, and caller_confirmed set to the literal boolean true. Anything else (absent, false, or a string) records nothing and returns not_confirmed.
A successful call records a structured, non-authorizing consent receipt in the agent runtime’s in-process mandate-consent registry, scoped to the tenant and the conversation, valid for expires_in_minutes (default 15, maximum 1440). The receipt is evidence of the buyer’s yes, not a payment authorization: it does not charge anyone and does not mint a signed mandate. Settlement is still authorized server-side against the buyer’s on-file mandate, as described in Authorization mandates. In the second phase, complete_checkout checks the registry before it mints anything. If no fresh receipt exists for the conversation, the call returns not_confirmed with a hint, and no PaymentRequest is minted:
The same applies when the receipt has expired: the agent re-runs the mandate flow and retries complete_checkout.

​
Channel-specific rendering

The tool maps the conversation’s stored channel to one of four supported checkout channels. There is no generic fallback: a conversation on any other channel (SMS, voice, email) returns unsupported_channel. For the Apple Messages for Business setup side, see Apple Messages commerce checkout.

​
Failure surface

Every failure is a typed envelope the agent can branch on. The two cart and channel rejects look like this:
The full vocabulary, in the order a call can hit it:

​
Retry and sandbox semantics

complete_checkout and confirm_payment_mandate are registered as mutative tools. Read-only tools (such as list_campaigns) are retried with backoff when a call fails; mutative tools are not, because a replay after a timeout could mint a second hosted pay-by-link for the same cart or double-record the same verbal consent. Each call therefore executes exactly once. If a call times out on the client side, treat the attempt as possibly completed: check the conversation for an open payment request before invoking the tool again. The same two tools are sandbox-blocked in the agent executor. When an agent runs in sandbox mode (test calls, eval and regression replays), the executor short-circuits the call before any dispatch and returns a deterministic, success-shaped mock envelope marked sandboxed: true. No PaymentRequest is minted against a live conversation, no consent receipt is recorded from a replayed “yes”, and no provider traffic leaves the platform. Operators reading a sandboxed run trace see the mock envelope flagged as sandboxed, distinguishable from a genuine provider response. Read-only tools still execute normally in sandbox mode so replays keep realistic grounding.

​
Payment rails boundary

Stripe is the only payment rail behind complete_checkout. The tool orchestrates Orbit’s own in-conversation commerce stack and nothing else: the ACP storefront adapter under /agentic/ and the UCP adapter under /ucp/ are untouched by this tool. Those adapters serve external AI storefront discovery over A2A federation; complete_checkout is the in-agent path. Do not read this tool as a generic PSP abstraction. For the external federation path, see A2A agentic-commerce transact skill: the transact skill is the A2A federation surface where a peer buyer agent submits a cart and mandate, while complete_checkout is the tool your own agent calls inside a live conversation. Both end in the same payment-request rails.

​
Reading reconcile outcomes

The bounded probe classifies each polled PaymentRequest snapshot into one of three verdicts: Two reading rules follow from that classification. A transient reconcile error (a non-200 response or an unparseable envelope) classifies as still pending, never as failed: the probe does not misreport a payment failure because a poll hiccuped. And still_pending at the end of the window is a terminal envelope, not an error: the hosted link is still open and the buyer can still pay on it, so the correct agent behavior is to point the buyer at the existing link rather than mint a new one. For the endpoint reference behind each step, see the Commerce API reference.