Ap2 payment mandate

AP2 Payment Mandate

中文摘要：生成并校验 AP2 三类 mandate(Intent/Cart/Payment,包成 Ed25519 签名的可验证数字 凭证 VDC),并把支付通过 payment.instruments / payment_handlers 挂到 UCP checkout session。 需要给商家"用户已授权 agent 发起这笔扣款"的密码学证明(尤其在 complete 步骤)时用。

When to use / 何时使用

• A UCP checkout session is ready_for_complete and you're about to POST …/complete.
• The merchant / PSP needs provable consent for an agent-initiated charge.
• You must bind authorization to an exact amount so it can't be replayed at a new price.

Two layers / 两层

1. AP2 mandates — the cryptographic consent layer (separate protocol UCP composes with).
2. UCP payment object — how the chosen instrument rides on the checkout session.

AP2 mandates (VDC, Ed25519 over canonical JSON; verify via signer_did)

Mandate	Real key fields	Created
IntentMandate	agent_did, max_amount, purpose, expires_at, allowed_merchants, allowed_categories (+ "prompt playback" NLP summary, TTL)	Before a cart exists; enables human-not-present delegated buys within limits
CartMandate	parent_id, merchant_did, line_items, total_amount, payment_method	When the cart/total is final; user-present authorization (device-signed)
PaymentMandate	hashed Cart/Intent ref, method, amount, presence signal (human-present / not-present), agent_id	At complete, just before charging; shared with network/issuer to build trust

All three are wrapped in a Verifiable Digital Credential (VDC): an Ed25519 signature over a canonical JSON serialization; verify by resolving signer_did → public key.

UCP payment object (on the checkout session)

"payment": {
  "instruments": [
    {
      "id": "pi_1",
      "handler_id": "google_pay",          // matches a key in ucp.payment_handlers (from profile)
      "type": "card",
      "selected": true,
      "display": { "brand": "visa", "last4": "4242" },
      "credential": { "type": "network_token", "token": "***" },
      "billing_address": { "address_country": "DE", "postal_code": "10115" }
    }
  ]
}

The merchant declares accepted handlers in ucp.payment_handlers (UCP profile); the AP2 PaymentMandate travels alongside to prove consent. UCP calls this Payment Token Exchange.

Workflow / 工作流

1. (Optional) IntentMandate for delegated flows: capture max_amount, allowed_merchants, allowed_categories, expires_at up front so the agent may buy within bounds.
2. CartMandate when the session total is authoritative: bind line_items + total_amount
   • merchant_did, parent_id → user signs (device/passkey). Don't fabricate consent.
3. PaymentMandate: bind hashed Cart/Intent + method + amount (== session total) + presence signal + agent_id; sign as a VDC.
4. Attach the chosen instrument to the session payment.instruments (handler_id must match a declared payment_handler).
5. POST /checkout-sessions/{id}/complete with payment + signals + Idempotency-Key. The merchant/PSP verifies the VDC signature and that amount == session total.
6. Verifier side: resolve signer_did, verify Ed25519 over canonical bytes, check amount match, merchant match, non-expiry, single-use.

Edge cases & failure modes / 边界与失败

• Amount mismatch (total changed after consent) → mandate invalid; re-confirm + re-issue. Never reuse a mandate at a new price. 改价必须重签。
• Expired (expires_at / TTL) → regenerate.
• Delegated buy exceeds max_amount / outside allowed_merchants → stop; require fresh consent.
• Replay → single-use + expires_at + Ed25519 signature + UCP Idempotency-Key defeat it.
• No device consent available → fall back to interactive payment; never proceed without real consent.
• handler_id not in payment_handlers → merchant can't process it; pick a declared handler.

Worked example / 示例

Session cs_01H… is ready_for_complete, total 28322 EUR, Google Pay.

1. CartMandate binds line_items + total_amount:28322 + merchant_did, user signs on device.
2. PaymentMandate: hashed CartMandate + method:card + amount:28322 + presence:human-present
   • agent_id, wrapped as Ed25519 VDC.
3. Attach payment.instruments[0] handler_id:"google_pay", credential.token:***.
4. POST …/complete → PSP verifies VDC + amount==28322 → charge authorized → order returned.

References / 参考

• AP2 spec & core concepts: https://ap2-protocol.org/specification/ · https://ap2-protocol.org/topics/core-concepts/
• AP2 × A2A extension: https://ap2-protocol.org/a2a-extension/
• UCP provable payments: https://developers.googleblog.com/under-the-hood-universal-commerce-protocol-ucp/
• Used by: ucp-checkout-session