prava-pay

Prava Pay — 面向 AI Agent 的智能钱包

驱动 Prava CLI：将此 Agent 与用户的 Prava 账户关联一次，然后创建一次性代币化卡凭证，即可在任何商家完成购买。此流程中恰好只有一个必须由用户确认的关卡：支出前确认（第 3 步）——在运行 prava sessions create 之前确认商家 + 商品 + 总额。绝不能跳过；确认后绝不能再增加额外的暂停。

根据意图选择流程（先阅读）

用户想要……	操作
在已知商家购买已知商品／订单／账单（“买这个”“在 Y 处支付 $X”“完成结账”）	执行下方支付步骤 1–5
让 Prava 先查找商品（尚未选定具体商店）	转交给 prava-shopping 技能（搜索 → 商品 → 报价 → 结账）。如果未安装，不要在此处自行尝试查找——请告知用户运行：npx --yes skills add https://github.com/Prava-Payments/prava-skills --skill prava-shopping --global --yes --full-depth，并请他们重试
设置 Prava／关联卡片（尚未购买）	仅执行步骤 1（设置 + 关联），然后停止
预先授权稍后／重复购买——“下周买这个”“给你 $200 用于消费”“等它降到 $X 时帮你买”“在 <store> 设置月度预算”	设置授权规则（§ 设置授权规则）
任何“买／支付”意图——可能已有授权规则涵盖	创建新会话前，先执行 先检查授权规则（§ 购买流程步骤 0）
关于 Prava 的一方问题（产品、安全性、定价、支持的卡片／国家、通行密钥、授权规则、退款、KYC、URL）	阅读 about-prava，并据此作答——不要运行任何 CLI 命令
加密货币转账、x402 API、P2P 支付	不在支持范围内——请说明这一点

**回答 Prava 相关问题：**直接引用参考资料中的信息；绝不要自行编造定价／计费模式（如果资料写着“联系咨询定价”，这就是答案）；如果有多个 URL 可以回答问题，请全部列出；如果资料未涵盖，请回答“我们的公开文档中没有相关信息”，并提供 [email protected] / https://docs.prava.space。

前置条件：CLI

运行任何 prava 命令前：执行 which prava。如果找不到，不要假定它未安装——Agent shell 往往缺少 nvm/Homebrew 路径。请先搜索：

find ~/.nvm/versions/node ~/.npm-global /opt/homebrew /usr/local -path '*/bin/prava' -type f 2>/dev/null

找到后 → 使用绝对路径，或将其 bin 目录添加到 PATH 前面。找不到 → 由用户安装，而不是你安装（绝不要使用 sudo，也绝不要在安装失败后以提升权限重试）：

未安装 Prava CLI。请在终端中运行 npm install -g @prava-sdk/cli，然后告诉我安装完成。

CLI 会在每次 API 调用时自动检查版本——不要单独运行版本检查命令。它会自行推断技能和版本；无需设置环境变量前缀。有关如何处理更新提示，请参阅下方的版本提示。

支付步骤

1. 验证链接状态

运行 prava status。按以下决策树判断（匹配第一项即停止）：

• “Skill update required (minimum: X.Y.Z)” — 真正的阻止条件（CLI 已验证）：运行 npx skills update prava-pay -g，然后重新运行 prava status。如果再次打印出相同警告，说明磁盘上的技能已更新，但本次会话加载的仍是旧版本——告知用户重启当前使用的 Agent 会话，并指出你实际运行的宿主（例如，如果你使用的是 Claude Code，就说“重启 Claude Code”，而不是 prava CLI，也不是机器），然后停止。（如果提示的是“Could not verify skill version”，则无妨——继续操作；在非标准宿主上，也可以设置 PRAVA_SKILL_VERSION=<this skill's version>。）
• “Link expired. Run prava setup again.” — 用一句话确认（“之前的链接已过期。我将生成一个新链接——确认吗？”），然后运行 prava setup --name "<name>" --platform <platform>，并立即运行 prava setup poll。
• “active” — 进入步骤 2。
• “pending” — CLI 会重新打印 Link: <URL>：将链接展示给用户，然后立即运行 prava setup poll。如果 Link: 行没有 URL → 旧链接无法恢复：先确认一次，然后重新运行 prava setup。（较旧的 CLI：参阅 cli-setup → Troubleshooting。）
• “No agent configured” — 引导用户完成设置：根据 platforms 检测平台和默认名称（绝不要询问平台；除非用户已提供名称，否则只需确认一次），运行 prava setup --name "<name>" --platform <platform>，展示 URL，然后立即运行 prava setup poll——不要等用户说“好了”。详情：cli-setup。

一直卡在“pending”？ 先排查问题，再操作设置：(a) 确认用户打开的是最近一次运行 prava setup 后生成的确切 URL（不是更早生成的）；(b) 检查网络连接——服务器无法访问时，prava status 会回退到本地状态，这可能会掩盖实际的批准状态；(c) 排查问题时，未经用户确认，绝不要重新运行 prava setup——这会轮换密钥对，并使用户可能仍准备批准的任何链接失效（仅以下情况例外：CLI 打印出 Link expired，或用户确认要生成新链接）。对于从不打印 Link expired 的较旧 CLI，长期解决方案是升级：npm update -g @prava-sdk/cli。如果有待处理的购买，请记住，prava sessions create 内置了自动链接检查，可能会直接检测到批准状态。完整的旧版说明：cli-setup → Troubleshooting。

