AP2 技术文档
核心概念

核心概念

AP2 用一组紧凑且可组合的对象，构建起安全、可观测的智能体支付系统。掌握这些对象及其生命周期，是在业务中集成 AP2 的第一步。

智能体身份与凭证

每个参与方都会拥有一个 Agent Identity：

{
  "did": "did:ap2:buyer-bot-9f32",
  "publicKeys": [
    {
      "kid": "sig-2025-09",
      "type": "ed25519",
      "publicKeyMultibase": "z6Mko..."
    }
  ],
  "policies": {
    "maxSinglePayment": "1000 USDC",
    "jurisdictions": ["US", "CA"],
    "requiresHumanApprovalAbove": "5000 USDC"
  },
  "metadata": {
    "organization": "Acme Retail",
    "riskTier": "medium",
    "contact": "[email protected]"
  }
}

身份由 AP2 控制平面签发，并与策略 Token（JWT）绑定，用于访问特定结算轨道。凭证既可以是 委托模式（需要人类审批），也可以是 自主管理模式（智能体持有私钥）。

支付意图

AP2 的核心对象是 PaymentIntent，它囊括了资金划转前所有必要信息：

{
  "id": "ap2_pi_7f0cf3",
  "createdAt": "2025-09-17T12:04:11Z",
  "amount": { "value": "749.00", "currency": "USDC" },
  "participants": {
    "buyer": "did:ap2:buyer-bot-9f32",
    "seller": "did:ap2:vendor-bot-2aa8"
  },
  "terms": {
    "settlementRail": "x402",
    "captureType": "escrow_release",
    "releaseCondition": "delivery-confirmation",
    "disputeWindow": "P5D"
  },
  "lineItems": [
    {
      "sku": "LOWES-ICEBOX-01",
      "quantity": 1,
      "unitPrice": "749.00",
      "metadata": { "warranty": "24m" }
    }
  ],
  "evidence": [
    { "type": "quote", "cid": "bafybeidemo..." }
  ],
  "status": "pending",
  "policyTrace": []
}

意图生命周期

  1. draft —— 买家构建意图并共享给卖家。
  2. pending —— 卖家确认条款后提交策略校验。
  3. authorized —— 控制平面批准，资金被预授权或托管。
  4. captured —— 结算轨道完成划转。
  5. settled —— 双方收到签名凭证。
  6. voided / refunded —— 策略或争议触发的异常流。

每个状态都会触发事件，可通过 Webhook 或 A2A 流实时订阅。

策略评估图谱

支付前，意图需通过配置化的策略图谱：

  • 身份审查：制裁名单、司法辖区、KYC 状态。
  • 交易风控：交易额度、频率、历史争议率。
  • 业务规则：SKU 限制、渠道定价、会员权益。

策略失败时，系统会返回结构化错误码（如 POLICY_THRESHOLD_EXCEEDED、JURISDICTION_BLOCKED）。智能体可在修复后重新提交。

结算凭证

结算完成后，AP2 会出具 SettlementProof：

{
  "id": "ap2_sp_9a10b1",
  "intentId": "ap2_pi_7f0cf3",
  "rail": "x402",
  "timestamp": "2025-09-17T12:04:57Z",
  "ledgerEntries": [
    { "account": "buyer-escrow", "delta": "-749.00" },
    { "account": "seller-operating", "delta": "+749.00" }
  ],
  "signatures": [
    {
      "signer": "did:ap2:rail:x402",
      "kid": "rail-key-12",
      "signature": "eyJhbGciOiJFZERTQSIsInR5cCI6IkpXVCJ9..."
    }
  ],
  "hash": "bafybeiaudittrail...",
  "compliance": {
    "travelRule": "fulfilled",
    "sanctions": "cleared"
  }
}

凭证具备防篡改能力，并关联对应的策略决策，可用于财务对账、监管审计或争议处理。

争议与退款

AP2 将争议建模为独立状态机：

  • dispute.opened —— 任一方提出异议。
  • dispute.escalated —— 控制平面交由人工或第三方处理。
  • dispute.resolved —— 产生部分/全额退款、释放托管或裁决结果。

退款通过原结算轨道执行，并生成新的凭证与原意图关联。建议订阅争议事件，以便智能体自动暂停履约或补充证据。

可观测性

沙盒默认提供：

  • 事件流（/events）用于实时监控。
  • 指标接口 输出意图数量、失败率、托管余额等。
  • 审计日志 API 用于查询签名的策略判定记录。

在生产环境中，可将这些数据接入风控看板、SIEM 或自动对账管线。

总结

概念用途关键字段
Agent Identity标识付款方与收款方DID、密钥、策略声明
Payment Intent描述付款内容与条件金额、参与方、条款、证据
Policy Trace记录系统允许/拒绝的原因规则 ID、结果、说明
Settlement Proof证明资金已结算账务条目、签名、合规状态
Dispute Case管理结算后的纠纷原因码、凭证、退款意图

掌握这些对象，后续阅读 API、SDK 及结算集成文档将更加顺畅。

快速上手支付轨道