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
Người dùng thanh toán từ số dư ví qua nút hoặc liên kết trong bot. Khoản tiền lớn cần xác nhận bằng mã PIN hoặc Face ID.
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. Kết nối bằng ứng dụng khách AI agent tương thích: AI agent có thể đọc tài liệu, yêu cầu tạo ứng dụng, cấu hình webhook và hỗ trợ viết mã tích hợp. Bạn duyệt ứng dụng trong Telegram, rồi kiểm tra và thử nghiệm kết quả.
- Bước 1
Gửi yêu cầu cho AI agent
Dùng ứng dụng khách AI agent có hỗ trợ MCP từ xa cho tài khoản hoặc không gian làm việc của bạn. Yêu cầu cũng có trong ứng dụng: 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
Hoàn tất và thử nghiệm tích hợp
AI agent nhận token giới hạn và hỗ trợ cấu hình hóa đơn, gói đăng ký, webhook. Để lấy khóa ký webhook, hãy cấp lại token chính trong ứng dụng và lưu an toàn trên máy chủ của bạn.
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 MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the 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 và Lì xì hết hạn, nhận Lì xì, hoàn tiền, chi trả và gói đăng ký có thể bật riêng trong cài đặt 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
Kết nối app.tgpaycrypto.com/mcp trong ứng dụng khách AI agent hỗ trợ MCP từ xa. Sau khi bạn duyệt trong Telegram, AI agent có thể tạo ứng dụng và hỗ trợ tích hợp. Hãy kiểm tra và thử nghiệm kết quả trước khi sử dụng.
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