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. KYAPAY (payment_method=KYAPAY or a kyapay_token): charging with KYApay is not available. KYApay is identity verification here, not a payment rail, so the call is rejected with PAYMENT_METHOD_NOT_CONFIGURED before anything is charged or written; use another payment method. The Skyfire KYA token serves identity on the REST API, not payment in this tool. On demo-store the approval step records a confirmation but does not verify that a human gave it. PAYMENT MANDATE: this tool also requires one, issued by the platform, not written by you. Call preview_checkout for this cart, open the approval_url it returns, poll approval_status_url with your agent credential, and send the mandate you receive as the payment_mandate argument or an X-Payment-Mandate header. The approval is bound to your agent credential and the cart; it does not verify that a person was present. Checkout guide: read the MCP resource trusteed://guides/checkout. 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. Send only evidence you can substantiate; it can only make a check stricter, never looser. Unknown keys or out-of-range values are rejected with INVALID_ARGUMENT. Keys: key_age_hours, requested_scopes, product_categories, price_delta_bps, discount_codes_tried, discount_bps, lowest_stock, return_policy_mismatch, is_subscription, autorenew_consent, is_b2b, purchase_order_hash, shipping_po_box, shipping_freight_forwarder, provider_confidence, stored_value_cents, cross_merchant_abuse, refund_ratio, dispute_count, completed_orders_24h, merchant_orders_1h, digital_good_types, agent_provider_id. | |
| kyapay_token | No | Not available for payment: charging with KYApay is switched off, because KYApay is identity verification here, not a payment rail. A call that passes this token is rejected with PAYMENT_METHOD_NOT_CONFIGURED before anything is charged or written. The Skyfire KYA token is used for identity on the REST API, not in this tool. | |
| payment_method | No | Payment method to use. PAYPAL creates a PayPal order and presents approval URL. KYAPAY is not available for payment: KYApay is identity verification here, so a request with KYAPAY is rejected without charging anything. 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 | REQUIRED as an argument in this tool: the `Idempotency-Key` header or `_meta` alone is not enough. 1-128 chars from [A-Za-z0-9._:/-]. Reuse the same value when retrying the same operation. | |
| payment_mandate | No | Payment mandate issued by the platform for this cart: the compact JWS you receive after the approval opened by `preview_checkout` is granted (its `exp` is Unix seconds and `aud` is this store's slug). Forward it as received; a mandate you write yourself is not accepted here. The approval is bound to your agent credential and does not verify that a person was present. 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) | |
| save_payment_method | No | Only with PayPal at a store that charges into its own PayPal account, for a signed-in buyer (not guest access), and only when the person asked for it: true asks PayPal to save this PayPal account during this purchase, so later purchases at this store can be charged without a new approval, within per-charge and daily limits. Never set it on your own initiative. In any other case it is ignored and the response says so in details; it never causes an error. | |
| 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 | ||
| details | No | ||
| 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 |