VietQR Payment Automation for AI Agents

2026-07-11 · AgentPay VN

vietqrai-agentspayment-automationpython-sdkvietnam

The Pain Point: AI Agents Can't Collect Vietnamese Payments Yet

You've built a brilliant AI agent—maybe it's a customer service bot that sells digital products, a course marketplace, or a café booking system. Your agent can chat, understand intent, and guide users through a purchase flow. But the moment it comes time to collect payment, you hit a wall.

Stripe doesn't work seamlessly in Vietnam without jumping through hoops. International payment gateways add latency, friction, and sometimes reject legitimate Vietnamese customers. Your agent sits there, unable to close the transaction. The worst part? You're losing revenue because the conversion funnel breaks right at checkout.

This is where AgentPay VN changes the game. It's an open-source Python SDK and MCP server that lets your AI agents collect payments directly via VietQR—Vietnam's native QR payment standard—without ever touching the money. The QR code points straight at your merchant bank account. Settlement happens through your bank feed. No middle-man delays, no complex reconciliation.

Why VietQR + AI Agents = Perfect Match

VietQR is the standard for bank transfers in Vietnam, used by nearly every Vietnamese bank. It's instant, ubiquitous, and trusted. When an AI agent generates a VietQR code and sends it to a customer, they see something familiar—a QR they scan with their banking app. No new app to download. No new account to create.

Traditional payment integrations force your agent to: - Redirect users to an external checkout page (breaks the conversational experience) - Wait for webhooks and reconcile complex state - Handle PCI compliance for card storage

AgentPay VN flips this: 1. Agent creates a payment request with amount, description, merchant info 2. Agent sends the checkout URL (or embeds the QR inline) 3. Agent awaits settlement confirmation from your bank feed

No redirects. No middle-man. Just direct, instant payments flowing into your account.

Installation & Setup (3 Minutes)

Install the SDK

pip install agentpay-vn

You'll also want the MCP server for seamless Claude integration:

pip install agentpay-mcp

Configure Your Merchant Account

AgentPay VN reads from environment variables or a config file. At minimum, you need:

export AGENTPAY_MERCHANT_ID="your_merchant_id"
export AGENTPAY_MERCHANT_NAME="Your Business Name"
export AGENTPAY_BANK_ACCOUNT="1234567890"
export AGENTPAY_BANK_CODE="970406"  # ACB example

Obtain these from your Vietnamese bank once you've registered as a merchant.

The Three-Line Payment Flow

AgentPay VN distills payment collection into three core operations. Let's walk through a real example: a Python tutoring bot that charges 299,000 VND for a course.

Step 1: Create a Payment Request

from agentpay_vn import AgentPayClient
import os

# Initialize the client with environment variables
client = AgentPayClient(
    merchant_id=os.getenv("AGENTPAY_MERCHANT_ID"),
    merchant_name=os.getenv("AGENTPAY_MERCHANT_NAME"),
    bank_account=os.getenv("AGENTPAY_BANK_ACCOUNT"),
    bank_code=os.getenv("AGENTPAY_BANK_CODE")
)

# Create a payment request for a course purchase
payment_request = client.create_payment_request(
    amount=299000,  # VND
    description="Python Masterclass - Full Access",
    reference_id="user_12345_course_001",  # Your internal order ID
    order_info="Python Masterclass"
)

print(f"Payment request ID: {payment_request['id']}")
print(f"Checkout URL: {payment_request['checkout_url']}")
print(f"VietQR Code (base64): {payment_request['qr_code']}")

What's happening: - amount=299000: The price in Vietnamese Dong - reference_id: Your internal order tracking (links back to the customer/course) - create_payment_request() returns an object with: - id: Unique payment ID (use this to query status later) - checkout_url: The shareable link your agent sends to the customer - qr_code: Base64-encoded QR image (display in chat or email)

Step 2: Send the Checkout URL to Your Customer

Your agent can now send the checkout URL. In a chat context:

# In your agent's response function
def send_payment_to_customer(customer_name, payment_request, chat_context):
    message = f"""
Hi {customer_name}! 🎓

Your Python Masterclass is ready. To unlock access, scan this QR or visit:
{payment_request['checkout_url']}

Amount: ₫299,000
Once you pay, your course access will activate instantly.
    """
    # Send via email, SMS, or chat platform
    return message

In practice, the customer: 1. Sees the QR in their chat or email 2. Opens their banking app (VCB, ACB, Vietcombank, etc.) 3. Scans the QR 4. Confirms the transfer 5. Payment is settled within seconds to your merchant account

Step 3: Await Settlement & Unlock Access

import time

def unlock_course_on_payment(payment_id, customer_id, max_wait_seconds=300):
    """
    Poll for payment settlement. In production, use a webhook/bank feed instead.
    """
    start_time = time.time()

    while time.time() - start_time < max_wait_seconds:
        # Check payment status
        status = client.await_settlement(payment_id)

        if status['settled']:
            print(f"✓ Payment confirmed for customer {customer_id}")
            # Trigger course unlock
            unlock_user_course(customer_id, course_id="python_masterclass")
            return True

        print(f"Waiting for payment... ({time.time() - start_time:.0f}s)")
        time.sleep(5)  # Poll every 5 seconds

    return False  # Timeout

