DEV Community

vishalmysore
vishalmysore

Posted on

What is Google AP2 Protocol : Step by Step Guide with Examples

#google #tutorial #ai #security

What is the Google AP2 Protocol?

The Agent Payments Protocol (AP2) is an open, non-proprietary protocol developed by Google in collaboration with several other organizations in financial services and tech industries. Its purpose is to establish a secure and auditable framework for payments initiated by AI agents. AP2 extends existing protocols like Agent2Agent (A2A) and Model Context Protocol (MCP) to specifically handle payment flows, ensuring transactions are authorized, authentic, and accountable

The rise of AI agents capable of transacting on behalf of users creates new challenges for secure, authenticated, and accountable payments. Traditional payment systems assume a human is directly clicking “buy” on a trusted surface, but autonomous agents break this assumption. The Agentic Payment Protocol (AP2) is an open, shared protocol that provides a common language for secure, compliant transactions between agents and merchants, preventing ecosystem fragmentation.

Code for this article is here

AP2 addresses three critical questions:

  • Authorization: Proving that a user gave an agent specific authority to make a particular purchase.
  • Authenticity: Enabling merchants to verify that an agent’s request accurately reflects the user’s true intent.
  • Accountability: Determining responsibility if a fraudulent or incorrect transaction occurs.

AP2 supports a wide range of payment types—from cards to stablecoins and real-time bank transfers—ensuring a consistent, secure, and scalable experience for users, merchants, and financial institutions.

How AP2 Works: Mandates and Verifiable Credentials

AP2 builds trust using Mandates—tamper-proof, cryptographically-signed digital contracts that serve as verifiable proof of a user’s instructions. Mandates are signed by verifiable credentials (VCs) and act as foundational evidence for every transaction.

Mandates support two primary shopping scenarios:

  • Real-time purchases (human present):
    The user asks an agent to find a product (e.g., “Find me new white running shoes”). The request is captured in an initial Intent Mandate, providing auditable context. After the agent presents a cart, the user’s approval signs a Cart Mandate, creating a secure, unchangeable record of the items and price.

  • Delegated tasks (human not present):
    The user delegates a task (e.g., “Buy concert tickets the moment they go on sale”) by signing a detailed Intent Mandate upfront, specifying rules like price limits and timing. The agent can automatically generate a Cart Mandate once conditions are met.

In both cases, the chain of evidence links the payment method to the verified contents of the Cart Mandate, creating a non-repudiable audit trail for authorization, authenticity, and accountability.

Java Implementation: Alignment with AP2 Protocol and Python Samples

My Java implementation closely follows the AP2 protocol and the reference Python samples:

  • Mandate System: Implements IntentMandate, CartMandate, and PaymentMandate as verifiable credentials, each with constraints, references, and cryptographic proofs.
  • Agent Roles: Defines agent classes for Shopping Agent, Merchant Agent, and Payment Processor, mirroring the modular structure of the Python samples.
  • Payment Lifecycle: Supports creation, authorization, capture, refund, and status queries using interfaces and domain classes similar to those in Python.
  • Security and Audit: Enforces signature verification, mandate chaining, and audit logging for accountability and security.
  • Agent Communication: Uses JSON-RPC and a2ajava for agent-to-agent messaging, just as the Python samples use HTTP and A2A message formats.

This alignment ensures that implementation is interoperable, secure, and true to the AP2 protocol’s design.

Typical Use Case: Agentic Commerce Flow

  1. User Authorization (Intent Mandate):

    • The user instructs an agent (e.g., “Buy running shoes under $100”).
    • The agent creates an Intent Mandate capturing the user’s intent and constraints.

  2. Cart Building & Approval (Cart Mandate):

    • The agent finds products and builds a cart.
    • The user reviews and approves the cart, resulting in a Cart Mandate.

  3. Payment Execution (Payment Mandate):

    • The agent initiates payment using the approved cart.
    • A Payment Mandate is created and sent to the payment processor.

  4. Payment Lifecycle:

    • The payment processor handles creation, authorization, capture, refund, and status queries.

  5. Mandate Verification & Audit:

    • All mandates are verified for signature and references, with audit logs for traceability.

  6. Agent-to-Agent Communication:

    • Mandates and messages are exchanged between agents, merchants, and processors using secure protocols.

