Merchant API là gì?
Merchant API là API thanh toán của ứng dụng, dành cho doanh nghiệp và bot. Bạn tạo một ứng dụng, lấy token API, rồi dùng token đó để thu tiền người dùng Telegram, chi trả cho họ và xem số dư — tất cả từ code của chính bạn.
API này dành cho lập trình viên và kết nối với cùng ứng dụng mà người dùng sử dụng: hóa đơn bạn tạo qua API chính là hóa đơn họ thanh toán bằng số dư sau khi xác nhận thanh toán.
Bạn làm được gì với nó
- Hóa đơn — tạo một hóa đơn để thu tiền (số tiền crypto cố định, giá theo tiền pháp định, hoặc số tiền mở để người thanh toán tự nhập), gửi liên kết cho người thanh toán, và nhận webhook có chữ ký sau khi thanh toán nếu đã cấu hình webhook URL.
- Hoàn tiền — hoàn toàn bộ hoặc một phần số tiền của hóa đơn đã thanh toán về đúng người đã trả, kể cả người thanh toán ẩn danh.
- Chuyển tiền — gửi crypto từ số dư ứng dụng của bạn tới ví của một người dùng Telegram, từng lệnh một hoặc tối đa 100 lệnh trong một lô.
- Lì xì — phát hành liên kết nhận tiền, lấy từ số dư ứng dụng của bạn, cho bất kỳ ai hoặc người nhận cụ thể, tùy cài đặt chi trả.
- Gói đăng ký — thu phí định kỳ: người dùng đăng ký một lần, hệ thống tự động trừ tiền mỗi kỳ.
- Số dư, tiền tệ, tỷ giá và thống kê — các endpoint chỉ đọc, phục vụ việc ghi sổ của riêng bạn.
Cách mọi thứ ghép với nhau
- Ứng dụng của bạn giữ một số dư riêng, tách khỏi ví cá nhân.
- Hóa đơn được người dùng thanh toán sẽ cộng vào số dư ứng dụng đó.
- Chuyển tiền và Lì xì trừ từ số dư đó.
- Các sự kiện thanh toán được hỗ trợ có thể gửi về máy chủ dưới dạng webhook có chữ ký khi bạn cấu hình URL và đăng ký sự kiện.
Thanh toán diễn ra bên trong ứng dụng chứ không phải on-chain: không phí mạng
lưới, không phải chờ xác nhận, và tiền dùng được ngay lúc vừa về. Người thanh
toán có thể nạp tiền cho hóa đơn từ ví ngoài nếu có tùy chọn này. Khoản nạp vào ví của chính họ; tự động thanh toán còn yêu cầu đủ số dư, không bị hạn chế chi tiền và chưa quá hạn thanh toán. Bạn cần xác nhận hóa đơn ở trạng thái paid trước khi giao hàng.
Tương thích với Crypto Bot
API này được thiết kế tương thích với Crypto Bot: cùng tên phương thức, cùng cấu trúc phản hồi
{ok, result}, cùng cách biểu diễn số tiền bằng chuỗi thập phân, cùng cơ chế
chữ ký webhook. Để chuyển một tích hợp sẵn có, đổi base URL và token, rồi thử các phương thức đang dùng theo tài liệu của chúng tôi.
Giống Crypto Bot, chúng tôi cũng có một
mạng thử nghiệm với bot và base URL riêng.
Header token chuẩn là TgPayCrypto-API-Token; tên cũ trước ngày 2026-09-07,
TgCryptoPay-API-Token, vẫn dùng được, còn Crypto-Pay-API-Token được chấp
nhận như tên gọi thay thế, để các thư viện client sẵn có chạy nguyên vẹn.
⚠️ Token API là chìa khóa chi tiền
Token chính cho phép chi trả trong phạm vi chế độ chi trả và hạn mức của ứng dụng. Hãy giữ nó ở phía máy chủ, không đưa vào ứng dụng client hay repository, và đổi token mới ngay khi nghi ngờ nó bị lộ. Với những máy chủ không cần toàn quyền, hãy tạo một token giới hạn quyền chỉ gồm đúng các scope chúng thực sự dùng — xem tài liệu API.
Tiếp theo
Bài viết này có giúp được bạn không?
Cảm ơn phản hồi của bạn.