如果用户最初的意图是购买商品，完成链接后立即进入步骤 2。

2. 收集购买信息——不要猜测

在铸造之前，必须具备以下所有信息（通过常规的信息收集流程获取；绝不可捏造）：

• 商家名称和完整 URL，且必须包含 https:// 协议（https://www.bestbuy.com，而不是 bestbuy.com）
• 已最终确定的商品，且每件商品都有实际发现的价格和明确的描述
• 总金额（字符串格式，例如“8.50”）；货币使用 ISO 4217 代码（USD，而不是“美元”）；商家所在国家使用 ISO 3166-1 alpha-2 代码（US，而不是“USA”）

Buy flow — step 0: 先检查是否有授权

继续执行下面的确认和生成步骤之前，运行 prava mandate list --json，查找已涵盖此次购买的授权：优先查找适用于该商家的商家专属授权，否则查找通用（any 范围）授权；授权的 remaining 额度必须充足，且尚未过期。

• 用户在场 → 主动询问：「你有一项 Nike 授权，还剩 $120——要用它支付 $40 吗？无需新的审批。」用户同意后 → 执行 prava mandate charge --mandate-id <id from --json> --amount 40.00 -y，然后使用返回的 token/cryptogram 完成结账（步骤 5），接着执行 prava mandate report --mandate-id <id> --txn-id <txn> --status APPROVED。这项主动询问并确认的流程取代下面的步骤 3–4——不要为同一次购买再生成新的会话。
• 用户不在场（用户预先给出的常设指令，例如「降到 $90 时就买」）→ 在限额内直接扣款，无需再次提示——设置授权时使用的通行密钥就是用户同意的凭据——然后通知用户：「已使用你的 Nike 授权，以 $90 买下 Nike 鞋。」
• 没有匹配的授权 → 继续执行下面的步骤 3（常规的确认和生成流程）。也可以主动询问是否设置授权（§ 设置授权）。

切勿向用户展示原始的 mdt_/txn ID——用商家名称、剩余额度和到期时间来指代授权（ID 只通过 --json 在命令之间传递）。将 remaining 视为参考值，而非权威数据——服务器会执行实际限额；mandate charge 返回 Visa 拒付（status:"failed"，例如 THRESHOLD_EXCEEDED）属于正常结果，应如实告知用户，而不是当作错误。

3. 向用户确认 — 必须硬性中止，直至确认

说明商家、购买内容以及总价和币种；必须获得明确的**「同意」**：

「我将向 Blue Bottle Coffee 支付 $8.50 USD，购买 1 份拿铁和 1 个羊角面包——确认吗？」

此确认环节发生在对话中，用户确实正在阅读的地方——浏览器中的通行密钥审批是第二道检查，而非替代。这样能在错误的商家或输错的金额被写入会话、而用户可能不假思索地批准之前，及时发现问题。「买 X」表达的是意图，并不代表用户已批准特定商家和总价——即使如此，也不得跳过这一步。

4. 生成会话并轮询

prava sessions create \
  --total-amount "8.50" --currency USD \
  --merchant-name "Blue Bottle Coffee" \
  --merchant-url "https://bluebottlecoffee.com" \
  --merchant-country US \
  --product '{"description":"Latte","unit_price":"5.00","quantity":1}' \
  --product '{"description":"Croissant","unit_price":"3.50","quantity":1}'

商品 JSON 格式为 {"description","unit_price","quantity"}——对于多件商品，使用 quantity（切勿为同一商品重复使用 --product，也不要写成「2x Latte」）；--total-amount 必须等于 Σ unit_price × quantity。该命令会输出支付 URL 和会话 ID，并且立即退出：将 URL 展示给用户，然后立即执行（不要等待回复）：

prava sessions poll --session-id <session_id>

用户在浏览器中批准时，命令会持续轮询，最长 10 分钟；随后返回Token（16 位 Visa 网络令牌 → 卡号字段）、Cryptogram（一次性动态 CVV → CVV 字段）和Expiry。详情请参阅：cli-sessions。

5. 完成结账

立即通过浏览器自动化，在商家的网站上使用这些凭据。凭据仅可使用一次，并会在约 30 分钟后过期——从生成到轮询再到结账，应迅速完成，不要停顿（确认已在步骤 3、凭据生成之前完成）。此处不要再次确认。

涉及多家商家的请求（「从 Amazon 买一本书，并从 Namecheap 买一个域名」）：一次处理一家商家——先完整完成 A 的创建 → 轮询 → 结账流程，再开始 B。每个会话仅对应一家商家；切勿并行执行 sessions create，在完成任何结账前轮询多个会话，或批量结账。

设置授权额度（现在授权，稍后购买）

授权额度允许用户通过通行密钥一次批准一张卡，之后你就可以在额度限制内扣款，无需再次征求批准。有两种类型：

