UCP and AP2 Integration

UCP is deeply integrated with Agent Payments Protocol (AP2), providing cryptographic-level security guarantees for agent transactions through the AP2 Mandates Extension.

Integration Overview

UCP + AP2 Synergy

UCP serves as the commerce protocol foundation layer, defining core capabilities like Checkout, Cart, and Order. AP2 acts as the trust layer, adding cryptographic proof mechanisms on top of these capabilities:

  flowchart LR
    A[UCP Core] --> B[Checkout Capability]
    C[AP2 Extension] --> D[AP2 Mandates]
    B --> E[Secure Checkout]
    D --> E
    E --> F[Verifiable Transaction]

Core Value Proposition

Feature	UCP Base Capability	+ AP2 Extension
Transaction Integrity	Structured data	Cryptographic signature verification
User Intent Proof	Optional authorization	Mandatory signature authorization
Payment Credentials	Basic payment methods	Verifiable digital credentials
Dispute Resolution	Order records	Complete evidence chain
Agent-Ready	Basic support	Full support

AP2 Mandates Extension

Capability Declaration

Businesses declare AP2 support in their Profile:

{
  "capabilities": [
    {
      "name": "dev.ucp.shopping.checkout",
      "version": "2026-01-11",
      "spec": "https://ucp.dev/specification/checkout",
      "schema": "https://ucp.dev/schemas/shopping/checkout.json"
    },
    {
      "name": "dev.ucp.shopping.ap2_mandate",
      "version": "2026-01-11",
      "spec": "https://ucp.dev/specification/ap2-mandates",
      "schema": "https://ucp.dev/schemas/shopping/ap2_mandate.json"
    }
  ]
}

Protocol Flow

  sequenceDiagram
    participant P as Platform
    participant B as Business
    participant U as User
    participant PP as Payment Processor

    Note over P,B: 1. Capability Negotiation
    P->>B: Get Profile
    B--)P: Return capability list (includes AP2)

    Note over P,B: 2. Create Checkout
    P->>B: Create Checkout (activate AP2)
    B--)P: Checkout + ap2.merchant_authorization

    Note over U: 3. User Authorization
    U->>P: Confirm purchase

    Note over P: 4. Generate Mandates
    P->>P: Generate CheckoutMandate
    P->>P: Generate PaymentMandate

    Note over P,B: 5. Complete Transaction
    P->>B: Complete Checkout + Mandates
    B->>PP: Verify PaymentMandate
    PP--)B: Payment authorization
    B--)P: Order confirmation

Data Structures

CheckoutMandate (Merchant Protection)

{
  "ap2": {
    "checkout_mandate": "eyJhbGciOiJFUzI1NksiLCJraWQiOiJkaWQ...",
    "merchant_authorization": "eyJhbGciOiJFUzI1NksiLCJraWQ..."
  }
}

PaymentMandate (Payment Authorization)

{
  "ap2": {
    "payment_mandate": {
      "payment_mandate_id": "pm_12345",
      "payment_details_id": "order_shoes_123",
      "payment_details_total": {
        "label": "Total",
        "amount": {
          "currency": "USD",
          "value": 120.00
        }
      }
    },
    "user_authorization": "eyJhbGciOiJFUzI1NksiLCJraWQ..."
  }
}

Terminology Mapping

UCP Concept	AP2 Concept	Description
Checkout Object	CartMandate	Merchant’s signed confirmation of purchase offer
CheckoutMandate	User Purchase Authorization	User’s signed authorization of purchase content
PaymentMandate	PaymentMandate	User’s authorization of payment credentials

Integration Scenarios

Agent Shopping Scenario

Exploration Phase (Cart)
- Agent uses Cart capability to explore products
- No payment configuration required, lightweight operations
Purchase Intent (Checkout + AP2)
- Convert to Checkout session
- Activate AP2 Mandates extension
- Obtain merchant signature authorization
User Confirmation (Mandates Generation)
- User confirms in trusted interface
- Generate CheckoutMandate and PaymentMandate
Transaction Completion (Verification & Execution)
- Merchant verifies Mandates
- Payment processor verifies PaymentMandate
- Complete payment and confirm order

Implementation Guide

Platform Side

# Pseudocode example
def create_checkout_with_ap2(cart_id):
    # 1. Create Checkout (activate AP2)
    checkout = ucp_client.create_checkout(
        cart_id=cart_id,
        extensions=["ap2_mandate"]
    )

    # 2. Get merchant authorization
    merchant_auth = checkout.ap2.merchant_authorization

    # 3. Generate Mandates after user confirmation
    if user_confirms():
        checkout_mandate = sign_checkout(checkout, merchant_auth)
        payment_mandate = generate_payment_mandate(checkout)

        # 4. Complete transaction
        result = ucp_client.complete_checkout(
            checkout.id,
            ap2={
                "checkout_mandate": checkout_mandate,
                "payment_mandate": payment_mandate
            }
        )
    return result

Business Side

# Pseudocode example
def handle_create_checkout(request):
    # 1. Create Checkout session
    checkout = create_checkout_session(request)

    # 2. Add merchant authorization if AP2 negotiated
    if "ap2_mandate" in negotiated_capabilities:
        checkout.ap2 = {
            "merchant_authorization": sign_checkout(checkout)
        }

    return checkout

def handle_complete_checkout(request):
    # 1. Verify AP2 Mandates
    if "ap2_mandate" in negotiated_capabilities:
        verify_merchant_authorization(request.checkout)
        verify_checkout_mandate(request.ap2.checkout_mandate)

    # 2. Process payment
    payment_result = process_payment(
        request.ap2.payment_mandate
    )

    return order_confirmation