ap2-dev-patterns

AP2 Development Patterns

Before writing code

Fetch live docs:

1. Fetch https://ap2-protocol.org/specification/ for the latest protocol details
2. Fetch https://ap2-protocol.org/topics/ap2-and-ucp/ for UCP integration patterns
3. Fetch https://ap2-protocol.org/topics/ap2-and-x402/ for x402 crypto integration
4. Web-search site:github.com google-agentic-commerce AP2 samples for reference architectures

Conceptual Architecture

Multi-Agent Payment Architecture

The standard AP2 architecture involves four agents communicating via A2A:

┌──────────────────────────────────────────────────┐
│                    User                           │
│          (trusted device surface)                 │
└──────────┬───────────────────────────────────────┘
           │ intent + signatures
┌──────────▼───────────────────────────────────────┐
│            Shopping Agent (SA)                     │
│    Orchestrator — coordinates the full flow        │
└──┬──────────────┬────────────────────────────────┘
   │              │
   │ A2A          │ A2A
   │              │
┌──▼──────┐  ┌───▼──────────┐
│ Merchant │  │ Credentials  │
│ Agent    │  │ Provider     │
│          │  │              │
│ catalog  │  │ payment      │
│ cart     │  │ methods      │
│ signing  │  │ tokenization │
└────┬─────┘  └──────────────┘
     │
     │ (Merchant → MPP)
     │
┌────▼─────────────┐
│ Merchant Payment  │
│ Processor (MPP)   │
│                   │
│ authorization     │
│ settlement        │
│ Payment Mandate   │
│ challenges        │
└────────┬──────────┘
         │
    ┌────▼──────────┐
    │ Network/Issuer │
    │ (Visa, MC,     │
    │  banks)        │
    └────────────────┘

Important: The SA communicates with the Merchant and the CP via A2A. The Merchant communicates with the MPP. The SA does not directly communicate with the MPP.

UCP Integration Pattern

UCP (Universal Commerce Protocol) operationalizes AP2:

• UCP's Checkout object maps to a commerce-level checkout flow
• UCP's checkout_mandate is distinct from (but related to) AP2's Cart Mandate — checkout_mandate is a UCP-specific concept that wraps the commerce checkout authorization, while AP2's Cart Mandate is the cryptographically signed VDC binding user consent to specific transaction terms
• UCP's /complete_checkout API = AP2's payment authorization step
• PaymentMandate (constructed by the MPP) proves payment authorization for the network/issuer