مرجع API: صورت‌حساب و بازگشت وجه

متدهای صورت‌حساب: createInvoice، getInvoices، deleteInvoice، refundInvoice. قراردادهای مشترک (احراز اصالت، قالب پاسخ، مبلغ‌ها، spend_id) در صفحه‌ی مرجع API پذیرنده آمده و راهنمای گام‌به‌گام در دریافت پرداخت با صورت‌حساب.

createInvoice

POST /pay/api/createInvoice — دامنه‌ی invoices، سقف 60 درخواست در دقیقه.

پارامتر	نوع	اجباری	معنی
currency_type	رشته	خیر	crypto (پیش‌فرض) یا fiat
asset	رشته	در حالت رمزارزی	دارایی‌ای که بابت آن پول می‌گیرید، مثلاً USDT. همراه با fiat مجاز نیست
fiat	رشته	در حالت فیات	ارز فیاتی که قیمت به آن تعیین شده (سطرهای is_fiat در getCurrencies)
accepted_assets	رشته / آرایه	خیر	فقط در حالت فیات: دارایی‌هایی که پرداخت‌کننده می‌تواند با آن‌ها بپردازد — یک رشته‌ی جداشده با ویرگول ("USDT,GRAM") یا یک آرایه‌ی JSON. اگر ارسال نشود، همه‌ی دارایی‌های پشتیبانی‌شده
amount	رشته	بله، مگر open_amount تنظیم شده باشد	رشته‌ی اعشاری مثبت: واحد دارایی در حالت رمزارزی، واحد فیات (حداکثر 2 رقم اعشار) در حالت فیات
open_amount	بولی	خیر	افزوده، فقط در حالت رمزارزی: بدون مبلغ ثابت — پرداخت‌کننده خودش هنگام پرداخت مبلغ را وارد می‌کند (کمک مالی و انعام). هم‌زمان با amount مجاز نیست
description	رشته	خیر	تا 1024 نویسه، که به پرداخت‌کننده نشان داده می‌شود
hidden_message	رشته	خیر	تا 2048 نویسه، که فقط پس از پرداخت به پرداخت‌کننده نشان داده می‌شود
payload	رشته	خیر	تا 4096 نویسه داده‌ی خودتان، که روی صورت‌حساب و وب‌هوک عیناً برمی‌گردد
allow_comments	بولی	خیر	اجازه‌ی گذاشتن نظر به پرداخت‌کننده (پیش‌فرض true)
allow_anonymous	بولی	خیر	اجازه‌ی پنهان کردن هویت به پرداخت‌کننده (پیش‌فرض true)
paid_btn_name	رشته	خیر	دکمه‌ی پس از پرداخت: viewItem، openChannel، openBot یا callback
paid_btn_url	رشته	خیر	نشانی http(s) همان دکمه — وقتی paid_btn_name ارسال شده باشد اجباری است
swap_to	رشته	خیر	پرداخت‌های دریافتی خودکار به این دارایی تبدیل شوند. در حد امکان: اگر تبدیل در لحظه‌ی پرداخت ممکن نباشد، پرداخت بدون تبدیل انجام می‌شود
expires_in	عدد صحیح	خیر	ثانیه تا انقضای صورت‌حساب، تا 2678400 (31 روز)؛ ارسال نشدن یا 0 یعنی بدون انقضا
rate_lock_seconds	عدد صحیح	خیر	افزوده، فقط در حالت فیات: نرخ تبدیل را در لحظه‌ی ساخت برای این بازه قفل می‌کند (پایین‌تر)

نتیجه — و محتوای وب‌هوک invoice_paid — همان شیء صورت‌حساب است. فیلدهای اصلی آن:

• هویت و وضعیت: invoice_id، hash (شناسه‌ی عمومی داخل pay_url)، status (active / paid / expired)، pay_url — لینک t.me که برای پرداخت‌کننده می‌فرستید (bot_invoice_url، mini_app_invoice_url، web_app_invoice_url نام‌های جایگزین همان لینک‌اند).
• مبلغ‌ها: amount (مبلغ اسمی — واحد فیات روی صورت‌حساب فیاتی، وگرنه رمزارز؛ تا وقتی صورت‌حساب با مبلغ دلخواه پرداخت نشده null است)، amount_minor، و روی صورت‌حساب‌های فیاتیِ پرداخت‌شده paid_asset / paid_amount / paid_fiat_rate — یعنی رمزارزی که واقعاً کسر شد و نرخی که به کار رفت.
• کارمزد: fee_asset / fee_amount، که در لحظه‌ی پرداخت ثبت می‌شوند — رقم مرجع برای حسابداری شما (fee و usd_rate نام‌های قدیمی Crypto Bot و منسوخ‌اند). کارمزد و سقف‌ها را ببینید.
• پرداخت‌کننده: paid_by_user_id (وقتی پرداخت‌کننده ناشناس مانده null)، paid_anonymously، comment.
• بازگشت وجه (افزوده): refunded_amount / refunded_minor (تجمعی) و refunded_at، که پس از بازگشت کامل ثبت می‌شود.
• قفل نرخ (افزوده): rate_lock_until و rate_lock_rates — نرخ‌های ثبت‌شده‌ی هر دارایی، که بدون درخواست قفل null می‌مانند.
• همان‌طور که ساخته شد: description، hidden_message، payload، paid_btn_name / paid_btn_url، expiration_date (expires_at نام دیگر آن است) و فیلدهای تبدیل (swap_to، is_swapped، swapped_to، swapped_rate، swapped_output، …).

