Nhận thanh toán bằng hóa đơn

Hóa đơn là cách bạn thu tiền một người dùng Telegram. Bạn tạo hóa đơn qua API, gửi liên kết cho người thanh toán, và số dư ứng dụng của bạn được cộng tiền ngay lúc họ xác nhận.

Luồng xử lý

Tạo hóa đơn bằng createInvoice, kèm tài sản và số tiền (hoặc một mức giá theo tiền pháp định — xem bên dưới).
Gửi cho người thanh toán liên kết lấy từ phản hồi. Mở liên kết là họ vào thẳng màn hình thanh toán trong ứng dụng.
Họ xác nhận và trả bằng số dư của mình — tức thì, không phí mạng lưới. Người thanh toán không đủ số dư vẫn có thể nạp tiền cho hóa đơn từ ví bên ngoài; hóa đơn tự động được thanh toán khi khoản chuyển của họ về tới, và với bạn thì mọi thứ vẫn như nhau.
Bạn được báo. Webhook invoice_paid bắn đi, và số tiền về số dư ứng dụng của bạn.
Giao hàng. Đừng chờ thêm gì nữa; tới lúc đó khoản thanh toán đã là cuối cùng.

Nếu bạn muốn tự hỏi trạng thái (polling) thay vì nhận webhook, getInvoices trả về các hóa đơn của bạn kèm trạng thái hiện tại. Webhook là đường nhanh hơn — polling chỉ là phương án dự phòng.

Định giá theo tiền pháp định

Hóa đơn có thể được định giá bằng crypto, hoặc bằng một loại tiền pháp định kèm danh sách tài sản được chấp nhận. Người thanh toán khi đó trả bằng tài sản nào họ đang có trong danh sách, quy đổi theo tỷ giá tại thời điểm thanh toán. Đó là lựa chọn thường thấy với một cửa hàng có bảng giá niêm yết bằng tiền thật.

Nếu bạn muốn chốt cứng mức giá, rate_lock_seconds đóng băng tỷ giá quy đổi ngay lúc tạo hóa đơn trong một khoảng thời gian có hạn — người thanh toán thấy đúng số tiền đã khóa, còn bạn gánh rủi ro tỷ giá trong mấy phút đó. Chi tiết ở tài liệu hóa đơn.

Bạn cũng có thể đặt swap_to để các khoản thanh toán vừa về là được quy đổi sang một tài sản duy nhất — tiện khi bạn muốn giữ số dư ở stablecoin mà không phải tự chạy các lệnh quy đổi.

Vài tùy chọn hữu ích của hóa đơn

description — hiện cho người thanh toán trên màn hình thanh toán.
hidden_message — chỉ lộ ra cho người thanh toán sau khi họ trả. Đây là cách bạn giao một mã, một khóa hay một liên kết mà không cần kênh giao hàng riêng.
payload — chuỗi dữ liệu của riêng bạn, được trả lại nguyên vẹn trên webhook. Hãy đặt mã đơn hàng vào đây.
expires_in — thời hạn, quá hạn thì hóa đơn không trả được nữa.
paid_btn_name / paid_btn_url — nút mà người thanh toán thấy sau khi trả, để đưa họ về bot, kênh hoặc trang sản phẩm của bạn.
open_amount — không cố định số tiền; người thanh toán tự nhập lúc trả. Dạng tự nhiên cho quyên góp và tiền tip.

Hóa đơn chưa thanh toán có thể hủy bằng deleteInvoice.

Hoàn tiền

refundInvoice trả mệnh giá của một hóa đơn đã thanh toán — hoặc một phần trong đó — từ số dư ứng dụng của bạn về đúng người đã trả, kể cả người thanh toán ẩn danh, mà không lộ ra họ là ai. Các lần hoàn một phần cộng dồn tới tối đa là mệnh giá; hóa đơn theo dõi con số này ở refunded_amount. Hãy truyền một spend_id để một lần thử lại sau khi hết thời gian chờ được phát lại thay vì hoàn tiền hai lần. Phí dịch vụ không được hoàn.

⚠️ Kiểm tra chữ ký webhook trước khi giao hàng

Ai cũng POST được tới webhook URL của bạn. Hãy kiểm tra header TgPayCrypto-API-Signature — HMAC-SHA256 trên nội dung thô của yêu cầu, dùng khóa là SHA-256 của token API của bạn — trước khi coi một khoản thanh toán là thật, và chống trùng theo update_id để một lần gửi lại không làm bạn giao hàng hai lần.