Production note: While polling works for demos, production systems should use: - Bank feed integration (your bank pushes settlement confirmations) - Webhook callbacks (if AgentPay VN supports them in your region)

This removes latency and keeps your agent responsive.

Integrating with Claude via MCP

If you're building an autonomous agent on Claude, use the AgentPay VN MCP server to give Claude native payment capabilities.

MCP Server Configuration

Add this to your Claude client's mcp_config.json:

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "env": {
        "AGENTPAY_MERCHANT_ID": "your_merchant_id",
        "AGENTPAY_MERCHANT_NAME": "Your Business",
        "AGENTPAY_BANK_ACCOUNT": "1234567890",
        "AGENTPAY_BANK_CODE": "970406"
      }
    }
  }
}

Now Claude can:

User: "I want to buy your data analysis course."

Claude: "Great! Let me set up payment for you."
[Claude calls MCP: create_payment_request(amount=499000, description="Data Analysis Masterclass")]

Claude: "Scan this QR code or visit [checkout_url] to pay ₫499,000. Your access activates immediately!"

Claude becomes a fully autonomous payment collection agent.

Real-World Walkthrough: Online Course Marketplace

Let's trace a complete flow for a Vietnamese online learning platform:

Scenario: Linh sells Python and AI courses. Her Discord bot (powered by Claude + AgentPay VN) handles customer inquiries and payments.

  1. Customer: "Do you have courses on LLMs?"
  2. Bot (Claude): "Yes! We have a 4-week LLM Bootcamp. ₫599,000. Interested?"
  3. Customer: "Yes, sign me up."
  4. Bot (internal): - Calls create_payment_request(amount=599000, reference_id="linh_user_99_bootcamp") - Gets checkout_url: https://agentpay.servicesai.vn/checkout/abc123xyz
  5. Bot (Claude): "Perfect! Scan this QR or click here. Your access starts immediately after payment."
  6. Customer: Scans QR with VCB app, confirms transfer.
  7. Bot (polling via bank feed): Detects settlement within 10 seconds.
  8. Bot (Claude): "Payment received! 🎉 Here's your course access link: [course_url]. Welcome to the Bootcamp!"
  9. Linh's account: ₫599,000 settled, minus network costs (~0.5-1%).

Total friction for customer: 30 seconds. No external redirects. Pure conversational UX.

Advanced Tips: Production Readiness

Idempotency: Prevent Double-Charges

Always use unique reference_id values:

import uuid

payment_request = client.create_payment_request(
    amount=299000,
    description="Course",
    reference_id=f"user_{customer_id}_{uuid.uuid4().hex[:8]}",
    order_info="Course Purchase"
)

Handle Timeouts Gracefully

def wait_for_payment_with_timeout(payment_id, timeout_seconds=600):
    try:
        result = client.await_settlement(payment_id, timeout=timeout_seconds)
        return result
    except TimeoutError:
        # Send customer a reminder to pay
        notify_customer(payment_id, "Your payment link is still active. Please complete the transfer.")
        return None

Logging & Monitoring

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("agentpay")

logger.info(f"Payment created: {payment_request['id']} for user {customer_id}")
logger.info(f"Settlement detected: {payment_id}")

Do's and Don'ts

Do Don't
Store reference_id in your database Store or transmit merchant bank details in logs
Use bank feeds for settlement in production Poll every second (use 5-10s intervals)
Validate amount matches your order before creating request Assume settlement without confirmation
Set reasonable timeout windows (5-10 minutes) Hardcode merchant credentials in code
Test with your actual bank account first Use VietQR for international payments

FAQ

Q: Does AgentPay VN hold my money? No. The QR code points directly at your merchant bank account. Settlement flows into your account controlled by your bank, not AgentPay VN.

Q: How long does settlement take? Typically 5-30 seconds from scan to confirmation (depends on customer's bank). Your agent can await confirmation and unlock access in near-real-time.

Q: Do I need a business bank account? Yes. AgentPay VN requires a Vietnamese merchant account registered with a local bank (ACB, VCB, Agribank, etc.). Contact your bank's merchant services.

Q: Can I use this for international customers? No. VietQR is designed for Vietnamese bank accounts only. Your customers must have Vietnamese banking apps and accounts.

Q: What about transaction fees? VietQR transfer fees vary by bank (typically 0.5-1% for businesses). These are charged by your bank, not AgentPay VN.

Key Takeaways

Getting Started

Ready to add autonomous payment collection to your AI agent? Start here:

pip install agentpay-vn

Build agents that don't just chat—agents that close sales, unlock courses, and settle payments directly into your Vietnamese bank account. No Stripe. No friction. Pure VietQR.

Get started →

← All posts