Complete a checkout after buyer approval

Present the hosted review URL, wait for approval of the current checkout revision, and complete the purchase once.

Use this flow when an agent controls checkout through Orderboost’s Model Context Protocol (MCP) tools. OAuth allows the agent to create and update checkout, but only a signed-in buyer can approve payment for the current revision.

The agent presents the URL and reads checkout state through MCP. It does not automate the browser review or ask for payment credentials.

Follow the approval lifecycle

Present the hosted review

When create_checkout or update_checkout returns requires_escalation, show the exact continue_url to the buyer. Do not shorten, reconstruct, scrape, or automate it.

The hosted page displays the authoritative merchant, items, fulfillment, shipping service, total, and saved payment method. The buyer approves that exact checkout revision.

The approval URL is short-lived and bound to its OAuth client, checkout, and revision. Treat a URL from an earlier result as stale after any checkout change.

Wait for the approved state

Call get_checkout after the buyer finishes the hosted review. Continue only when the result contains:

• status: "ready_for_complete"
• A purchase-grant identifier for the current revision
• The items and total that the buyer approved

Read the purchase grant from the protected tool result. Never ask the buyer to copy it from the browser.

If the checkout remains requires_escalation, present only the latest continue_url. If it becomes complete_in_progress, poll get_checkout with bounded backoff instead of submitting payment again.

Complete the checkout once

Call complete_checkout with the returned purchase grant and one stable idempotency key. Follow the live tool schema exposed by your MCP client.

The approved payment instrument is already bound to the purchase grant. Send an empty payment object when the schema requests checkout.payment. Do not ask for a card number, wallet key, or payment token.

Orderboost validates the approved merchant, revision, quote, amount, currency, fulfillment, payment reference, and OAuth client before completion. Report success only when the result contains status: "completed" and a persisted order.

Handle every checkout status

Use the current checkout result to choose the next action:

Recover safely

Any mutable update revokes the active purchase grant. Fetch checkout again, present its new approval URL, and complete only the newly approved revision.

If a completion response is lost, call get_checkout before retrying. Reuse the original idempotency key only for the same approved revision and request. Never create a second checkout solely because the response was ambiguous.

If an approval URL fails to open, fetch the current checkout:

• Use its latest continue_url when the status is requires_escalation
• Continue without reopening review when the status is ready_for_complete
• Report the order when the status is completed

Read Use Orderboost MCP tools for the complete status contract.