Thanh toán crypto trong bot Telegram: hóa đơn, webhook, chi trả
Merchant API là API thanh toán của TgPay Crypto cho bot và dịch vụ. Tạo ứng dụng, lấy token, phát hành hóa đơn từ mã và nhận webhook có chữ ký khi thanh toán. Bạn cũng có thể giao phần tích hợp cho AI agent qua MCP. Thanh toán nội bộ không có phí mạng lưới hay thời gian chờ xác nhận.
Địa chỉ gốc API: app.tgpaycrypto.com/pay/api · Testnet: testnet.tgpaycrypto.com
Từ token đến thanh toán đầu tiên trong bốn bước
Tạo hóa đơn, hiển thị liên kết và chờ sự kiện thanh toán.
Tạo ứng dụng
Trong bot, mở Thêm → Merchant API, nhập tên và URL webhook. Token chỉ hiển thị một lần, hãy giữ trên máy chủ.
Tạo hóa đơn
Gửi POST đến createInvoice với số tiền crypto hoặc pháp định, mô tả và hạn. Phản hồi chứa liên kết thanh toán.
Hiển thị liên kết cho người dùng
Đặt nút hoặc liên kết trong bot. Người dùng trả từ số dư ví.
Xử lý webhook
Máy chủ nhận invoice_paid có chữ ký HMAC-SHA256. Xác thực chữ ký, loại trùng theo update_id rồi giao hàng.
AI agent có thể chuẩn bị tích hợp
Merchant API có máy chủ MCP. Gửi URL cho AI agent để đọc tài liệu, tạo ứng dụng khi bạn duyệt, đặt webhook và viết mã. Không cần sao chép token thủ công.
- Bước 1
Gửi yêu cầu cho AI agent
Dùng Claude Code, claude.ai, Claude Desktop, ChatGPT hoặc ứng dụng khách MCP khác. Cùng yêu cầu có trong Thêm → Merchant API → Kết nối AI agent.
- Bước 2
Duyệt ứng dụng trong Telegram
AI agent cung cấp liên kết t.me. Bot hiển thị yêu cầu để bạn duyệt. Liên kết dùng một lần, chưa duyệt thì chưa tạo ứng dụng.
- Bước 3
AI agent hoàn tất cài đặt
Nhận token giới hạn và cấu hình hóa đơn, gói đăng ký, webhook. Khóa ký webhook vẫn do bạn quản lý trong ứng dụng.
Token cấp qua quy trình này có thể nhận thanh toán và đặt webhook, nhưng không chuyển tiền, tạo Lì xì hay hoàn tiền. Giao dịch đưa tiền ra cần quyền riêng do bạn kiểm soát.
Quy trình với AI agent trong tài liệuConnect the tgpay MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the TgPay Merchant API.
claude mcp add --transport http tgpay https://app.tgpaycrypto.com/mcp
Thêm app.tgpaycrypto.com/mcp làm máy chủ MCP trong cài đặt ứng dụng khách
https://testnet.tgpaycrypto.com/mcp
Phí và hạn mức
Giá trị lấy từ danh mục hạn mức công khai tại thời điểm tạo trang. Ứng dụng là nguồn thông tin hiện hành.
Các chức năng của Merchant API
Ứng dụng có số dư riêng, tách khỏi ví. Hóa đơn cộng tiền vào đó; chi trả và Lì xì trừ từ số dư này.
Hóa đơn và hoàn tiền
Số tiền crypto cố định, giá theo tiền pháp định hoặc số tiền do người trả chọn. Hoàn toàn bộ hoặc một phần, kể cả cho người trả ẩn danh.
Gói đăng ký
Người dùng đồng ý một lần. Sau đó thu tiền tự động mỗi kỳ, kèm sự kiện cho từng lần thu.
Chuyển tiền và Lì xì
Chi trả từ số dư ứng dụng cho người dùng Telegram và tạo Lì xì qua liên kết, người nhận cần đáp ứng điều kiện đã đặt.
Webhook
invoice_paid luôn được gửi. Sự kiện hóa đơn hết hạn, nhận Lì xì, hoàn tiền và gói đăng ký được bật riêng cho từng ứng dụng.
Testnet
Cùng API và ứng dụng nhỏ trong @tgpaycrypto_testnet_bot. Nút ở màn hình chính cấp coin thử nghiệm mỗi giờ một lần.
AI agent và MCP
Gửi app.tgpaycrypto.com/mcp cho AI agent để tạo ứng dụng, đặt webhook và chuẩn bị mã tích hợp. Bạn duyệt việc tạo ứng dụng trong bot.
Tương thích Crypto Bot API
Tên phương thức, cấu trúc {ok, result} và cách ký webhook tương thích. Đổi URL gốc và token rồi kiểm tra các phương thức đang dùng.
Kiểm soát token
Token giới hạn quyền, thay token tức thì, chỉ chi trả cho người cho phép hoặc tắt chi trả, kèm hạn mức ngày khi token bị lộ.
Câu hỏi về API
Token, chữ ký webhook, thử nghiệm và chuyển từ API khác.
Tùy chính sách hiện hành, có thể cần hoàn tất xác minh danh tính. Nếu tạo ứng dụng báo lỗi xác minh, hoàn tất trong ứng dụng rồi thử lại.
Header TgPayCrypto-API-Signature chứa HMAC-SHA256 của nội dung yêu cầu, dùng SHA-256 của token chính làm khóa. So sánh trên byte gốc của nội dung. Chưa xác thực thành công thì không giao hàng hoặc đánh dấu đã thanh toán.
Merchant API hỗ trợ phương thức, cấu trúc {ok, result}, số tiền dạng chuỗi thập phân và cách ký của Crypto Bot API. Đổi URL gốc, token rồi thử tích hợp. Header Crypto-Pay-API-Token được chấp nhận làm tên thay thế.
Testnet dùng cùng API và ứng dụng nhỏ: bot @tgpaycrypto_testnet_bot, địa chỉ gốc testnet.tgpaycrypto.com/pay/api. Nút ở màn hình chính cấp 1.000 USDT, 1.000 GRAM, 0,01 BTC thử nghiệm mỗi giờ một lần. Token mainnet và testnet không dùng thay nhau.
AI agent nhận token giới hạn để tạo hóa đơn, gói đăng ký, đọc số dư và thống kê, đặt webhook. Chuyển tiền, Lì xì và hoàn tiền cần thêm quyền và bật tính năng tương ứng.
Tài liệu Merchant API công khai
Tham khảo phương thức, đặc tả OpenAPI và hướng dẫn từng bước tại docs.tgpaycrypto.com.
Tích hợp thanh toán vào sản phẩm
Tạo ứng dụng trong @tgpaycryptobot hoặc đưa liên kết MCP cho AI agent rồi duyệt trong bot.
Mở bot