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; khi thanh toán thành công, số dư ứng dụng được cộng tiền sau khi trừ phí dành cho người bá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 nếu có tùy chọn này. Tự động thanh toán yêu cầu đủ số dư đã ghi có trước hạn thanh toán và tài khoản không bị hạn chế chi tiền. Chỉ có khoản nạp chưa chứng minh hóa đơn đã được trả.
Bạn được báo. Nếu đã cấu hình webhook URL, sự kiện invoice_paid được đưa vào hàng đợi sau khi thanh toán. Ứng dụng nhận số tiền sau khi trừ phí.
Giao hàng. Trước tiên, kiểm tra chữ ký webhook, đối chiếu hóa đơn với đơn hàng và xác nhận trạng thái paid. Bạn cũng có thể kiểm tra bằng getInvoices; không cần chờ thêm xác nhận blockchain.

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 pháp định.

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 khi có thể quy đổi. Nếu không quy đổi được, thanh toán vẫn thành công bằng tài sản ban đầu; hãy kiểm tra is_swapped và các trường swapped_*.

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.

Mô tả, nội dung sau thanh toán và nút bấm có thể bị ẩn với người trả cho đến khi được duyệt. Đừng mặc định các nội dung này hiển thị ngay sau khi tạo hóa đơn.

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

Hoàn tiền

refundInvoice trả số crypto thực tế đã 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à số crypto đã trả ban đầu; hóa đơn theo dõi con số này ở refunded_amount. Với hóa đơn fiat, hoàn tiền dùng paid_asset và paid_amount, không dùng mệnh giá tiền pháp định. Ứng dụng phải có đủ tài sản thanh toán ban đầu, kể cả sau khi tự động quy đổi. Hãy truyền một spend_id để yêu cầu gửi lại sau khi hết thời gian chờ trả về kết quả đã lưu 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 chính 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.