AgentPay VN

AgentPay VN

AI エージェント向けの VietQR 決済インフラ — あらゆる会話の中で支払いを受け付けられます。

AgentPay VN を使うと、AI エージェント（Claude、GPT、カスタムボット）が決済用 QR コードを生成してユーザーに送り、入金があったときに自動で確認できます。資金を保有したり、触れたりすることは一切ありません。資金は支払者の銀行口座から加盟店の口座へ直接移動します。AgentPay は決済確認のために銀行取引フィードを読み取るだけです。

ステータス： 早期アクセス／セルフホスト可能 — Sổ Nợ AI と同じスウォーム上で稼働しています。

---

仕組み

AI Agent                   AgentPay API              Bank feed (SePay)
   |                            |                           |
   |-- create_payment_request ->|                           |
   |<- { qr_image_url, id } ----|                           |
   |                            |                           |
   |-- send QR to user -------->|                           |
   |                            |      user scans & pays    |
   |                            |<-- webhook (bank txn) ----|
   |                            |-- match AP* pay_code      |
   |                            |-- status → settled        |
   |<-- await_settlement done --|                           |
   |                            |                           |
   |-- deliver order / unlock ->|                           |

1. 作成 — エージェントが POST /v1/payment-requests を呼び出し、VietQR 画像の URL とチェックアウトページを取得します。
2. 送信 — エージェントが QR 画像を埋め込むか、チャットでチェックアウトリンクをユーザーに送信します。
3. 待機 — エージェントが await_settlement()（または MCP ツール）を呼び出し、status = settled になるまでポーリングします。
4. 提供 — 決済が確認されてから、エージェントが商品やサービスを提供します。

AgentPay は資金を保有しません。 QR コードは加盟店の銀行口座番号を直接指定します。プラットフォームは、照合対象の送金を検出するために銀行取引フィードを監視するだけです。

---

クイックスタート

1. インストール

pip install agentpay-vn

2. API キーを取得 — アカウントは不要です

サンドボックスキーはセルフサービスで、すぐに発行されます。

curl -X POST https://agentpay.servicesai.vn/v1/sandbox/register \
  -H "Content-Type: application/json" -d '{"shop_name": "My Bot"}'
# -> { "api_key": "ap_test_...", "expires_at": "..." }

export AGENTPAY_API_KEY=ap_test_xxx

Python からは register_sandbox() を呼び出します。エージェントからは、register_sandbox MCP ツールを呼び出すだけです。キーが発行され、セッションに適用されます。

サンドボックスキーの有効期間は 7 日間です。実際の資金は移動せず、同じ email を指定して同じエンドポイントを呼び出すと更新されます。実際の決済には ap_live_* キーが必要です。このキーの取得には、ベトナムの銀行口座を持つ加盟店としての登録が必要です。agentpay.servicesai.vn から登録してください。

3. 決済を受け付ける（3 行）

from agentpay.client import AsyncAgentPayClient, await_settlement
import asyncio

async def main():
    async with AsyncAgentPayClient("ap_test_xxx") as client:
        pr = await client.create_payment_request(amount=50_000, description="Order #1")
        print(pr["checkout_url"])          # send this link to your user
        result = await await_settlement(client, pr["id"], timeout=120)
        assert result["status"] == "settled"

asyncio.run(main())

実行可能な完全版は examples/quickstart.py をご覧ください。

---

MCP サーバーのセットアップ

AgentPay には MCP サーバーが付属しているため、MCP 対応の AI エージェントであれば、追加のコードなしでツールとして呼び出せます。

Claude Desktop／Claude Code

claude_desktop_config.json に追加します（または examples/claude_desktop_config.json を使用します）。

{
  "mcpServers": {
    "agentpay": {
      "command": "python",
      "args": ["-m", "agentpay.mcp_server"],
      "env": {
        "AGENTPAY_API_KEY": "ap_test_xxx",
        "AGENTPAY_BASE_URL": "https://agentpay.servicesai.vn/v1"
      }
    }
  }
}

または、インストール済みのコンソールスクリプトを使用します。

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "env": { "AGENTPAY_API_KEY": "ap_live_xxx" }
    }
  }
}

利用可能な MCP ツール

ツール	説明
register_sandbox	無料の ap_test_* キーをセルフサービスで発行します。キーが設定されていない場合は、最初に呼び出してください
create_payment_request	指定した金額の VietQR コードを生成します
check_payment	決済リクエストの現在のステータスを取得します
await_settlement	入金またはタイムアウトまでポーリングします（最大 600 秒）
list_recent_payments	直近 N 件の決済済み取引を一覧表示します

---

エージェントスキル（Claude Code、Cursor、その他のエージェント）

MCP サーバーはエージェントに ツール を提供します。同梱の スキル は、いつ課金するか、VND 金額をどう書式設定するか、そして status = settled になるまで何も出荷してはならないというルールを判断するための指針を提供します。詳細は skills/agentpay-vn/SKILL.md をご覧ください。

