مرجع 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 یعنی عمر پیش‌فرض. expiration_date را در پاسخ بخوانید |
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،
400 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 نرخ لحظه‌ی ساخت برای هر دارایی پذیرفته‌شده ثبت
می‌شود. تا وقتی قفل برقرار است، پرداخت‌کننده دقیقاً همان مبلغ‌های ثبت‌شده را
می‌بیند و پرداخت با همان نرخ تبدیل می‌شود — ریسک نرخ در آن بازه با شماست. سرور
مدت درخواستی را با محدوده پشتیبانی‌شده تطبیق می‌دهد. مهلت واقعی را از rate_lock_until پاسخ بخوانید.
وقتی قفل تمام شود، صورت‌حساب منقضی‌نشده همچنان قابل پرداخت می‌ماند و به‌طور خودکار به تبدیل
لحظه‌ی پرداخت برمی‌گردد. اگر می‌خواهید صورت‌حساب هم‌زمان با نرخ منقضی شود،
expires_in را در محدوده پشتیبانی‌شده قفل انتخاب کنید و expiration_date و rate_lock_until پاسخ را مقایسه کنید.
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: همه یا بخشی از رمزارز واقعاً پرداخت‌شده را از موجودی برنامه به پرداخت‌کننده برمی‌گرداند، حتی به پرداخت‌کننده ناشناس و بدون افشای هویت. در صورت‌حساب فیات از paid_asset و paid_amount استفاده کنید؛ بازپرداخت تبدیل فیات جدیدی نیست.
| پارامتر | نوع | اجباری | معنی |
|---|---|---|---|
invoice_id | عدد صحیح | بله | همان صورت‌حساب پرداخت‌شده |
amount | رشته | خیر | مقدار رمزارز بازپرداختی به دارایی اولیه پرداخت (paid_asset برای فیات). اگر ارسال نشود، تمام باقی‌مانده بازپرداخت‌نشده. بازپرداخت‌های جزئی تا سقف مقدار رمزارز اولیه جمع می‌شوند |
spend_id | رشته | خیر | کلید جلوگیری از پرداخت دوباره — از آن استفاده کنید تا درخواستی که تایم‌اوت شده به‌جای بازگرداندن دوباره، همان نتیجه را تکرار کند |
نتیجه، شیء به‌روزشده‌ی صورت‌حساب است با refunded_amount / refunded_minor
تجمعی؛ refunded_at وقتی ثبت می‌شود که مبلغ صورت‌حساب به‌طور کامل بازگشته باشد. وضعیت
paid می‌ماند. کارمزد پلتفرم برنمی‌گردد. موجودی کافی از دارایی اولیه پرداخت لازم است، حتی اگر swap_to مبلغ دریافتی را به دارایی دیگری تبدیل کرده باشد. هر بازگشت، وب‌هوک
اختیاری 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.
آیا این مطلب برای شما مفید بود؟
از بازخوردتان ممنونیم.