AP2 Mandates Extension | UCP Documentation

Overview

AP2 (Agent Payment Protocol 2) Mandates provide cryptographic authorization that allows AI agents to make purchases on behalf of users within defined constraints. This enables truly autonomous commerce while maintaining user control and security.

Extension Identifier

dev.ucp.shopping.ap2_mandate

How Mandates Work

User creates mandate - Defines constraints (budget, categories, merchants)
User signs mandate - Cryptographically signs with their identity
Agent receives mandate - Stores securely for future use
Agent uses mandate - Includes proof with purchase request
Business validates - Verifies signature and constraints

Mandate Structure

{
  "mandate_id": "mandate_xyz789",
  "version": "1.0",
  "principal": {
    "type": "user",
    "identifier": "user:john@example.com"
  },
  "agent": {
    "type": "agent",
    "identifier": "agent:shopping-assistant-v1",
    "public_key": "-----BEGIN PUBLIC KEY-----..."
  },
  "constraints": {
    "max_single_purchase": {
      "amount": 500.00,
      "currency": "USD"
    },
    "max_daily_total": {
      "amount": 1000.00,
      "currency": "USD"
    },
    "allowed_categories": ["electronics", "home", "clothing"],
    "excluded_categories": ["adult", "gambling"],
    "allowed_merchants": [],  // Empty = all merchants
    "excluded_merchants": ["merchant:blocked-store"],
    "require_approval_above": {
      "amount": 200.00,
      "currency": "USD"
    }
  },
  "validity": {
    "not_before": "2025-01-01T00:00:00Z",
    "not_after": "2025-12-31T23:59:59Z"
  },
  "created_at": "2025-01-01T00:00:00Z",
  "signature": "base64-encoded-signature..."
}

Using Mandates in Checkout

POST /checkout/sessions/{session_id}/complete
Content-Type: application/json
Authorization: Bearer {agent_token}

{
  "payment": {
    "handler": "stripe",
    "token": "tok_xxx"
  },
  "mandate": {
    "mandate_id": "mandate_xyz789",
    "proof": {
      "transaction_hash": "sha256:abc123...",
      "nonce": "random-nonce-value",
      "timestamp": "2025-01-15T10:30:00Z",
      "signature": "base64-agent-signature..."
    }
  }
}

Mandate Validation

Businesses validate mandates by checking:

Signature validity - Principal's signature is authentic
Agent identity - Agent matches mandate's authorized agent
Constraint compliance - Purchase is within defined limits
Temporal validity - Mandate is not expired
Revocation status - Mandate has not been revoked

Constraint Types

max_single_purchaseMaximum amount per transaction

max_daily_totalMaximum daily spending limit

max_weekly_totalMaximum weekly spending limit

max_monthly_totalMaximum monthly spending limit

allowed_categoriesProduct categories permitted

excluded_categoriesProduct categories blocked

allowed_merchantsSpecific merchants permitted

excluded_merchantsSpecific merchants blocked

require_approval_aboveHuman approval threshold

Revocation

POST /mandates/{mandate_id}/revoke
Content-Type: application/json
Authorization: Bearer {user_token}

{
  "reason": "User requested revocation"
}

Audit Trail

Every mandate usage is logged for accountability:

{
  "event_type": "mandate.used",
  "mandate_id": "mandate_xyz789",
  "agent_id": "agent:shopping-assistant-v1",
  "transaction": {
    "order_id": "ord_abc123",
    "amount": 149.99,
    "merchant": "merchant:acme-store"
  },
  "timestamp": "2025-01-15T10:30:00Z",
  "constraints_checked": {
    "max_single_purchase": "passed",
    "daily_total_remaining": 850.01,
    "category_check": "passed"
  }
}

Error Handling

MANDATE_INVALID - Signature verification failed
MANDATE_EXPIRED - Mandate validity period ended
MANDATE_REVOKED - Mandate has been revoked
MANDATE_EXCEEDED - Purchase exceeds constraints
CATEGORY_NOT_ALLOWED - Product category not permitted
MERCHANT_BLOCKED - Merchant is excluded
APPROVAL_REQUIRED - Amount exceeds auto-approval threshold

Next Steps

Learn about Buyer Consent for privacy compliance
See AI Agent Integration for implementation
Explore A2A Transport for agent communication

AP2 Mandates