ucp_complete_checkout
Complete a UCP checkout session. Transitions to 'completed' status. Idempotent — safe to retry with the same idempotency_key. Use ONLY for a checkout session created with ucp_create_checkout (Universal Commerce Protocol); for the standard flow (create_cart, preview_checkout, complete_checkout) do not call this tool. For a cart built with create_cart use complete_checkout. 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.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"checkout_id": "<checkout_id>",
"idempotency_key": "<idempotency_key>"
},
"name": "ucp_complete_checkout"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ap2 | No | AP2 mandates extension. Required when the checkout carries ap2.merchant_authorization. | |
| meta | No | UCP request metadata. meta['ucp-agent'].profile = URL of the platform profile; it must be an https URL without credentials (at most 2048 characters). | |
| buyer | No | Buyer name and email, needed to request the approval link. | |
| payment | No | UCP payment. With AP2, the Payment Mandate goes in instruments[].credential.token. | |
| agent_key | No | Sandbox credential from `create_sandbox_key`. Use this when your client cannot set an `Authorization: Bearer` header. | |
| checkout_id | Yes | UCP checkout session ID (valid UUID) | |
| x402_payload | No | x402: signed payment for the server offer (omit to get it). | |
| 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_handler | No | Payment handler the store profile publishes. Omit for default. | |
| 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. | |
| 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. |