AP2: Agent Payments Protocol

Overview

AP2 (Agent Payments Protocol) is Google’s standard for authorizing agent-initiated payments. It uses cryptographic mandates to prove that a user has explicitly authorized a specific spending action.

AP2 sits in the Authorization Layer of our three-layer protocol architecture, answering the question: “Did the user approve this spend?”

Key Concepts

Mandates

Mandates are cryptographically signed authorization tokens. There are three types:

Type	Purpose	Use Case
Intent Mandate	Pre-authorization for product search	”Find me a laptop under $1500”
Cart Mandate	Authorization for specific items	”I approve these 3 items totaling $1,200”
Payment Mandate	Final authorization for payment	”Process payment of $1,200 to merchant X”

Mandate Flow

1. User creates intent — Sets budget, category, preferences
2. Agent searches — Finds matching products within mandate constraints
3. Cart approval — User reviews and approves selected items
4. Payment execution — Cryptographically signed payment authorization

Implementation

Create an Intent Mandate

const mandate = await soft.ap2.intents.create({
  user_id: 'user_123',
  max_amount: 1500,
  currency: 'USD',
  category: 'electronics',
  constraints: {
    merchants: ['merchant_a', 'merchant_b'],
    expires_in: 3600,  // 1 hour
  },
});

Verify Mandate Signature

All mandates include ECDSA signatures that must be verified:

const isValid = await soft.ap2.mandates.verify({
  mandate_id: mandate.id,
  signature: mandate.signature,
  public_key: mandate.issuer_public_key,
});

if (!isValid) {
  throw new Error('Invalid mandate signature');
}

Create a Cart Mandate

const cart = await soft.ap2.carts.create({
  intent_mandate_id: mandate.id,
  items: [
    { product_id: 'prod_456', quantity: 1, price: 1199.99 },
  ],
  total: 1199.99,
});

Process Payment

const payment = await soft.ap2.payments.create({
  cart_mandate_id: cart.id,
  payment_method: 'google_pay',
  idempotency_key: 'unique_key_123',
});

Security

AP2 implements multiple security layers:

• ECDSA Signature Verification — Every mandate is cryptographically signed
• Nonce Validation — Prevents replay attacks (5-minute TTL via KV)
• Amount Constraints — Mandates enforce maximum spend limits
• Merchant Restrictions — Mandates can limit which merchants receive payment
• Expiration — All mandates have configurable TTLs

API Endpoints

Method	Path	Description
POST	/ap2/intents	Create intent mandate
GET	/ap2/intents/:id	Get intent mandate
PUT	/ap2/intents/:id	Update intent mandate
POST	/ap2/carts	Create cart mandate
POST	/ap2/payments	Process payment mandate
GET	/ap2/mandates	List all mandates
GET	/ap2/mandates/:id	Get mandate details
DELETE	/ap2/mandates/:id	Revoke mandate

Google Pay Integration

AP2 integrates with Google Pay for seamless checkout:

const paymentData = await soft.ap2.googlePay.createPaymentData({
  mandate_id: cart.id,
  merchant_id: 'BCR2DN5TTDH57OS2',
  merchant_name: 'soft.house',
});

Google Pay is currently in TEST mode. Contact us for production activation.