Phí và hạn mức Merchant API

Hóa đơn chịu một khoản phí dịch vụ trừ vào phần bạn nhận được; chuyển tiền và Lì xì thì có hạn mức số tiền. Các con số dưới đây là thiết lập hiện hành, không phải điều khoản hợp đồng — khi chúng lệch với những gì bạn thấy thì ứng dụng mới đúng, và nguồn đáng tin nhất luôn là chính các hóa đơn đã thanh toán của bạn.

Phí hóa đơn

Người thanh toán luôn trả đúng mệnh giá của hóa đơn. Phí trừ vào phía bạn: số dư ứng dụng của bạn được cộng phần đã trừ phí.

Phí là 3% số tiền hóa đơn, và tự động giảm dần theo doanh số thanh toán 30 ngày gần nhất:

Khối lượng 30 ngày	Phí
dưới 10.000 USD	3%
từ 10.000 USD	2,9%
từ 25.000 USD	2,8%
từ 50.000 USD	2,7%
từ 75.000 USD	2,6%
từ 100.000 USD	2,5%

Hai quy tắc còn quan trọng hơn cả con số:

Phí được chốt và khóa lại tại thời điểm thanh toán. Mức phí đổi về sau không bao giờ đụng tới hóa đơn đã trả xong.
Mức phí của bạn thay đổi theo doanh số. Doanh số thanh toán cao hơn trong cửa sổ 30 ngày gần nhất có thể tự động đưa bạn xuống bậc phí thấp hơn. Bạn không phải đăng ký và cũng không có gì để cấu hình.

Muốn biết chính xác đã thu bao nhiêu phí, hãy đọc fee_asset và fee_amount trên hóa đơn đã thanh toán — từ payload webhook invoice_paid hoặc từ getInvoices. Đó là con số chuẩn để ghi sổ.

Hoàn tiền không bao gồm phí: phần refundInvoice gửi cho người thanh toán được trừ từ số dư của bạn, còn phí thì không được hoàn — kể cả khi hoàn một phần.

Các lần thu tiền gói đăng ký cũng chịu phí ở phía bạn; mỗi lần thu báo con số của riêng nó ở trường charge.fee trong webhook subscription_charged.

Hạn mức chuyển tiền

transfer có mức tối thiểu và tối đa cho mỗi lệnh, tính theo giá trị quy đổi ước lượng ra USD theo tỷ giá hiện hành chứ không phải theo từng tài sản. Số tiền nằm ngoài khoảng này bị từ chối kèm lỗi rõ ràng, nên hãy xử lý amount_too_small và amount_too_big trong phần tích hợp của bạn.

Lệnh chuyển cũng thất bại khi:

số dư ứng dụng của bạn không đủ ở tài sản đó,
người nhận chưa dùng ứng dụng — chi trả tới một Telegram ID lạ hoặc gõ sai sẽ báo lỗi chứ không cộng tiền vào một ví chẳng ai mở,
tài khoản người nhận đang bị chặn.

Giới hạn tần suất

Các phương thức động tới tiền bị giới hạn tần suất theo từng ứng dụng (dùng chung cho mọi token của ứng dụng đó): createInvoice và createCheck 60 lần mỗi phút, refundInvoice và transfer 30 lần, transferBatch 10 lần. Các phương thức đọc không bị giới hạn. Một tích hợp đàng hoàng sẽ không bao giờ chạm tới; một vòng lặp thử lại thì có — hãy giãn nhịp khi gặp rate_limited thay vì gọi dồn dập.

Idempotency

transfer bắt buộc phải có spend_id do bạn tự sinh; createCheck và refundInvoice thì nhận nếu có. Dùng lại đúng giá trị đó sẽ phát lại kết quả gốc thay vì chuyển tiền lần thứ hai — nhờ vậy một yêu cầu hết thời gian chờ luôn an toàn để thử lại với cùng spend_id, còn một spend_id mới chỉ dành cho khoản chi thật sự khác.

Những gì không mất phí

Merchant API không hề có phí mạng lưới ở bất cứ đâu — hóa đơn, chuyển tiền và Lì xì đều diễn ra bên trong ứng dụng, off-chain. Phí dịch vụ trên hóa đơn là khoản thu duy nhất.

⚠️ Đừng bao giờ tự tính ra phí

Đừng gán cứng một tỷ lệ phần trăm hay dựng lại số tiền thực nhận từ mệnh giá. Bậc phí và mức phí đều thay đổi, và một hằng số cũ sẽ âm thầm làm hỏng sổ sách của bạn. Hãy đọc con số phí đã ghi trên hóa đơn, lần nào cũng vậy.