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 trước khi áp dụng bậc phí theo doanh số. Mức phí của bạn phụ thuộc vào các bậc được cấu hình và doanh số hóa đơn đã thanh toán trong 30 ngày gần nhất:

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 có thể 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ị tương đương USD thay vì số tiền riêng cho từng tài sản. Xử lý amount_too_small và amount_too_big khi số tiền bị từ chối do các hạn mức này.

Ngược lại, username chưa có trong ứng dụng tạo khoản chi trả đang chờ nếu chế độ chi trả cho phép; xem chuyển tiền và Lì xì.

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.

Hạn mức chi trả hằng ngày

Chủ sở hữu có thể đặt hạn mức cho 24 giờ gần nhất trong Cài đặt chi trả của ứng dụng. Chuyển tiền, Lì xì và các khoản chi từ số dư ứng dụng dùng chung hạn mức. Vượt hạn mức trả 403 daily_cap_exceeded; lô lệnh được kiểm tra trước khoản chi đầu tiên. Hoàn tiền không tính vào hạn mức này. getMe trả daily_payout_max_usd_cents và daily_payout_spent_usd_cents.

Hạn chế của chủ sở hữu cũng có thể chặn chuyển tiền, Lì xì và hoàn tiền (403 verification_required); tạm dừng chi trả trả 503 merchant_payouts_paused.

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): createInvoice và createCheck ở mức 60 mỗi phút; refundInvoice ở mức 30 mỗi phút; transfer ở mức 30 mỗi phút; transferBatch ở mức 10 mỗi phút. updateApp và createSubscriptionPlan cũng có giới hạn; xem tài liệu API. Khi gặp rate_limited, tăng thời gian chờ trước khi thử lại.

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ị đó với cùng tham số sẽ trả về 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í nền tảng có thể áp dụng cho hóa đơn và các lần thu phí gói đăng ký. Tự động quy đổi, nếu chọn, dùng báo giá quy đổi. Nạp tiền vào ví người trả từ ví ngoài có thể chịu phí do ví gửi hoặc mạng thu.

⚠️ Đừ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.