DEV Community: ServicesAI VN

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.

VietQR payment automation for AI agents (an alternative to Strip

ServicesAI VN — Tue, 14 Jul 2026 00:33:47 +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.

Collect VietQR Payments in Telegram Bots with AgentPay

ServicesAI VN — Fri, 10 Jul 2026 00:36:48 +0000

The Problem: Manual Payment Friction in Telegram Bots

Imagine you're running an online course business via Telegram. A student wants to enroll in your Python masterclass—$50 course fee. Today, you're sending them a PayPal link, a bank transfer form, or worse, asking for manual payment confirmation. They drop out halfway through checkout. By the time they've copied account numbers and sent a screenshot, the friction has killed the sale.

Or you're a café owner with a delivery bot. Customers order coffee, but payment collection is either impossible (you have no payment gateway) or clunky (third-party checkout that breaks the flow).

This is the gap AgentPay VN closes: native, frictionless VietQR payment collection directly inside Telegram, with zero setup on the merchant's end and zero money touching your platform.

What is AgentPay VN?

AgentPay VN is an open-source (MIT license) Python SDK that lets AI agents and applications collect payments via VietQR—Vietnam's interbank QR standard. The key insight: AgentPay never holds funds. The QR code points directly to your merchant bank account. A bank feed confirms settlement in real time. You build the bot; your bank does the heavy lifting.

Two deployment options:

Python SDK (pip install agentpay-vn): Direct integration into your bot code.
MCP Server (agentpay-mcp): Claude or other AI agents invoke payment functions as tools.

For a Telegram bot, you'll typically use the Python SDK directly, with optional MCP integration if you're running Claude as your bot brain.

Setting Up Your Telegram Bot with AgentPay

Prerequisites

Python 3.9+ installed.
A Telegram bot token (create one via @BotFather on Telegram).
A Vietnamese merchant bank account (VietComBank, Agribank, ACB, etc.; VietQR is universally supported).
python-telegram-bot library for Telegram integration.

Step 1: Install Dependencies

pip install agentpay-vn python-telegram-bot

This installs:

agentpay-vn: Payment request generation, settlement confirmation.
python-telegram-bot: Telegram API bindings.

Step 2: Create Your First Payment Request

Here's a minimal Python bot that accepts a payment via VietQR:

from telegram import Update, InlineKeyboardButton, InlineKeyboardMarkup
from telegram.ext import Application, CommandHandler, ContextTypes
from agentpay_vn import create_payment_request, await_settlement
import uuid

# Initialize your Telegram bot
TELEGRAM_TOKEN = "your_telegram_bot_token_here"
MERCHANT_ACCOUNT = "0123456789"  # Your VietQR-enabled bank account
MERCHANT_NAME = "My Telegram Store"

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    """Send a welcome message with a payment button."""
    await update.message.reply_text(
        "Welcome! 🎉 I sell premium tutorials for $10 each.\n"
        "Click the button below to pay via VietQR."
    )

async def buy_tutorial(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    """Create a payment request and send the checkout URL."""

    # Step 1: Generate a unique payment request
    payment_id = str(uuid.uuid4())
    amount = 10  # USD equivalent; AgentPay handles conversion
    description = "Premium Python Tutorial Access"

    # Create the payment request (this generates a VietQR string)
    payment_request = create_payment_request(
        merchant_account=MERCHANT_ACCOUNT,
        merchant_name=MERCHANT_NAME,
        amount=amount,
        description=description,
        payment_id=payment_id,
        currency="USD"  # or "VND" if you prefer
    )

    # Step 2: Generate checkout URL (contains the QR or deep link)
    checkout_url = payment_request["checkout_url"]
    qr_image_url = payment_request["qr_image_url"]

    # Step 3: Send to user
    keyboard = [
        [InlineKeyboardButton("Pay Now", url=checkout_url)],
        [InlineKeyboardButton("Show QR Code", callback_data=f"qr_{payment_id}")]
    ]
    reply_markup = InlineKeyboardMarkup(keyboard)

    await update.message.reply_text(
        f"📱 Scan or tap to pay {amount} USD for tutorial access:\n\n"
        f"Transaction ID: {payment_id}",
        reply_markup=reply_markup
    )

    # Store payment_id in context for later confirmation
    context.user_data['pending_payment'] = payment_id

async def confirm_payment(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    """Poll the bank feed to check if payment settled."""
    payment_id = context.user_data.get('pending_payment')

    if not payment_id:
        await update.message.reply_text("❌ No pending payment found.")
        return

    # Step 4: Wait for settlement confirmation from the bank
    settlement_data = await_settlement(
        payment_id=payment_id,
        timeout_seconds=300  # Poll for up to 5 minutes
    )

    if settlement_data['settled']:
        user_id = update.message.from_user.id
        # Grant access (e.g., send PDF, unlock content)
        await update.message.reply_text(
            f"✅ Payment confirmed! Amount: {settlement_data['amount']} VND\n"
            f"Access link: [Download Tutorial](https://your-course-link.com)"
        )
        # Log transaction
        print(f"User {user_id}: {settlement_data}")
    else:
        await update.message.reply_text(
            "⏳ Payment still pending. Check your bank app or try again in 2 minutes."
        )

if __name__ == "__main__":
    app = Application.builder().token(TELEGRAM_TOKEN).build()

    app.add_handler(CommandHandler("start", start))
    app.add_handler(CommandHandler("buy", buy_tutorial))
    app.add_handler(CommandHandler("confirm", confirm_payment))

    app.run_polling()

Line-by-line explanation:

Lines 10–11: Bot token and merchant account (replace with your actual values).
Lines 19–21: buy_tutorial() generates a unique payment ID using UUID.
Lines 24–32: create_payment_request() builds a VietQR payment object with amount, description, and merchant details. It returns a checkout_url (deeplink to VietQR apps) and qr_image_url.
Lines 35–42: Creates Telegram inline buttons so users can tap directly from chat.
Lines 52–60: await_settlement() polls the bank feed every 2–5 seconds (configurable) until the bank confirms the transaction or timeout.
Lines 61–65: Once settled, grant access (send PDF, unlock content, issue API key, etc.).

Real-World Walkthrough: Online Course Bot

Let's say you're selling a 4-week "Build with Claude" course for 500,000 VND (~$20 USD):

User sends /buy → Bot generates a payment request with amount=500000, currency="VND".
User taps "Pay Now" → They're taken to their default VietQR app (Vietcombank, Agribank, Momo, etc.) with the QR pre-filled.
They authorize in 3 seconds → Bank debits their account, credits yours.
Bot polls the bank feed → Within 10–30 seconds, AgentPay confirms settlement.
Bot unlocks course → Sends access link, lesson 1 PDF, and Discord invite.

No Stripe account. No PayPal hold. No payment gateway fees (beyond your bank's standard transfer fee, typically 0–0.5% VND). Pure direct-to-bank flow.

MCP Integration for AI Agents

If you're building a multi-agent system where Claude or another LLM orchestrates your bot, use AgentPay's MCP server:

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "env": {
        "AGENTPAY_MERCHANT_ACCOUNT": "0123456789",
        "AGENTPAY_MERCHANT_NAME": "My Telegram Store",
        "AGENTPAY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Now Claude can invoke payment functions as tools:

User: "I want to buy the premium tutorial."
Claude (via MCP): agentpay:create_payment_request(amount=500000, currency="VND")
Claude: "Here's your payment link: [link]. Once paid, I'll unlock your content."

Advanced Tips

Idempotency & Duplicate Prevention

Always use a unique payment_id (UUID or timestamp + user ID). If the same user clicks "Pay" twice, reuse the same payment_id. AgentPay deduplicates on the bank feed, so you won't double-charge.

Graceful Timeout Handling

Bank feeds can take 10–60 seconds depending on the issuing bank. Set timeout_seconds generously:

# Poll for up to 2 minutes; don't block the user
await_settlement(payment_id=payment_id, timeout_seconds=120)

Alternatively, send a "Payment pending" message and ask them to check back later.

Store Metadata

Associate each payment with user data:

# Before creating the payment request
user_id = update.message.from_user.id
user_phone = update.message.from_user.phone_number

payment_request = create_payment_request(
    merchant_account=MERCHANT_ACCOUNT,
    amount=10,
    payment_id=f"{user_id}_{uuid.uuid4()}",
    metadata={"user_id": user_id, "phone": user_phone, "product": "tutorial"}
)

Retrieve metadata when settlement confirms, so you know exactly who paid for what.

Multi-Currency Support

AgentPay auto-converts USD/EUR to VND at market rates. Test with:

# Charge $10 USD
payment_request = create_payment_request(
    amount=10,
    currency="USD",
    ...
)

# Or charge 250,000 VND directly
payment_request = create_payment_request(
    amount=250000,
    currency="VND",
    ...
)

Do's and Don'ts

Do	Don't
Use HTTPS for all URLs	Hardcode merchant account in repo
Store `payment_id` in a database	Reuse the same `payment_id` for multiple users
Poll settlement asynchronously (don't block)	Charge the user before settlement confirms
Log every transaction for audit	Expose API keys in Telegram messages
Set reasonable timeouts (60–120s)	Assume instant settlement (takes 10–60s)
Test with small amounts first ($1 USD)	Use production merchant account before testing

FAQ

Q: Does AgentPay charge a fee?
A: No. AgentPay is open-source (MIT). You only pay your bank's standard wire/transfer fees (typically 0–0.5% in Vietnam).

Q: What if a user scans the QR but cancels payment?
A: await_settlement() will timeout and return settled=False. Send a friendly "Payment not received" message; they can retry.

Q: Can I use AgentPay outside Vietnam?
A: VietQR is Vietnam-specific, so the merchant account must be at a Vietnamese bank. However, users can pay from international cards via some banks' apps.

Q: Is settlement guaranteed?
A: Yes. The bank feed is the source of truth. Once await_settlement() returns settled=True, the money is in your account.

Key Takeaways

✅ AgentPay removes payment friction: VietQR is instant, native to Vietnamese banking apps, and requires zero gateway setup.
✅ Your money stays yours: No platform hold or escrow. QR points directly to your bank account.
✅ 3-line integration: create_payment_request() → checkout_url → await_settlement().
✅ Production-ready: Open-source, battle-tested, supports both Python SDK and MCP for AI agents.
✅ Multi-use: Courses, e-commerce, cafés, subscriptions, tips, donations—anywhere you need payment in a chat interface.

Getting Started Now

Install AgentPay VN:

   pip install agentpay-vn

Read the full docs:
https://agentpay.servicesai.vn/v1/docs
Clone the GitHub repo for examples:
https://github.com/phuocdu/agentpay-vn
Test with a small transaction (e.g., 10,000 VND / ~$0.40 USD) to confirm your merchant account and Telegram bot work end-to-end.

Your Telegram users deserve frictionless payments. AgentPay VN makes that possible—no gateway, no middleman, no delays. Start collecting payments in minutes.

Collect VietQR Payments in Telegram Bots with AgentPay

ServicesAI VN — Thu, 09 Jul 2026 00:35:20 +0000

The Problem: Why Most Telegram Payment Bots Fail

You've built a Telegram bot that sells digital courses, takes coffee orders, or offers freelance services. Traffic is flowing. But when your bot tries to collect payment, you hit a wall:

Payment gateways demand hefty setup fees and compliance audits
You end up holding customer money in an intermediary account (legal liability)
Settlement takes 3–5 days, frustrating both you and buyers
Integration is a maze of webhooks, IPNs, and error handling

A founder we know spent two weeks wrestling with Stripe's Telegram integration, only to discover the monthly fee ate 40% of his margins on $2–5 transactions. He needed something lighter, faster, and truly peer-to-peer.

Enter AgentPay VN: an open-source Python SDK that lets your Telegram bot generate QR codes pointing directly to your bank account. No middleman. No holding funds. Just instant VietQR payments via the banking system Vietnameses already use daily.

What Is AgentPay VN?

AgentPay VN is an MIT-licensed Python SDK + MCP server that orchestrates VietQR payment requests. Here's the mental model:

You create a payment request in your bot (e.g., "Customer ordered coffee for 50,000 VND")
AgentPay generates a checkout URL with an embedded QR code
Customer scans → pays → bank confirms settlement in seconds
Your bot receives a webhook callback and fulfills the order

The key: AgentPay never touches money. The QR points straight at your merchant bank account. A bank feed confirms settlement. You own the transaction end-to-end.

Why Telegram + VietQR?

Telegram has 180+ million users, with especially strong adoption in Southeast Asia. Vietnamese merchants already use banking apps (MB Bank, Techcombank, VCB) that natively support VietQR scanning. Your bot becomes a natural extension of their daily workflow:

Customer receives a payment link in chat
Opens the QR code (in-app or screenshot)
Scans with their banking app (2–3 taps)
Money clears to your account in minutes
Bot auto-confirms and ships the digital good / service

No authentication screens. No signup. Pure banking rails.

Step 1: Installation & Setup

Install AgentPay SDK

pip install agentpay-vn

Verify the installation:

python -c "import agentpay; print(agentpay.__version__)"

Get Your Merchant Credentials

You'll need:

Merchant ID (from your bank's VietQR partner)
API Key (provided by the bank or AgentPay partner)
Bank Account details (IBAN/ACN)

For testing, AgentPay provides a sandbox environment. Check the official docs for your bank.

Set Environment Variables

export AGENTPAY_MERCHANT_ID="your_merchant_id"
export AGENTPAY_API_KEY="your_api_key"
export TELEGRAM_BOT_TOKEN="your_telegram_token"

Step 2: Build Your First Payment Bot

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

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

# Initialize AgentPay
agentpay_client = AgentPayClient(
    merchant_id=os.getenv("AGENTPAY_MERCHANT_ID"),
    api_key=os.getenv("AGENTPAY_API_KEY"),
)

async def start(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    """Send welcome message with a /buy command."""
    await update.message.reply_text(
        "🎉 Welcome! Use /buy to purchase an item.\n"
        "Type /help for more info."
    )

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

    # Step 1: Create a payment request
    # This tells AgentPay: "I want 50,000 VND from user X"
    payment_request = agentpay_client.create_payment_request(
        amount=50000,  # VND
        currency="VND",
        merchant_ref_id=f"order_{user_id}_{int(time.time())}",
        description="Premium Course - Python Mastery",
        metadata={"user_id": user_id, "product": "course_python"},
    )

    # Step 2: Get the checkout URL with embedded QR
    checkout_url = payment_request.get("checkout_url")
    payment_id = payment_request.get("payment_id")

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

    await update.message.reply_text(
        f"📦 Order Summary:\n"
        f"Product: Premium Course\n"
        f"Price: 50,000 VND\n\n"
        f"Tap the button below to pay with your banking app.",
        reply_markup=keyboard
    )

    # Store payment_id for later confirmation
    context.user_data["pending_payment_id"] = payment_id

async def check_payment(update: Update, context: ContextTypes.DEFAULT_TYPE) -> None:
    """Poll for payment settlement (in production, use webhooks)."""
    payment_id = context.user_data.get("pending_payment_id")

    if not payment_id:
        await update.message.reply_text("No pending payment found.")
        return

    # Step 3: Await settlement confirmation
    # In production, listen to bank webhooks instead of polling
    status = agentpay_client.await_settlement(
        payment_id=payment_id,
        timeout=300,  # Wait max 5 minutes
    )

    if status["settled"]:
        await update.message.reply_text(
            f"✅ Payment confirmed!\n"
            f"Amount: {status['amount']:,} VND\n"
            f"Your premium course access is now active.\n"
            f"📚 [Open Course](https://example.com/course)"
        )
        # Grant access to course, send API key, etc.
    else:
        await update.message.reply_text(
            "⏳ Payment not yet confirmed. Try again in a moment."
        )

def main():
    """Start the bot."""
    app = Application.builder().token(
        os.getenv("TELEGRAM_BOT_TOKEN")
    ).build()

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

    print("🤖 Bot running...")
    app.run_polling()

if __name__ == "__main__":
    import time
    main()

Line-by-line breakdown:

Lines 10–12: Initialize AgentPayClient with credentials from environment
Lines 19–21: /start sends a welcome message
Lines 23–37: /buy creates a payment request with amount, reference ID, and metadata
Lines 39–41: Extract the checkout URL (contains QR) and payment ID
Lines 43–47: Send an inline button linking to the checkout URL
Lines 51–65: /check polls for settlement status (use webhooks in production!)
Lines 67–74: On settlement, confirm and grant access

Step 3: Production Setup with Webhooks

Polling is fine for demos, but slow and unreliable. Use bank webhooks to get instant payment confirmation:

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhook/agentpay", methods=["POST"])
def handle_payment_webhook():
    """AgentPay calls this when payment settles."""
    payload = request.json

    # Verify the signature (AgentPay docs explain this)
    if not agentpay_client.verify_webhook_signature(
        payload, request.headers.get("X-Signature")
    ):
        return {"error": "Invalid signature"}, 401

    payment_id = payload["payment_id"]
    status = payload["status"]  # "settled" or "failed"
    amount = payload["amount"]
    merchant_ref_id = payload["merchant_ref_id"]

    if status == "settled":
        # Extract user ID from merchant_ref_id
        user_id = int(merchant_ref_id.split("_")[1])

        # Grant access to the user
        # e.g., send them an API key, activate subscription, etc.
        grant_access(user_id)

        # Notify user via Telegram
        asyncio.run(
            send_telegram_message(
                user_id,
                f"✅ Payment received! ({amount:,} VND)\n"
                "Your access is active."
            )
        )

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

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000)

Configure your webhook URL in the AgentPay dashboard to https://yourdomain.com/webhook/agentpay.

Step 4: Use AgentPay with Claude (MCP Server)

If you're using Claude as your AI agent orchestrator, install the MCP server:

pip install agentpay-mcp

Configure Claude's MCP settings:

{
  "mcpServers": {
    "agentpay": {
      "command": "agentpay-mcp",
      "env": {
        "AGENTPAY_MERCHANT_ID": "your_merchant_id",
        "AGENTPAY_API_KEY": "your_api_key"
      }
    }
  }
}

Now Claude can call AgentPay directly:

User: "I want to sell a course for 200,000 VND."
Claude: I'll create a payment request for you.
[Calls agentpay.create_payment_request()]
Claude: Payment link: https://checkout.agentpay.vn/...

Real-World Example: Coffee Shop Telegram Bot

Imagine a café selling espresso shots via Telegram:

Customer: /order → "1x Espresso (40,000 VND)"
Bot: Creates payment request, sends QR code
Customer: Scans QR, confirms in banking app (10 seconds)
Bank: Settles to café's account instantly
Webhook: Fires, bot receives settlement notification
Bot: "✅ Order confirmed! Your coffee is ready at counter #3"
Café owner: Checks dashboard, sees +40,000 VND received

The entire flow takes 30 seconds. No payment processor fees. No settlement delays.

Advanced Tips & Gotchas

Tip 1: Use Idempotent Keys

Always include a unique merchant_ref_id to prevent duplicate charges if the network retries:

import uuid

merchant_ref_id = f"order_{user_id}_{uuid.uuid4()}"

Tip 2: Handle Webhook Timeouts

Not all webhooks arrive instantly. Implement retry logic:

from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(5), wait=wait_exponential())
async def notify_user_via_telegram(user_id, message):
    # Attempt up to 5 times with exponential backoff
    await bot.send_message(user_id, message)

Tip 3: Store Payment State

Use a database (PostgreSQL, MongoDB) to track payment status:

class PaymentRecord(db.Model):
    payment_id = db.Column(db.String, primary_key=True)
    user_id = db.Column(db.Integer)
    amount = db.Column(db.Integer)  # VND
    status = db.Column(db.String)  # pending, settled, failed
    created_at = db.Column(db.DateTime, default=datetime.now)

Tip 4: Test on Sandbox First

AgentPay provides a sandbox environment. Always test before going live:

agentpay_client = AgentPayClient(
    merchant_id="sandbox_merchant_id",
    api_key="sandbox_api_key",
    environment="sandbox",  # Switch to "production" later
)

Do's and Don'ts

✅ Do	❌ Don't
Use webhook callbacks for payment confirmation	Poll the API in a tight loop
Store merchant_ref_id; match it in webhook	Trust the order of webhook events
Verify webhook signatures	Skip signature verification
Implement idempotent request IDs	Assume network calls always succeed
Start with sandbox environment	Go live without testing
Monitor settlement times	Assume instant settlement (usually seconds, but be safe)
Log all payment events	Ignore payment failures silently

FAQ

Q: Can AgentPay handle payments in other currencies (USD, etc.)?

A: Currently, AgentPay VN is designed for VND (Vietnamese Dong) via VietQR, which is a Vietnamese banking standard. International currency support would require additional bank partnerships.

Q: What if the customer's bank doesn't support VietQR?

A: Most Vietnamese banks (MB, Vietcombank, Techcombank, ACB, VP Bank, etc.) support VietQR. If a customer's bank doesn't, they can ask their bank to enable it, or you can provide a fallback (e.g., direct bank transfer details).

Q: How much does AgentPay cost?

A: AgentPay itself is free (MIT open-source). You pay your bank's standard VietQR transaction fees (typically 0–0.5%), which is much cheaper than Stripe (2.9% + $0.30) or PayPal (3.5%).

Q: How long does settlement take?

A: Usually 1–5 seconds. The money goes directly to your bank account, so it's as fast as an interbank transfer. Some banks may batch settlements end-of-day, but that's rare.

Key Takeaways

No middleman: AgentPay never holds funds; QR codes point straight to your bank account
Fast setup: Install with pip install agentpay-vn and get your first payment in under 10 minutes
Telegram-native: Customers pay without leaving Telegram; no signup required
Low fees: Pay only your bank's VietQR fees (0–0.5%), not 3% payment processor cuts
Production-ready: Use webhooks, idempotent IDs, and proper error handling
Open-source: MIT license means full transparency and community support
MCP integration: Use with Claude or other AI agents for autonomous payment orchestration

Next Steps

Install AgentPay: pip install agentpay-vn
Get credentials: Contact your bank or visit agentpay.servicesai.vn
Clone the repo: github.com/phuocdu/agentpay-vn
Read the docs: agentpay.servicesai.vn/v1/docs
Build your bot: Follow the examples above and ship!

Your Telegram payment bot is minutes away. No more payment processor headaches. Just you, your customers, and the Vietnamese banking system doing what it does best.

Collect VietQR Payments in Telegram Bots with AgentPay

ServicesAI VN — Mon, 06 Jul 2026 00:13:45 +0000

The Problem: Getting Paid Through Telegram Is Messy

You've built a useful Telegram bot—maybe it sells online courses, takes café orders, or books freelance services. Your users love it. But when payment time comes, everything breaks down. You're manually sending payment screenshots, users are using unsafe third-party links, and nobody's sure if money actually arrived. You definitely don't want to hold customer funds in your own account (legal liability, licensing headaches). What you need is a way for your bot to generate a VietQR code pointing directly at your bank account, and then automatically confirm when the payment settles. That's where AgentPay VN comes in.

Why VietQR + AgentPay Is the Right Move

VietQR is Vietnam's national instant payment standard—every bank supports it, every Vietnamese smartphone has a QR scanner built-in, and users trust it because it uses their actual bank app. AgentPay VN is an MIT-licensed Python SDK that wraps the complexity away. It never touches your money (the QR points straight to your bank), and a real bank feed confirms settlement in seconds. No middleman fees, no foreign exchange hassles, no merchant account approval delays.

The magic is in three lines:

create_payment_request — generate a unique request tied to your bot order
send checkout_url — post the QR code to your user
await_settlement — block until the bank confirms payment

That's it. Let's build it.

Installation and Setup

Step 1: Install the SDK

pip install agentpay-vn

Verify it works:

python -c "import agentpay; print(agentpay.__version__)"

Step 2: Set Up Your Bank Feed (One-Time)

AgentPay needs a way to know when your bank receives money. You'll configure a webhook or use AgentPay's bank integration partner. Visit https://agentpay.servicesai.vn/v1/docs for your bank's specific setup—most Vietnamese banks (Vietcombank, Techcombank, Agribank, etc.) are already supported.

Step 3: Get Your API Credentials

AGENTPAY_API_KEY — your secret key
AGENTPAY_MERCHANT_ID — identifies your account
TELEGRAM_BOT_TOKEN — from BotFather

Store these in a .env file (never commit it):

AGENTPAY_API_KEY=your_key_here
AGENTPAY_MERCHANT_ID=your_merchant_id
TELEGRAM_BOT_TOKEN=your_bot_token

Building Your First Payment Flow

Full Working Example: Course Sales Bot

Let's say you're selling a "Python Mastery" course for 299,000 VND via Telegram. Here's the complete flow:

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

load_dotenv()

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

app = Application.builder().token(os.getenv("TELEGRAM_BOT_TOKEN")).build()

# Store pending payments in memory (use Redis in production)
pending_payments = {}

async def start_course_purchase(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    User sends /buy_course — we create a payment request
    """
    user_id = update.effective_user.id
    course_price = 299000  # VND
    course_name = "Python Mastery 2024"

    # Step 1: Create a payment request with AgentPay
    payment_request = await client.create_payment_request(
        amount=course_price,
        description=f"Course: {course_name}",
        order_id=f"course_{user_id}_{int(asyncio.get_event_loop().time())}",
        customer_name=update.effective_user.full_name or "Anonymous",
        customer_phone="",  # Optional; collect if needed
        redirect_url="https://t.me/your_bot_username"  # Where to send user after payment
    )

    # Step 2: Store the payment request locally (for later confirmation)
    pending_payments[payment_request.order_id] = {
        "user_id": user_id,
        "amount": course_price,
        "course": course_name
    }

    # Step 3: Send checkout URL to user with QR code
    checkout_url = payment_request.checkout_url
    keyboard = InlineKeyboardMarkup(
        [[InlineKeyboardButton("💳 Pay with VietQR", url=checkout_url)]]
    )

    await update.message.reply_text(
        f"🎓 Ready to buy **{course_name}**?\n\n"
        f"Price: **{course_price:,} VND**\n\n"
        f"Click the button below to scan the QR code with your bank app. "
        f"You'll be redirected back here once payment is confirmed.",
        reply_markup=keyboard,
        parse_mode="Markdown"
    )

    # Step 4 (Background): Wait for settlement
    asyncio.create_task(wait_for_payment(payment_request.order_id, user_id, course_name))

async def wait_for_payment(order_id: str, user_id: int, course_name: str):
    """
    Poll AgentPay until payment settles (timeout: 30 minutes)
    """
    max_wait = 1800  # 30 minutes
    elapsed = 0

    while elapsed < max_wait:
        try:
            # Check if payment has settled
            settlement = await client.await_settlement(
                order_id=order_id,
                timeout=10  # Check every 10 seconds
            )

            if settlement.status == "confirmed":
                # Payment successful! Grant access to course
                await app.bot.send_message(
                    chat_id=user_id,
                    text=f"✅ **Payment confirmed!**\n\n"
                         f"Your access to {course_name} is now active.\n"
                         f"Check your email for login details.\n\n"
                         f"Transaction ID: `{settlement.transaction_id}`",
                    parse_mode="Markdown"
                )

                # Log the successful transaction
                print(f"Payment confirmed: {order_id} | Amount: {settlement.amount} VND")
                return

        except asyncio.TimeoutError:
            elapsed += 10
        except Exception as e:
            print(f"Error checking payment {order_id}: {e}")
            await asyncio.sleep(10)
            elapsed += 10

    # Timeout — notify user
    await app.bot.send_message(
        chat_id=user_id,
        text=f"⏱️ Payment timeout. If you already paid, please wait a few seconds and try /check_payment\n"
             f"If not, use /buy_course to try again."
    )

async def check_payment(update: Update, context: ContextTypes.DEFAULT_TYPE):
    """
    User can manually check status with /check_payment
    """
    user_id = update.effective_user.id
    user_orders = [o for o, p in pending_payments.items() if p["user_id"] == user_id]

    if not user_orders:
        await update.message.reply_text("No pending payments found.")
        return

    for order_id in user_orders:
        try:
            settlement = await client.get_payment_status(order_id)
            if settlement.status == "confirmed":
                await update.message.reply_text(f"✅ Payment {order_id} is confirmed!")
            else:
                await update.message.reply_text(f"⏳ Payment {order_id} is still pending...")
        except Exception as e:
            await update.message.reply_text(f"Error checking status: {e}")

app.add_handler(CommandHandler("buy_course", start_course_purchase))
app.add_handler(CommandHandler("check_payment", check_payment))

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

Line-by-line explanation:

Lines 10-14: Initialize AgentPayClient with your credentials.
Lines 23-39: create_payment_request() generates a unique payment link tied to this user's order.
Lines 42-44: Store the order locally so we can track who paid for what.
Lines 46-54: Build a Telegram inline button linking to the checkout URL (which displays the VietQR code).
Lines 57: Kick off a background task to wait for settlement—the user doesn't have to stay in the chat.
Lines 62-86: await_settlement() polls the bank feed until payment is confirmed. Once confirmed, we grant course access.
Lines 88-105: Optional /check_payment command lets users manually check if payment went through.

Using AgentPay with Claude and MCP

If you're using AI agents (Claude, etc.) to manage your bot, AgentPay provides an MCP (Model Context Protocol) server. Install it:

pip install agentpay-mcp

Configure it in your Claude settings (or .mcp.json):

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

Now Claude can call AgentPay functions directly:

User: "A customer wants to buy my e-book for 99,000 VND. Create a payment link."

Claude: I'll use AgentPay to create a payment request for you.
[Calls: create_payment_request(amount=99000, description="E-book", ...)]
→ Returns checkout_url

Claude: "Here's your payment link: [link]. Share it with your customer."

Real-World Walkthrough: Café Ordering Bot

Imagine a small coffee shop in Saigon. They built a Telegram bot where customers can order coffee, pay, and pick up. Here's how AgentPay fits:

Order placed: Customer types /order → selects "2x Cà Phê Đen + 1x Trà Lạnh" (120,000 VND).
Payment link sent: Bot calls create_payment_request() → generates VietQR code → sends link to customer.
Customer scans: User opens their Agribank/Vietcombank app → scans QR → confirms transfer.
Settlement confirmed: Bank webhook hits AgentPay → await_settlement() resolves → bot sends "Order ready! Pick up at counter #3."
Record kept: Shop owner can see all payments in their AgentPay dashboard (linked to their actual bank statement).

Total time: 2 minutes. No middle app, no fees beyond normal bank transfer, no fraud risk.

Do's and Don'ts

✅ Do	❌ Don't
Use `.env` files for secrets	Hardcode API keys in source code
Implement retry logic on timeouts	Assume QR codes are unique per user (they're not—reuse is safe)
Log transaction IDs for reconciliation	Hold customer funds in a separate account
Set reasonable timeouts (5–30 min)	Use old/revoked QR codes
Test with small amounts first	Ignore bank feed errors silently
Store order metadata (product, user, timestamp)	Forget to handle network disconnects

Advanced Tips

Tip 1: Batch Payments

If you're selling multiple items, don't create separate payment requests. Sum the total and create one request:

total = sum([item["price"] for item in cart])
await client.create_payment_request(
    amount=total,
    description=f"{len(cart)} items",
    order_id=f"cart_{user_id}_{timestamp}"
)

Tip 2: Idempotency

If your bot crashes mid-payment, reuse the same order_id to avoid double-charging:

order_id = f"course_{user_id}_{course_id}"  # Deterministic
settlement = await client.get_payment_status(order_id)
if settlement and settlement.status == "confirmed":
    # Already paid—grant access
    pass
else:
    # Create new request
    await client.create_payment_request(order_id=order_id, ...)

Tip 3: Webhooks Instead of Polling

For production bots with thousands of users, polling is inefficient. Configure a webhook with AgentPay:

@app.post("/agentpay/webhook")
async def handle_settlement(payload: dict):
    order_id = payload["order_id"]
    status = payload["status"]

    if status == "confirmed":
        user_id = pending_payments[order_id]["user_id"]
        await app.bot.send_message(user_id, "✅ Payment confirmed!")

This way, AgentPay notifies you when payment settles—no polling required.

FAQ

Q: Does AgentPay hold my money?
No. The VietQR code points directly to your bank account. AgentPay only confirms settlement via your bank feed—it never touches the funds.

Q: What if a customer disputes the payment?
AgentPay logs all transactions with bank-confirmed transaction IDs. Disputes go through your bank's normal chargeback process—AgentPay provides the proof.

Q: Can I use AgentPay outside Vietnam?
Currently, VietQR is Vietnam-only. If you want to accept international payments, you'll need a separate solution (Stripe, PayPal).

Q: How long does settlement confirmation take?
Typically 2–10 seconds after the customer completes the transfer. Occasionally up to 2 minutes depending on the bank.

Q: Do I need to register my bot with the government?
Regulations vary. For educational or small commercial bots, you're usually fine. For large-scale commerce, consult a Vietnamese lawyer about merchant licensing.

Key Takeaways

VietQR + AgentPay = friction-free payments in Telegram bots without holding customer funds.
Installation is one line: pip install agentpay-vn
The flow is simple: create_payment_request() → send checkout_url() → await_settlement()
Bank confirmation is real: Your bank feed confirms every transaction—no fake payments.
Works at scale: Use webhooks for thousands of concurrent users; use polling for hobby bots.
MIT licensed & open-source: Full transparency, no vendor lock-in.
Vietnam-specific: Built for VietQR, integrated with major Vietnamese banks.

Get Started Now

You have everything you need. Install AgentPay VN, wire up a test bot, and accept your first payment in under 20 minutes.

pip install agentpay-vn

Read the full API reference and bank-specific setup guides at https://agentpay.servicesai.vn/v1/docs and explore the source code on GitHub.

Have questions? Join the community, open an issue, or reach out. Happy collecting! 🎉

Agent-native payments: building idempotent checkout flows with AgentPay

ServicesAI VN — Thu, 25 Jun 2026 04:04:22 +0000

Problem: AI agents need to collect money without holding it

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

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

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

How AgentPay solves it

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

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

The flow is 3 lines:

from agentpay import PaymentClient

client = PaymentClient(api_key="your_key")

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

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

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

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

Wiring it into Claude via MCP

Install the MCP server:

pip install agentpay-vn

Add to claude_desktop_config.json:

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

Now in Claude:

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

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

Idempotency + webhooks matter

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

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

Webhooks let you skip polling:

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

Honest limitations

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

DEV Community: ServicesAI VN

Build a Telegram Payment Bot with VietQR & AgentPay

The Problem: Why Telegram Bots Need Native Payment Support

Why VietQR + Telegram Is the Perfect Pairing

Installation & Setup

Step 1: Install the SDK

Step 2: Get Your Merchant Info

Step 3: Set Environment Variables (Optional)

Building Your First Payment Flow

The 3-Step Pattern

Line-by-Line Breakdown

Real-World Example: A Café Order Bot

Using AgentPay with AI Agents (MCP Server)

Do's & Don'ts

Advanced Tips

1. Custom Expiry Times

2. Handling Payment Failures Gracefully

3. Batch Payments for Subscriptions

FAQ

Key Takeaways

Next Steps

Collect VietQR Payments in Telegram Bots with AgentPay

The Problem: Telegram Bots That Can't Monetize

Why AgentPay Changes the Game

Installation & Setup

Step 1: Install the SDK

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

Step 3: Get Your Merchant Info

The 3-Line Payment Flow

Real-World Example: A Course-Selling Telegram Bot

Integrating with Claude via MCP

Do's and Don'ts

Advanced Tips

Batch Payments for Subscriptions

Webhook Notifications (Future Feature)

Multi-Currency (Future)

FAQ

Key Takeaways

Get Started Now

Build a Telegram Payment Bot with VietQR & AgentPay

The Problem: Selling on Telegram Without Payment Friction

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

Part 1: Installation & Setup

Step 1: Install the SDK

Step 2: Configure Your Merchant Account

Step 3: Set Up Your Telegram Bot

Part 2: The Three-Line Payment Flow Explained

Part 3: Build Your First Bot

Part 4: Using AgentPay with Claude (MCP Mode)

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

Part 6: Do's and Don'ts

Part 7: Advanced Tips

Tip 1: Reconciliation Dashboard

Tip 2: Retry Logic for Flaky Networks

Tip 3: Multi-Product Catalog with Webhooks

FAQ

Key Takeaways

Next Steps

Build a paid MCP server: charge users from inside Claude

Overview

Links

Telegram Bot Payments with VietQR: AgentPay Guide

The Problem: Payments Break Telegram Bots

What Is AgentPay VN?

Why Telegram + VietQR + AgentPay?

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

1. Set Up Your Merchant Account

2. Install and Initialize

3. Create Your First Payment Request

4. Integrate with Claude via MCP

Real-World Walkthrough: Café Pre-Order Bot

Do's and Don'ts

Advanced Tips

Batch Payments

Webhook Integration (Production)

Multi-Currency Support

FAQ

Key Takeaways

Get Started Now

Agent-native payments: idempotency, webhooks, settlement