• 指定商户（“在 Nike 消费 $120”）→ 使用 --scope listed 和商户标志。
• 通用预算（“在任何地方消费 $200”）→ 使用 --scope any（仅限 one_time——核心会强制要求定期授权额度锁定到商户）。

1. 验证关联状态——与 Payment 步骤 1 相同（prava status）。
2. 收集信息——商户（或“任意商户”）、额度金额和货币、期限。清楚说明限制：
   • one_time / 通用（any 范围）授权额度有效期最长为 7 天——即使传入更长的 --valid-until，服务端也会强制执行此限制。
   • 对于长期安排，请使用定期授权额度（--frequency weekly|monthly|yearly）——核心会强制将其设为 --scope listed（锁定到单个商户），且每个周期只允许扣款一次。
3. 必须设置硬性确认步骤——确认商户、额度和实际期限；将其表述为授权，而不是空白支票：

   “我将设置一笔授权额度，允许在 Nike 消费最多 $120，有效期为 7 天——你通过通行密钥批准一次，之后我就可以从 Nike 购买商品，无需每次都征求你的同意。确认吗？”

4. 创建：

   prava mandate create --merchant-name "Nike" --merchant-url "https://nike.com" --merchant-country US \
     --amount 120.00 --currency USD --frequency one_time --scope listed -y
   

   通用预算：省略三个 --merchant-* 标志，改为传入 --scope any。命令会输出一个批准 URL——将其显示给用户：“请使用通行密钥批准。”
5. 确认已生效：

   prava mandate poll --scope listed --merchant "Nike" --amount 120.00 --currency USD
   

   使用传给 mandate create 的准确商户名称；不接受 URL。通用预算：prava mandate poll --scope any --amount 200.00 --currency USD。只有状态、范围、商户、额度和货币都与一笔可用的有效授权额度完全匹配时，轮询才会通过，否则将失败关闭。按描述报告，切勿报告 ID：“✓ 你的 Nike 授权额度已生效——$120，周日到期。”

版本提示（在命令输出中）

• CLI 更新——npm update -g @prava-sdk/cli；“Critical update required” = 必须先更新才能继续。
• Skill 更新——仅当 CLI 确认版本低于最低要求后才会显示：npx skills update prava-pay -g，然后重试；更新后再次显示 → 用户必须重新启动 Agent 会话（宿主应用，而非 CLI/机器）。
• 两种更新都不会重新关联 Agent——除非确实需要设置，否则更新后不要运行 prava setup。

自动行为与输出约定

• **自动检查关联状态：**在待处理期间运行 sessions create 会自动检测到新批准状态——设置与创建之间无需运行 prava status。
• stdout = 人类可读；stderr = 纯文本错误。退出码 0 表示成功（包括已关联时 setup 无操作）；1 表示错误；2 表示 Agent 未配置/未获批准。

快速参考

prava setup --name "<name>" --platform <platform> [--description "<desc>"]   # prints URL, exits immediately
prava setup poll                       # waits for link approval
prava status                           # link state (also detects approval)
prava sessions create --total-amount <amt> --currency <CUR> --merchant-name "<n>" --merchant-url "<url>" --merchant-country <XX> --product '<json>' [--product ...]
prava sessions poll --session-id <id>  # waits for tokenized credentials
prava mandate create --amount <amt> --currency <CUR> [--merchant-name "<n>" --merchant-url "<url>" --merchant-country <XX>] [--frequency one_time|weekly|monthly|yearly] [--scope listed|any] -y   # prints approval URL
prava mandate poll --scope listed|any [--merchant "<exact name>"] --amount <amt> --currency <CUR>   # merchant required for listed, omitted for any
prava mandate list [--merchant <url>] --json                     # resolve id + remaining/expiry internally — never shown raw to the user
prava mandate charge --mandate-id <id> --amount <amt> [--reference <ref>] -y   # no passkey; returns token+cryptogram
prava mandate report --mandate-id <id> --txn-id <id> --status APPROVED|DECLINED
prava mandate cancel --mandate-id <id> -y                        # revokes; stops future charges

反模式

• 在第 3 步确认商户和总额之前创建会话。这是绝不能跳过的首要步骤。
• 如果已有匹配的授权额度涵盖此次购买，却仍创建新的 sessions create——先检查 § 购买流程步骤 0。
• 向用户展示原始授权额度或交易 ID——应按商户 + 剩余额度 + 到期时间来指代授权额度，并通过 mandate list --json 在内部解析。
• 承诺 one_time/通用授权额度有效期超过 7 天，或声称定期授权额度涵盖多个商户。
• 在 Agent 关联前，或购买信息收集完成前，运行 sessions create。
• 猜测或编造金额、货币或购买背景。
• 向用户索要密钥、卡号或凭据——CLI 会在本地处理所有身份验证。
• 收到凭据后暂停，未完成结账。
• 自行安装 CLI，或使用 sudo——应由用户安装。
• 已关联时仍运行 setup（虽不会造成问题，但没有必要）。
• 在此技能中进行商品探索——那属于 prava-shopping。

---

由 Prava Payments 构建——面向 AI Agent 的支付技术栈。