Capability negotiation

ACP uses capability negotiation so agents and sellers can discover what each supports and agree on a common set of features for a checkout. A single capabilities object is sent in requests (from the agent) and returned in responses (from the seller), with the seller returning only the intersection of mutually supported capabilities.

Why capability negotiation?

Agents and sellers can support different payment methods, authentication flows, and interaction patterns. Without a standard way to negotiate:

• Agents cannot know in advance whether they can complete a given checkout.
• Sellers cannot communicate requirements (e.g., 3D Secure for certain transactions).
• New features (e.g., biometric auth, BNPL) require ad-hoc integration instead of a single, extensible mechanism.

Capability negotiation addresses this by:

1. Single capability declaration — The same capabilities structure is used for both parties; context (request vs response) indicates who is declaring.
2. Intersection-based response — The seller returns only the intersection of supported capabilities, so the agent does not need to compute compatibility.
3. Early incompatibility detection — Mismatches can be detected before payment, with clear errors or fallbacks.

Where capabilities appear

• Requests: Agents MUST include capabilities on checkout session create requests. At minimum, agents declare intervention support, e.g. {"interventions": {"supported": []}}.
• Responses: Sellers MUST include capabilities on all checkout session responses (create, retrieve, update, complete). The response holds the negotiated capabilities for that session.

capabilities in requests is write-only and is not echoed back; the response always reflects the seller-computed negotiated capabilities.

The capabilities object

Agent request (what the agent sends)

Agents declare what they can handle, especially for user interventions (e.g., 3DS, biometric, address verification):

• interventions (optional but recommended):
  • supported — Array of intervention types the agent can handle, such as 3ds or biometric.
  • display_context — How the agent presents interventions: native within an application, a browser webview, etc.
  • redirect_context — How redirects are handled: in_app, external_browser, or none.
  • max_redirects — Maximum number of redirects the agent can handle in one flow.
  • max_interaction_depth — Maximum depth of nested interactions (e.g., 3DS inside a webview).

Agents may also declare extensions they understand (e.g., ["discount"]) so the seller can enable compatible extensions for the session.

Seller response (negotiated capabilities)

The seller returns only what both sides support and adds seller-specific information:

• payment — Payment configuration for this session. Includes handlers: the list of payment handlers (e.g., tokenized card, wallet) the seller accepts. Each handler describes its name, version, spec URL, whether it uses Delegate Payment, PCI requirements, and instrument schemas.
• interventions:
  • supported — Intersection of agent and seller supported interventions. Only intervention types both support appear here.
  • required — (Optional) Interventions the seller requires for this session (e.g., ["3ds"]). If empty or absent, none are required.
  • enforcement — (Optional) When required interventions apply: always, conditional (e.g., based on risk), or optional.
• extensions — For sessions with extensions, the seller returns an array of extension declarations (name, schema/spec URLs, which schema fields they extend) for extensions active in this session.

Note: interventions.supported in the response is exactly the intersection of supported interventions. The agent does not need to compute it; the seller does and returns only mutually supported values.

Intersection semantics

When the agent sends capabilities.interventions.supported, the seller:

1. Computes the intersection with its own supported interventions.
2. Returns that intersection in capabilities.interventions.supported in the response.
3. Adds seller-only fields (required, enforcement) and payment/extensions as applicable.

Example:

• Agent sends: {"interventions": {"supported": ["3ds", "biometric", "address_verification"]}}
• Seller internally supports: ["3ds", "address_verification"]
• Seller returns: {"interventions": {"supported": ["3ds", "address_verification"], "required": [], "enforcement": "conditional"}}

So the agent immediately sees that for this session only 3DS and address verification are mutually supported; biometric is not.

Intervention compatibility

A session is compatible for interventions when:

1. The intersection (returned in supported) includes every intervention in required, or required is empty/absent, and
2. Any expected interaction depth does not exceed the agent’s declared max_interaction_depth (if present).

If the seller requires 3DS but the agent declared supported: [], the intersection is empty. The seller still returns capabilities (e.g. supported: [], required: ["3ds"]) and can add an error message (e.g. with code intervention_required) so the agent can inform the user that 3DS is required but not supported in the current environment.

Payment and extensions

• Payment: The seller advertises payment handlers in capabilities.payment.handlers. Each handler identifies how payment is processed (e.g., tokenized card via Delegate Payment), which PSP is used, and which instrument schemas apply. The agent uses this to know which payment methods and flows are available for the session.
• Extensions: The agent can list extension identifiers it understands in capabilities.extensions in the request. The seller returns capabilities.extensions in the response as an array of extension declaration objects (name, extends, schema, spec) for extensions active in that session. This allows optional, composable features (e.g., discounts) without changing the core schema.

Error handling and unknown values

• Intervention requirement mismatch: When the intersection does not cover required, the seller can set the checkout sesssion status (e.g. not_ready_for_payment) and include a message with code such as intervention_required and a human-readable explanation.
• Unknown capabilities: Implementations MUST ignore unknown capability values

Security and privacy notes

• Sellers MUST NOT use agent-declared capabilities as the sole basis for security decisions; they MUST enforce authentication and payment rules server-side.
• Sellers SHOULD advertise only capabilities relevant to the current session and avoid exposing unnecessary internal detail.
• Agents SHOULD declare only capabilities needed for checkout and avoid declaring more than necessary (e.g., for fingerprinting).

Summary

Next steps