このリポジトリは Claude Code のプラグインマーケットプレイスでもあるため、スキルと MCP サーバーを 1 回の手順でまとめてインストールできます。

claude plugin marketplace add phuocdu/agentpay-vn
claude plugin install agentpay-vn@agentpay-vn

Claude Code は API キーの入力を求めます（settings.json ではなく、OS の認証情報ストアに保存されます）。サンドボックスから始める場合は空欄のままにしてください。エージェントは最初の課金時に register_sandbox を呼び出します。

その他のエージェントでは、skills/agentpay-vn/ をそのエージェントがスキルを読み込む場所にコピーし、上記の手順に従って MCP サーバーを追加してください。

---

Python SDK

同期

from agentpay.client import AgentPayClient

with AgentPayClient("ap_live_xxx") as client:
    # Create
    pr = client.create_payment_request(
        amount=150_000,
        description="Consulting session 30 min",
        ttl_minutes=30,
        idempotency_key="session-abc-123",
    )

    # Poll manually
    import time
    for _ in range(60):
        pr = client.get_payment_request(pr["id"])
        if pr["status"] != "pending":
            break
        time.sleep(5)

    # Reconcile
    txns = client.list_transactions(limit=10)

非同期

from agentpay.client import AsyncAgentPayClient, await_settlement

async with AsyncAgentPayClient("ap_live_xxx") as client:
    pr = await client.create_payment_request(amount=75_000, description="eBook download")
    result = await await_settlement(client, pr["id"], timeout=300)
    if result["status"] == "settled":
        send_download_link(result["metadata"].get("email"))

Webhook の検証

import hashlib, hmac

def verify_webhook(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Webhook エンドポイントを登録します：

ep = client.register_webhook(
    url="https://your-server.com/webhooks/agentpay",
    events=["payment.settled", "payment.expired"],
)
print(ep["secret"])  # store this — shown only once

---

API リファレンス

• OpenAPI 仕様： agentpay-openapi.yaml
• ベース URL： https://agentpay.servicesai.vn/v1
• 認証： Authorization: Bearer ap_live_xxx（サンドボックスでは ap_test_xxx）

主なエンドポイント

メソッド	パス	説明
POST	/v1/payment-requests	決済リクエストを作成
GET	/v1/payment-requests/{id}	ステータスを取得
POST	/v1/payment-requests/{id}/cancel	保留中のリクエストをキャンセル
GET	/v1/transactions	決済済みの取引を一覧表示
POST	/v1/webhook-endpoints	Webhook URL を登録
POST	/v1/sandbox/simulate-settlement	決済をシミュレート（サンドボックスのみ）
GET	/pay/{pay_code}	公開チェックアウトページ（HTML、モバイル対応）

---

セルフホスティング

AgentPay は、Sổ Nợ AI の FastAPI バックエンドの一部として動作します。

必要条件

• Docker Swarm クラスター（Sono と同じ）
• MongoDB（Sono と共有）
• SePay の銀行フィードアカウント（本番決済用）
• agentpay.servicesai.vn の vhost を設定した Nginx

環境変数

変数	デフォルト	説明
AGENTPAY_BASE_URL	https://agentpay.servicesai.vn	チェックアウトリンクの公開ベース URL
MONGO_URI	mongodb://localhost:27017	Sono から継承
BILLING_WEBHOOK_TOKEN	—	SePay の Webhook トークン（継承）

API キーを作成する（管理者）

curl -X POST https://sono.servicesai.vn/api/admin/agentpay/keys \
  -H "Authorization: Bearer <admin-jwt>" \
  -H "Content-Type: application/json" \
  -d '{"org_id": "<shop-user-id>", "name": "My bot", "livemode": true}'

レスポンスには完全なキーが含まれます。すぐに保存してください。キーが表示されるのは一度だけです。

---

レート制限

ティア	月間決済件数	リクエスト数／分
Free	50	120

---

設計原則

1. 資金を預からない — QR コードは加盟店の銀行口座に直接紐付いています。AgentPay は取引フィードを読み取るだけで、資金には一切触れません。

2. 冪等性 — POST /payment-requests に Idempotency-Key ヘッダーを指定すると、重複を作成せずに安全に再試行できます（重複排除期間は24時間）。

3. HMAC による Webhook 検証 — 送信されるすべての Webhook は、AgentPay-Signature ヘッダー内で HMAC-SHA256(whsec_..., raw_body) により署名されます。処理する前に必ず検証してください。

4. サンドボックス — ap_test_* キーと POST /v1/sandbox/simulate-settlement を使って、実際の取引なしで開発やテストを行えます。

5. 信頼境界を最小限にする — MCP サーバーは、API キー以外にローカルの秘密情報を持たない薄い REST クライアントです。エージェントキーが侵害された場合でも、公開されるのは1つのテナントの決済リクエスト作成権限だけです。

---

ライセンス

MIT © 2026 ServicesAI — LICENSE を参照してください。