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à 1,5% số tiền hóa đơn — một mức phí cố định cho mọi hóa đơn, không có giảm phí theo doanh số.

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.
• Phí được làm tròn xuống tới đơn vị nhỏ nhất của tài sản, nên một hóa đơn rất nhỏ có thể hoàn toàn không mất phí.

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 phí đăng ký cũng có thể tính phí cho đối tác — hiện là 0%. Phí của từng lần thu được ghi trong trường charge.fee của webhook subscription_charged.

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

transfer có mức tối đa mỗi lần chuyển là 25.000 USD, tính theo giá trị tương đương đô la Mỹ thay vì một số tiền riêng cho từng tài sản. Mức tối thiểu mỗi lần chuyển cũng có thể được đặt; hiện không có mức tối thiểu. Trong phần tích hợp, xử lý amount_too_big và cả amount_too_small nếu sau này có mức tối thiểu, khi số tiền bị từ chối do các giới hạn này (cả hai đều là 400). Mức tối đa không áp dụng cho tài sản hiện không có giá theo đô la Mỹ.

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 từng mở TgPay Crypto — 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 — được báo bằng cùng lỗi 404 user_not_found.

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, mỗi phương thức đếm riêng): 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 tự tính số tiền thực nhận từ mệnh giá. Mức phí có thể 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.