دریافت پرداخت با صورت‌حساب

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

مسیر کار

1. صورت‌حساب را بسازید — با createInvoice، و دارایی و مقدار را مشخص کنید (یا قیمت فیات — پایین‌تر بخوانید).
2. لینک را برای پرداخت‌کننده بفرستید؛ همان لینکی که در پاسخ آمده. باز کردن آن او را به صفحه‌ی پرداخت در برنامه می‌برد.
3. او تأیید می‌کند و از موجودی خودش پرداخت می‌کند — آنی و بدون کارمزد شبکه. پرداخت‌کننده‌ای که موجودی کافی ندارد می‌تواند صورت‌حساب را از یک کیف پول بیرونی تأمین کند؛ با رسیدن انتقال، صورت‌حساب خودکار تسویه می‌شود و از دید شما هیچ فرقی نمی‌کند.
4. به شما خبر می‌رسد. وب‌هوک invoice_paid فرستاده می‌شود و مبلغ به موجودی برنامه‌ی شما اضافه می‌شود.
5. سفارش را انجام دهید. منتظر چیز دیگری نمانید؛ پرداخت از همان لحظه قطعی است.

اگر ترجیح می‌دهید به‌جای دریافت وب‌هوک خودتان وضعیت را استعلام کنید، getInvoices صورت‌حساب‌هایتان را همراه با وضعیت فعلی‌شان برمی‌گرداند. وب‌هوک مسیر سریع‌تر است و استعلام دوره‌ای راه جایگزین.

قیمت‌گذاری به فیات

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

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

با swap_to هم می‌توانید تنظیم کنید که پرداخت‌های دریافتی به‌محض رسیدن به یک دارایی واحد تبدیل شوند — برای نگه داشتن موجودی در یک استیبل‌کوین، بی‌آنکه خودتان تبدیل‌ها را انجام دهید.

گزینه‌های کاربردی صورت‌حساب

• description — چیزی که پرداخت‌کننده در صفحه‌ی پرداخت می‌بیند.
• hidden_message — فقط بعد از پرداخت به پرداخت‌کننده نشان داده می‌شود. به این ترتیب کد، کلید یا لینک را بدون کانال تحویل جداگانه می‌رسانید.
• payload — رشته‌ی دلخواه خودتان که در وب‌هوک عیناً برمی‌گردد. شناسه‌ی سفارش را اینجا بگذارید.
• expires_in — مهلتی که بعد از آن دیگر نمی‌شود صورت‌حساب را پرداخت کرد.
• paid_btn_name / paid_btn_url — دکمه‌ای که پرداخت‌کننده پس از پرداخت می‌بیند، برای برگرداندن او به ربات، کانال یا صفحه‌ی کالای شما.
• open_amount — بدون مبلغ ثابت؛ پرداخت‌کننده خودش موقع پرداخت مبلغ را وارد می‌کند. گزینه‌ی مناسب برای کمک مالی و انعام.

صورت‌حساب پرداخت‌نشده را می‌شود با deleteInvoice لغو کرد.

بازگشت وجه

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

⚠️ پیش از انجام سفارش، امضای وب‌هوک را بررسی کنید

هر کسی می‌تواند به آدرس وب‌هوک شما POST بزند. پیش از آنکه پرداختی را واقعی بدانید، هدر TgCryptoPay-API-Signature را بررسی کنید — HMAC-SHA256 روی بدنه‌ی خام درخواست، با کلیدی که چکیده‌ی SHA-256 توکن API شماست — و تکراری‌ها را بر پایه‌ی update_id حذف کنید تا یک تلاش دوباره سفارش را دو بار نفرستد.