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.
Đây là mặt dành cho lập trình viên của đúng sản phẩm mà người dùng nhìn thấy: hóa đơn bạn tạo qua API chính là hóa đơn họ thanh toán bằng số dư chỉ với một chạm.
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 callback có chữ ký ngay khi hóa đơn được trả.
- 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 cho bất kỳ ai, lấy từ số dư ứng dụng của bạn.
- 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ư đó.
- Mọi sự kiện đáng quan tâm đều có thể được đẩy về máy chủ của bạn dưới dạng webhook có chữ ký.
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 vẫn có thể nạp tiền cho hóa đơn từ ví bên ngoài — khoản nạp về ví của chính họ và hóa đơn tự động được thanh toán từ đó; về phía bạn, nó trông y hệt mọi hóa đơn đã thanh toán khác.
Tương thích với Crypto Bot
API này cố ý dựng theo Crypto Bot: cùng tên phương thức, cùng envelope
{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. Bạn có thể trỏ một tích hợp Crypto Bot sẵn có sang chúng tôi chỉ
bằng cách đổi base URL và token — cấu trúc yêu cầu và phản hồi không thay đổi.
Header token chuẩn là TgPayCrypto-API-Token, 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
Ai cầm token cũng chuyển được số dư ứng dụng của bạn đi. 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.