شروع کار برای توسعه‌دهنده‌ها

در مینی‌برنامه یک برنامه بسازید، توکن API آن را یک بار کپی کنید و فراخوانی API را شروع کنید. همه‌ی این تنظیمات زیر بیشتر ← API پذیرنده جمع شده است.

مراحل

1. بیشتر ← API پذیرنده را باز کنید.
2. یک نام برنامه وارد کنید (مثلاً «فروشگاه من») و اگر خواستید یک آدرس وب‌هوک.
3. روی ساخت برنامه بزنید.
4. توکن API را همان لحظه کپی کنید. فقط همان یک بار نشان داده می‌شود و بعد از آن دیگر هیچ‌وقت نمایش داده نمی‌شود — TgPay تنها هش آن را نگه می‌دارد.
5. اولین درخواستتان را با همان توکن در هدر TgCryptoPay-API-Token بفرستید.

اولین فراخوانی

کلاینت خود را به آدرس پایه‌ی https://crypto.tgpaybot.com/pay/api وصل کنید و getMe را فراخوانی کنید تا مطمئن شوید توکن کار می‌کند. getBalance موجودی‌های برنامه‌ی شما را برمی‌گرداند و getCurrencies دارایی‌هایی را که می‌توانید به کار ببرید نشان می‌دهد.

متدهای خواندنی GET هستند. متدهایی که پول جابه‌جا می‌کنند — createInvoice، transfer، createCheck و متدهای حذف متناظرشان — عمداً فقط POST هستند: تا مبلغ و کلید جلوگیری از پرداخت دوباره در لاگ‌های دسترسی ثبت نشوند. پارامترها را می‌توانید به‌صورت بدنه‌ی JSON، form-urlencoded یا پارامتر آدرس بفرستید.

مدیریت یک برنامه

کارت هر برنامه در API پذیرنده شناسه و موجودی آن را نشان می‌دهد و با آن می‌توانید:

• آدرس وب‌هوک را تنظیم یا عوض کنید و آن را ذخیره کنید.
• رویدادهای بیشتر وب‌هوک را انتخاب کنید — به‌محض اینکه یک آدرس وب‌هوک ثبت شود، کلیدهای رویدادهای بیشتر وب‌هوک اجازه می‌دهند رویدادهایی فراتر از invoice_paid را هم بگیرید (مرجع وب‌هوک‌ها را ببینید).
• توکن‌های محدود بسازید — توکن‌های API اضافی زیر توکن‌های محدود، هرکدام محدود به همان دامنه‌های دسترسی که خودتان انتخاب می‌کنید (مرجع API را ببینید).
• تعویض توکن — توکن جدیدی صادر می‌کند و توکن قبلی را بی‌درنگ باطل می‌کند. اگر توکنی نشت کرده، از همین استفاده کنید؛ توکن جدید هم مثل زمان ساخت فقط یک بار نشان داده می‌شود.
• حذف — درخواست‌های آن برنامه دیگر پذیرفته نمی‌شوند، اما موجودی و تاریخچه‌ی پرداخت‌هایش حفظ می‌شوند. حذف یک برنامه هیچ‌وقت پول آن را از بین نمی‌برد.

وب‌هوک‌ها

اگر آدرس وب‌هوک را ثبت کنید، TgPay یک بدنه‌ی JSON امضاشده را با POST به آن می‌فرستد:

{ "update_id": …, "update_type": "invoice_paid", "request_date": …, "payload": { … } }

امضا در هدر TgCryptoPay-API-Signature می‌آید (Crypto-Pay-API-Signature هم نام جایگزین سازگاری است): HMAC-SHA256 روی بدنه‌ی خام، با کلیدی که SHA-256 توکن API شما است. پیش از آنکه به چیزی در محتوای آن اعتماد کنید، امضا را بررسی کنید.

ارسال‌های ناموفق با فاصله‌های فزاینده و در بازه‌ای طولانی دوباره فرستاده می‌شوند و update_id در همه‌ی تلاش‌ها یکسان می‌ماند — تکراری‌ها را بر همین اساس حذف کنید و هندلرتان را طوری بنویسید که تکرار به آن آسیبی نزند.

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

⚠️ توکن را مثل کلید خصوصی نگه دارید

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