کارمزد و سقف‌های API پذیرنده
صورت‌حساب‌ها یک کارمزد پلتفرم دارند که از سهم شما کسر می‌شود؛ انتقال‌ها و چک‌ها هم به سقف مبلغ محدودند. عددهای زیر تنظیمات فعلی‌اند، نه شرط قرارداد — هر جا با آنچه در برنامه می‌بینید مطابقت نداشت، ملاک برنامه است و منبع قابل اتکا همیشه صورت‌حساب‌های پرداخت‌شده‌ی خودتان است.
کارمزد صورت‌حساب
پرداخت‌کننده همیشه مبلغ اسمی صورت‌حساب را می‌پردازد. کارمزد از سمت پذیرنده برداشته می‌شود: موجودی برنامه‌ی شما به اندازه‌ی مبلغ پس از کسر کارمزد شارژ می‌شود.
کارمزد 1.5% مبلغ صورت‌حساب است؛ نرخی ثابت برای همه‌ی صورت‌حساب‌ها، بدون تخفیف بر اساس حجم پرداخت.
دو قاعده از خود عدد مهم‌ترند:
- کارمزد در لحظه‌ی پرداخت تعیین و قفل می‌شود. تغییر بعدی نرخ هرگز به صورت‌حسابی که پیش‌تر پرداخت شده دست نمی‌زند.
- کارمزد رو به پایین گرد می‌شود تا کوچک‌ترین واحد دارایی؛ برای همین ممکن است صورت‌حساب خیلی کوچک اصلاً کارمزد نداشته باشد.
برای اینکه ببینید دقیقاً چه چیزی کسر شده، fee_asset و fee_amount را از
صورت‌حساب پرداخت‌شده بخوانید — از محتوای وب‌هوک invoice_paid یا از
getInvoices. برای حسابداری شما همان عدد معتبر است.
بازگشت وجه کارمزد را برنمی‌گرداند: آنچه refundInvoice به پرداخت‌کننده
می‌فرستد از موجودی شما کم می‌شود و کارمزد بازنمی‌گردد — در بازگشت جزئی هم همین
است.
برای هر پرداخت اشتراک هم ممکن است از پذیرنده کارمزد گرفته شود؛ کارمزد فعلی 0% است. کارمزد هر پرداخت در فیلد charge.fee وب‌هوک subscription_charged گزارش می‌شود.
سقف انتقال
transfer دارای سقف هر انتقال برابر با 25,000 دلار است. این سقف بر پایه‌ی معادل دلاری تعیین می‌شود، نه مبلغی جداگانه برای هر دارایی. ممکن است کف هر انتقال هم تعیین شود؛ در حال حاضر کف ندارد. اگر مبلغ به‌دلیل این محدودیت‌ها رد شد، در یکپارچه‌سازی خطای amount_too_big و در صورت تعیین کف، خطای amount_too_small را مدیریت کنید (هر دو 400 هستند). برای دارایی‌ای که فعلاً نرخ دلاری ندارد، این سقف اعمال نمی‌شود.
اگر حالت پرداخت اجازه بدهد، username ناشناخته به‌جای خطا یک پرداخت در انتظار ایجاد می‌کند؛ انتقال و چک را ببینید.
انتقال در این حالت‌ها هم ناموفق می‌شود:
- در آن دارایی موجودی برنامه‌تان کم بیاید،
- گیرنده هرگز TgPay Crypto را باز نکرده باشد — پرداخت به شناسه‌ی تلگرامِ ناشناخته یا اشتباه، به‌جای شارژ کیف پولی که کسی آن را باز نمی‌کند، خطا می‌دهد،
- حساب گیرنده مسدود باشد — با همان
404 user_not_foundگزارش می‌شود.
سقف روزانه پرداخت
مالک می‌تواند در تنظیمات پرداخت برنامه، سقفی برای هر بازه 24 ساعته تعیین کند. انتقال‌ها، چک‌ها و پرداخت‌های موجودی برنامه از همین سقف مشترک استفاده می‌کنند. عبور از آن خطای 403 daily_cap_exceeded می‌دهد؛ در پرداخت دسته‌ای، سقف پیش از اولین پرداخت بررسی می‌شود. بازگشت وجه جزو این سقف نیست. getMe مقدارهای daily_payout_max_usd_cents و daily_payout_spent_usd_cents را برمی‌گرداند.
محدودیت حساب مالک هم می‌تواند انتقال، چک و بازگشت وجه را متوقف کند (403 verification_required)؛ توقف موقت پرداخت‌ها خطای 503 merchant_payouts_paused می‌دهد.
سقف درخواست
متدهایی که دارایی جابه‌جا می‌کنند برای هر برنامه سقف دارند (مشترک بین همه توکن‌هایش، با شمارش جداگانه برای هر متد): createInvoice و createCheck هر دقیقه 60 بار، refundInvoice هر دقیقه 30 بار، transfer هر دقیقه 30 بار و transferBatch هر دقیقه 10 بار. updateApp و createSubscriptionPlan هم سقف دارند؛ مرجع API را ببینید. با دیدن rate_limited، فاصله بین تلاش‌های دوباره را بیشتر کنید.
جلوگیری از پرداخت دوباره
transfer به یک spend_id نیاز دارد که خودتان می‌سازید؛ createCheck و
refundInvoice هم آن را می‌پذیرند. اگر همان مقدار را با همان پارامترها دوباره بفرستید، به‌جای
جابه‌جایی دوباره‌ی دارایی، همان نتیجه‌ی اول تکرار می‌شود — پس درخواستی را که تایم‌اوت
شده می‌توان بی‌خطر با همان spend_id دوباره فرستاد و فقط پرداختی که واقعاً
جدید است spend_id جدید می‌گیرد.
چه چیزی هزینه ندارد
در API پذیرنده هیچ‌جا کارمزد شبکه وجود ندارد — صورت‌حساب، انتقال و چک همگی داخل خود برنامه و بیرون از زنجیره تسویه می‌شوند. کارمزد پلتفرم ممکن است به صورت‌حساب‌ها و پرداخت‌های اشتراک تعلق بگیرد. تبدیل خودکار اختیاری با نرخ پیشنهادی تبدیل انجام می‌شود. تأمین موجودی پرداخت‌کننده از کیف پول بیرونی هم ممکن است کارمزد آن کیف پول یا شبکه را داشته باشد.
⚠️ هرگز کارمزد را خودتان حساب نکنید
درصد را در کد ثابت نکنید و مبلغ خالص را از روی مبلغ اسمی محاسبه نکنید. نرخ ممکن است عوض شود و یک ثابتِ قدیمی بی‌سروصدا حسابداری شما را خراب می‌کند. هر بار کارمزد ثبت‌شده را از خود صورت‌حساب بخوانید.
آیا این مطلب برای شما مفید بود؟
از بازخوردتان ممنونیم.