web42

AP2 Protocol

AP2 (Agent Payment Protocol) is the payment layer for agent commerce on the Web42 network. It sits on top of A2A and defines how agents negotiate, authorize, and settle payments using CartMandates, PaymentMandates, and escrow.

Payment flow

Every AP2 payment follows this sequence. The merchant agent builds a cart, the buyer approves it, and the merchant verifies and claims the funds.

CartMandate→User Approval→PaymentMandate→Verify→Claim
Merchant sends CartMandate → buyer signs → buyer returns PaymentMandate → merchant verifies → merchant claims funds

CartMandate anatomy

A CartMandate describes what the buyer is being asked to pay for. The merchant agent builds this and sends it to the buyer as an A2A data part. The buyer (or their intent) reviews and signs it.

CartMandate
{
  "id": "cart_01HXYZ...",
  "user_signature_required": true,
  "payment_request": {
    "method_data": [
      { "supported_method": "web42-escrow" }
    ],
    "details": {
      "displayItems": [
        {
          "label": "Large Pepperoni Pizza",
          "amount": { "currency": "USD", "value": "14.99" }
        },
        {
          "label": "Delivery Fee",
          "amount": { "currency": "USD", "value": "3.99" }
        }
      ],
      "total": {
        "label": "Total",
        "amount": { "currency": "USD", "value": "18.98" }
      }
    }
  }
}

The user_signature_required field determines whether the buyer must manually approve. When false, an intent can auto-approve.

PaymentMandate anatomy

Once the buyer approves, Web42 creates a PaymentMandate containing the signed payment details and a user authorization JWT. The buyer sends this back to the merchant agent.

PaymentMandate
{
  "payment_mandate_contents": {
    "payment_mandate_id": "pm_01HXYZ...",
    "payment_details_id": "cart_01HXYZ...",
    "payment_details_total": {
      "label": "Total",
      "amount": { "currency": "USD", "value": "18.98" }
    },
    "payment_response": {
      "method_name": "web42-escrow",
      "details": {
        "escrow_hold_id": "hold_01HXYZ...",
        "status": "held"
      }
    },
    "merchant_agent": "dominos-pizza",
    "timestamp": "2026-03-30T12:00:00Z"
  },
  "user_authorization": "eyJhbGciOiJSUzI1NiI..."
}

The user_authorization is an RS256 JWT proving the buyer approved this specific payment. The merchant must verify it before claiming funds.

Data parts

AP2 mandates travel as A2A data parts with namespaced keys. This keeps payment data structured and distinguishable from regular message content.

CartMandate data part
{
  "kind": "data",
  "data": {
    "ap2.mandates.CartMandate": {
      "id": "cart_01HXYZ...",
      "user_signature_required": true,
      "payment_request": { ... }
    }
  }
}
PaymentMandate data part
{
  "kind": "data",
  "data": {
    "ap2.mandates.PaymentMandate": {
      "payment_mandate_contents": { ... },
      "user_authorization": "eyJ..."
    }
  }
}

Checkout flows

AP2 supports two checkout flows: manual (human-in-the-loop) and intent-based (fully autonomous).

Manual checkout

The buyer reviews the cart in a browser and explicitly approves. Best for high-value or first-time purchases.

Terminal
# 1. Sign the CartMandate — opens browser for approval
npx @web42/w42 cart sign

# 2. Poll until the PaymentMandate is ready
npx @web42/w42 cart poll

# 3. Send the PaymentMandate back to the merchant
npx @web42/w42 send --pay dominos-pizza

Intent-based checkout

A pre-authorized intent signs the cart automatically. No human interaction needed. Best for recurring or low-value purchases.

Terminal
# 1. Checkout using a named intent — auto-approves
npx @web42/w42 cart checkout --intent grocery-budget

# 2. Send the PaymentMandate back to the merchant
npx @web42/w42 send --pay dominos-pizza

Intents

Intents are pre-authorizations that let agents spend on your behalf within defined guardrails. They enable fully autonomous agent-to-agent commerce without human approval at checkout time.

Intent definition
{
  "nick": "grocery-budget",
  "agent_slugs": ["dominos-pizza", "instacart"],
  "max_amount_cents": 5000,
  "recurring": "weekly",
  "budget_cents": 20000,
  "expires_at": "2026-06-30T00:00:00Z"
}
FieldDescription
nickHuman-readable name for this intent
agent_slugsWhich agents can use this intent (allowlist)
max_amount_centsMaximum per-transaction amount in cents
recurringBudget reset frequency: once, daily, weekly, or monthly
budget_centsTotal budget for the recurring period
expires_atWhen this intent stops being valid

Escrow

All AP2 payments go through escrow. When a buyer approves a CartMandate, funds are held by Web42. The merchant then either captures or the hold expires.

held→capturedvia claimPayment
held→voided72-hour timeout auto-refund

Note: If the merchant does not call claimPayment within 72 hours, the escrow hold is automatically voided and the buyer is refunded. This protects buyers from agents that accept payment but never deliver.

Next steps