Agent-native payments: building idempotent checkout flows with AgentPay

#ai #python #payments #mcp

Problem: AI agents need to collect money without holding it

When Claude or another LLM agent needs to collect a payment—say, to unlock premium features or settle a service charge—most solutions require:

Complex integrations (Stripe, PayPal APIs with credential management)
Trust trade-offs (money sitting in escrow or a third-party account)
State management headaches (tracking payment status across agent runs)

Vietnam's VietQR ecosystem is perfect for this: QR codes point directly at merchant bank accounts. But there was no agent-native SDK until now.

How AgentPay solves it

AgentPay VN is an open-source (MIT) Python SDK + MCP server that:

Never touches money — QR codes point straight to your bank account
Confirms settlement by reading your SePay bank feed (one API key)
Supports idempotency — safe to retry without double-charging
Ships webhooks — your agent can await payment without polling

The flow is 3 lines:

from agentpay import PaymentClient

client = PaymentClient(api_key="your_key")

# Create a payment request
request = client.create_payment_request(
    amount=100000,  # VND
    description="Premium feature unlock",
    idempotency_key="user_123_2024_01_15"
)

print(f"Checkout: {request.checkout_url}")

# Await settlement (blocks until paid or timeout)
receipt = client.await_settlement(
    request_id=request.id,
    timeout=300  # 5 minutes
)

if receipt:
    print(f"Paid! Transaction: {receipt.transaction_id}")
else:
    print("Payment not received")

Wiring it into Claude via MCP

Install the MCP server:

pip install agentpay-vn

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "env": {
        "AGENTPAY_API_KEY": "your_api_key",
        "AGENTPAY_ACCOUNT_ID": "your_account_id"
      }
    }
  }
}

Now in Claude:

User: "Lock my export feature behind a $5 payment."

Claude: Calls agentpay_create_payment → sends VietQR checkout URL → calls agentpay_await_settlement → confirms and unlocks feature.

Idempotency + webhooks matter

Idempotent requests prevent accidental double-charges if your agent retries:

# Same idempotency_key = same request, no duplicate charge
request = client.create_payment_request(
    amount=50000,
    idempotency_key="order_abc_retry_1"
)

Webhooks let you skip polling:

# Instead of await_settlement (blocking),
# configure a webhook in dashboard
# and handle POST at your endpoint

Honest limitations

VietQR only — Vietnam domestic payments. Not global.
SePay bank feed dependency — needs your bank to expose transaction data (Techcombank, VCB, BIDV support confirmed).
Settlement delay — typically 1-2 hours via SePay API.
No dispute resolution — you're responsible for refunds (it's a QR code, not a payment processor).