خطاها: 400 invalid_currency (اشتباه گرفتن asset و fiat)، 400 invalid_amount، 404 unknown_asset، 400 unsupported_fiat، 400 paid_btn_url_required، و برای درخواست‌های قفل نرخ 400 rate_lock_fiat_only، 409 ratelock_disabled، 409 rate_unavailable (برای یکی از دارایی‌های پذیرفته‌شده نرخ به‌روزی در دسترس نیست — دوباره تلاش کنید).

صورت‌حساب‌ها چگونه پرداخت می‌شوند

پرداخت‌کننده از موجودی کیف پولش در مینی‌برنامه می‌پردازد — آنی و بدون کارمزد شبکه. همچنین می‌تواند صورت‌حساب را از یک کیف پول بیرونی تأمین کند: برنامه یک آدرس واریز به او نشان می‌دهد، انتقال او به کیف پول خودش واریز می‌شود و صورت‌حساب به‌محض رسیدن آن خودکار تسویه می‌شود. در هر دو حالت آنچه شما می‌بینید یکی است: یک صورت‌حساب عادی با وضعیت paid و یک وب‌هوک invoice_paid — نه پارامتر اضافه‌ای در کار است و نه فیلد جدیدی که باید پردازش کنید.

روی صورت‌حساب فیاتی، مبلغ رمزارز در لحظه‌ی پرداخت محاسبه و به سود شما به بالا گرد می‌شود، پس هیچ‌وقت کمتر از مبلغ اسمی فیات به شما نمی‌رسد. اگر نرخ جدیدی در دسترس نباشد، پرداخت سمت پرداخت‌کننده ناموفق می‌شود و با نرخ قدیمی تسویه نمی‌شود.

قفل کردن نرخ روی صورت‌حساب فیاتی

با فرستادن rate_lock_seconds نرخ لحظه‌ی ساخت برای هر دارایی پذیرفته‌شده ثبت می‌شود. تا وقتی قفل برقرار است، پرداخت‌کننده دقیقاً همان مبلغ‌های ثبت‌شده را می‌بیند و پرداخت با همان نرخ تبدیل می‌شود — ریسک نرخ در آن بازه با شماست. سرور این بازه را به حداقل 60 ثانیه و حداکثر پلتفرم (فعلاً 15 دقیقه) محدود می‌کند.

وقتی قفل تمام شود، صورت‌حساب همچنان قابل پرداخت می‌ماند و به‌طور خودکار به تبدیل لحظه‌ی پرداخت برمی‌گردد. اگر می‌خواهید صورت‌حساب هم‌زمان با نرخ منقضی شود، expires_in را روی همان مقدار بگذارید.

getInvoices

GET /pay/api/getInvoices — دامنه‌ی read. فیلترها: asset، fiat، invoice_ids (جداشده با ویرگول)، status (active / paid / expired — expired افزوده است؛ active صورت‌حساب‌هایی را که مهلت آن‌ها گذشته است شامل نمی‌شود)، به‌علاوه‌ی offset / count. خروجی {"items": [invoice, …]} است، به ترتیب از جدیدترین.

deleteInvoice

POST /pay/api/deleteInvoice — دامنه‌ی invoices. یک پارامتر: invoice_id. صورت‌حساب پرداخت‌نشده را لغو می‌کند و true برمی‌گرداند. خطاها: 404 invoice_not_found، 409 invoice_already_paid — صورت‌حساب پرداخت‌شده را نمی‌شود حذف کرد، پول پیش‌تر جابه‌جا شده است.

refundInvoice

POST /pay/api/refundInvoice — دامنه‌ی refunds، سقف 30 درخواست در دقیقه. افزوده‌ای بر Crypto Bot: مبلغ اسمی یک صورت‌حساب پرداخت‌شده — یا بخشی از آن — را از موجودی برنامه‌ی شما به همان کسی که پرداخت کرده برمی‌گرداند، حتی به پرداخت‌کننده‌ی ناشناس و بدون فاش کردن هویتش.

پارامتر	نوع	اجباری	معنی
invoice_id	عدد صحیح	بله	همان صورت‌حساب پرداخت‌شده
amount	رشته	خیر	مبلغی که برمی‌گردد، به دارایی خود صورت‌حساب. اگر ارسال نشود، کل باقی‌مانده‌ی بازنگشته. بازگشت‌های جزئی روی هم جمع می‌شوند تا سقف مبلغ اسمی
spend_id	رشته	خیر	کلید جلوگیری از پرداخت دوباره — از آن استفاده کنید تا درخواستی که تایم‌اوت شده به‌جای بازگرداندن دوباره، همان نتیجه را تکرار کند

نتیجه، شیء به‌روزشده‌ی صورت‌حساب است با refunded_amount / refunded_minor تجمعی؛ refunded_at وقتی ثبت می‌شود که مبلغ صورت‌حساب به‌طور کامل بازگشته باشد. وضعیت paid می‌ماند. کارمزد پلتفرم برنمی‌گردد. هر بازگشت، وب‌هوک اختیاری refund_completed را می‌فرستد.

خطاها: 404 invoice_not_found، 409 invoice_not_paid، 409 already_refunded (چیزی برای بازگرداندن نمانده)، 409 amount_too_big (بیشتر از باقی‌مانده‌ی بازنگشته)، 409 insufficient_funds، 400 invalid_amount، و دو خطای مربوط به spend_id، یعنی 409 idempotency_conflict / 409 idempotency_in_progress.