complete_checkout
Complete the purchase. Provide buyer.name and buyer.email from the conversation before opening approval; ask in chat if either is missing. The approval page only reviews these details. PREFER THE CART CARD: if there is an interactive card for this cart, let the buyer confirm and (when the store offers a choice) pick the payment method there — including retrying after a declined payment or switching method — instead of calling this tool yourself. Each call you make here opens a new card in the transcript instead of updating the one already open. Only call it yourself when there is no interactive card or the buyer explicitly asks you to complete it in chat. Idempotent — replay is keyed on checkout_session_id: any retry against a session that already has an order returns that same order (COMPLETED or PENDING_EXTERNAL_CONFIRMATION) without re-charging. The provided idempotency_key is recorded on the session for audit and short-circuits a repeated call with the same key.
If the response has status PENDING_EXTERNAL_CONFIRMATION, no purchase has completed yet: read order_placed and next_action — a person has to approve or pay at its url; next_action says whether calling again with the same checkout_session_id and idempotency_key can read the outcome. SKYFIRE TOKEN (payment_method=KYAPAY): Requires a Skyfire pay or kya-pay token. Preferred: pass the JWT in the skyfire-pay-id request header. Alternative: pass as kyapay_token parameter. Claims validated: sub (account ID), jti (replay prevention), amount (USD, matched against cart total), cur (must be USD), sps (pricing scheme). Missing token with KYAPAY method → error. Invalid token → error 'Invalid Skyfire token'. For other payment methods (MOCK, PAYPAL) no Skyfire token is required. PAYMENT MANDATE: this tool also requires one. Send it as the payment_mandate argument if your client cannot set headers, or as an X-Payment-Mandate header. It must carry mandate_id, max_amount_cents, currency, exp, sub, aud. Two of these are rejected outright if guessed: exp is an INTEGER of Unix seconds (not an ISO 8601 date), and aud is this store's slug (the one in the URL you are calling, not a domain). Its currency must match the cart's currency. Demo Store enforces max_amount_cents against the cart total; a real merchant may only observe that boundary, so enforce the buyer's limit in the agent too. The mandate is a spending cap you declare to limit yourself — it authorises nothing and does not prove the buyer's consent — and its sub must be the identity you authenticate as. max_amount_cents is the spending limit the person you are buying for gave you: ask them if they gave none. Schema: https://trusteed.xyz/.well-known/payment-mandate.schema.json. Checkout guide: https://trusteed.xyz/.well-known/agent-checkout-guide.json. CREDENTIAL: this store needs one. Call the create_sandbox_key tool first (it is in this tool list and needs no credential), then pass the key you get back as the agent_key argument — or as an Authorization: Bearer header if your client can set headers. Do not ask a person to log in: there is no human login for this store.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| buyer | No | Optional buyer contact information | |
| agent_key | No | Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header. | |
| cel_context | No | Optional enforcement context for Trusteed native MCP flows (no Shopify/WooCommerce/PrestaShop/Magento plugin). Providing these fields enables full evaluation of rules R004, R006, R008, R012-R013, R015-R017, R026-R028. See each field's own description for what it means and whether the server verifies it. These values are not signed into the receipt — do not include values you cannot substantiate. | |
| kyapay_token | No | Skyfire pay or kya-pay JWT for autonomous payment via Skyfire (payment_method=KYAPAY). Alternative to passing the token in the skyfire-pay-id request header — the header takes precedence if both are provided. Claims required: sub, jti, amount (USD), cur=USD, sps. | |
| payment_method | No | Payment method to use. PAYPAL creates a PayPal order and presents approval URL. KYAPAY requires kyapay_token. ACP (Stripe-native settlement) returns a 'not enabled' response unless this deployment enables native settlement; when enabled it charges the Stripe Shared Payment Token passed as shared_payment_token. X402 is available through the configured x402 protocol flow, not this checkout tool. MOCK moves no money: it completes the order without charging. Whether a store accepts it depends on the store's configuration (it is the default on demo-store). Defaults to MOCK if not specified. | |
| payment_option | No | Payment method THE PERSON chose, when preview_checkout returned payment_options. Ask the person; never choose for them. Card numbers and wallet keys are never sent here: the person approves (and, with own_wallet, signs) on the approval page. | |
| idempotency_key | Yes | Unique key to prevent duplicate charges on retry. Generate once per purchase attempt. Replay is enforced primarily on checkout_session_id (the existing order is returned). The first key seen for a session is recorded; reusing the same key short-circuits to the existing order. | |
| payment_mandate | No | Payment mandate with `mandate_id`, `max_amount_cents` (integer, minor units), `currency` (3 letters, must match the cart's), `exp` (expiry as an INTEGER of Unix seconds — not an ISO 8601 date string), `sub` (the identity you authenticate as — it is compared against it) and `aud` (the store slug this mandate is for, e.g. the slug in the URL you are calling — not a domain). It is a spending cap you declare to limit yourself: it authorises nothing and does not prove the buyer's consent. Use this when your client cannot set an `X-Payment-Mandate` header. | |
| checkout_session_id | Yes | Checkout session ID from preview_checkout — the same value as create_cart's cart_id (must be a valid UUID) | |
| shared_payment_token | No | Stripe Shared Payment Token (spt_…) granted by the buyer's agent wallet for payment_method=ACP. Issued by Stripe, scoped to this merchant, amount and currency, and consumed when used: it can be charged once. Only honoured when this deployment enables native ACP settlement. | |
| reconfirmed_state_hash | No | SHA-256 of the authoritative merchant state, as returned in details.reconfirm_state_hash by a previous STATE_RECONFIRMATION_REQUIRED error. Required to proceed when the merchant state moved after the approved preview. Passing a stale hash is refused: it means the state moved again and must be reconfirmed anew. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | ||
| currency | Yes | ||
| order_id | Yes | ||
| idempotent | Yes | ||
| store_name | Yes | ||
| test_funds | No | ||
| money_moves | No | ||
| next_action | No | ||
| payment_url | No | ||
| total_cents | Yes | ||
| approval_url | No | ||
| order_placed | No | ||
| funding_source | No | ||
| payment_method | No | ||
| shipping_source | No | ||
| payment_captured | No | ||
| external_order_id | No | ||
| checkout_session_id | Yes | ||
| shipping_authoritative | No |