This flow demonstrates how AP2 enables secure, user-controlled, and auditable agentic commerce, with your Java implementation faithfully reflecting the protocol’s architecture and intent.

Java Code Samples: Mandate Flow and Payment Lifecycle

Below are sample code snippets from the Java implementation, demonstrating how AP2 mandates and payment flows are handled. These examples are directly inspired by the official AP2 sample implementations and closely follow their structure and logic.

1. Intent Mandate

When a user instructs an agent (e.g., "Buy running shoes under $100"), the agent creates an Intent Mandate:

IntentMandate mandate = new IntentMandate(
   "intent-123",                 // Unique ID
   "user-agent-456",             // Requesting agent
   "merchant-789",               // Receiving agent/merchant
   new BigDecimal("100.00"),     // Maximum allowed amount
   true                          // Requires human approval
);
mandate.setAllowedCategories(Collections.singletonList("shoes"));
Enter fullscreen mode Exit fullscreen mode

2. Cart Mandate

After finding options, the agent builds a cart and seeks user approval. The Cart Mandate references the original Intent Mandate and contains specific items and prices:

List<CartMandate.CartItem> items = new ArrayList<>();
items.add(new CartMandate.CartItem(
   "item-123",                   // Item ID
   "Nike Air Zoom Pegasus",      // Description
   new BigDecimal("95.00"),      // Price
   1                             // Quantity
));

CartMandate cartMandate = new CartMandate(
   "cart-456",                   // Unique ID
   "user-agent-456",             // Requesting agent
   "merchant-789",               // Receiving agent/merchant
   "intent-123",                 // Parent Intent Mandate ID
   items,                        // List of items
   "USD",                        // Currency
   Instant.now().plusMinutes(30) // Expiration
);
Enter fullscreen mode Exit fullscreen mode

3. Payment Mandate

With the cart approved, the agent executes payment. The Payment Mandate references the Cart Mandate and includes payment details:

Map<String, Object> paymentDetails = new HashMap<>();
paymentDetails.put("paymentMethodId", "card-123");

PaymentMandate paymentMandate = new PaymentMandate(
   "payment-789",                // Unique ID
   "user-agent-456",             // Requesting agent
   "merchant-789",               // Receiving agent/merchant
   "order-321",                  // Payment reference
   new BigDecimal("95.00"),      // Amount
   "USD",                        // Currency
   "cart-456",                   // Parent Cart Mandate ID
   paymentDetails,                // Payment details
   Instant.now().plusMinutes(15)  // Expiration
);
Enter fullscreen mode Exit fullscreen mode

4. Mandate Verification

Mandates are verified for signature, expiration, and correct references:

boolean isValid = mandateVerifier.verifyIntentMandate(intentMandate, paymentRequest);
if (isValid) {
   isValid = mandateVerifier.verifyCartMandate(cartMandate, intentMandate, paymentRequest);
   // ...
}
Enter fullscreen mode Exit fullscreen mode

5. Payment Processing Flow

The payment processor handles creation, authorization, capture, refund, and status queries:

PaymentProcessor paymentProcessor = new SamplePaymentProcessor();
AP2Client ap2Client = new AP2Client(paymentProcessor, agentCard);

PaymentRequest paymentRequest = PaymentRequest.builder()
      .amount(new BigDecimal("50.00"))
      .currencyCode("USD")
      .requestingAgentId("agent-123")
      .receivingAgentId("merchant-456")
      .description("Service payment")
      .build();

PaymentResponse response = ap2Client.createPayment(paymentRequest).get();
Enter fullscreen mode Exit fullscreen mode

Alignment with Official AP2 Sample Implementations

The above Java samples directly mirror the official AP2 sample implementations (Python and Android):

  • Mandate Chain: The use of Intent, Cart, and Payment Mandates as verifiable credentials is identical to the reference samples.
  • Agent Roles: The modular agent structure (Shopping Agent, Merchant Agent, Payment Processor) matches the official design.
  • Payment Flow: The lifecycle (create, authorize, capture, refund, status) and mandate verification logic are implemented as described in the AP2 specification and samples.
  • Security: Signature verification, expiration, and audit logging are enforced, just as in the official samples.
  • Communication: The use of JSON-RPC and agent-to-agent messaging aligns with the protocol’s recommended transport and message formats.

Top comments (0)