Skip to main content
Glama
agentpay-vn

agentpay-vn

by phuocdu

AgentPay VN

PyPI version License: MIT MCP Registry phuocdu/agentpay-vn MCP server

VietQR payment infrastructure for AI agents — collect money inside any conversation.

AgentPay VN lets AI agents (Claude, GPT, custom bots) generate payment QR codes, send them to users, and automatically confirm when the money arrives — all without ever holding or touching funds. Money flows directly from the payer's bank account into the merchant's account; AgentPay only reads the bank transaction feed to confirm settlement.

Status: Early access / self-hosted — running on the same swarm as Sổ Nợ AI.


How it works

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. Create — agent calls POST /v1/payment-requests → gets a VietQR image URL and a checkout page.

  2. Send — agent embeds the QR image or sends the checkout link to the user in chat.

  3. Await — agent calls await_settlement() (or the MCP tool) to poll until status = settled.

  4. Deliver — only after confirmed settlement does the agent release the goods/service.

AgentPay never holds money. The QR points directly at the merchant's bank account number. The platform only monitors the bank transaction feed to detect matching transfers.


Related MCP server: Lightning Enable MCP

Quick start

1. Install

pip install agentpay-vn

2. Get an API key — no account needed

A sandbox key is self-serve and instant:

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

From Python: register_sandbox(). From an agent: just call the register_sandbox MCP tool — it issues the key and applies it to the session.

Sandbox keys last 7 days, move no real money, and renew by calling the same endpoint with the same email. For real payments you need an ap_live_* key, which requires a registered merchant with a Vietnamese bank account — sign up at agentpay.servicesai.vn.

3. Collect a payment (3 lines)

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())

See examples/quickstart.py for the full runnable version.


MCP server setup

AgentPay ships an MCP server so any MCP-compatible AI agent can call it as a tool — no extra code needed.

Claude Desktop / Claude Code

Add to claude_desktop_config.json (or use 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"
      }
    }
  }
}

Or use the installed console script:

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

Available MCP tools

Tool

Description

register_sandbox

Self-issue a free ap_test_* key — call this first when no key is set

create_payment_request

Generate a VietQR code for a given amount

check_payment

Get current status of a payment request

await_settlement

Poll until payment arrives or timeout (max 600 s)

list_recent_payments

List last N settled transactions


Agent skill (Claude Code, Cursor, and other agents)

The MCP server gives an agent the tools. The bundled skill gives it the judgement: when to charge, how to format a VND amount, and the rule that nothing ships before status = settled. See skills/agentpay-vn/SKILL.md.

This repository is also a Claude Code plugin marketplace, so the skill and the MCP server install together in one step:

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

Claude Code prompts for your API key (stored in the OS credential store, not in settings.json). Leave it blank to start in sandbox — the agent will call register_sandbox on its first charge.

For other agents, copy skills/agentpay-vn/ into wherever that agent reads skills from, and add the MCP server as shown above.


Python SDK

Synchronous

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)

Asynchronous

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 verification

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)

Register a webhook endpoint:

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 reference

  • OpenAPI spec: agentpay-openapi.yaml

  • Base URL: https://agentpay.servicesai.vn/v1

  • Authentication: Authorization: Bearer ap_live_xxx (or ap_test_xxx for sandbox)

Key endpoints

Method

Path

Description

POST

/v1/payment-requests

Create payment request

GET

/v1/payment-requests/{id}

Get status

POST

/v1/payment-requests/{id}/cancel

Cancel pending request

GET

/v1/transactions

List settled transactions

POST

/v1/webhook-endpoints

Register webhook URL

POST

/v1/sandbox/simulate-settlement

Simulate payment (sandbox only)

GET

/pay/{pay_code}

Public checkout page (HTML, mobile-friendly)


Self-hosting

AgentPay runs as part of the Sổ Nợ AI FastAPI backend.

Requirements

  • Docker Swarm cluster (same as Sono)

  • MongoDB (shared with Sono)

  • SePay bank feed account (for live payments)

  • Nginx with an agentpay.servicesai.vn vhost

