Merchant integration with ACP: checkout sessions, delegated tokens and safe retries

What it is

Status as of 25 October 2026. This article uses the dated ACP 2026-04-17 specification snapshot and its release changelog. Re-check the agreed API version, payment-handler schemas and release notes before integration. Do not silently substitute examples from an older website page or the repository's unreleased directory.

The Agentic Checkout API gives a merchant a programmatic checkout interface: create a session, update or retrieve it, complete it, or cancel it. The merchant returns authoritative cart state. An agent can request changes and present the result to the buyer, while the merchant's backend owns the checkout calculation and order processing.

Why it matters

Checkout agreement and payment credential delegation are separate operations. The Delegate Payment API tokenizes a credential for constrained use by the merchant's payment service provider. Its response contains a vault-token identifier. Its allowance includes a maximum amount, currency, checkout-session identifier, merchant identifier and expiry; the documented usage reason is one_time.

This token is not a general permission for the agent to shop. The merchant and payment provider must integrate the agreed handler and enforce its constraints. As a defensive implementation practice, keep credential collection and token issuance in dedicated payment components, outside model prompts and ordinary request logs.

How to apply

• Expose the session operations. Implement creation at /checkout_sessions, retrieval and updates on the session resource, and the /complete and /cancel operations. Return current totals, fulfillment information, messages and status. Preserve the distinction between ready_for_payment, authentication_required, complete_in_progress and completed.
• Negotiate payment handling. Use the handler advertised by the checkout, and send completion payment data using its handler_id and instrument schema. A vault token alone is not a complete checkout request. Confirm the provider understands the token before enabling that payment path.
• Authenticate the integration. The security documentation specifies HTTPS and bearer-token authentication. Supply the required API-Version header from the chosen contract; authorize session access within the authenticated merchant-agent relationship.
• Implement safe retries. This release requires Idempotency-Key on POST requests. Reuse a key only for the same operation and body. Missing keys produce idempotency_key_required; an active duplicate produces idempotency_in_flight; a changed body under the same key produces idempotency_conflict.
• Verify order notifications. The release defines Merchant-Signature webhook authentication over the timestamp and raw body, with timestamp-window checks against replay. Link authenticated updates to the checkout and order before changing local fulfillment state.

Pitfalls

HTTP success does not imply that the session is completed. An operational reconciliation process should compare checkout, payment and order states after interruptions rather than initiating another purchase immediately.

The dated release makes idempotency mandatory even though older documentation describes it as optional. Pin schemas and test that rule explicitly. Tokenization, buyer confirmation, payment authorization and fulfillment each need their own evidence; none should be inferred solely from a conversational success message.