UCP AP2 Mandates Extension
Before writing code
Fetch live spec:
- Web-search
site:ucp.dev specification ap2-mandatesfor the extension schema - Fetch https://ucp.dev/2026-01-23/documentation/ucp-and-ap2/ for the conceptual relationship
- Web-search
site:ap2-protocol.orgfor the AP2 protocol specification
Conceptual Architecture
What AP2 Enables
AP2 (Agent Payments Protocol) enables fully autonomous agent commerce — the agent can authorize payments cryptographically without requiring real-time human approval for each transaction. The user pre-authorizes spending parameters, and the agent proves authorization via signed credentials.
Two Mandate Artifacts
-
Checkout Mandate (
ap2.checkout_mandate): An SD-JWT+kb (Selective Disclosure JWT with Key Binding) credential that proves the user authorized the agent to complete this specific checkout at these specific terms. -
Payment Mandate (
payment_data.token): A separate credential proving payment authorization, verified by the PSP (not the Business).
Merchant Authorization
Before the Platform generates mandates, the Business must sign the checkout terms:
- Format: JWS Detached Content (RFC 7515 Appendix F) —
<header>..<signature> - Canonicalization: JSON Canonicalization Scheme (RFC 8785)
- Algorithms: ES256, ES384, ES512 (elliptic curve)
The Business returns this merchant_authorization in the checkout response.
7-Step Flow
- Discovery — Business publishes AP2 support in capabilities
- Session Activation — Platform signals AP2 intent
- Business Signing — Business returns checkout +
merchant_authorization(JWS detached content) - Authorization Generation — Platform creates CheckoutMandate (SD-JWT-VC) + PaymentMandate
- Submission — Platform sends both mandates in the
complete_checkoutcall - Verification — Business verifies checkout mandate; PSP verifies payment mandate
- Confirmation — Order confirmed
Security Lock
Once AP2 is negotiated for a checkout session, a Security Lock is activated: neither party may revert to a standard (non-AP2) checkout flow for that session. This prevents downgrade attacks where a malicious actor could bypass the cryptographic mandate requirements by falling back to a simpler payment flow.
Error Codes
AP2-specific errors:
mandate_required— AP2 mandates needed but not providedagent_missing_key— Agent's signing key not foundmandate_invalid_signature— Signature verification failedmandate_expired— Mandate past validity windowmandate_scope_mismatch— Mandate doesn't match checkout termsmerchant_authorization_invalid— Business signature invalidmerchant_authorization_missing— Business didn't sign terms
Implementation Guidance
This is the most complex UCP extension. Before implementing:
- Understand SD-JWT-VC (Selective Disclosure JWT Verifiable Credentials) — this is the credential format
- Understand JWS Detached Content (RFC 7515 Appendix F) — this is the merchant signing format
- Understand JSON Canonicalization (RFC 8785) — deterministic JSON serialization for signing
- Fetch the latest AP2 protocol spec from https://ap2-protocol.org for the full mandate lifecycle
- Check the conformance test suite: https://github.com/Universal-Commerce-Protocol/conformance (ap2_test.py)
This extension is intended for advanced autonomous agent scenarios. Most initial implementations should start with standard payment handlers (Google Pay, Shop Pay) before adding AP2.