Environment variables

Variable

Default

Description

AGENTPAY_BASE_URL

https://agentpay.servicesai.vn

Public base URL for checkout links

MONGO_URI

mongodb://localhost:27017

Inherited from Sono

BILLING_WEBHOOK_TOKEN

—

SePay webhook token (inherited)

Create an API key (admin)

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}'

The response includes the full key — store it immediately; it is shown only once.


Rate limits

Tier

Settled payments/month

Requests/minute

Free

50

120


Design principles

  1. No money held — QR codes point directly at the merchant's bank account. AgentPay only reads the transaction feed; it never touches the money.

  2. Idempotency — pass an Idempotency-Key header on POST /payment-requests to safely retry without creating duplicates (24-hour deduplication window).

  3. HMAC webhook verification — every outbound webhook is signed with HMAC-SHA256(whsec_..., raw_body) in the AgentPay-Signature header. Always verify before processing.

  4. Sandbox — use ap_test_* keys and POST /v1/sandbox/simulate-settlement to develop and test without real transactions.

  5. Minimal trust surface — the MCP server is a thin REST client with no local secrets beyond the API key. Compromising an agent key only exposes one tenant's payment-request creation ability.


License

MIT © 2026 ServicesAI — see LICENSE.

Available Tools

4 tools
await_settlementA

Wait for a payment request to be settled (polls on behalf of the agent).

Polls every 5 seconds until status != pending or the timeout is reached (maximum 600 s). Call this after sending the QR to the payer. If the timeout expires while still pending, ask the user whether to keep waiting or cancel.

Args: payment_request_id: The id returned by create_payment_request. timeout_seconds: How long to wait in seconds (10–600, default 180).

Inputs: payment_request_id (required), timeout_seconds. Returns: result

check_paymentA

Check the current status of a payment request.

Returns: One of: pending | settled | underpaid | expired | cancelled, along with the amount received so far. Only treat a payment as complete when status=settled.

Inputs: payment_request_id (required). Returns: result

create_payment_requestA

Create a VietQR payment request.

Args: amount: Amount in VND, minimum 1 000. description: Short description for the payer (e.g. "Order #123 — 2 kg coffee"). ttl_minutes: QR validity window in minutes (5–1 440, default 60). metadata_note: Internal note from the agent (order id, conversation id, etc.) — echoed back in webhook events.

Returns: id, pay_code, QR image URL, and checkout page URL. Send qr_image_url or checkout_url to the payer, then call await_settlement(id) to wait for the money to arrive.

Inputs: amount (required), description (required), ttl_minutes, metadata_note. Returns: result

list_recent_paymentsB

List the most recently settled transactions (quick reconciliation).

Args: limit: Number of transactions to return (1–50, default 10).

Inputs: limit. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a distinct and clear purpose: creating a payment request, checking status, awaiting settlement, and listing recent payments. No two tools overlap in functionality, ensuring an agent can easily select the correct one.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (create_payment_request, check_payment, await_settlement, list_recent_payments). The naming is predictable and unambiguous.

    Tool Count4/5

    Four tools is a reasonable number for a focused payment processing server. While it covers core operations, it is slightly lean; adding a cancel tool might improve completeness, but the count is appropriate.

    Completeness4/5

    The tool set covers the main lifecycle of a payment request: create, check, await, and list. Missing an explicit cancel/expire function, but the await tool handles timeouts gracefully. Minor gap, but overall sufficient for typical workflows.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for AgentPay — the payment gateway for autonomous AI agents. Fund a wallet once, give your agent the key, and it discovers, provisions, and pays for tool APIs on its own. One key, every tool.
      112 npm
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server that enables AI agents to make autonomous Bitcoin Lightning Network payments using the L402 protocol. Agents can pay for API access, purchase resources, and complete transactions without human intervention — invoice comes in, sats go out, done.
      17
      9
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      A remote MCP server that lets any AI agent accept PromptPay QR, credit/debit cards, TrueMoney wallet, internet banking payments in Thailand, and check payment status.
      MIT