DEV Community: ServicesAI VN

Build a Paid MCP Server: Charge Users Inside Claude

ServicesAI VN — Fri, 25 Sep 2026 00:20:10 +0000

The Problem: AI Agents Need Revenue Models

You've built an amazing MCP server that helps users—maybe it writes better code, researches market trends, or automates customer support. Your Claude plugin works flawlessly. But here's the catch: users expect it for free, and you're footing the API bills.

Traditional payment gateways won't help. Stripe requires account setup, webhook complexity, and 2.9% + $0.30 per transaction. Worse, payment flows break Claude's conversational flow—users get bounced to external checkout pages, lose context, and abandon halfway through.

What if payments happened inside the conversation? What if your AI agent could ask for payment, the user scans a QR code on their phone, and—within seconds—the agent confirms payment and delivers the result? That's the AgentPay VN promise.

What Is AgentPay VN?

AgentPay VN is an open-source (MIT license) Python SDK + MCP server that lets AI agents collect VietQR payments directly from conversations. The key innovation: AgentPay never touches your money. Instead, it generates QR codes that point straight to your merchant bank account. When a user scans and pays, your bank confirms the settlement via API.

This means:

Zero payment custody risk
No separate merchant account setup beyond your existing bank
Instant settlement confirmation in Claude
Built for Vietnamese banking infrastructure, but extensible

Install in one line:

pip install agentpay-vn

Then plug the MCP server into Claude, and you're ready to charge.

The 3-Line Payment Flow

Before diving into code, understand AgentPay's core workflow:

create_payment_request → Generate a unique payment request (amount, description, reference ID)
send checkout_url → Share the QR code/checkout link with the user
await_settlement → Poll your bank feed until the payment confirms

That's it. No OAuth redirects, no webhook spaghetti, no third-party account management.

Step 1: Set Up Your AgentPay Environment

Start by installing the SDK and configuring your bank credentials.

Installation

pip install agentpay-vn

Next, you'll need:

Bank Account: A Vietnamese business or personal bank account that supports VietQR (most major banks do: Vietcombank, Agribank, Techcombank, etc.)
Bank API Access: Credentials to read your bank statement or transaction feed. Most banks offer this via internet banking or an open-banking API.
MCP Integration: The AgentPay MCP server package

Installing the MCP Server

For Claude Desktop integration:

pip install agentpay-mcp

Or build from source:

git clone https://github.com/phuocdu/agentpay-vn.git
cd agentpay-vn
pip install -e .

Step 2: Create Your First Payment Request

Here's a real Python example—imagine you're building a "code review bot" that charges $5 per review:

from agentpay_vn import PaymentClient, create_payment_request
import asyncio

# Initialize the payment client with your bank details
client = PaymentClient(
    merchant_id="your_merchant_id",  # Unique ID for your account
    bank_account="1234567890",       # Your VietQR-enabled bank account
    bank_code="970422",               # Vietcombank's code; see docs for others
    api_key="your_bank_api_key"       # From your bank's developer portal
)

# Create a payment request for a code review
request = create_payment_request(
    amount=5.00,                           # USD equivalent (AgentPay handles conversion)
    currency="USD",
    description="Code Review: refactor_user_auth.py",
    reference_id="review_user_auth_001",  # Unique per transaction
    metadata={"user_id": "claude_user_42", "service": "code_review"}
)

print(f"Payment Request ID: {request.id}")
print(f"QR Code URL: {request.qr_code_url}")
print(f"Amount (VND): {request.amount_vnd}")

Line-by-line breakdown:

PaymentClient holds your bank credentials securely
create_payment_request() generates a unique payment object with an expiry (default 15 minutes)
amount is in your preferred currency; AgentPay converts to VND using live rates
reference_id ties the payment to your internal system (store this!)
qr_code_url points to a QR that users scan with any banking app

Step 3: Integrate with Claude via MCP

Now the magic: make this payment flow available inside Claude conversations.

Configure the MCP Server in Claude Desktop

Edit ~/.claude/config.json (create if missing):

{
  "mcpServers": {
    "agentpay": {
      "command": "python",
      "args": ["-m", "agentpay_mcp.server"],
      "env": {
        "AGENTPAY_MERCHANT_ID": "your_merchant_id",
        "AGENTPAY_BANK_ACCOUNT": "1234567890",
        "AGENTPAY_BANK_CODE": "970422",
        "AGENTPAY_API_KEY": "your_bank_api_key"
      }
    }
  }
}

Restart Claude Desktop. You'll now have access to AgentPay tools within conversations.

Step 4: Poll for Settlement

Once the user pays, you need to confirm it. Here's how to wait for settlement:

async def wait_for_payment(client, reference_id, timeout_seconds=120):
    """
    Poll the bank feed until the payment is confirmed.
    Returns True if payment received, False if timeout.
    """
    start_time = asyncio.get_event_loop().time()

    while asyncio.get_event_loop().time() - start_time < timeout_seconds:
        # Check your bank's transaction feed
        transactions = await client.fetch_bank_transactions(
            limit=10,
            filters={"reference_id": reference_id}
        )

        # Look for a matching payment
        for txn in transactions:
            if txn.reference_id == reference_id and txn.status == "SETTLED":
                print(f"✅ Payment confirmed! Transaction ID: {txn.id}")
                print(f"Amount received: {txn.amount_vnd} VND")
                return True

        # Wait 2 seconds before checking again (reduces API calls)
        await asyncio.sleep(2)

    print(f"❌ Timeout waiting for payment after {timeout_seconds}s")
    return False

# Usage in your MCP handler:
async def handle_code_review_request(code, user_id):
    # Create payment request
    payment = create_payment_request(
        amount=5.00,
        description=f"Code Review for {user_id}",
        reference_id=f"review_{user_id}_{int(time.time())}"
    )

    # Tell Claude to show the QR to the user
    yield f"Please scan this QR code to pay: {payment.qr_code_url}"

    # Wait for settlement
    is_paid = await wait_for_payment(client, payment.reference_id, timeout_seconds=120)

    if is_paid:
        # Deliver the service
        review = await perform_code_review(code)
        yield f"Your code review:\n\n{review}"
    else:
        yield "Payment not received. Please try again."

Key points:

fetch_bank_transactions() queries your actual bank feed (via their API)
Polling every 2 seconds is efficient; most settlements happen within 5-10 seconds
The reference_id ties everything together—payment request → transaction confirmation → service delivery

Real-World Example: A Paid Course Bot

Let's build a concrete scenario: an "AI prompt engineering course" bot that charges $9.99 per lesson.

The Bot Workflow

User asks Claude: "I want to learn advanced prompt engineering. Show me lesson 3."
Claude's MCP server checks if the user has paid for lesson 3
If not: "Lesson 3 costs $9.99. Scan this QR code to unlock it: [QR link]"
User scans on their phone (takes 5 seconds), confirms payment in their banking app
Bot detects settlement: "Payment confirmed! Here's lesson 3..." [delivers full lesson content]
Bot logs the transaction for your records (user_id → lesson_id → payment_id)

Code Sketch

from agentpay_vn import PaymentClient
import json

class CourseBot:
    def __init__(self, client):
        self.client = client
        self.paid_lessons = {}  # Track paid lessons per user

    async def unlock_lesson(self, user_id, lesson_id):
        # Check if already paid
        if self.is_user_paid(user_id, lesson_id):
            return await self.get_lesson_content(lesson_id)

        # Create payment request
        lesson_price = 9.99
        payment = create_payment_request(
            amount=lesson_price,
            currency="USD",
            description=f"Prompt Engineering Course - Lesson {lesson_id}",
            reference_id=f"{user_id}_lesson_{lesson_id}_{int(time.time())}",
            metadata={"user_id": user_id, "lesson_id": lesson_id}
        )

        # Prompt user to pay
        yield f"Lesson {lesson_id} costs ${lesson_price}. Scan to pay: {payment.qr_code_url}"

        # Wait for payment
        is_paid = await self.client.await_settlement(
            reference_id=payment.reference_id,
            timeout=120
        )

        if is_paid:
            # Mark as paid and deliver
            self.paid_lessons[user_id] = self.paid_lessons.get(user_id, set())
            self.paid_lessons[user_id].add(lesson_id)
            yield await self.get_lesson_content(lesson_id)
        else:
            yield "Payment failed. Try again?"

    def is_user_paid(self, user_id, lesson_id):
        return lesson_id in self.paid_lessons.get(user_id, set())

    async def get_lesson_content(self, lesson_id):
        # Return the actual lesson (e.g., from a database)
        return f"[Full content of Lesson {lesson_id}...]"

Do's and Don'ts: Payment Best Practices

✅ DO	❌ DON'T
Store reference_id in your database for reconciliation	Charge without showing the QR code first
Set reasonable timeout (60–120 seconds)	Timeout instantly; users need time to scan
Log all transactions (payment_id, user_id, status)	Forget to log failures for debugging
Use unique reference_ids (avoid duplicates)	Reuse reference_ids across transactions
Handle network errors gracefully (retry logic)	Crash if bank API is slow
Offer payment retry if settlement times out	Block user permanently after one failed attempt

Advanced: Handling Edge Cases

Multiple Retries with Exponential Backoff

import random

async def await_settlement_with_retry(client, reference_id, max_retries=3):
    for attempt in range(max_retries):
        try:
            result = await client.await_settlement(
                reference_id=reference_id,
                timeout=120
            )
            if result:
                return True
        except Exception as e:
            print(f"Attempt {attempt + 1} failed: {e}")
            if attempt < max_retries - 1:
                # Exponential backoff: 1s, 2s, 4s
                wait_time = 2 ** attempt + random.uniform(0, 1)
                await asyncio.sleep(wait_time)
    return False

Currency Conversion

AgentPay auto-converts USD ↔ VND using live rates. For other currencies:

payment = create_payment_request(
    amount=100,  # 100 EUR
    currency="EUR",
    # AgentPay converts EUR → VND at current rate
)

Frequently Asked Questions

Q: Does AgentPay hold my money?
No. QR codes point directly to your merchant bank account. Settlement happens bank-to-bank via VietQR. AgentPay only facilitates the payment flow.

Q: What if a user pays but I deliver the service, then the transaction reverses?
Implement a webhook listener (advanced) or periodic reconciliation. Store transaction IDs from bank confirmations. If a reversal occurs, you can disable the user's access to that service. See docs for webhook setup.

Q: Can I charge in USD/EUR if I'm in Vietnam?
Yes. AgentPay converts currencies automatically. However, your bank may apply FX fees. Check your bank's rate.

Q: How long does settlement take?
Most VietQR payments settle within 5–30 seconds. Some banks take up to 2 minutes during peak hours. Set timeout to 120 seconds for safety.

Q: Can I use this outside Vietnam?
Currently, AgentPay targets Vietnamese banking (VietQR). International support is on the roadmap. Join the GitHub discussions for updates.

Key Takeaways

AgentPay VN is an MIT open-source SDK that lets Claude agents collect VietQR payments without holding money
Installation: pip install agentpay-vn; MCP server via agentpay-mcp
Core flow: create_payment_request() → share QR → await_settlement() → deliver service
Zero friction: Users scan QR in their banking app (5 seconds); Claude continues the conversation without leaving the context
Bank-direct: Money goes straight to your merchant account; AgentPay just orchestrates
Logging matters: Always store reference_id and transaction metadata for reconciliation and debugging
Real use cases: Paid courses, premium code reviews, API access, consulting bots, digital goods

Next Steps

Get started now: Install AgentPay VN with pip install agentpay-vn
Read the docs: Full API reference at https://agentpay.servicesai.vn/v1/docs
Explore the repo: Check out examples and contribute at https://github.com/phuocdu/agentpay-vn
Build your bot: Start with a simple paid service (e.g., $1 for a feature), test the flow, then scale

Your AI agent just became a revenue engine. Happy selling!

Build a Telegram Payment Bot with VietQR & AgentPay

ServicesAI VN — Thu, 24 Sep 2026 00:18:25 +0000

The Problem: Running a Telegram Business Without Payment Integration

Imagine you're selling online courses through a Telegram bot. A student messages: "How do I pay?" Right now, you're copying a bank account number into chat, hoping they'll transfer the right amount with the correct reference. You wait hours—sometimes days—to manually confirm payment. Half your customers get confused and abandon the purchase. Your dream of automated digital product sales hits a wall.

This is the daily reality for thousands of Vietnamese creators, service providers, and small businesses trying to monetize on Telegram. You have an audience. You have a product. But payment collection feels stuck in 2015.

Enter AgentPay VN: an open-source Python SDK that lets your Telegram bot generate VietQR payment links in seconds, automatically confirm settlements, and continue conversations without you lifting a finger. No merchant account overhead. No money sitting in escrow. Just direct transfers to your bank account.

Why VietQR + Telegram = Perfect Match for Vietnamese Creators

VietQR is ubiquitous in Vietnam—every bank app supports it. Telegram's API is bulletproof and cost-free. Together, they're unstoppable.

Here's why AgentPay VN solves this uniquely:

No fund holding: Money goes straight to your merchant bank account. AgentPay is invisible.
MIT open-source: Full transparency. You own the code.
MCP server support: Integrates with Claude and other AI agents—automate payment workflows end-to-end.
3-line API: create_payment_request() → send checkout_url() → await_settlement(). That's it.
Bank feed confirmation: Real-time settlement notification, no webhooks to babysit.

Getting Started: Installation & Setup

Install the SDK

pip install agentpay-vn

That's your first step. The SDK is lightweight (~50KB uncompressed) and depends only on standard HTTP libraries.

Set Up MCP Server (Optional but Powerful)

If you're using Claude or planning to delegate payment logic to an AI agent:

pip install agentpay-mcp

Then configure Claude's MCP settings (e.g., in your .cursor/rules or Claude config):

{
  "mcpServers": {
    "agentpay-vn": {
      "command": "python",
      "args": ["-m", "agentpay.mcp"],
      "env": {
        "AGENTPAY_MERCHANT_ID": "your_merchant_id",
        "AGENTPAY_API_KEY": "your_api_key"
      }
    }
  }
}

Once configured, Claude can natively call AgentPay functions—perfect for building conversational payment flows.

Real-World Walkthrough: A Telegram Course-Selling Bot

Let's build a concrete example: TechCourse Bot. A creator sells Python courses ($15–$50 each) via Telegram. When someone messages /buy, the bot:

Asks which course
Generates a VietQR payment link
Sends the checkout link
Waits for settlement confirmation
Delivers course access automatically

Step 1: Create a Payment Request

from agentpay_vn import AgentPay
import json

# Initialize the SDK
agent_pay = AgentPay(
    merchant_id="YOUR_MERCHANT_ID",
    api_key="YOUR_API_KEY"
)

# User buys the "Advanced Python" course for 199,000 VND
payment = agent_pay.create_payment_request(
    amount_vnd=199000,
    order_id="order_adv_python_001",
    description="Advanced Python Course - TechCourse Bot",
    customer_phone="0912345678",
    metadata={
        "course_id": "adv_python",
        "customer_name": "Nguyen Van A",
        "expires_in_minutes": 30
    }
)

print(f"Payment Request Created:")
print(f"  Order ID: {payment['order_id']}")
print(f"  Amount: {payment['amount_vnd']:,} VND")
print(f"  QR Code URL: {payment['qr_code_url']}")
print(f"  Checkout URL: {payment['checkout_url']}")
# Output:
# Payment Request Created:
#   Order ID: order_adv_python_001
#   Amount: 199,000 VND
#   QR Code URL: https://agentpay.servicesai.vn/qr/abc123xyz
#   Checkout URL: https://checkout.agentpay.vn/abc123xyz

Line-by-line:

create_payment_request() takes the amount in VND (Vietnamese Dong), a unique order ID, and optional metadata.
It returns a response with qr_code_url (for inline display) and checkout_url (for sharing via link).
The QR points directly at your bank account—AgentPay is transparent infrastructure.

Step 2: Send to Telegram User

import logging
from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import Application, CommandHandler, ContextTypes

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

