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

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

مراحل

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

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

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

متدهای خواندنی GET هستند. متدهای نوشتنی مانند createInvoice، transfer، createCheck، deleteInvoice و deleteCheck فقط POST هستند. پارامترها را می‌توانید به‌صورت بدنه JSON، form-urlencoded یا پارامتر آدرس بفرستید. بهتر است از بدنه درخواست استفاده کنید تا مقدار دارایی و کلید جلوگیری از پرداخت دوباره در گزارش آدرس‌های درخواستی ثبت نشوند.

شبکه‌ی آزمایشی

یکپارچه‌سازی را اول در شبکه‌ی آزمایشی بسازید — همان API، همان مینی‌برنامه، رمزارزهای آزمایشی بدون ارزش واقعی:

	شبکه‌ی اصلی	شبکه‌ی آزمایشی
ربات	@tgpaycryptobot	@tgpaycrypto_testnet_bot
آدرس پایه‌ی API	https://app.tgpaycrypto.com/pay/api	https://testnet.tgpaycrypto.com/pay/api
سرور MCP	https://app.tgpaycrypto.com/mcp	https://testnet.tgpaycrypto.com/mcp

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

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

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

در API پذیرنده برنامه موردنظر را باز کنید تا شناسه و موجودی آن را ببینید. در این صفحه می‌توانید:

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

وب‌هوک‌ها

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

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

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

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

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

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

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