prava-pay

Prava Pay — AI エージェント向けスマートウォレット

Prava CLI を操作します。このエージェントをユーザーの 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 を実行してください。見つからない場合も、インストールされていないと決めつけてはいけません。エージェントのシェルでは nvm／Homebrew のパスが通っていないことがよくあります。まず検索してください。

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

見つかった場合は、絶対パスを使うか、その bin ディレクトリを PATH の先頭に追加します。見つからない場合は、CLI をインストールするのはユーザーであり、あなたではありません（sudo は絶対に使わず、失敗したインストールを権限昇格して再試行しないでください）。

Prava CLI がインストールされていません。ターミナルで npm install -g @prava-sdk/cli を実行し、完了したら知らせてください。

CLI は API 呼び出しのたびにバージョンを自動確認します。別途バージョン確認コマンドを実行しないでください。CLI 自身がスキルとバージョンを判別するため、環境変数のプレフィックスは不要です。更新通知への対応については、以下のバージョン通知をご覧ください。

支払い手順

1. リンクの状態を確認する

prava status を実行します。決定木（最初に一致したものを適用）：

• 「Skill update required (minimum: X.Y.Z)」 — 実際にブロックされています（CLI で確認済みです）：npx skills update prava-pay -g を実行し、prava status を再実行します。同じ警告が再び表示された場合、ディスク上のスキルは新しいものの、このセッションでは古いスキルが読み込まれています。ユーザーに、実行中のホスト名を明示してエージェントのセッションを再起動するよう伝えます（たとえば、Claude Code を使用している場合は「Claude Code を再起動してください」と伝えます。prava CLI やマシンではありません）。その後、停止します。（「Could not verify skill version」の場合は問題ありません。続行するか、標準ではないホストでは PRAVA_SKILL_VERSION=<this skill's version> を設定してください。）
• 「Link expired. Run prava setup again.」 — 1文で確認します（「以前のリンクは期限切れです。新しいリンクを生成します。よろしいですか？」）。その後、prava setup --name "<name>" --platform <platform> を実行し、ただちに prava setup poll を実行します。
• 「active」 — 手順 2 に進みます。
• 「pending」 — CLI が Link: <URL> を再表示します。ユーザーに表示し、ただちに prava setup poll を実行します。Link: の行に URL がない場合、古いリンクは復元できません。1度だけ確認してから、新たに prava setup を実行します。（古い CLI の場合は、cli-setup → Troubleshooting を参照してください。）
• 「No agent configured」 — 初期設定を行います。platforms からプラットフォームとデフォルト名を検出し（プラットフォームを尋ねてはいけません。ユーザーがすでに名前を伝えている場合を除き、名前を1度だけ確認します）、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. 購入のコンテキストを収集する — 推測しない

ミントを行う前に、以下のすべてを必ず確認します（通常の情報収集フローを通じて取得し、決して捏造しないでください）。

• 販売店名と https:// スキームを含む完全な URL（bestbuy.com ではなく https://www.bestbuy.com）
• 実際に確認した価格と明確な説明をそれぞれ備えた、購入対象の商品
• 文字列としての合計金額（「8.50」）、ISO 4217 の通貨コード（「dollars」ではなく USD）、ISO 3166-1 alpha-2 の販売店所在国コード（「USA」ではなく US）

購入フロー — ステップ 0：まず委任設定を確認する

以下の確認・発行ステップに進む前に、prava mandate list --json を実行し、今回の購入をすでにカバーする委任設定があるか確認します。まずこの加盟店専用のものを探し、なければ汎用（any スコープ）のものを探します。remaining が購入額以上で、有効期限内である必要があります。

• ユーザーがその場にいる場合 → 提案します：「Nike の委任設定には $120 残っています。今回の $40 の支払いに使いますか？ 新たな承認は不要です。」承諾されたら → prava mandate charge --mandate-id <id from --json> --amount 40.00 -y を実行し、返されたトークン／クリプトグラムを使ってチェックアウトします（ステップ 5）。その後、prava mandate report --mandate-id <id> --txn-id <txn> --status APPROVED を実行します。この提案と確認のフローは、以下のステップ 3～4を置き換えます。同じ購入について新たにセッションを発行しないでください。
• ユーザーがその場にいない場合（「価格が $90 になったら購入して」のように、あらかじめ継続的な指示が与えられている場合）→ 新たなプロンプトを求めず、上限の範囲内で請求します。委任設定の作成時にパスキーで承認済みです。その後、「Nike の委任設定を使って、Nikes を $90 で購入しました。」と通知します。
• 該当する委任設定がない場合 → 以下のステップ 3（通常の確認・発行フロー）に進みます。必要に応じて、委任設定の作成を提案してください（§ 委任設定を作成する）。