async def buy_course(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """Handle /buy command in Telegram."""

    user = update.message.from_user
    course_id = "adv_python"
    amount_vnd = 199000
    order_id = f"order_{course_id}_{user.id}_{int(time.time())}"

    # Create payment request
    payment = agent_pay.create_payment_request(
        amount_vnd=amount_vnd,
        order_id=order_id,
        description=f"Course: Advanced Python",
        customer_phone=user.username or "unknown",
        metadata={"course_id": course_id, "user_id": user.id}
    )

    # Build inline keyboard with payment button
    keyboard = [
        [
            InlineKeyboardButton(
                "💳 Pay 199,000 VND",
                url=payment['checkout_url']
            )
        ]
    ]
    reply_markup = InlineKeyboardMarkup(keyboard)

    # Send message with QR code image and payment link
    await update.message.reply_photo(
        photo=payment['qr_code_url'],
        caption=(
            f"🎓 *Advanced Python Course*\n\n"
            f"💰 Price: 199,000 VND\n"
            f"⏱️ Link expires in 30 minutes\n\n"
            f"Scan the QR or tap the button below 👇"
        ),
        reply_markup=reply_markup,
        parse_mode='Markdown'
    )

    # Store order in memory/database for settlement tracking
    context.user_data['pending_order'] = {
        'order_id': order_id,
        'course_id': course_id,
        'user_id': user.id
    }
    logger.info(f"Payment link sent to {user.id} for order {order_id}")

async def main():
    """Start the bot."""
    app = Application.builder().token("YOUR_TELEGRAM_BOT_TOKEN").build()
    app.add_handler(CommandHandler("buy", buy_course))
    await app.run_polling()

if __name__ == '__main__':
    import asyncio
    asyncio.run(main())

What happens: User taps the button or scans the QR. Their bank app opens with pre-filled details. They confirm. Money lands in your account.

Step 3: Wait for Settlement & Auto-Deliver

import asyncio
from datetime import datetime

async def check_settlement(order_id: str, max_wait_seconds: int = 1800):
    """Poll for payment settlement (30-minute timeout)."""

    start_time = datetime.now()
    poll_interval = 10  # Check every 10 seconds

    while (datetime.now() - start_time).total_seconds() < max_wait_seconds:
        settlement = agent_pay.await_settlement(
            order_id=order_id,
            timeout_seconds=poll_interval
        )

        if settlement['status'] == 'settled':
            logger.info(f"✅ Payment confirmed for {order_id}")
            logger.info(f"   Settled amount: {settlement['amount_vnd']:,} VND")
            logger.info(f"   Settled at: {settlement['settled_at']}")
            return settlement

        elif settlement['status'] == 'pending':
            logger.info(f"⏳ Waiting for settlement: {order_id}")
            await asyncio.sleep(poll_interval)

        else:  # 'expired', 'failed', 'cancelled'
            logger.warning(f"❌ Order {order_id} has status: {settlement['status']}")
            return settlement

    logger.error(f"Timeout waiting for settlement: {order_id}")
    return None

async def process_settlement(user_id: int, course_id: str, order_id: str, context: ContextTypes.DEFAULT_TYPE):
    """Background task to monitor payment and deliver course."""

    try:
        settlement = await check_settlement(order_id)

        if settlement and settlement['status'] == 'settled':
            # Payment confirmed!
            # 1. Generate course access (e.g., unique enrollment link)
            enrollment_link = f"https://courses.example.com/enroll/{course_id}?token=unique_token_123"

            # 2. Send to user
            await context.bot.send_message(
                chat_id=user_id,
                text=(
                    f"🎉 *Payment successful!*\n\n"
                    f"Your course access is ready:\n"
                    f"🔗 {enrollment_link}\n\n"
                    f"Questions? Reply to this message."
                ),
                parse_mode='Markdown'
            )

            # 3. Log to your system
            logger.info(f"Course delivered to user {user_id} for {order_id}")

    except Exception as e:
        logger.error(f"Settlement check failed: {e}")
        await context.bot.send_message(
            chat_id=user_id,
            text="⚠️ Payment verification issue. Please contact support."
        )

# In your /buy handler, spawn the background task:
# asyncio.create_task(process_settlement(user.id, course_id, order_id, context))

The flow: After the user pays, your bot polls await_settlement() every 10 seconds. When the bank confirms the transfer, status changes to 'settled'. You immediately deliver the course—no manual intervention.

Advanced Tips & Patterns

1. Handle Multiple Courses with Dynamic Pricing

COURSES = {
    "python_basics": {"name": "Python Basics", "price_vnd": 99000},
    "adv_python": {"name": "Advanced Python", "price_vnd": 199000},
    "web_dev": {"name": "Web Dev Masterclass", "price_vnd": 349000}
}

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """Show course list with /start."""
    keyboard = [
        [InlineKeyboardButton(f"{data['name']} ({data['price_vnd']:,} VND)", 
                            callback_data=f"buy_{course_id}")]
        for course_id, data in COURSES.items()
    ]
    await update.message.reply_text(
        "📚 Choose a course:",
        reply_markup=InlineKeyboardMarkup(keyboard)
    )

2. Retry Failed Payments Gracefully

MAX_RETRIES = 3

async def retry_payment(order_id: str, user_id: int, context: ContextTypes.DEFAULT_TYPE, attempt: int = 1):
    """Retry payment with backoff."""
    if attempt > MAX_RETRIES:
        await context.bot.send_message(
            chat_id=user_id,
            text="❌ Payment failed after retries. Request a new link: /buy"
        )
        return False

    settlement = await check_settlement(order_id, max_wait_seconds=300)

    if settlement and settlement['status'] == 'settled':
        return True
    else:
        wait_seconds = 2 ** attempt  # Exponential backoff: 2s, 4s, 8s
        await asyncio.sleep(wait_seconds)
        return await retry_payment(order_id, user_id, context, attempt + 1)

3. Use MCP for AI-Driven Payment Workflows

If you're using Claude or another AI agent as your Telegram bot brains:

# Claude can now call:
# tools = [
#   {"name": "create_payment_request", "params": [...] },
#   {"name": "await_settlement", "params": [...] },
#   {"name": "list_orders", "params": [...] }
# ]

# Example: Claude-driven conversation
# User: "I want to buy the web dev course"
# Claude: Calls create_payment_request() → extracts checkout_url → tells user to pay
# User pays
# Claude: Calls await_settlement() → delivers course when confirmed

Do's and Don'ts

Do ✅	Don't ❌
Store `order_id` in a database for audit trails	Store sensitive bank details in Telegram messages
Use unique `order_id` per transaction (include timestamp/user ID)	Rely solely on client-side confirmation—always poll `await_settlement()`
Set reasonable QR expiry (15–30 min) via metadata	Send payment requests without clearing old expired ones
Log all settlement events for reconciliation	Assume payment succeeded without backend verification
Test with small amounts ($1–$5) first	Hardcode prices—fetch from your database
Monitor bank feeds daily	Leave polling tasks unmonitored—add error handling

FAQ

Q: Does AgentPay hold my money?
No. The QR code points directly to your merchant bank account. AgentPay is infrastructure—it never touches funds.

Q: What if a user pays twice by accident?
Each payment request has a unique order_id. Check your bank feed for duplicates and process refunds manually (or automate via bank API). Log duplicates and contact the user.

Q: Can I refund payments?
Yes, via your bank app or API. AgentPay doesn't refund—it's your transaction. Many Vietnamese banks support automated refunds; check yours.

Q: How fast is settlement?
Most Vietnamese banks settle within 1–5 minutes for same-bank transfers, 2–24 hours for cross-bank. AgentPay notifies you via bank feed as soon as it clears.

Q: Is there a fee?
AgentPay itself has no transaction fee (open-source, MIT license). Your bank may charge standard VietQR transfer fees (~0–0.5% depending on the bank).

Key Takeaways

VietQR + Telegram is native to Vietnam: Use what customers already have.
AgentPay is minimal, transparent, and free: No escrow, no complications.
The 3-line flow is genuinely simple: Create → Send → Await. That's payment automation.
Start small: Test with a demo course or coffee shop. Build confidence before scaling.
Monitor settlements daily: Reconcile your bank feed with bot records weekly.
Use metadata wisely: Store course ID, user ID, and expiry—everything you need for post-payment logic.
Combine with AI agents: MCP server unlocks Claude-powered payment conversations—next-level automation.

Next Steps

You now have a blueprint for monetizing on Telegram without payment complexity. Ready to build?

Install: pip install agentpay-vn
Get your merchant ID and API key from your Vietnamese bank (most major banks support VietQR merchant registration—free or low-cost).
Check the docs: agentpay.servicesai.vn/v1/docs for full API reference.
Explore the code: github.com/phuocdu/agentpay-vn — it's open-source, so fork it, extend it, and own it.
Deploy: Host on Railway, Render, or your own VPS. Test with real payments.

Your Telegram bot is about to earn its first payment. That's not far away.

Collect VietQR Payments in Telegram Bots with AgentPay

ServicesAI VN — Tue, 22 Sep 2026 00:15:14 +0000

The Problem: Selling Digital Products Without a Payment Gateway

You've built a Telegram bot that offers something valuable—an online course, design templates, or consulting services. Every day, customers ask how to pay. Your options feel limited: manually send a bank transfer request, ask for a mess of screenshots, or integrate with a complex payment processor that takes 2–5% and demands endless documentation.

Meanwhile, in Vietnam, VietQR is everywhere. Your customers want to scan a QR code and send money directly to your bank account. No middleman. No waiting. But wiring that into a Telegram bot? That's felt like a custom development nightmare—until now.

AgentPay VN changes this. In under 50 lines of Python, you can turn your Telegram bot into a payment collector that generates VietQR codes, sends checkout links, and confirms settlement directly from your bank feed. No holding customer funds. No complex integrations. Just Python, a Telegram bot, and your bank account.

Let's build it.

What is AgentPay VN and Why It Matters

AgentPay VN is an open-source MIT-licensed Python SDK plus an MCP server that lets AI agents (and your own bots) collect VietQR payments. Here's what makes it different:

No escrow or balance: Money flows directly to your merchant bank account. AgentPay never holds a single dong.
Bank-feed confirmation: Settlement status comes from your actual bank, not a third-party API.
Designed for agents: Built for Claude, custom LLMs, and traditional bot scripts—works everywhere.
MIT open-source: Full transparency, no vendor lock-in.
Simple 3-step flow: Create a payment request → send a checkout URL → wait for settlement confirmation.

If you're selling in Vietnam and want frictionless payments without fees eating your margin, this is it.

Installation and Initial Setup

Step 1: Install the SDK

pip install agentpay-vn

That's it. The package includes everything you need to create payment requests and monitor settlements.

Step 2: Set Your Merchant Bank Details

You'll need:

Bank account number (your business or personal account)
Bank code (e.g., 970436 for Techcombank, 970422 for Vietcombank)
Account holder name (exactly as registered at the bank)
Amount to collect (in VND)

Store these securely. AgentPay uses them to generate VietQR codes that point directly to your bank account.

Step 3: Verify Bank Feed Access (Optional but Recommended)

For automatic settlement confirmation, AgentPay can listen to your bank feed. This requires:

Open banking credentials (varies by bank)
Or manual webhook setup from your bank's API portal

Check the docs for your specific bank.

Building a Telegram Payment Bot: Complete Walkthrough

Real Scenario: A Course-Selling Bot

Imagine you're selling a 6-week Python course for ₫299,000. You want a Telegram bot where users:

Click /buy_course
Receive a VietQR checkout link
Scan and pay
Get course access automatically when settled

Here's how to build it with AgentPay and python-telegram-bot:

Code Block 1: Create a Payment Request

from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes
from agentpay_vn import PaymentRequest, AgentPayClient
import uuid

# Initialize AgentPay with your merchant details
client = AgentPayClient(
    bank_account="1234567890",
    bank_code="970436",  # Techcombank
    account_holder="John Nguyen",
)

# Initialize Telegram bot
app = Application.builder().token("YOUR_TELEGRAM_TOKEN").build()

async def handle_buy_course(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    User triggers /buy_course. We create a payment request and send checkout.
    """
    user_id = update.effective_user.id

    # Create a unique payment request
    payment_request = PaymentRequest(
        order_id=f"course_{user_id}_{uuid.uuid4().hex[:8]}",
        amount_vnd=299000,
        description="6-Week Python Mastery Course",
        metadata={"user_id": user_id, "product": "python_course"},
    )

    # Generate VietQR checkout URL
    checkout_url = await client.create_payment_request(payment_request)

    # Send to user with a nice button
    await update.message.reply_text(
        f"🎓 **Python Course - ₫299,000**\n\n"
        f"Ready to level up? Click below to pay securely via VietQR.\n\n",
        reply_markup={
            "inline_keyboard": [
                [{"text": "💳 Pay Now", "url": checkout_url}]
            ]
        },
        parse_mode="Markdown"
    )

    # Store the order_id in context for settlement tracking
    context.user_data["pending_order_id"] = payment_request.order_id

app.add_handler(CommandHandler("buy_course", handle_buy_course))

Line-by-line breakdown:

Lines 6–11: Initialize AgentPayClient with your bank details. These credentials are used to generate VietQR codes pointing to your account.
Line 18: Extract the user's Telegram ID—useful for tracking purchases per user.
Lines 21–27: Create a PaymentRequest object with a unique order ID, the amount (₫299,000), a description, and metadata (we'll use this later to grant access).
Line 30: Call create_payment_request() to generate the VietQR checkout URL. This is a fully formed link with the QR embedded.
Lines 33–40: Send the checkout URL as an inline button. The user taps it, scans the QR, and pays from their banking app.
Line 44: Store the order ID so we can track settlement later.

Code Block 2: Monitor Settlement and Grant Access

import asyncio
from agentpay_vn import SettlementChecker

# Initialize settlement checker (uses bank feed)
settlement_checker = SettlementChecker(
    bank_account="1234567890",
    bank_code="970436",
    # Bank feed credentials or webhook endpoint (see docs)
)

async def monitor_settlement(user_id: int, order_id: str, context: ContextTypes.DEFAULT_TYPE):
    """
    Poll for settlement confirmation, then grant course access.
    """
    max_wait_seconds = 600  # Wait up to 10 minutes
    check_interval = 5     # Check every 5 seconds
    elapsed = 0

    while elapsed < max_wait_seconds:
        # Check if payment settled from bank feed
        settlement_status = await settlement_checker.await_settlement(
            order_id=order_id,
            amount_vnd=299000,
            timeout_seconds=5,
        )

        if settlement_status.is_settled:
            # Payment confirmed! Grant access.
            await context.bot.send_message(
                chat_id=user_id,
                text=(
                    "✅ **Payment Received!**\n\n"
                    "Welcome to the 6-Week Python Course. Your course access is active.\n\n"
                    "📚 Start here: <a href="https://yoursite.com/course">Course Dashboard</a>\n"
                ),
                parse_mode="Markdown"
            )

            # Log success (you'd typically save to DB)
            print(f"User {user_id} paid for course. Order: {order_id}")
            return True

        # Not yet settled; wait and retry
        await asyncio.sleep(check_interval)
        elapsed += check_interval

    # Timeout: payment didn't come through
    await context.bot.send_message(
        chat_id=user_id,
        text="⏱️ Payment not received after 10 minutes. Please try again."
    )
    return False

# Attach to the payment creation flow:
async def handle_buy_course(update: Update, context: ContextTypes.DEFAULT_TYPE):
    # ... [payment request code from above] ...

    # Start settlement monitoring in background
    asyncio.create_task(
        monitor_settlement(
            user_id=update.effective_user.id,
            order_id=payment_request.order_id,
            context=context
        )
    )

What's happening here:

Lines 4–8: Create a SettlementChecker tied to your bank. This queries your actual bank account to confirm money arrived.
Lines 10–45: Define monitor_settlement(). It polls the bank feed every 5 seconds for up to 10 minutes.
Lines 16–22: Call await_settlement() with the order ID and amount. AgentPay checks your bank feed for a matching transaction.
Lines 24–33: If settled, send a confirmation message and grant access (in real apps, you'd update your DB).
Lines 42–48: If timeout occurs (no payment after 10 minutes), remind the user to try again.

The key insight: AgentPay never holds the money. It's simply confirming that your bank received it.

Setting Up AgentPay with MCP Servers (For AI Agents)

If you're building AI agents that handle payments (e.g., Claude + AgentPay), use the MCP server:

Install the MCP Server

pip install agentpay-mcp

MCP Configuration for Claude (Claude.json)

{
  "mcpServers": {
    "agentpay": {
      "command": "python",
      "args": ["-m", "agentpay_mcp"],
      "env": {
        "AGENTPAY_BANK_ACCOUNT": "1234567890",
        "AGENTPAY_BANK_CODE": "970436",
        "AGENTPAY_ACCOUNT_HOLDER": "John Nguyen",
        "AGENTPAY_BANK_FEED_KEY": "your_bank_feed_api_key"
      }
    }
  }
}

Once configured, Claude can:

Call agentpay:create_payment_request to generate checkout links
Call agentpay:check_settlement to confirm payments
Automate refunds or adjustments

This is powerful for agentic workflows where you want Claude to handle payments autonomously.

Best Practices and Do's/Don'ts

Do's and Don'ts

✅ Do	❌ Don't
Store `order_id` in your database to reconcile	Rely on user's word that they paid
Use bank feed for settlement confirmation	Trust Telegram notifications alone
Set timeouts (5–10 min) for settlement checks	Loop forever if payment doesn't arrive
Log all transactions (order_id, user_id, amount)	Forget to track who paid for what
Regenerate QR for retry (new order_id)	Reuse QR codes or send identical links
Keep bank credentials in environment variables	Hardcode credentials in your repo

Advanced Tip: Webhook-Based Settlement

Instead of polling, configure your bank to send webhooks when money arrives:

from fastapi import FastAPI, HTTPException

app = FastAPI()

@app.post("/webhook/bank-settlement")
async def handle_bank_webhook(payload: dict):
    """
    Your bank sends a webhook when transaction arrives.
    Payload includes order_id, amount, timestamp.
    """
    order_id = payload.get("order_id")
    amount = payload.get("amount")

    # Verify signature (varies by bank)
    if not verify_bank_signature(payload):
        raise HTTPException(status_code=403, detail="Invalid signature")

    # Grant access, send confirmation, etc.
    await grant_course_access(order_id)
    return {"status": "success"}

Webhooks are faster and more reliable than polling.

Real-World Example: Café Merch Shop

A coffee roastery uses AgentPay to sell their signature blend (₫185,000/kg) via Telegram:

User: /buy_merch
Bot shows product + VietQR
User scans and pays from their bank
Bank settles in ~5 seconds
AgentPay confirms → Bot sends shipping address form
Café prepares and ships

Result: Zero payment friction, no fees, direct bank settlement. The café owner checks their bank statement the next day and sees the order clearly labeled with customer metadata.

FAQ

Q: Does AgentPay hold my customer's money?
No. AgentPay generates a VietQR that points directly to your bank account. Money bypasses AgentPay entirely.

Q: What if my bank doesn't support open banking?
You can manually confirm settlements or ask your bank for a webhook API. See docs for your specific bank.

Q: Can I use AgentPay without Telegram?
Absolutely. It's a general Python SDK—use it with Discord, WhatsApp, Slack, or any bot platform.

Q: What are typical VietQR payment times?
Most transfers settle in 5–30 seconds. AgentPay checks your bank feed, so you see confirmation almost instantly.

Q: Is there a transaction fee?
No. AgentPay is open-source and free. Your bank may charge a standard domestic transfer fee (usually ₫0–5,000).

Key Takeaways

AgentPay VN is a Python SDK + MCP server for collecting VietQR payments in bots and AI agents.
Install in seconds with pip install agentpay-vn; no complex integrations.
Money flows directly to your bank account—AgentPay never holds customer funds.
Three-step flow: create a payment request, send the checkout URL, await settlement confirmation from your bank.
Built for scale: Works with Telegram bots, AI agents (Claude/MCP), Discord, and more.
MIT open-source: Full control, no vendor lock-in, transparent code on GitHub.
Use bank feeds or webhooks for settlement confirmation—polling works, but webhooks are faster.

Next Steps: Get Started

Ready to add VietQR payments to your bot?

Install AgentPay: pip install agentpay-vn
Review the full docs: agentpay.servicesai.vn/v1/docs
Explore the source: github.com/phuocdu/agentpay-vn
Try the examples: Copy the code blocks above and adapt them to your bot.

Your customers in Vietnam want to pay via VietQR. AgentPay makes it dead simple. Build it today.

Build a Paid MCP Server: Charge Users Inside Claude

ServicesAI VN — Sat, 12 Sep 2026 00:23:34 +0000

The Problem: AI Agents Need Money Too

You've built a powerful Model Context Protocol (MCP) server. Maybe it's a research tool, a code generator, or a content analyzer. Claude's ecosystem loves it. Users are asking for it. But here's the friction:

How do you collect payment when Claude is orchestrating the entire interaction?

Traditional payment flows break the agent's autonomy. You can't redirect to Stripe's checkout and expect Claude to handle it gracefully. You need a payment solution that:

Works inside the Claude environment
Executes in milliseconds (no lengthy redirects)
Settles instantly to your bank account
Never touches your server's memory

That's exactly the problem AgentPay VN solves.

Why AgentPay VN Changes the Game

AgentPay VN is an open-source Python SDK (MIT license) + MCP server that lets AI agents collect VietQR payments—Vietnam's standardized QR payment format—without ever holding funds.

Here's what makes it different:

Zero liability: Money flows directly from customer → merchant bank account. Your server never touches the funds.
Bank-confirmed settlement: A bank feed verifies payment confirmation before your agent continues.
AI-native: Designed to work with Claude's decision-making, not against it.
Three-step flow: create_payment_request → send_checkout_url → await_settlement.
Drop-in integration: Install with pip install agentpay-vn and integrate in under 20 minutes.

Unlike Stripe or PayPal, there's no long-lived session state, no webhook complexity, and no redirect fatigue.

Architecture: How Payments Flow Through Claude

When Claude uses an AgentPay MCP server, here's what happens:

Claude Agent                AgentPay MCP Server          VietQR/Bank
    |                              |                          |
    |--[request payment]---------->|                          |
    |                              |--[create QR code]------->|
    |<--[checkout URL]-------------|                          |
    |                              |                          |
    |--(sends to user)------------>| (user scans QR)          |
    |                              |                          |
    |                              |<--[payment received]-----|
    |<--[await_settlement OK]------|                          |
    |                              |                          |
    |--(continues workflow)------->|

The agent never waits blindly. It polls the settlement status, and the bank feed confirms the money arrived. Only then does it proceed.

Getting Started: Installation & Setup

Step 1: Install the SDK

pip install agentpay-vn

Step 2: Set Your Bank Details

Create a .env file in your project:

# .env
MERCHANT_BANK_ACCOUNT=1234567890
MERCHANT_BANK_NAME=VietcomBank  # or your Vietnamese bank
MERCHANT_NAME="Your Business Name"
AGENTPAY_API_KEY=your_api_key_here  # from agentpay.servicesai.vn/v1/docs

Step 3: Start the MCP Server

agentpay-mcp

This boots a local server on http://localhost:3000 exposing AgentPay's tools to Claude.

Code Example 1: Basic Payment Request Flow

Here's a minimal Python script showing how to create and await a payment:

from agentpay_vn import PaymentClient
import asyncio
import os

# Initialize the client
client = PaymentClient(
    api_key=os.getenv("AGENTPAY_API_KEY"),
    merchant_bank="VietcomBank",
    merchant_account="1234567890"
)

async def charge_user_for_premium_feature():
    """
    Example: User wants to unlock a premium report.
    Price: 50,000 VND (~$2 USD)
    """

    # Step 1: Create a payment request
    payment = await client.create_payment_request(
        amount_vnd=50000,
        description="Premium Report - Monthly Subscription",
        customer_name="Nguyen Van A",
        order_id="ORD_2024_001"
    )
    # Returns: { 'id': 'pay_abc123', 'checkout_url': 'https://...qr...', 'expires_at': '2024-...' }

    print(f"Send this URL to customer: {payment['checkout_url']}")
    # The customer receives a link with an embedded VietQR code.
    # They scan it with their banking app and confirm payment.

    # Step 2: Wait for settlement
    # Poll every 2 seconds (bank feed updates within 10-30 seconds in Vietnam)
    settlement = await client.await_settlement(
        payment_id=payment['id'],
        poll_interval_seconds=2,
        max_wait_seconds=120
    )

    if settlement['status'] == 'confirmed':
        print(f"✓ Payment received! {settlement['amount_vnd']} VND")
        print(f"  Settlement ref: {settlement['bank_ref']}")
        # Money is now in your merchant account.
        # Unlock the premium feature for this user.
        return True
    else:
        print("✗ Payment timeout or cancelled.")
        return False

# Run it
asyncio.run(charge_user_for_premium_feature())

Line-by-line explanation:

create_payment_request(): Generates a unique VietQR code for this transaction. Returns a checkout URL and payment ID.
await_settlement(): Polls the bank feed (via AgentPay's cloud relay) every 2 seconds. The bank confirms the money within 10–30 seconds. Once confirmed, you proceed.
No redirect, no session, no webhook complexity.

Code Example 2: MCP Server Configuration for Claude

To expose AgentPay tools to Claude, configure your MCP server in Claude's config.json (or equivalent):

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "env": {
        "AGENTPAY_API_KEY": "your_api_key",
        "MERCHANT_BANK": "VietcomBank",
        "MERCHANT_ACCOUNT": "1234567890",
        "MERCHANT_NAME": "Your Shop"
      }
    }
  }
}

Once configured, Claude gains access to three tools:

create_payment_request - Initiates a charge.
get_payment_status - Checks if customer has paid (non-blocking).
await_settlement - Blocks until payment confirmed (typically 10–30 seconds).

Claude automatically routes through these based on your agent's logic.

Real-World Example: Online Course Checkout Bot

Imagine you run an online Python course platform. A user messages Claude:

"I want to buy your 'Advanced Async Patterns' course."

Here's what Claude orchestrates:

1. Claude: "Great! That's 199,000 VND. Let me create a payment link."
   → Calls: create_payment_request(amount_vnd=199000, description="Advanced Async Patterns Course")

2. Claude: "Scan this QR code with your bank app to confirm."
   → Sends checkout_url to user

3. [User scans QR and confirms payment in their bank app: ~10 seconds]

4. Claude: [Non-blocking check] "Is payment confirmed?"
   → Calls: get_payment_status() → Returns: pending

5. Claude: [Waits] "Still processing..."
   → Calls: await_settlement() [polls internally]

6. [Bank feed confirms payment received]

7. Claude: "✓ Payment confirmed! Here's your course access link and login."
   → Sends enrollment credentials

Total time: 40–50 seconds. No page redirects. No session timeouts. No confusion.

Advanced Tips: Handling Edge Cases

Tip 1: Retry Logic for Network Blips

from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=2, max=10))
async def robust_await_settlement(client, payment_id):
    return await client.await_settlement(payment_id, poll_interval_seconds=3)

If the bank feed is briefly unavailable, retry with exponential backoff.

Tip 2: Multi-Currency Pricing

VietQR is VND-only, but you can accept USD by converting at real-time rates:

import httpx

async def usd_to_vnd(usd_amount):
    async with httpx.AsyncClient() as client:
        r = await client.get("https://api.exchangerate-api.com/v4/latest/USD")
        rate = r.json()["rates"]["VND"]
        return int(usd_amount * rate)

usd_price = 10  # $10
vnd_price = await usd_to_vnd(usd_price)  # ~250,000 VND
await agentpay.create_payment_request(amount_vnd=vnd_price, ...)

Tip 3: Timeout Handling

If a user abandons the QR code, your agent should gracefully exit:

try:
    settlement = await client.await_settlement(
        payment_id=payment['id'],
        max_wait_seconds=300  # 5 minutes
    )
except TimeoutError:
    print("User didn't pay within 5 minutes. Cancelling order.")
    await client.cancel_payment(payment['id'])

Do's and Don'ts

Do	Don't
✓ Create a new payment request per order.	✗ Reuse payment IDs across customers.
✓ Await settlement before unlocking access.	✗ Trust `get_payment_status()` alone; always use `await_settlement()` for critical paths.
✓ Store `order_id` in your DB for reconciliation.	✗ Assume the transaction succeeded without bank confirmation.
✓ Set reasonable timeouts (3–5 min).	✗ Wait indefinitely; users may abandon payment.
✓ Log settlement refs for support tickets.	✗ Ignore the `bank_ref` field; it's your proof of payment.

Deployment Checklist

Before going live:

[ ] Test with a real VietQR bank account (AgentPay supports major Vietnamese banks).
[ ] Set .env variables in your production environment (never hardcode API keys).
[ ] Use a queue (Redis, RabbitMQ) to decouple payment polling from Claude's main thread.
[ ] Implement idempotency: if Claude retries, use the same order_id to avoid duplicate charges.
[ ] Monitor bank feed latency; set alerts if confirmations exceed 60 seconds.
[ ] Log all payment events to a database for PCI compliance and dispute resolution.

FAQ

Q: Does AgentPay hold customer money?
No. The VietQR code directs payment straight to your bank account. AgentPay only relays the bank's settlement confirmation. You own the money immediately.

Q: What if the bank feed is delayed?
Vietnam's VietQR system typically confirms within 10–30 seconds. If you hit the timeout, gracefully ask the user to retry or contact support. AgentPay provides a bank_ref for manual reconciliation.

Q: Can I charge non-Vietnamese customers?
VietQR is Vietnam-specific. Non-Vietnamese users must have a Vietnamese bank account to pay. If you need international support, consider pairing AgentPay with Stripe for non-VN users.

Q: Is my customer's banking data secure?
Yes. AgentPay never stores banking credentials. VietQR is a standardized, bank-issued QR protocol with built-in encryption. Your server only sees the payment confirmation, not the customer's account details.

Key Takeaways

AgentPay VN enables AI agents to collect real money without breaking the conversational flow.
Three-step integration: install SDK, configure MCP, call three functions (create_payment_request, get_payment_status, await_settlement).
Money goes straight to your bank; AgentPay is a relay only, removing liability and complexity.
VietQR is instant: 10–30 second confirmation means users don't wait around.
Perfect for: courses, reports, subscriptions, premium features, consultations—anything Claude offers that has value.
Deployment is simple: single .env file, single MCP config, robust retry logic.

Next Steps

Ready to monetize your Claude agent?

Install AgentPay VN: pip install agentpay-vn
Read the full docs: https://agentpay.servicesai.vn/v1/docs
Explore the source code: https://github.com/phuocdu/agentpay-vn
Start the MCP server: agentpay-mcp
Build your first paid agent and share it with us!

The future of AI commerce runs through agents. AgentPay VN is your bridge to revenue.

Build a Payment-Collecting Telegram Bot with VietQR

ServicesAI VN — Thu, 10 Sep 2026 00:21:33 +0000

The Problem: Accepting Payments in Telegram Is a Nightmare

You've built a Telegram bot that sells digital products—online courses, design templates, or meal subscriptions. Your customers are already in Telegram. They're ready to pay. But then you hit the wall: integrating a payment gateway requires complex webhook setups, holding customer money in a merchant account, or routing payments through third-party aggregators that take 3–5% cuts and delay settlements by days.

Worse, you need to manage account balances, reconcile transactions, and handle refunds manually. It's 2025; this shouldn't be this hard.

AgentPay VN solves this. It's an open-source Python SDK that lets your Telegram bot generate a VietQR code pointing directly to your bank account—no escrow, no middleman, no delays. Your customer scans the QR with their mobile banking app, pays you instantly, and your bot automatically confirms the order. Settlement lands in your bank within minutes.

What Is AgentPay VN? The Five-Second Version

AgentPay VN is a MIT-licensed Python SDK built for AI agents and bots to collect Vietnamese payments via VietQR. Here's what makes it different:

Direct bank transfers: QR codes point to your bank account, not a middleman wallet.
Zero holding: AgentPay never touches money. You get paid straight into your bank.
Instant confirmation: Bank feed integration verifies settlement in seconds, not hours.
AI-native: Built as an MCP (Model Context Protocol) server, so Claude and other AI agents can trigger payments natively.
Open source: Full MIT license. Run it yourself, fork it, modify it.

Installation is one command:

pip install agentpay-vn

That's genuinely it.

How It Works: The Three-Line Payment Flow

Before we code, understand the mental model. Every payment follows this pattern:

1. create_payment_request()  → Generate a unique payment link + QR
2. send checkout_url()       → Display QR to customer in Telegram
3. await_settlement()        → Wait for bank confirmation, unlock order

That's the entire lifecycle. No polling. No cron jobs. Just request → link → settle.

Step 1: Install and Configure AgentPay

Installation

# Install the SDK
pip install agentpay-vn

# If you're building a Claude-integrated bot, also install the MCP server
pip install agentpay-mcp

Set Up Your Bank Details

AgentPay needs your bank account and VietQR information. Create a .env file in your project:

# .env
BANK_ACCOUNT_NUMBER=0123456789
BANK_CODE=BIDV  # or VCOMBANK, ACB, etc.
BANK_ACCOUNT_NAME="Your Full Legal Name"
MERCHANT_ID=your_merchant_id  # From your bank or VietQR provider

These details ensure QR codes point to your account, not AgentPay's.

Step 2: Build Your First Payment-Enabled Telegram Bot

Let's create a simple bot that sells a 50,000 VND e-book. Here's the full code:

Python Code: Core Bot Logic

import os
from dotenv import load_dotenv
from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import Application, CommandHandler, ContextTypes, CallbackQueryHandler
from agentpay_vn import AgentPayClient, PaymentRequest
import asyncio

load_dotenv()

# Initialize AgentPay client
agentpay = AgentPayClient(
    bank_account=os.getenv("BANK_ACCOUNT_NUMBER"),
    bank_code=os.getenv("BANK_CODE"),
    account_name=os.getenv("BANK_ACCOUNT_NAME"),
    merchant_id=os.getenv("MERCHANT_ID")
)

# Initialize Telegram bot
app = Application.builder().token(os.getenv("TELEGRAM_TOKEN")).build()

# Product catalog
PRODUCTS = {
    "ebook": {"name": "Python Mastery E-Book", "price": 50000, "file_id": "python_ebook.pdf"}
}

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """Show product menu."""
    keyboard = [[InlineKeyboardButton("📖 Buy E-Book (50,000 VND)", callback_data="buy_ebook")]]
    reply_markup = InlineKeyboardMarkup(keyboard)
    await update.message.reply_text(
        "Welcome! Here's what we offer:",
        reply_markup=reply_markup
    )

async def buy_product(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """Handle purchase button press."""
    query = update.callback_query
    product_key = query.data.replace("buy_", "")
    product = PRODUCTS[product_key]

    # Step 1: Create payment request
    payment_request = PaymentRequest(
        amount=product["price"],
        description=f"Purchase: {product['name']}",
        order_id=f"order_{update.effective_user.id}_{int(asyncio.get_event_loop().time())}",
        customer_id=str(update.effective_user.id)
    )

    # Step 2: Generate QR and checkout URL
    qr_code, checkout_url = agentpay.create_payment_request(payment_request)

    # Send QR code image to customer
    await query.message.reply_photo(
        photo=qr_code,
        caption=(
            f"🏧 Scan to pay {product['price']:,} VND\n\n"
            f"Or tap here: {checkout_url}\n\n"
            f"We'll deliver your {product['name']} once payment confirms!"
        )
    )

    # Step 3: Wait for settlement (non-blocking)
    context.application.create_task(
        wait_for_payment(update.effective_user.id, payment_request.order_id, product_key, context)
    )

async def wait_for_payment(user_id: int, order_id: str, product_key: str, context: ContextTypes.DEFAULT_TYPE):
    """Poll for payment confirmation."""
    max_wait = 300  # 5 minutes
    elapsed = 0

    while elapsed < max_wait:
        # Check if payment settled
        settlement = agentpay.await_settlement(order_id, timeout=10)

        if settlement["status"] == "confirmed":
            # Payment received!
            product = PRODUCTS[product_key]
            await context.bot.send_message(
                chat_id=user_id,
                text=(
                    f"✅ Payment received! {settlement['amount']:,} VND\n\n"
                    f"Your {product['name']} is ready. Download: [link to file]"
                )
            )
            return

        elapsed += 10
        await asyncio.sleep(10)

    # Timeout
    await context.bot.send_message(
        chat_id=user_id,
        text="⏱️ Payment timeout. Please try again."
    )

# Register handlers
app.add_handler(CommandHandler("start", start))
app.add_handler(CallbackQueryHandler(buy_product, pattern="buy_"))

if __name__ == "__main__":
    app.run_polling()

Line-by-Line Explanation

Lines 13–18: Initialize AgentPay with your bank details from .env.
Lines 21–22: Set up the Telegram bot.
Lines 35–42: /start command shows a button to buy the e-book.
Lines 44–73: When user clicks "Buy", we:
- Create a PaymentRequest with amount and order ID.
- Call create_payment_request() to get QR code and URL.
- Send the QR to the user.
- Spawn an async task to monitor payment.
Lines 75–102: wait_for_payment() polls the bank feed every 10 seconds. When settlement is confirmed, deliver the product.

Key insight: The entire flow is non-blocking. Your bot can handle 1,000 concurrent payments without freezing.

Step 3: Connect Claude (or Any AI Agent) via MCP

Want Claude to autonomously handle payment collection? Use the MCP server.

MCP Configuration for Claude Desktop

Create or edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the Windows equivalent:

{
  "mcpServers": {
    "agentpay": {
      "command": "python",
      "args": ["-m", "agentpay_mcp"],
      "env": {
        "BANK_ACCOUNT_NUMBER": "0123456789",
        "BANK_CODE": "BIDV",
        "BANK_ACCOUNT_NAME": "Your Name",
        "MERCHANT_ID": "your_id"
      }
    }
  }
}

Now Claude can call AgentPay functions natively:

User: "Set up a payment for 100,000 VND for a course enrollment."

Claude: I'll create a payment request for you.
→ Calls: create_payment_request(amount=100000, description="Course Enrollment")
→ Returns QR code and checkout URL

Claude: Here's your QR code. Scan it to pay 100,000 VND. I'll notify you once settled.

Real-World Example: An Online Course Bot

Imagine you run an online Python course and sell it via Telegram for 299,000 VND.

Customer joins Telegram group → Bot shows "Enroll" button.
Customer clicks → Bot generates VietQR payment link.
Customer scans QR → Pays from mobile banking app (2–3 seconds).
Settlement arrives → Bank confirms within 30 seconds.
Bot gets notification → Automatically adds customer to course channel, sends access link.
No refund headaches → If customer disputes, bank handles it (not you).

Money flow:

Customer Bank Account
        ↓ (scans QR, pays 299,000 VND)
Your Bank Account ← Money lands here instantly
        ↓ (AgentPay reads bank feed)
Your Bot ← Confirmation received
        ↓ (unlocks course access)
Customer Gets Course

Total latency: 45 seconds from scan to access.

Advanced Tips & Best Practices

1. Handle Payment Disputes

VietQR payments are bank transfers. If a customer disputes payment, the bank handles the chargeback, not you. Your bot should still keep logs:

# Log all payments to a database
from datetime import datetime

def log_payment(order_id, user_id, amount, status):
    with open("payments.log", "a") as f:
        f.write(f"{datetime.now()} | {order_id} | {user_id} | {amount} | {status}\n")

2. Retry Failed Payments

If await_settlement() times out, regenerate the QR instead of re-using it:

# Don't reuse order_id; create a new one
new_payment = PaymentRequest(
    amount=product["price"],
    order_id=f"order_{user_id}_{int(time.time())}_retry",  # New ID
    description=f"Retry: {product['name']}"
)

3. Test with Mock Settlements

AgentPay supports a test mode. Set AGENTPAY_ENV=test to simulate payments without real money:

AGENTPAY_ENV=test python your_bot.py

Do's and Don'ts

✅ Do	❌ Don't
Generate a unique order ID per payment	Reuse order IDs or QR codes
Store `order_id` and `customer_id` for records	Rely on settlement being instant (use 30–60 sec timeout)
Log all payments for tax/audit purposes	Assume QR code is valid forever (regenerate on retry)
Use MCP for AI-to-payment integration	Hold customer data longer than needed (GDPR)
Test with `AGENTPAY_ENV=test` first	Hardcode bank details in code (use `.env`)

Frequently Asked Questions

Q: Does AgentPay hold my money?

A: No. AgentPay never touches your funds. The QR code points directly to your bank account. Money lands in your bank account; AgentPay only reads the settlement from the bank feed.

Q: How fast is payment confirmation?

A: Typically 30–60 seconds after the customer pays. VietQR is a bank transfer, so it's as fast as your bank's feed updates (usually real-time).

Q: Can I use this outside Vietnam?

A: No. VietQR and the bank integration currently work only for Vietnamese banks. If you need international payments, consider Stripe or PayPal alongside AgentPay.

Q: What happens if the customer's payment fails?

A: The money never leaves their account. Your bot will timeout waiting for settlement. You can then ask the customer to retry, and AgentPay will generate a new QR code.

Key Takeaways

VietQR is instant, direct, and zero-fee: Money goes straight to your bank.
AgentPay is open-source MIT: You own the code, run it yourself, modify as needed.
Three-step flow: Create request → Send QR → Await settlement.
Telegram + Payments = Seamless UX: Customers never leave the app.
AI-native via MCP: Claude and other agents can trigger payments automatically.
Production-ready: Used by Vietnamese merchants for courses, e-commerce, and subscriptions.

Get Started Now

Install AgentPay VN:

pip install agentpay-vn

Read the full docs:
→ https://agentpay.servicesai.vn/v1/docs

Fork the repository:
→ https://github.com/phuocdu/agentpay-vn

Your Telegram bot can accept payments in minutes, not weeks. Build it today.

Build a Telegram Payment Bot with VietQR & AgentPay

ServicesAI VN — Thu, 27 Aug 2026 00:45:44 +0000

The Problem: Why Telegram Bots Need Native Payment Support

Imagine you're running an online Vietnamese course platform. Students find you via Telegram, join your bot, and ask about enrollment. You send them a payment link—but it takes them outside the app, adds friction, and half abandon the checkout. Or worse: you're a café owner using a Telegram bot for orders, and customers can't pay directly in chat. They text you asking for bank details, you manually verify transfers, and your back-office becomes a mess.

This is where most Telegram payment integrations fail. They either:

Require API heavy lifting – integrating Stripe, MoMo, or ZaloPay feels overkill for small merchants
Hold customer money – payment processors take days to settle, and you're liable for disputes
Don't work with local QR codes – VietQR is ubiquitous in Vietnam, but few tools support it natively in chat apps

AgentPay VN solves all three. In under 50 lines of Python, you can embed instant, settlement-confirmed VietQR payments directly into your Telegram bot. No escrow. No delays. Money lands in your bank account within hours, and your bot confirms it automatically.

Let's build one.

Why VietQR + Telegram Is the Perfect Pairing

VietQR is Vietnam's standardized QR code format. It's printed on every receipt, every bill, every storefront. Your customers already trust it. When a Telegram bot shows them a VietQR code, they don't think "another scam payment link"—they think "normal bank payment."

AgentPay VN treats VietQR as a first-class citizen:

No escrow: QR points straight to your real bank account (BID, Vietcombank, Techcombank, BIDV, etc.)
Settlement confirmed: Bank feeds tie to the payment request; when money arrives, your bot knows
AI-native: Built for MCP servers—Claude, ChatGPT, and other AI agents can trigger payments programmatically
MIT licensed: Fork it, customize it, ship it

The typical flow takes 3 seconds:

User says "I want to buy"
Bot calls create_payment_request()
Bot displays QR code, awaits bank settlement
Payment confirmed → deliver product/service

Installation & Setup

Step 1: Install the SDK

pip install agentpay-vn

Verify it works:

python -c "from agentpay_vn import create_payment_request; print('✓ AgentPay VN installed')"

Step 2: Get Your Merchant Info

You'll need:

Bank account holder name (your name or business name)
Bank account number (10-20 digits, depends on bank)
Bank code (e.g., 970418 for Techcombank, 970010 for BIDV)
Transaction description (optional, shows on customer's statement)

Find your bank code here: VietQR bank list

Step 3: Set Environment Variables (Optional)

For security, store your merchant details in .env:

export AGENTPAY_ACCOUNT_NAME="Nguyen Van A"
export AGENTPAY_ACCOUNT_NUMBER="0123456789"
export AGENTPAY_BANK_CODE="970418"

Or pass them directly in your code (we'll show both below).

Building Your First Payment Flow

The 3-Step Pattern

Here's the complete flow for a Telegram bot:

from agentpay_vn import create_payment_request, await_settlement
import os
from telegram import Update
from telegram.ext import ContextTypes

# Initialize AgentPay with your merchant details
merchant_account = {
    "account_name": os.getenv("AGENTPAY_ACCOUNT_NAME"),
    "account_number": os.getenv("AGENTPAY_ACCOUNT_NUMBER"),
    "bank_code": os.getenv("AGENTPAY_BANK_CODE"),
}

async def handle_purchase(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    User sends /buy command → bot creates payment request → displays QR → awaits settlement
    """

    # STEP 1: Create the payment request
    payment_request = create_payment_request(
        amount=299_000,  # 299,000 VND for example course
        description="Online Python Course - 3 Months Access",
        merchant=merchant_account,
        request_id=f"telegram_{update.effective_user.id}_{update.message.date}",  # Unique ID
    )

    # payment_request contains:
    # - qr_code (PNG bytes)
    # - checkout_url (for sharing outside Telegram)
    # - settlement_reference (to verify later)
    # - expires_at (usually 15 minutes)

    # STEP 2: Send the QR code to user
    await update.message.reply_photo(
        photo=payment_request["qr_code"],
        caption=(
            f"💳 Scan to pay: {payment_request['amount']:,} VND\n"
            f"📝 {payment_request['description']}\n"
            f"⏰ Expires in 15 minutes\n\n"
            f"Your course access unlocks instantly after payment."
        ),
    )

    # Store the settlement reference for later verification
    context.user_data["pending_settlement"] = payment_request["settlement_reference"]

    # STEP 3: Wait for settlement (non-blocking)
    # In production, you'd use a background job queue. For this example:
    try:
        settlement = await_settlement(
            settlement_reference=payment_request["settlement_reference"],
            timeout_seconds=900,  # Wait up to 15 minutes
        )

        # Payment confirmed! Deliver the product
        await update.effective_user.send_message(
            text=(
                f"✅ Payment confirmed!\n\n"
                f"Amount: {settlement['amount']:,} VND\n"
                f"Settled at: {settlement['settled_at']}\n\n"
                f"Your course access is active. Login here: https://example.com/courses"
            )
        )

        # Log the transaction
        print(f"[PAYMENT] User {update.effective_user.id} paid {settlement['amount']} VND")

    except TimeoutError:
        await update.effective_user.send_message(
            "⏱️ Payment window expired. Please try again or contact support."
        )

# Wire this into your telegram.ext.Application

Line-by-Line Breakdown

Line 18-26 (create_payment_request):

amount: Payment in VND (must be integer)
description: What's being sold (shown on QR + bank statement)
merchant: Your bank details
request_id: Unique per transaction; we use user ID + timestamp

Line 32 (reply_photo):

Telegram automatically renders PNG QR codes. User scans with any banking app.
Caption explains the amount and deadline (15 minutes by default)

Line 42 (await_settlement):

Blocks until payment clears or times out
In production, wrap this in a Celery/RQ background task so your bot doesn't hang
settlement_reference ties the QR to the bank transaction

Real-World Example: A Café Order Bot

Let's say you run a café and want customers to order & pay via Telegram:

from agentpay_vn import create_payment_request, await_settlement
import asyncio

class CaféOrderBot:
    def __init__(self):
        self.orders = {}  # Track pending orders
        self.merchant = {
            "account_name": "Cafe Nguyen Coffee",
            "account_number": "0987654321",
            "bank_code": "970418",
        }

    async def process_order(self, user_id: str, items: list, total: int):
        """
        Example: user orders 2 iced coffees + 1 pastry = 85,000 VND
        """

        # Create payment
        payment = create_payment_request(
            amount=total,
            description=f"Café Order: {', '.join(items)}",
            merchant=self.merchant,
            request_id=f"cafe_{user_id}_{int(asyncio.get_event_loop().time())}",
        )

        # Store order
        self.orders[payment["settlement_reference"]] = {
            "user_id": user_id,
            "items": items,
            "amount": total,
            "qr_code": payment["qr_code"],
            "status": "awaiting_payment",
        }

        # Return QR for display
        return payment

    async def confirm_and_fulfill(self, settlement_reference: str):
        """
        Called when payment settles—trigger order fulfillment
        """

        order = self.orders[settlement_reference]
        order["status"] = "paid"

        # Send to kitchen
        print(f"🍳 [KITCHEN] Order for {order['user_id']}: {order['items']}")

        # Could integrate with kitchen display system (KDS) here
        # Notify customer
        return {
            "message": f"✅ Order confirmed! Ready in ~10 minutes. Pickup #42",
            "pickup_number": 42,
        }

In your Telegram handler, you'd call this and show the QR:

café = CaféOrderBot()

async def /order(update, context):
    # User selected items in inline menu
    items = ["Iced Americano", "Iced Americano", "Croissant"]
    total = 85_000

    payment = await café.process_order(str(update.effective_user.id), items, total)

    await update.message.reply_photo(
        photo=payment["qr_code"],
        caption=f"Pay {total:,} VND to confirm your order 🍵"
    )

    # Background task: await settlement
    settlement = await_settlement(payment["settlement_reference"], timeout_seconds=600)

    result = await café.confirm_and_fulfill(payment["settlement_reference"])
    await update.effective_user.send_message(result["message"])

Using AgentPay with AI Agents (MCP Server)

If you're building AI agents (Claude, ChatGPT plugins), use the MCP server:

pip install agentpay-mcp
agentpay-mcp --port 3001

Then configure Claude's MCP client (e.g., in Claude Desktop):

{
  "mcpServers": {
    "agentpay": {
      "command": "python",
      "args": ["-m", "agentpay_mcp"],
      "env": {
        "AGENTPAY_ACCOUNT_NAME": "Your Business",
        "AGENTPAY_ACCOUNT_NUMBER": "0123456789",
        "AGENTPAY_BANK_CODE": "970418"
      }
    }
  }
}

Now an AI agent can autonomously:

Listen for payment requests from users
Call agentpay:create_payment_request to generate QR codes
Monitor settlements and unlock content without human intervention

Example:

User: "I want to buy your AI course. How much?"

Claude (via MCP): Calls create_payment_request(amount=500000, description="AI Mastery Course"), gets QR code, returns it.

User: Scans QR, pays from their banking app.

Claude (via polling/webhook): Detects settlement, sends course access link automatically.

Do's & Don'ts

✅ DO	❌ DON'T
Store `settlement_reference` to match QR to bank transactions	Hardcode merchant details—use env vars
Set unique `request_id` per payment (prevents duplicates)	Display the same QR twice (expires in 15 min)
Use background jobs for `await_settlement()` (don't block the bot)	Trust QR codes without verifying bank feed
Log all transactions for accounting/audit	Accept payments before `await_settlement()` completes
Test in sandbox mode first (if available)	Share your `AGENTPAY_BANK_CODE` publicly

Advanced Tips

1. Custom Expiry Times

payment = create_payment_request(
    amount=100_000,
    description="Premium feature unlock",
    merchant=merchant_account,
    request_id="feature_unlock_user_123",
    expires_in_minutes=30,  # Default is 15; extend for high-value items
)

2. Handling Payment Failures Gracefully

async def safe_await_settlement(settlement_ref: str, max_retries: int = 3):
    for attempt in range(max_retries):
        try:
            return await_settlement(settlement_ref, timeout_seconds=60)
        except TimeoutError:
            if attempt < max_retries - 1:
                await asyncio.sleep(5)  # Wait 5s, then retry
            else:
                raise  # Final timeout

3. Batch Payments for Subscriptions

# Monthly subscription bot
async def renew_subscription(user_id: str, tier: str):
    prices = {"starter": 99_000, "pro": 299_000, "enterprise": 999_000}

    payment = create_payment_request(
        amount=prices[tier],
        description=f"{tier.title()} Plan - Monthly Renewal",
        merchant=merchant_account,
        request_id=f"sub_{user_id}_{date.today().isoformat()}",
    )

    # Store subscription state
    subscriptions[user_id] = {
        "tier": tier,
        "settlement_ref": payment["settlement_reference"],
        "expires_at": date.today() + timedelta(days=30),
    }

    return payment["qr_code"]

FAQ

Q: Does AgentPay hold my money?

No. The QR code points directly to your bank account. When customers scan and pay, the money goes straight to your bank. AgentPay only confirms settlement via bank feeds—it never touches the funds.

Q: Which banks are supported?

All major Vietnamese banks that support VietQR: Vietcombank, Techcombank, BIDV, Agribank, DongA Bank, etc. Check the bank code list for your bank's 6-digit code.

Q: How long does settlement take?

Typically 1-4 hours. Techcombank and BIDV are fastest (~30 minutes). Bank feeds notify AgentPay when money arrives, so your bot confirms near-instantly.

Q: Can I use AgentPay for international payments?

Currently, AgentPay supports Vietnamese bank accounts and VND only. If you need multi-currency, integrate with Stripe or PayPal separately.

Q: Is it secure?

Yes. AgentPay uses official VietQR standards. All payment requests are tied to your real bank account via standardized banking protocols. There's no custom wallet or payment processor—just standard banking APIs.

Key Takeaways

Telegram + VietQR = friction-free payments for Vietnamese users; no API complexity
AgentPay VN handles the hard part: QR generation, bank settlement confirmation, security
3-line flow: create_payment_request() → display QR → await_settlement()
Use background jobs to avoid blocking your bot while waiting for payment confirmation
MCP server lets AI agents trigger payments and unlock content autonomously
No escrow, no delays: money lands in your account within hours, confirmed automatically
MIT licensed: fork it, customize bank descriptions, integrate with your KDS/CRM

Next Steps

Install AgentPay VN today:

   pip install agentpay-vn

Read the full documentation: https://agentpay.servicesai.vn/v1/docs
Explore the source code and contribute: https://github.com/phuocdu/agentpay-vn
Build your first bot: Start with the café example above, adapt to your use case (courses, subscriptions, e-commerce orders), and go live in minutes.

Happy shipping. 🚀

Collect VietQR Payments in Telegram Bots with AgentPay

ServicesAI VN — Wed, 26 Aug 2026 00:25:18 +0000

The Problem: Telegram Bots That Can't Monetize

You've built a Telegram bot. It's gaining users. People ask, "How do I pay you?" and you freeze.

Maybe you're selling:

Online courses (₫49,000–₫2,000,000 per course)
Café loyalty programs (₫15,000 per coffee card)
Freelance gigs (₫500,000–₫5,000,000 per project)
Digital products (ebooks, presets, templates)

You don't want to integrate Stripe (foreign, fees, compliance headaches). You don't want to ask users to visit a separate website. You need payments to happen inside Telegram, instantly, using VietQR—the payment standard every Vietnamese bank supports.

Enter AgentPay VN: an open-source Python SDK + MCP server that lets your Telegram bot (or any AI agent) generate VietQR payment requests, send checkout links, and await settlement confirmation—all without touching the money itself.

Why AgentPay Changes the Game

AgentPay is intentionally minimal. It doesn't hold, collect, or manage funds. Instead:

You create a payment request → AgentPay generates a unique VietQR code
User scans the QR → Payment goes directly to your merchant bank account
Bank confirms settlement → AgentPay notifies your bot, you deliver the product

This is radically different from Stripe or PayPal, which act as intermediaries. With AgentPay:

✅ Zero intermediary fees (pay only your bank's standard VietQR fee: ~0.5%)
✅ Money lands in your account immediately
✅ Full control—no waiting for settlement windows
✅ Open-source (MIT license)—audit the code, self-host the MCP server
✅ AI-native—built for Claude, OpenAI, and any MCP-compatible agent

Installation & Setup

Step 1: Install the SDK

pip install agentpay-vn

Verify the installation:

python -c "from agentpay_vn import create_payment_request; print('✓ AgentPay installed')"

Step 2: Deploy the MCP Server (Optional but Recommended)

If you're using Claude or another MCP-compatible AI agent, run:

agentpay-mcp

This starts a local MCP server that exposes AgentPay functions to Claude. Your AI agent can now create and await payments autonomously.

Step 3: Get Your Merchant Info

You need:

Bank name (e.g., "Vietcombank", "Techcombank")
Account number (your merchant bank account)
Account holder name (registered with your bank)

These values are public (users need them to scan the QR code), so don't stress over secrecy here. However, keep your bank account secure from actual transfers outside AgentPay flows.

The 3-Line Payment Flow

Here's the core pattern you'll use in every Telegram bot:

from agentpay_vn import create_payment_request, await_settlement
import asyncio

# Step 1: Create a payment request
payment = create_payment_request(
    amount=99000,  # ₫99,000 for a course
    description="Python FastAPI Masterclass",
    merchant_name="Your Store Name",
    merchant_bank="Techcombank",
    merchant_account="1234567890",
    order_id="order_20250115_user123"  # Unique per transaction
)

print(f"Checkout URL: {payment['checkout_url']}")
# User scans the QR code or clicks the link

# Step 2: Wait for settlement confirmation
settlement = await_settlement(
    order_id="order_20250115_user123",
    timeout_seconds=600  # 10-minute timeout
)

if settlement['confirmed']:
    print(f"✓ Payment confirmed! User {settlement['amount']} VND")
    # Deliver the course, unlock features, etc.
else:
    print("✗ Payment not received or timed out")

Line-by-line breakdown:

create_payment_request(...): Generates a VietQR payment request. AgentPay creates a checkout URL (either a hosted page or a deep-link to the user's banking app).
payment['checkout_url']: The URL you send to the user via Telegram. They click it, their bank app opens, they confirm the payment.
await_settlement(...): Polls your bank's API (through AgentPay's bank feed adapter) to confirm the transfer has landed. Returns {'confirmed': True, 'amount': 99000, 'timestamp': ...} when the payment is settled.

Real-World Example: A Course-Selling Telegram Bot

Let's build a bot that sells Python courses.

from telegram import Update
from telegram.ext import Application, CommandHandler, ContextTypes, ConversationHandler
from agentpay_vn import create_payment_request, await_settlement
import asyncio

# Course catalog
COURSES = {
    "python_basics": {"name": "Python Basics", "price": 99000},
    "fastapi_pro": {"name": "FastAPI Pro", "price": 299000},
    "ai_agents": {"name": "AI Agents Masterclass", "price": 499000},
}

MERCHANT_INFO = {
    "name": "TechSchool VN",
    "bank": "Techcombank",
    "account": "1234567890",
}

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """Show course catalog."""
    courses_text = "📚 **Available Courses:**\n\n"
    for code, course in COURSES.items():
        courses_text += f"/{code} — {course['name']} (₫{course['price']:,})\n"

    await update.message.reply_text(courses_text, parse_mode="Markdown")

async def buy_course(update: Update, context: ContextTypes.DEFAULT_TYPE, course_code: str):
    """Handle course purchase: create payment request and await settlement."""
    user_id = update.effective_user.id
    course = COURSES.get(course_code)

    if not course:
        await update.message.reply_text("❌ Course not found.")
        return

    # Create payment request
    order_id = f"order_{user_id}_{course_code}_{int(time.time())}"
    payment = create_payment_request(
        amount=course["price"],
        description=f"Purchase: {course['name']}",
        merchant_name=MERCHANT_INFO["name"],
        merchant_bank=MERCHANT_INFO["bank"],
        merchant_account=MERCHANT_INFO["account"],
        order_id=order_id,
    )

    # Send checkout link to user
    await update.message.reply_text(
        f"🛒 **{course['name']}**\n"
        f"Price: ₫{course['price']:,}\n\n"
        f"[💳 Pay Now]({payment['checkout_url']})",
        parse_mode="Markdown",
    )

    # Wait for payment in background
    asyncio.create_task(
        handle_payment_settlement(update, order_id, course_code)
    )

async def handle_payment_settlement(update, order_id: str, course_code: str):
    """Poll for settlement and deliver course on confirmation."""
    try:
        settlement = await_settlement(order_id=order_id, timeout_seconds=900)

        if settlement["confirmed"]:
            # Payment successful—deliver course
            course = COURSES[course_code]
            await update.message.reply_text(
                f"✅ **Payment Confirmed!**\n"
                f"Amount: ₫{settlement['amount']:,}\n\n"
                f"📥 Your {course['name']} course materials are being sent...\n\n"
                f"🔗 [Access your course](https://courses.techschool.vn/dashboard)\n"
                f"📧 Check your email for login credentials.",
                parse_mode="Markdown",
            )
            # TODO: Provision course access in your database
        else:
            await update.message.reply_text(
                "⏱️ **Payment Timeout**\n"
                "We didn't receive your payment within 15 minutes. "
                "Please try again: /start"
            )
    except Exception as e:
        await update.message.reply_text(
            f"❌ **Error**\nSomething went wrong: {str(e)}\n"
            "Please contact support."
        )

# Register handlers
app = Application.builder().token("YOUR_TELEGRAM_BOT_TOKEN").build()
app.add_handler(CommandHandler("start", start))

# Dynamic handlers for each course
for course_code in COURSES.keys():
    async def course_handler(update, context, code=course_code):
        await buy_course(update, context, code)
    app.add_handler(CommandHandler(course_code, course_handler))

if __name__ == "__main__":
    app.run_polling()

What happens:

User types /python_basics in Telegram
Bot creates a payment request for ₫99,000
Bot sends a checkout link (inline button or Markdown link)
User clicks → their banking app opens → they confirm the payment
Bot polls await_settlement() every 2 seconds (under the hood)
When the bank feed confirms the ₫99,000 arrived in your account, settlement returns confirmed=True
Bot sends course access credentials

Integrating with Claude via MCP

If you want Claude to autonomously manage payments (e.g., a support bot that upsells and charges), configure Claude with the AgentPay MCP server:

Claude Desktop config (~/.claude_desktop_config.json on Mac/Linux, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "args": []
    }
  }
}

Now restart Claude Desktop. In any conversation, Claude can:

User: "I want to buy the FastAPI course. My account is techbank 9876543210."

Claude: "I'll create a payment request for ₫299,000."
[Claude invokes create_payment_request via MCP]
"Here's your checkout link: https://agentpay.servicesai.vn/v1/checkout?id=xyz"
[Claude then awaits_settlement in the background]
"Payment confirmed! Your course access is ready."

Do's and Don'ts

✅ DO	❌ DON'T
Store `order_id` in your database to track purchases	Hardcode the same `order_id` for multiple users
Set realistic `timeout_seconds` (5–15 minutes)	Set timeout to 60+ seconds—VietQR can be slow in peak hours
Validate `settlement['amount']` matches your price	Trust the amount without verification—always check
Use unique order IDs (e.g., `order_{user_id}_{timestamp}`)	Reuse order IDs across sessions
Keep your merchant bank account private	Share your bank account number in client-side code
Handle `await_settlement()` exceptions gracefully	Let timeout errors crash your bot
Test with small amounts first (₫1,000–₫10,000)	Go live with big prices immediately

Advanced Tips

Batch Payments for Subscriptions

For monthly subscriptions, create a recurring payment:

import schedule

def charge_monthly_subscription(user_id: str, email: str):
    payment = create_payment_request(
        amount=49000,
        description=f"Monthly subscription for {email}",
        merchant_name="Your SaaS",
        merchant_bank="Techcombank",
        merchant_account="9876543210",
        order_id=f"sub_{user_id}_{datetime.now().strftime('%Y%m')}",
    )
    # Send payment link via email or Telegram
    send_payment_link(email, payment['checkout_url'])

schedule.every().month.at("00:00").do(charge_all_subscribers)

Webhook Notifications (Future Feature)

AgentPay currently uses polling. For high-volume bots, set up a webhook listener:

from fastapi import FastAPI
app = FastAPI()

@app.post("/webhook/settlement")
async def settlement_webhook(payload: dict):
    order_id = payload["order_id"]
    amount = payload["amount"]

    # Deliver product immediately without polling
    deliver_course(order_id, amount)
    return {"status": "ok"}

(This is on the roadmap for AgentPay v2.)

Multi-Currency (Future)

Currently, AgentPay supports VND only. USD/THB support is planned.

FAQ

Q: Does AgentPay hold my money?

No. AgentPay never touches the funds. Payment goes directly from the user's bank to your merchant account. AgentPay only orchestrates the QR generation and settlement confirmation.

Q: What if a user scans the QR but doesn't complete the payment?

The await_settlement() function times out after your specified duration (default 10 minutes). You'll get confirmed=False. You can ask the user to retry or provide a new checkout link.

Q: Is AgentPay free?

Yes, the SDK is free (MIT license, open-source). You pay only your bank's standard VietQR fee (~0.5% of the transaction). No AgentPay markup.

Q: Can I use AgentPay outside Telegram?

Absolutely. It works in any Python app: Discord bots, Slack bots, web apps, CLI tools, AI agents. It's payment-method-agnostic.

Q: What if I need invoicing or receipts?

AgentPay provides settlement data. You can generate invoices in your app using libraries like reportlab or integrate with accounting software (Wave, Xero) via their APIs.

Key Takeaways

🎯 AgentPay solves a real problem: Monetizing Telegram bots (and any Python app) without intermediaries or bank integration friction.
💰 Money lands instantly in your merchant account—no waiting for settlement windows or escrow.
🔐 Zero intermediary risk: You control the funds. AgentPay is transparent, open-source, and minimal.
🚀 3-line flow: create_payment_request() → send checkout link → await_settlement() and you're done.
🤖 AI-native: Use with Claude, OpenAI agents, or any MCP-compatible tool for autonomous payment collection.
📝 Easy integration: ~50 lines of code adds full payment processing to a Telegram bot.
🌐 Vietnam-first: Built for VietQR, the payment standard every Vietnamese user understands.

Get Started Now

Install AgentPay:

   pip install agentpay-vn

Read the full docs:
https://agentpay.servicesai.vn/v1/docs
Explore the source code:
https://github.com/phuocdu/agentpay-vn
Build your first payment bot using the course-selling example above.

Your Telegram bot can start accepting VietQR payments today. No bank calls, no paperwork, no intermediaries. Just Python, AgentPay, and instant settlement.

Happy selling! 🚀

Build a Telegram Payment Bot with VietQR & AgentPay

ServicesAI VN — Fri, 21 Aug 2026 00:20:41 +0000

The Problem: Selling on Telegram Without Payment Friction

You've built a Telegram bot that delivers real value—course lessons, digital assets, coffee reservations, marketplace items. Users love it. But every time someone wants to buy, the conversation dies:

"Send me your bank details via DM. No wait, use this PayPal link. Actually, just Momo me..."

They abandon the chat. You lose the sale. Your bot sits incomplete—intelligent logic, zero monetization.

This is the gap AgentPay VN solves. In three lines of code, your Telegram bot becomes a payment-collecting machine. QR codes appear instantly. Money settles directly into your merchant account. No middleman. No complexity.

In this tutorial, you'll build a live Telegram bot that sells digital products using VietQR—and see deposits confirm in real time.

Why VietQR + Telegram Is the Vietnamese E-Commerce Sweet Spot

VietQR is ubiquitous in Vietnam. Every banking app displays it natively. Your customer scans a QR code from their Telegram chat, completes payment in seconds, and the bot instantly confirms delivery.

AgentPay VN eliminates the complexity. It's:

Open-source (MIT): No vendor lock-in. Self-host if you want.
Bank-agnostic: Works with any merchant account supporting VietQR.
Non-custodial: Payments flow directly to your bank account. AgentPay never touches the money.
Settlement-verified: A bank feed confirms when funds arrive—no polling mystery.
AI-native: Built as an MCP server; Claude, Claude Code, and other agents integrate seamlessly.

Part 1: Installation & Setup

Step 1: Install the SDK

pip install agentpay-vn

This gives you the core Python SDK. If you're using Claude or another agent framework:

pip install agentpay-mcp

This installs the MCP server wrapper, letting Claude call payment functions directly via tool use.

Step 2: Configure Your Merchant Account

You'll need:

A Vietnamese bank account supporting VietQR (Vietcombank, Techcombank, Agribank, etc.).
Your VietQR code (ask your bank, or generate via their online portal).
API credentials from AgentPay (if using their default server; for self-hosting, use your own endpoint).

Store these as environment variables:

export AGENTPAY_MERCHANT_ID="your-merchant-id"
export AGENTPAY_SECRET="your-secret-key"
export VIETQR_ACCOUNT="your-bank-account-number"
export VIETQR_BANK_CODE="970407"  # Example: Techcombank

Step 3: Set Up Your Telegram Bot

You'll need the Telegram Bot API token. Create a bot via BotFather and save:

export TELEGRAM_BOT_TOKEN="your-telegram-token"

Part 2: The Three-Line Payment Flow Explained

AgentPay's philosophy is simplicity. Every payment follows three steps:

create_payment_request() — Generate a unique payment order.
send_checkout_url() — Push the QR checkout link to the user.
await_settlement() — Wait for bank confirmation.

Understand this flow, and you've got 90% of what you need.

Part 3: Build Your First Bot

Here's a fully working Telegram bot that sells a digital product (say, a 10-lesson Python course for 149,000 VND):

import os
import asyncio
from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import Application, CommandHandler, CallbackContext, CallbackQueryHandler
from agentpay_vn import PaymentClient, PaymentRequest

# Initialize AgentPay and Telegram
payment_client = PaymentClient(
    merchant_id=os.getenv("AGENTPAY_MERCHANT_ID"),
    secret_key=os.getenv("AGENTPAY_SECRET"),
    api_url="https://agentpay.servicesai.vn/v1"  # Or your self-hosted endpoint
)

# Product catalog
PRODUCTS = {
    "python_course": {
        "name": "Complete Python Bootcamp",
        "price_vnd": 149000,
        "description": "10 lessons covering OOP, async, and web frameworks",
        "delivery_content": "https://example.com/course-link"
    }
}

async def start(update: Update, context: CallbackContext) -> None:
    """Send a welcome message with product options."""
    keyboard = [
        [
            InlineKeyboardButton(
                f"{PRODUCTS['python_course']['name']} (₫{PRODUCTS['python_course']['price_vnd']:,})",
                callback_data="buy_python_course"
            )
        ]
    ]
    reply_markup = InlineKeyboardMarkup(keyboard)
    await update.message.reply_text(
        "Welcome! 🎓 Check out our digital products:",
        reply_markup=reply_markup
    )

async def buy_product(update: Update, context: CallbackContext) -> None:
    """Handle purchase requests."""
    query = update.callback_query
    await query.answer()

    product_key = query.data.replace("buy_", "")
    product = PRODUCTS[product_key]
    user_id = query.from_user.id

    # Step 1: Create a payment request
    payment_req = PaymentRequest(
        merchant_order_id=f"order_{user_id}_{int(asyncio.get_event_loop().time())}",
        amount_vnd=product["price_vnd"],
        description=f"Purchase: {product['name']}",
        customer_email=query.from_user.username or "telegram_user",
        return_url="https://t.me/your_bot"  # Where user returns after payment
    )

    try:
        payment_response = await payment_client.create_payment_request(payment_req)
        order_id = payment_response["order_id"]
        checkout_url = payment_response["checkout_url"]
        qr_code_data = payment_response["qr_code"]

        # Step 2: Send checkout message with QR code
        await query.edit_message_text(
            text=(
                f"📱 **{product['name']}**\n"
                f"💰 Price: ₫{product['price_vnd']:,}\n\n"
                f"Scan this QR code to pay:\n"
                f"```
{% endraw %}
\n{qr_code_data}\n
{% raw %}
```\n\n"
                f"_Your bot is waiting for payment confirmation..._"
            ),
            parse_mode="Markdown"
        )

        # Step 3: Wait for settlement (non-blocking)
        asyncio.create_task(wait_and_deliver(query, order_id, product, user_id))

    except Exception as e:
        await query.edit_message_text(
            text=f"❌ Payment setup failed: {str(e)}\n\nPlease try again or contact support."
        )

async def wait_and_deliver(query, order_id: str, product: dict, user_id: int) -> None:
    """Wait for payment settlement, then deliver the product."""
    try:
        # Step 3: Await settlement confirmation
        settlement = await payment_client.await_settlement(
            order_id=order_id,
            timeout_seconds=900  # 15 minutes
        )

        if settlement["status"] == "settled":
            # Payment confirmed!
            await query.bot.send_message(
                chat_id=user_id,
                text=(
                    f"✅ **Payment Confirmed!**\n\n"
                    f"Your access to **{product['name']}** is ready.\n"
                    f"📥 Download link: {product['delivery_content']}\n\n"
                    f"Thank you for your purchase! 🙏"
                ),
                parse_mode="Markdown"
            )
        else:
            await query.bot.send_message(
                chat_id=user_id,
                text=f"⏳ Payment pending. Status: {settlement['status']}"
            )

    except asyncio.TimeoutError:
        await query.bot.send_message(
            chat_id=user_id,
            text="⏱️ Payment timeout. Please try again or contact support."
        )
    except Exception as e:
        await query.bot.send_message(
            chat_id=user_id,
            text=f"❌ Settlement check failed: {str(e)}"
        )

async def main() -> None:
    """Start the bot."""
    application = Application.builder().token(os.getenv("TELEGRAM_BOT_TOKEN")).build()

    application.add_handler(CommandHandler("start", start))
    application.add_handler(CallbackQueryHandler(buy_product))

    await application.run_polling()

if __name__ == "__main__":
    asyncio.run(main())

What's happening line by line:

Lines 28–40: User taps "Buy". The buy_product handler triggers.
Lines 42–49: We create a unique PaymentRequest with order ID, amount, and description.
Lines 51–62: create_payment_request() returns a checkout URL and QR code. We send this to the user.
Lines 64–65: We spawn a background task (wait_and_deliver) to listen for settlement.
Lines 68–95: In the background, await_settlement() blocks until the bank confirms the payment. When it does, we send the user their course link.

Part 4: Using AgentPay with Claude (MCP Mode)

If you're letting Claude manage your bot's logic, use the MCP server. First, ensure it's installed:

pip install agentpay-mcp

Configure your Claude client with this MCP definition:

{
  "name": "agentpay-vn-mcp",
  "command": "python",
  "args": ["-m", "agentpay_mcp"],
  "env": {
    "AGENTPAY_MERCHANT_ID": "${AGENTPAY_MERCHANT_ID}",
    "AGENTPAY_SECRET": "${AGENTPAY_SECRET}",
    "VIETQR_ACCOUNT": "${VIETQR_ACCOUNT}",
    "VIETQR_BANK_CODE": "${VIETQR_BANK_CODE}"
  }
}

Now Claude can call:

claude_call("create_payment_request", {"amount_vnd": 149000, "description": "Python Course"})
claude_call("await_settlement", {"order_id": "order_123", "timeout_seconds": 900})

Claude manages the entire flow—from generating QR codes to confirming delivery—without you writing async code.

Part 5: Real-World Example: A Café Pre-Order Bot

Let's say you run a café and want customers to pre-order from Telegram. They browse a menu, order, pay via VietQR, and pick up at a specific time.

Flow:

Bot shows menu: "Cà phê đen (35k) | Matcha Latte (55k) | Croissant (25k)"
User taps "Matcha Latte."
Bot creates a payment request for 55,000 VND.
User scans QR code → pays from their banking app.
Bot confirms: "Your order is ready at 3 PM, table 7. Pick-up code: ABC123."
Settlement notification reaches your phone.

The entire process takes ~2 minutes. No SMS, no phone calls, no manual verification.

Part 6: Do's and Don'ts

✅ Do	❌ Don't
Store order metadata (product name, user ID, timestamp) in your own database before creating the payment request.	Assume the QR code is valid indefinitely—they expire after a time window (default: 15 min). Refresh if needed.
Test with small amounts (5,000–10,000 VND) first to validate your bank integration.	Hard-code merchant IDs or secrets. Use environment variables.
Use `await_settlement()` with a reasonable timeout (e.g., 900 seconds = 15 min). Users take time to open banking apps.	Implement your own polling loop instead of `await_settlement()`—AgentPay's method is optimized for bank feed latency.
Log the `order_id` and `merchant_order_id` for every transaction—essential for reconciliation.	Deliver digital goods before `await_settlement()` returns `status == "settled"`.
Monitor your bot's logs for `PaymentClient` errors. They're your first sign of bank connectivity issues.	Forget that AgentPay never holds money. If your bot crashes post-settlement, the user's payment is already safe in your bank account.

Part 7: Advanced Tips

Tip 1: Reconciliation Dashboard

Create a simple admin endpoint that shows settlements:

async def reconciliation_report():
    """Fetch all settled orders from the last 7 days."""
    settled_orders = await payment_client.list_settlements(
        start_date="2024-01-01",
        end_date="2024-01-07",
        status="settled"
    )
    total_vnd = sum(order["amount_vnd"] for order in settled_orders)
    print(f"Settled this week: {total_vnd:,} VND across {len(settled_orders)} orders")

Tip 2: Retry Logic for Flaky Networks

from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=2, max=10))
async def create_payment_with_retry(payment_req):
    return await payment_client.create_payment_request(payment_req)

Tip 3: Multi-Product Catalog with Webhooks

If AgentPay supports webhooks (check the docs), register a webhook endpoint so settlement notifications arrive immediately:

app.post("/agentpay-webhook")
async def handle_settlement_webhook(request):
    payload = await request.json()
    order_id = payload["order_id"]
    status = payload["status"]

    if status == "settled":
        # Immediately deliver without polling
        await deliver_product_for_order(order_id)

    return {"success": True}

FAQ

Q1: Does AgentPay take a cut of my payments?
No. AgentPay is a non-custodial payment SDK. 100% of the customer's payment flows to your merchant bank account. AgentPay doesn't hold, freeze, or redirect funds. You only pay for infrastructure (if using their hosted MCP server) or self-host for free.

Q2: What if a customer scans the QR code but doesn't pay within 15 minutes?
The QR code expires (default: 15 minutes). You can either prompt the user to request a fresh one or increase the timeout in PaymentRequest. The bot should re-call create_payment_request() to generate a new QR.

Q3: Can I use AgentPay with a Viettelpay or Momo wallet instead of a bank?
AgentPay is VietQR-specific, which routes to bank accounts. Momo and Viettel operate separate payment rails. For multi-wallet support, you'd integrate those SDKs separately. However, VietQR covers ~95% of Vietnamese banking, so one integration often suffices.

Q4: Is my bot compliant with Vietnamese fintech regulations?
AgentPay handles the technical plumbing. You should ensure you have a business license and comply with SBV (State Bank of Vietnam) guidelines for payment service users. Consult a local legal advisor—AgentPay's non-custodial model reduces compliance burden, but due diligence is still your responsibility.

Key Takeaways

Telegram + VietQR = Frictionless payments: Users scan a QR code and complete checkout without leaving the chat.
AgentPay is non-custodial: Your money lands in your bank account instantly. No escrow, no middleware risk.
Three-line flow: create_payment_request() → send_checkout_url() → await_settlement(). That's the whole model.
Use environment variables for credentials. Never hard-code secrets.
Test small amounts first (5k–10k VND) to verify your bank's VietQR setup.
Log order IDs: Critical for troubleshooting and reconciliation.
Self-host or use AgentPay's MCP server: Both are valid. MCP is simpler if you're already using Claude.

Next Steps

You're ready to monetize your Telegram bot. Here's the action plan:

Install AgentPay: pip install agentpay-vn
Read the full documentation: https://agentpay.servicesai.vn/v1/docs
Explore the GitHub repo for more examples: https://github.com/phuocdu/agentpay-vn
Build your first payment request with a test amount.
Deploy to production and watch settlements flow into your account.

The Vietnamese e-commerce landscape is moving toward bot-native commerce. With AgentPay, you're not just building a chatbot—you're building a payment-enabled business. Start small, ship fast, and scale.

Happy selling. 🚀

Build a paid MCP server: charge users from inside Claude

ServicesAI VN — Mon, 17 Aug 2026 00:17:28 +0000

Overview

AgentPay VN lets your AI agent collect VietQR payments without ever holding the money.

pip install agentpay-vn

from agentpay.client import AsyncAgentPayClient, await_settlement

async with AsyncAgentPayClient('ap_live_xxx') as c:
    pr = await c.create_payment_request(amount=50_000, description='Order #1')
    # send pr['checkout_url'] to the user
    r = await await_settlement(c, pr['id'], timeout=120)

The QR points at your own bank account; AgentPay only confirms settlement.

Telegram Bot Payments with VietQR: AgentPay Guide

ServicesAI VN — Fri, 31 Jul 2026 00:03:59 +0000

The Problem: Payments Break Telegram Bots

Imagine you've built a Telegram bot that sells online courses. A user types /buy, sees your course, and hits "Pay Now." Then… nothing. You have no way to collect money directly in the chat. You'd need to redirect them to Stripe, PayPal, or a separate checkout page—and half your users abandon the flow right there.

Worse: if you do integrate a payment processor, you're trusting a third party to hold customer funds, dealing with settlement delays, and paying transaction fees that eat into your margin. For Vietnamese merchants selling digital products, physical goods, or services via Telegram, the friction is even higher—most global processors don't support VietQR or Vietnamese bank accounts seamlessly.

That's where AgentPay VN changes the game.

What Is AgentPay VN?

AgentPay VN is an open-source MIT-licensed Python SDK (plus MCP server) that lets AI agents and bots collect payments via VietQR—Vietnam's instant payment standard. Here's what makes it different:

No fund holding. The QR code points directly to your merchant bank account. You get paid instantly.
Bank-verified settlement. A feed confirms when money lands—no waiting, no disputes.
AI-native. Built for Claude, ChatGPT, and other agents to create payments on the fly.
Simple 3-line flow. Create a payment request → send the checkout URL → await settlement.
Free to start. MIT license, zero vendor lock-in.

Install it today:

pip install agentpay-vn

Or use the MCP server for Claude integration:

agentpay-mcp

Why Telegram + VietQR + AgentPay?

Telegram has 900+ million users and millions of bots. Vietnamese Telegram users are highly engaged and prefer instant payments over web checkout. VietQR (launched by the State Bank of Vietnam in 2021) is now the standard for peer-to-peer and merchant payments—almost every Vietnamese bank supports it.

Combining all three means:

Zero friction. User sees QR, scans with their banking app, pays in 10 seconds.
Trust. VietQR is backed by the State Bank. Your customers know the payment is secure.
Developer simplicity. A few lines of Python handle the entire flow.

Step-by-Step: Build Your First Payment-Ready Bot

1. Set Up Your Merchant Account

Before coding, you'll need:

A Vietnamese bank account (or a business account that supports VietQR).
Your bank's merchant ID or account number for QR generation.
Access to your bank's transaction feed (most major banks: VCB, Techcombank, MB, ACB, etc.).

Refer to AgentPay docs for bank-specific setup.

2. Install and Initialize

pip install agentpay-vn python-telegram-bot

3. Create Your First Payment Request

Here's a minimal Telegram bot that collects a payment:

from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import Application, CommandHandler, ContextTypes
from agentpay_vn import AgentPayClient
import os

# Initialize AgentPay
AGENTPAY_API_KEY = os.getenv("AGENTPAY_API_KEY")
client = AgentPayClient(api_key=AGENTPAY_API_KEY)

# Initialize Telegram bot
TG_TOKEN = os.getenv("TELEGRAM_BOT_TOKEN")
app = Application.builder().token(TG_TOKEN).build()

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """Send welcome message with a sample product."""
    await update.message.reply_text(
        "Welcome to TechCourse Bot!\n"
        "We sell premium Python courses. Use /buy to get started."
    )

async def buy(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """Create a payment request and send checkout URL."""
    user_id = update.effective_user.id

    # Step 1: Create payment request
    payment = await client.create_payment_request(
        amount=499000,  # 499,000 VND
        description="Advanced Python Mastery Course",
        merchant_ref=f"course_{user_id}_{int(time.time())}",
        customer_email="user@example.com",
        redirect_url="https://yourdomain.com/success"  # Optional: where to send them after payment
    )

    # Step 2: Extract the VietQR checkout URL
    checkout_url = payment["checkout_url"]
    payment_id = payment["id"]

    # Step 3: Send inline button to user
    keyboard = InlineKeyboardMarkup([
        [InlineKeyboardButton("💳 Pay 499K VND", url=checkout_url)]
    ])

    await update.message.reply_text(
        "*Advanced Python Mastery*\n"
        "📚 12 hours of video content\n"
        "💻 50+ real-world projects\n"
        "🎓 Certificate included\n\n"
        "Price: 499,000 VND",
        reply_markup=keyboard,
        parse_mode="Markdown"
    )

    # Step 4: Store payment_id for later settlement check
    context.user_data["payment_id"] = payment_id

async def check_payment(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """Check if payment settled."""
    if "payment_id" not in context.user_data:
        await update.message.reply_text("No pending payment found. Use /buy first.")
        return

    payment_id = context.user_data["payment_id"]

    # Step 5: Await settlement (polls or webhook)
    status = await client.await_settlement(
        payment_id=payment_id,
        timeout_seconds=300  # Wait up to 5 minutes
    )

    if status["settled"]:
        await update.message.reply_text(
            "✅ Payment confirmed!\n"
            f"Amount: {status['amount']:,} VND\n"
            f"Transaction ID: {status['transaction_id']}\n\n"
            "Your course access link: https://yourdomain.com/course/xyz"
        )
    else:
        await update.message.reply_text("⏱️ Payment timeout. Please try again.")

# Register handlers
app.add_handler(CommandHandler("start", start))
app.add_handler(CommandHandler("buy", buy))
app.add_handler(CommandHandler("check", check_payment))

# Run bot
if __name__ == "__main__":
    app.run_polling()

Line-by-line explanation:

Lines 7–8: Initialize AgentPay with your API key (get it from dashboard).
Lines 10–11: Load Telegram token from environment.
Lines 13–18: /start sends a welcome message.
Lines 20–49: /buy creates a payment request with create_payment_request(), which returns a checkout URL. The URL embeds the VietQR code. We send it as an inline button so users tap → pay in their banking app.
Lines 51–67: /check calls await_settlement() to poll for payment confirmation. Once settled, you unlock the course.

4. Integrate with Claude via MCP

If you want your bot powered by Claude (for smarter responses), use the MCP server. Create an .mcp-config.json:

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "env": {
        "AGENTPAY_API_KEY": "your-api-key-here"
      }
    }
  }
}

Now Claude can create payments directly:

User: "I want to buy the course."
Claude: (calls agentpay.create_payment_request with course details)
Claude: "Here's your checkout link: [QR image]"

Real-World Walkthrough: Café Pre-Order Bot

Let's say you run a specialty coffee shop in Hanoi and want to let customers pre-order drinks via Telegram.

Scenario:

Customer texts the bot: /menu
Bot shows coffee options with prices (e.g., Cà Phê Sữa: 35K, Espresso: 50K).
Customer picks a drink and clicks "Order & Pay."
Bot creates a payment request for 35,000 VND.
Customer scans the VietQR code with their banking app and pays instantly.
Bot confirms: "Your order is ready for pickup at 3 PM."

In code (simplified):

MENU = {
    "ca_phe_sua": {"name": "Cà Phê Sữa", "price": 35000},
    "espresso": {"name": "Espresso", "price": 50000},
    "matcha_latte": {"name": "Matcha Latte", "price": 55000},
}

async def order_coffee(update: Update, context: ContextTypes.DEFAULT_TYPE):
    item_key = context.args[0]  # e.g., "ca_phe_sua"
    item = MENU[item_key]

    payment = await client.create_payment_request(
        amount=item["price"],
        description=f"Pre-order: {item['name']}",
        merchant_ref=f"cafe_{update.effective_user.id}_{item_key}"
    )

    keyboard = InlineKeyboardMarkup([
        [InlineKeyboardButton(
            f"💳 Pay {item['price']:,} VND",
            url=payment["checkout_url"]
        )]
    ])

    await update.message.reply_photo(
        photo="path/to/coffee/image.jpg",
        caption=f"*{item['name']}*\n{item['price']:,} VND",
        reply_markup=keyboard,
        parse_mode="Markdown"
    )

After payment settles, trigger fulfillment (notify barista, send pickup time, etc.).

Do's and Don'ts

Do	Don't
✅ Store `payment_id` to track orders	❌ Re-create the same payment request twice
✅ Set a reasonable timeout (5–10 min)	❌ Assume payment is instant; always confirm
✅ Log transactions for accounting	❌ Skip bank feed verification
✅ Use descriptive merchant_ref (e.g., user ID, timestamp)	❌ Use generic refs; you'll lose order context
✅ Validate amount before creating request	❌ Trust user input directly
✅ Handle network errors gracefully	❌ Crash if settlement times out

Advanced Tips

Batch Payments

If your bot handles multiple concurrent orders, create a queue:

import asyncio
from collections import defaultdict

payment_queue = defaultdict(list)

async def process_payment_queue():
    """Periodically check settled payments."""
    while True:
        for user_id, payments in list(payment_queue.items()):
            for payment in payments:
                status = await client.get_payment_status(payment["id"])
                if status["settled"]:
                    # Handle success
                    await notify_user(user_id, "Order ready!")
                    payments.remove(payment)
        await asyncio.sleep(10)  # Check every 10 seconds

# Run in background
asyncio.create_task(process_payment_queue())

Webhook Integration (Production)

For real-time updates, use webhooks instead of polling:

@app.post("/webhook/agentpay")
async def webhook_handler(request: Request):
    payload = await request.json()
    payment_id = payload["id"]
    status = payload["status"]  # "settled", "pending", "failed"

    if status == "settled":
        user_id = extract_user_id_from_ref(payload["merchant_ref"])
        await send_telegram_message(user_id, "✅ Payment confirmed!")

    return {"ok": True}

Multi-Currency Support

AgentPay supports VND only (Vietnam-specific), but you can convert prices:

import httpx

async def usd_to_vnd(usd_amount: float) -> int:
    async with httpx.AsyncClient() as client:
        r = await client.get("https://api.exchangerate-api.com/v4/latest/USD")
        rate = r.json()["rates"]["VND"]
    return int(usd_amount * rate)

# Usage
price_vnd = await usd_to_vnd(9.99)  # ~240K VND

FAQ

Q: Does AgentPay hold my money?
No. The VietQR points directly to your bank account. AgentPay is just the orchestration layer; settlement happens directly with your bank.

Q: Can I use AgentPay outside Vietnam?
No, AgentPay is Vietnam-specific (it uses VietQR, a Vietnamese standard). If your users are abroad, they won't have VietQR-capable banks.

Q: How long does payment settlement take?
VietQR transfers are instant (real-time gross settlement). Money appears in your account within seconds.

Q: Can I refund a payment?
Yes, you can initiate a refund via the SDK (client.refund_payment(payment_id)) or your bank's portal. The amount goes back to the customer's account.

Q: What if my Telegram bot goes offline?
You'll miss real-time updates, but the bank feed still confirms settlement. When your bot restarts, query await_settlement() to catch up on pending payments.

Key Takeaways

🎯 Telegram + VietQR = instant payment collection with zero friction for Vietnamese users.
💰 AgentPay holds zero funds. Money goes straight to your bank account.
🚀 Simple 3-step flow: create_payment_request() → send checkout URL → await_settlement().
🤖 AI-native. Claude can create payments on the fly via MCP server.
📱 Production-ready. Webhook support, batch processing, and error handling built in.
🏦 Bank-verified. Transactions confirmed by your bank's feed, not a third-party API.

Get Started Now

Your first payment-collecting Telegram bot is minutes away:

pip install agentpay-vn

Then head to:

Documentation: https://agentpay.servicesai.vn/v1/docs
GitHub: https://github.com/phuocdu/agentpay-vn
API Key: Sign up on the AgentPay dashboard.

Start collecting VietQR payments in your bot today. No fund holding, no vendor lock-in, just instant settlement straight to your Vietnamese bank account.

Agent-native payments: idempotency, webhooks, settlement

ServicesAI VN — Wed, 29 Jul 2026 00:02:23 +0000

The Silent Killer: Double Charges in Agent Payment Flows

Imagine your AI assistant just closed a $500 course sale for a customer. The agent calls create_payment_request(), sends a checkout link, and waits. The network hiccups. The agent retries. Now the customer sees two payment prompts—or worse, two transactions hit their bank account. By the time you notice, three more duplicates have cascaded through.

This isn't theoretical. It happens daily in production systems where agents handle financial transactions autonomously. Traditional payment gateways hold your money temporarily and reverse duplicates. But AgentPay VN works differently: it never holds funds. The VietQR code points directly to your merchant bank account. Settlement confirmation comes from your bank's own feed. This means you must architect idempotency, webhooks, and settlement tracking—or lose money to duplicate charges.

In this guide, we'll build bulletproof payment flows using AgentPay VN's Python SDK and MCP server, ensuring your agents collect payments safely, confirm settlement, and handle failure gracefully.

Why Idempotency Matters for AI Agents

AI agents are inherently retry-prone. They face network timeouts, rate limits, and transient errors. A naive agent that retries create_payment_request() without idempotency will spawn multiple payment requests—each generating a unique QR code—leading to split payments or abandoned carts.

Idempotency ensures the same logical request always yields the same result, even if called 100 times. It's the foundation of reliable agent payments.

AgentPay VN supports idempotency through request IDs. When you provide a request_id (a stable, deterministic identifier derived from order details), the system guarantees:

First call: Creates payment request, returns checkout_url.
Retry with same request_id: Returns the same checkout_url without creating a new request.
No duplicate charges: Your agent can safely retry without fear.

This is critical for multi-agent systems where different agent instances might process the same order or where network failures trigger automatic retries.

Building Idempotent Payment Requests

Generating Stable Request IDs

The key is deriving request_id deterministically from immutable order data:

import hashlib
from agentpay_vn import AgentPayClient

# Stable request ID: hash of order essentials
def generate_request_id(customer_id: str, product_id: str, amount: int) -> str:
    data = f"{customer_id}:{product_id}:{amount}"
    return hashlib.sha256(data.encode()).hexdigest()[:16]

# Initialize client
client = AgentPayClient(api_key="your-api-key")

# Create idempotent payment request
customer_id = "cust_alice_001"
product_id = "course_python_101"
amount_vnd = 500000  # 500k VND

request_id = generate_request_id(customer_id, product_id, amount_vnd)

# First call: creates request
payment = client.create_payment_request(
    request_id=request_id,
    amount=amount_vnd,
    description="Python Mastery Course",
    merchant_order_id=f"order_{customer_id}_{product_id}"
)

checkout_url = payment.checkout_url
print(f"Checkout URL: {checkout_url}")

# Retry with same request_id: returns identical checkout_url
# No new payment request created
payment_retry = client.create_payment_request(
    request_id=request_id,
    amount=amount_vnd,
    description="Python Mastery Course",
    merchant_order_id=f"order_{customer_id}_{product_id}"
)

assert payment_retry.checkout_url == checkout_url
print("✓ Idempotency verified: same request_id → same checkout_url")

Why this works:

request_id is derived from customer, product, and amount—data that don't change during retries.
If any of those change, a new order should be created (new request_id).
The API deduplicates based on request_id, not on customer retry attempts.

Webhook Handling: Confirming Customer Action

After the customer scans the VietQR and completes the transfer, AgentPay VN sends a webhook to your system. This webhook is your proof that a payment was attempted—but not necessarily settled.

Setting Up Webhook Endpoints

In your agent configuration or backend:

from fastapi import FastAPI, Request, HTTPException
import hmac
import hashlib
import json

app = FastAPI()

WEBHOOK_SECRET = "your-webhook-secret"  # From AgentPay dashboard

def verify_webhook_signature(body: bytes, signature: str) -> bool:
    """Verify webhook came from AgentPay VN."""
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

@app.post("/webhooks/agentpay")
async def handle_agentpay_webhook(request: Request):
    signature = request.headers.get("X-AgentPay-Signature")
    body = await request.body()

    # Verify authenticity
    if not verify_webhook_signature(body, signature or ""):
        raise HTTPException(status_code=401, detail="Invalid signature")

    payload = json.loads(body)
    request_id = payload.get("request_id")
    status = payload.get("status")  # "pending", "paid", "expired"

    if status == "paid":
        # Customer has sent money; await settlement confirmation
        print(f"✓ Payment received for request {request_id}")
        # Update local DB: mark as "payment_received"
    elif status == "expired":
        print(f"✗ Payment expired for request {request_id}")
        # Prompt agent to create new request

    return {"status": "received"}

Critical distinction:

Webhook status="paid" means the customer's transfer is in flight to your account.
It does NOT mean settlement is complete; bank processing takes seconds to minutes.
Use webhooks to update UI and trigger settlement polling, not to deliver goods immediately.

Settlement Confirmation: Trust Your Bank Feed

AgentPay VN does not track settlement. Your bank does. When the customer's bank processes the transfer, it credits your merchant account. AgentPay provides tools to poll settlement status, but the source of truth is your bank's transaction feed.

Polling for Settlement

import time
from agentpay_vn import AgentPayClient

client = AgentPayClient(api_key="your-api-key")

# After webhook confirms payment_received, poll settlement
async def await_settlement(request_id: str, timeout_seconds: int = 60) -> dict:
    """
    Poll settlement status until confirmed or timeout.
    """
    start = time.time()

    while time.time() - start < timeout_seconds:
        settlement = client.get_settlement_status(request_id=request_id)

        if settlement.status == "settled":
            print(f"✓ Settlement confirmed: {settlement.amount} VND")
            return {
                "settled": True,
                "amount": settlement.amount,
                "bank_ref": settlement.bank_reference_id
            }

        if settlement.status == "failed":
            print(f"✗ Settlement failed: {settlement.error_reason}")
            return {"settled": False, "reason": settlement.error_reason}

        # Still pending; wait and retry
        await asyncio.sleep(2)

    # Timeout; settlement not confirmed within window
    return {"settled": False, "reason": "Timeout after settlement webhook"}

# Usage in agent flow
result = await await_settlement(request_id)
if result["settled"]:
    print(f"Deliver course to student. Bank ref: {result['bank_ref']}")
else:
    print(f"Settlement pending or failed. Retry in 1 minute.")

Best practice: Pair webhook notifications with polling. Webhooks are fast but can be delayed or lost; polling is slower but guarantees eventual consistency.

MCP Server: Integrating with Claude and Other AI Agents

For Claude and other AI agents, AgentPay VN provides a Model Context Protocol (MCP) server. This exposes payment operations as callable tools.

Claude Integration Configuration

Add this to your Claude configuration file (e.g., claude_config.json):

{
  "mcpServers": {
    "agentpay-vn": {
      "command": "agentpay-mcp",
      "env": {
        "AGENTPAY_API_KEY": "your-api-key",
        "AGENTPAY_WEBHOOK_SECRET": "your-webhook-secret"
      }
    }
  }
}

Once configured, Claude gains these tools:

create_payment_request: Create a new VietQR payment with idempotency.
get_payment_status: Check if customer has sent money.
await_settlement: Poll until settlement confirmed.
create_refund: Reverse a payment if needed.

Example: Claude as a Course Sales Bot

User: "I want to buy your Python course."

Claude (using MCP tools):
1. Calls create_payment_request(request_id="user_alice_python_101", amount=500000)
2. Receives checkout_url
3. Responds: "Here's your payment link: [URL]. Scan with your bank app."
4. Waits for webhook (customer scans and pays)
5. On webhook, calls await_settlement(request_id)
6. Once settled, says: "✓ Payment confirmed! Sending course materials now."
7. Delivers course download link

No manual intervention. The agent orchestrates the entire flow.

Real-World Walkthrough: Online Coffee Shop

Let's trace a complete order:

Scenario: A coffee shop ("CoffeeAI") runs a WhatsApp bot powered by Claude + AgentPay VN. A customer orders 2 espressos for 120,000 VND.

Flow:

Order Creation (11:45 AM)
- Agent generates request_id = hash("user_bob", "2espresso", 120000) → a7f3e2b1
- Calls create_payment_request(request_id="a7f3e2b1", amount=120000, description="2x Espresso")
- Returns checkout_url = "https://vietqr.io/...?"
- Agent sends WhatsApp: "Pay here: [link]"
Customer Scans (11:46 AM)
- Customer opens link, scans QR with banking app
- Bank sees: "CoffeeAI merchant account, 120,000 VND"
- Customer confirms transfer
Webhook Receipt (11:46:03 AM)
- AgentPay sends webhook: {request_id: "a7f3e2b1", status: "paid"}
- Shop backend receives it, stores in DB: orders[a7f3e2b1].status = "payment_received"
- Agent is notified via polling or event listener
Settlement Polling (11:46:05 AM)
- Agent calls await_settlement(request_id="a7f3e2b1")
- First poll: status: "pending" (bank still processing)
- Second poll (2 sec later): status: "settled", bank_ref: "VCB_20250201_987654"
- Agent sends WhatsApp: "✓ Payment received! Your order is being prepared."
Fulfillment (11:50 AM)
- Order marked as confirmed in kitchen system
- Barista prepares 2 espressos
- Order ready; agent sends: "Ready for pickup!"

Key insight: The agent never held money. It verified the customer sent it, waited for the bank to confirm receipt, then triggered fulfillment. If the customer's bank failed to process (unlikely with VietQR), the agent would have retried the webhook polling and eventually returned an error to the customer.

Do's and Don'ts: Common Pitfalls

Do	Don't
Use deterministic `request_id` from order data	Generate random UUIDs for `request_id`
Verify webhook signatures before processing	Trust webhook payload without verification
Implement polling with exponential backoff	Poll once and assume settlement failed
Store `bank_reference_id` from settlement response	Treat webhook as proof of settlement
Retry `create_payment_request` on network error	Create new payment requests on every retry
Set reasonable timeouts (30–60 sec) for settlement polling	Poll forever without a timeout
Log all payment lifecycle events for audits	Discard payment logs after 1 week

FAQ

Q: What if the customer closes the checkout page without paying?
A: The webhook never arrives. Your agent's polling times out and returns {settled: False, reason: "Timeout"}. The agent can then prompt the customer to try again or offer support.

Q: Can I refund a payment after settlement?
A: Yes. Call client.create_refund(request_id, reason="customer_request"). The refund is sent back to the customer's bank account. Settlement is confirmed via the same polling mechanism.

Q: How does AgentPay handle concurrent requests from multiple agents?
A: Idempotency is your shield. If agent A and agent B both call create_payment_request(request_id="x") simultaneously, AgentPay's database lock ensures only one payment request is created. Both agents receive the same checkout_url and proceed safely.

Q: What's the maximum polling timeout?
A: VietQR typically settles within 5–30 seconds. Set your polling timeout to 60 seconds to be safe. If settlement isn't confirmed by then, escalate to support; it's rare and indicates a bank-side issue.

Key Takeaways

Idempotency is non-negotiable: Derive request_id from immutable order data. Retries are safe; duplicates are prevented.
Webhooks notify; polling confirms: Webhooks tell you the customer sent money. Polling confirms the bank received it. Use both.
Never assume settlement: Webhook status="paid" is not settlement. Always call await_settlement() before delivering goods.
Bank reference is your proof: Once settled, store bank_reference_id. It's your audit trail if disputes arise.
Agent-native means autonomous: With proper idempotency and error handling, your AI agents can collect payments end-to-end without human intervention.

Get Started Now

AgentPay VN makes agent payments safe and simple. Install the SDK and MCP server, integrate idempotency and webhooks into your agent flow, and let your AI collect payments directly to your bank account.

Next steps:

Install the SDK: pip install agentpay-vn
Set up the MCP server: agentpay-mcp (configure in your Claude or agent config)
Read the full docs: https://agentpay.servicesai.vn/v1/docs
Explore the code: GitHub: phuocdu/agentpay-vn
Build: Start with a test agent and process a few test payments to verify your idempotency and settlement flow.

Happy collecting!

Build a Paid MCP Server: Charge Users Inside Claude

ServicesAI VN — Sun, 26 Jul 2026 00:00:45 +0000

The Problem: Free Tools Don't Scale

You've built something useful—a Claude MCP server that helps users do research, generate content, or manage data. Your tool sees 500 requests a week. But you're covering the infrastructure costs yourself, and every popular feature you add burns more cloud credits. You wonder: "How do I charge users without becoming a fintech company?"

This is the exact gap AgentPay VN fills. You can now accept payments directly inside Claude conversations without ever touching the money, holding customer data, or managing a payment processor integration yourself. Your users get their VietQR checkout link, scan with their bank app, and your MCP server immediately knows payment succeeded—all in under 3 seconds.

Let's build it.

Why MCP Payments Are Different

Traditional SaaS requires users to leave your product, go to a website, enter a credit card, and return. With MCP servers running inside Claude, payments become conversational. A user asks your tool for something premium. You present a QR code. They scan. Settlement confirms in seconds. They're back to the conversation—no friction, no page redirects, no signup forms.

AgentPay VN handles this because:

Open-source MIT license – Deploy anywhere, modify freely
Zero-knowledge architecture – The QR points directly to the merchant's bank account; AgentPay never holds funds
Bank-level settlement confirmation – A feed from your bank tells your code when money arrived
Lightweight – Just 3 lines of flow logic: create request → send URL → await settlement

How AgentPay VN Works (The 3-Line Flow)

Understanding the architecture first saves debugging later:

Create Payment Request – You specify the amount and metadata (user ID, feature name, etc.)
Send Checkout URL – The response includes a checkout_url that renders a VietQR QR code
Await Settlement – Poll or webhook to confirm the user's bank transfer arrived

Your user sees a simple QR in Claude. They scan with their bank app. Their bank sends the payment directly to your registered merchant bank account. AgentPay's bank feed watches your account and tells your MCP server "payment cleared." Your code then unlocks the feature.

No intermediary holds money. No credit card friction. Pure bank transfer.

Installation & Setup

Step 1: Install the SDK

pip install agentpay-vn

This gives you the Python client to communicate with AgentPay's API.

Step 2: Register Your Bank Account

Visit https://agentpay.servicesai.vn/v1/docs and register your VietQR merchant account. You'll receive:

merchant_id (unique identifier for your account)
api_key (authentication token)
A bank feed configured to your registered merchant bank account

Step 3: Configure Your MCP Server Environment

Store your credentials securely:

export AGENTPAY_MERCHANT_ID="your_merchant_id"
export AGENTPAY_API_KEY="your_api_key"

Building Your First Paid MCP Tool

Code Example 1: Creating a Payment Request

Here's a complete MCP server that charges users for a "premium research report" feature:

import os
import json
from agentpay_vn import AgentPayClient
from datetime import datetime, timedelta

# Initialize the AgentPay client with your credentials
client = AgentPayClient(
    merchant_id=os.getenv("AGENTPAY_MERCHANT_ID"),
    api_key=os.getenv("AGENTPAY_API_KEY")
)

def create_premium_research_request(user_id: str, research_topic: str) -> dict:
    """
    Create a payment request for premium research.
    User pays 50,000 VND for detailed analysis.
    """

    # Step 1: Create payment request with AgentPay
    payment_request = client.create_payment_request(
        amount=50000,  # 50,000 VND
        description=f"Premium research report: {research_topic}",
        metadata={
            "user_id": user_id,
            "feature": "premium_research",
            "topic": research_topic,
            "timestamp": datetime.now().isoformat()
        },
        expires_in=600  # QR code valid for 10 minutes
    )

    # Step 2: Extract checkout URL for display to user
    checkout_url = payment_request["checkout_url"]
    request_id = payment_request["request_id"]

    # Step 3: Store request ID in your database for settlement tracking
    # (pseudocode: save_to_db(request_id, user_id, "pending"))

    return {
        "status": "awaiting_payment",
        "request_id": request_id,
        "checkout_url": checkout_url,
        "amount": 50000,
        "currency": "VND",
        "message": f"Scan the QR code to pay 50,000 VND for premium research on '{research_topic}'"
    }

# Example usage in your MCP handler
result = create_premium_research_request(
    user_id="claude_user_456",
    research_topic="Vietnamese E-Commerce Market 2024"
)
print(json.dumps(result, indent=2))

Line-by-line explanation:

Lines 8-10: Initialize AgentPayClient with your stored credentials
Lines 12-31: Define a function that accepts user ID and research topic
Lines 17-27: Call create_payment_request() with:
- amount: 50,000 VND (adjust to your pricing)
- description: Human-readable text for the user's bank receipt
- metadata: JSON object storing context (user ID, feature name) for later matching
- expires_in: Seconds until QR code expires
Lines 30-32: Extract the checkout_url (the QR code URL Claude will display) and request_id (for settlement confirmation)
Line 35: Return a response object Claude can render as a message with the QR code embedded

Code Example 2: Confirming Settlement

Once the user scans and pays, your server needs to confirm the settlement:

import asyncio
from agentpay_vn import AgentPayClient

client = AgentPayClient(
    merchant_id=os.getenv("AGENTPAY_MERCHANT_ID"),
    api_key=os.getenv("AGENTPAY_API_KEY")
)

async def wait_for_settlement(request_id: str, user_id: str, timeout_seconds: int = 300):
    """
    Poll AgentPay until the payment settles or timeout.
    Returns True if payment confirmed, False if timeout.
    """

    start_time = time.time()
    poll_interval = 2  # Check every 2 seconds

    while time.time() - start_time < timeout_seconds:
        try:
            # Query payment status from AgentPay
            status = client.get_payment_status(request_id)

            if status["state"] == "settled":
                # Payment confirmed! User funds arrived at your merchant account
                print(f"✓ Payment settled for user {user_id}")
                print(f"  Amount: {status['amount']} VND")
                print(f"  Bank reference: {status['bank_reference']}")

                # Update your database: mark user as paid, unlock feature
                # (pseudocode: unlock_premium_feature(user_id))

                return True

            elif status["state"] == "expired":
                print(f"✗ QR code expired for user {user_id}")
                return False

            elif status["state"] == "pending":
                # Payment not yet confirmed, keep polling
                print(f"⏳ Awaiting settlement... ({time.time() - start_time:.0f}s)")

        except Exception as e:
            print(f"Error checking payment: {e}")

        # Wait before next check
        await asyncio.sleep(poll_interval)

    print(f"✗ Timeout waiting for settlement of request {request_id}")
    return False

# Usage in your MCP tool
# After displaying QR to user, await settlement
result = await wait_for_settlement(
    request_id="req_abc123xyz",
    user_id="claude_user_456",
    timeout_seconds=600  # Wait up to 10 minutes
)

if result:
    print("Unlock premium research now!")
else:
    print("Payment not received. Please retry.")

Key points:

Lines 10-31: The polling loop checks settlement status every 2 seconds
Line 18: Call get_payment_status(request_id) to query AgentPay's bank feed
Lines 20-24: If state is "settled", the user's bank transfer cleared—unlock the feature
Lines 29-32: If state is "pending", keep waiting; if "expired", the QR code timed out
Line 45-51: In real usage, wrap this in your MCP tool handler so Claude can display status updates

Configuring Your MCP Server for Claude

Your MCP server exposes tools to Claude via JSON schema. Here's the configuration:

{
  "tools": [
    {
      "name": "request_premium_research",
      "description": "Request a premium research report. Initiates a payment request for 50,000 VND.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "topic": {
            "type": "string",
            "description": "The research topic (e.g., 'E-Commerce Market Trends')"
          },
          "depth": {
            "type": "string",
            "enum": ["standard", "deep"],
            "description": "Research depth level"
          }
        },
        "required": ["topic"]
      }
    },
    {
      "name": "check_payment_status",
      "description": "Check if a premium research payment has settled.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string",
            "description": "The payment request ID from AgentPay"
          }
        },
        "required": ["request_id"]
      }
    }
  ]
}

When Claude calls request_premium_research, your Python handler runs create_premium_research_request() and returns the QR code URL. Claude renders it inline. When the user says "check status", Claude calls check_payment_status(), which polls AgentPay and confirms if funds arrived.

Real-World Walkthrough: Online Course Platform

Imagine you run an AI-assisted course platform. Users ask Claude questions about Vietnamese business law. Free tier answers are brief; premium tier ($2 = ~50,000 VND) unlocks detailed analysis with case studies.

Flow:

User (in Claude): "I need detailed analysis of new e-commerce tax rules."
Claude checks user's subscription status in your database
User is free tier; Claude calls request_premium_research tool
Your MCP server creates payment request → returns QR code URL
Claude displays: "Scan this QR to unlock detailed analysis (50,000 VND)"
User scans QR with their bank app → transfers money
Backend polls AgentPay → detects settlement via bank feed
Your system unlocks premium access for that user's ID
Claude now calls internal tool to generate deep-dive analysis
User reads it in the same conversation

No credit card entry. No account creation. No payment processor dashboard. Just a bank transfer and a QR code.

Do's & Don'ts

DO	DON'T
Store `request_id` + `user_id` mapping in your DB	Display QR without storing request metadata
Poll settlement status regularly (2-5 sec intervals)	Trust payment instantly without confirmation
Set reasonable QR expiry (5-10 minutes)	Leave QR codes valid indefinitely
Log settlement confirmations for auditing	Ignore bank feed data—it's your proof of payment
Handle timeout gracefully (offer retry button)	Force users to wait >10 minutes for confirmation

Advanced Tips

Webhook-Based Settlement (Instead of Polling)

For production, configure AgentPay to send webhooks when payments settle:

from flask import Flask, request

app = Flask(__name__)

@app.route("/agentpay/webhook", methods=["POST"])
def handle_settlement_webhook():
    """
    AgentPay sends POST to this endpoint when payment settles.
    Signature verification prevents spoofing.
    """
    payload = request.json

    # Verify signature (provided in docs)
    if not verify_agentpay_signature(request.headers["X-Signature"], payload):
        return {"error": "Invalid signature"}, 403

    request_id = payload["request_id"]
    user_id = payload["metadata"]["user_id"]
    amount = payload["amount"]
    bank_ref = payload["bank_reference"]

    # Unlock feature immediately
    unlock_premium_feature(user_id)

    # Log transaction
    log_settlement(request_id, user_id, amount, bank_ref)

    return {"status": "processed"}, 200

Webhooks are faster and more reliable than polling, especially for high-volume services.

Tiered Pricing

Modify create_premium_research_request() to accept a pricing parameter:

pricing_tiers = {
    "standard": 50000,    # 50k VND
    "deep": 100000,       # 100k VND
    "enterprise": 500000  # 500k VND
}

def create_payment_by_tier(user_id: str, tier: str):
    amount = pricing_tiers.get(tier, 50000)
    return client.create_payment_request(
        amount=amount,
        description=f"Premium research ({tier} tier)",
        metadata={"user_id": user_id, "tier": tier}
    )

Claude can dynamically choose tiers based on user requests.

Rate Limiting & Fraud Prevention

Store payment requests in a database with timestamps. Reject users who spam payment requests:

import time
from collections import defaultdict

payment_history = defaultdict(list)

def check_rate_limit(user_id: str, max_requests: int = 5, window_seconds: int = 300):
    """
    Allow max 5 payment requests per user every 5 minutes.
    """
    now = time.time()
    # Remove old requests outside window
    payment_history[user_id] = [
        ts for ts in payment_history[user_id] 
        if now - ts < window_seconds
    ]

    if len(payment_history[user_id]) >= max_requests:
        return False, "Too many payment requests. Try again later."

    payment_history[user_id].append(now)
    return True, "OK"

FAQ

Q: Does AgentPay hold my money?
No. The QR code points directly to your merchant bank account. AgentPay is a payment request orchestrator, not a payment processor. You receive 100% of funds; there are no hidden fees or cuts.

Q: How do I verify settlement actually happened?
AgentPay monitors your merchant bank account via a configured bank feed (read-only access). When your bank reports a new incoming transfer matching the requested amount, AgentPay's API confirms it. You can also manually check your bank account for the transfer; the bank_reference field correlates transactions.

Q: What if the user's bank transfer fails?
The payment request expires (default 10 minutes). Your polling or webhook handler detects the expiry. You can offer the user to retry by generating a fresh QR code. Failed transfers never leave your merchant account, so no refunds are needed.

Q: Can I use this for non-Vietnamese users?
Currently, AgentPay VN is optimized for VietQR (Vietnamese bank transfers). International users would need a Vietnamese bank account or a local intermediary. Check docs for roadmap updates on multi-currency support.

Key Takeaways

Monetize Claude conversations instantly: No credit card required, no payment processor integration
3-line architecture: Create request → Send QR → Confirm settlement
Zero-knowledge design: Money goes straight to your bank; AgentPay never touches it
Settlement is certain: Bank feed confirmation = guaranteed funds arrival
Integrate in minutes: pip install agentpay-vn + 2 API calls + 1 MCP config
Open-source freedom: MIT license, deploy anywhere, full transparency

Next Steps

Install AgentPay VN: pip install agentpay-vn
Register your merchant account: Visit https://agentpay.servicesai.vn/v1/docs
Deploy the sample code: Adapt the Python examples above to your MCP server
Test with a small amount: Create a payment request for 10,000 VND, scan the QR with your bank app, and confirm settlement
Read the full docs: https://agentpay.servicesai.vn/v1/docs for webhooks, error handling, and advanced features
Join the community: Star the repo at https://github.com/phuocdu/agentpay-vn and contribute improvements

You now have everything needed to build a profitable MCP server that charges users directly inside Claude—with zero payment processor overhead.