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

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

مسیر کار

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

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

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

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

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

با swap_to می‌توانید پرداخت‌های دریافتی را در صورت امکان به یک دارایی تبدیل کنید. اگر تبدیل ممکن نباشد، پرداخت با دارایی اصلی موفق می‌شود؛ is_swapped و فیلدهای swapped_* را بررسی کنید.

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

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

توضیح، محتوای پنهان و دکمه پس از پرداخت ممکن است تا تأیید محتوا از پرداخت‌کننده پنهان بمانند. روی نمایش فوری آن‌ها پس از ساخت حساب نکنید.

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

بازگشت وجه

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

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

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