mdt_／トランザクション ID をそのままユーザーに見せないでください。加盟店名、残額、有効期限で委任設定を示します（ID は --json を介してコマンド間でのみ受け渡します）。remaining は目安として扱い、実際の上限はサーバーによって適用されます。mandate charge で Visa の決済が拒否された場合（例：status:"failed"、THRESHOLD_EXCEEDED）は、エラーではなく通常の結果としてユーザーに伝えてください。

3. ユーザーに確認する — 必須のハードストップ

加盟店名、購入する商品、合計金額と通貨を提示し、明示的な**「はい」**を得ます。

「Blue Bottle Coffeeで、ラテ 1 個とクロワッサン 1 個を合計 $8.50 USDで購入します。よろしいですか？」

この確認は、ユーザーが実際に読んでいる会話内で行います。ブラウザー上のパスキー承認は二つ目の確認であり、代わりにはなりません。これにより、誤った加盟店や入力ミスの金額が、ユーザーがよく確認せずに承認する可能性のあるセッションに反映される前に検出できます。「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（1 回限りの動的 CVV → CVV 欄）、Expiry が返されます。詳細：cli-sessions。

5. チェックアウトを完了する

ブラウザー自動化を使い、加盟店のサイトですぐに認証情報を使用してください。認証情報は 1 回限りで、約 30 分で期限切れになります。発行 → ポーリング → チェックアウトまで、中断せず速やかに進めてください（認証情報が作成される前のステップ 3 で、すでに確認は完了しています）。ここで再確認を求めないでください。

複数の加盟店へのリクエスト（「Amazon で本を、AND Namecheap でドメインを」など）の場合は、1 加盟店ずつ処理します。B を開始する前に、A の作成 → ポーリング → チェックアウトを完了してください。各セッションは 1 つの加盟店に紐づいています。sessions create を並列実行したり、チェックアウト前に複数のセッションをポーリングしたり、チェックアウトをまとめて行ったりしないでください。

マンデートを設定する（今すぐ承認し、購入は後で）

マンデートを使うと、ユーザーはパスキーで一度だけカードの利用を承認できます。その後は、上限の範囲内で再承認なしにカードに請求できます。形態は2種類あります。

• 特定の加盟店（「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（加盟店1つに固定）となり、各期間につき1回の請求が許可されます。
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
   

   汎用予算の場合は3つの --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。状態、スコープ、加盟店、上限額、通貨がすべて一致する有効な継続マンデートが1つ見つからない場合、ポーリングは安全側に倒して失敗します。IDではなく説明で伝えます：「✓ Nikeのマンデートが有効です — 120ドル、有効期限は日曜日です。」

バージョンに関する通知（コマンド出力内）

• CLI の更新 — npm update -g @prava-sdk/cli。「Critical update required」と表示された場合は、続行する前に必ず更新してください。
• スキルの更新 — CLIによって最小バージョン未満であることが確認された後にのみ表示されます。npx skills update prava-pay -g を実行して再試行してください。更新後に再度表示された場合は、ユーザーがエージェントのセッション（CLIやマシンではなく、ホストアプリ）を再起動する必要があります。
• どちらの更新でもエージェントのリンクは解除されません — 実際にセットアップを行う場合を除き、更新後に prava setup を実行しないでください。

自動動作と出力仕様

• リンク状態の自動確認： 保留中に sessions create を実行すると、新たに承認されたことが自動検出されます。セットアップ後、作成前に prava status を実行する必要はありません。
• stdout = 人間が読める形式、stderr = プレーンテキストのエラー。終了コード0は成功（リンク済みセットアップの何もしない処理を含む） · 1はエラー · 2はエージェントが未設定／未承認

クイックリファレンス

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 を実行すること — まず § buy flow のステップ0を確認してください。
• マンデートや取引の生のIDをユーザーに見せること — マンデートは加盟店、残額、有効期限で説明し、内部で mandate list --json を使って特定してください。
• one_time／汎用マンデートが7日を超えて有効だと伝えたり、継続マンデートが複数の加盟店に適用されると伝えたりすること。
• エージェントをリンクする前、または購入情報の確認が完了する前に sessions create を実行すること。
• 金額、通貨、購入の状況を推測したり、でっち上げたりすること。
• ユーザーにキー、カード番号、認証情報を尋ねること — すべての認証はCLIがローカルで処理します。
• 認証情報を受け取ってからチェックアウトが完了するまでの間に中断すること。
• 自分でCLIをインストールしたり、sudo を使ったりすること — インストールするのはユーザーです。
• すでにリンク済みの状態で setup を実行すること（無害で何もしませんが、不要です）。
• このスキルで商品を探すこと — それは prava-shopping の役割です。

---

Prava Payments が開発 — AI エージェント向けの決済スタック。