مرجع API پذیرنده

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

این API در متدهای مستندشده اینجا از قواعد Crypto Bot پیروی می‌کند. آدرس پایه و توکن را عوض کنید و سپس متدهای مورد استفاده را در شبکه آزمایشی بیازمایید. قابلیت‌های اضافه ما در ادامه با افزوده مشخص شده‌اند.

مشخصات ماشین‌خوان OpenAPI 3.1 نیز در دسترس است: crypto-pay-openapi.yaml · crypto-pay-openapi.json. می‌توانید آن را به تولیدکننده‌های کد، کلاینت‌های API یا ابزارهای هوش مصنوعی بدهید، اما صفحه هر متد را هم بررسی کنید؛ ممکن است قابلیت‌های جدید هنوز به این مشخصات اضافه نشده باشند.

آدرس پایه و احراز اصالت

همه‌ی متدها روی https://app.tgpaycrypto.com/pay/api/<methodName> قرار دارند. در شبکه‌ی آزمایشی آدرس پایه https://testnet.tgpaycrypto.com/pay/api است — برنامه‌ها و توکن‌های جدا، رمزارزهای آزمایشی بدون ارزش واقعی.

هر درخواست را با توکن در هدر TgPayCrypto-API-Token احراز اصالت کنید (TgCryptoPay-API-Token — نام پیش از 2026-09-07 — و Crypto-Pay-API-Token هم به‌عنوان نام‌های جایگزین برای سازگاری پذیرفته می‌شوند؛ اگر چند هدر فرستاده شود، هدر با نام رسمی ملاک است). اگر توکن فرستاده نشود، نامعتبر یا باطل باشد — یا توکن محدود منقضی شده باشد، برنامه حذف شده باشد یا حساب مالک مسدود باشد — پاسخ 401 unauthorized برمی‌گردد.

توکن به شکل <app_id>:<secret> است و فقط یک بار، موقع ساخت یا تعویض، نشان داده می‌شود؛ سرور تنها هش آن را نگه می‌دارد. شروع کار برای توسعه‌دهنده‌ها را ببینید.

توکن‌ها و دامنه‌های دسترسی

دو نوع اعتبارنامه به یک شکل احراز می‌شوند:

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

دامنه	متدهایی که باز می‌کند
(هر توکن معتبر)	getMe, getCurrencies, getExchangeRates
read	getBalance, getStats, getInvoices, getChecks, getTransfers, getSubscriptionPlans, getSubscriptions
invoices	createInvoice, deleteInvoice
refunds	refundInvoice
payouts	transfer, transferBatch
checks	createCheck, deleteCheck
subscriptions	createSubscriptionPlan, archiveSubscriptionPlan, cancelSubscription
webhooks	updateApp

دامنه‌ها روی هم جمع می‌شوند و از هم مستقل‌اند — invoices شامل read نمی‌شود، پس سروری که فقط صورت‌حساب می‌سازد می‌تواند توکنی داشته باشد که به موجودی و تاریخچه پرداخت دسترسی ندارد. فراخوانی متدی که توکن آن را پوشش نمی‌دهد 403 scope_required برمی‌گرداند. getMe دامنه‌های توکن فعلی را در scopes (برای توکن اصلی null) و نامش را در token_name گزارش می‌کند، پس همیشه می‌توانید ببینید چه چیزی در دست دارید.

حالت پرداخت

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

payout_mode	transfer، transferBatch و createCheck چه کاری می‌توانند انجام دهند
any	پرداخت به هر کاربری، نگه داشتن پرداخت در انتظار برای @username ناشناخته، ساخت چک در وجه حامل — حالت پیش‌فرض و همان رفتار Crypto Bot
allowlist	پرداخت فقط به کاربران تلگرام در فهرست گیرندگان برنامه. تمام گیرندگان مشخص چک باید در فهرست باشند. گیرندگان دیگر، @username ناشناخته و چک در وجه حامل خطای 403 recipient_not_allowed می‌گیرند
off	هیچ — هر فراخوانی پرداخت 403 payouts_disabled برمی‌گرداند؛ صورت‌حساب‌ها، اشتراک‌ها، بازگشت وجه و وب‌هوک‌ها مثل همیشه کار می‌کنند

اگر پرداختی رد شود، مالک در تلگرام مطلع می‌شود و می‌تواند حالت را تغییر دهد. سقف روزانه‌ی پرداخت علاوه بر این حالت اعمال می‌شود. شرایط API پذیرنده تعیین می‌کند بابت چه چیزی می‌توانید پرداخت کنید.

درخواست‌ها و پاسخ‌ها

• متدهای خواندنی GET هستند و پارامترها را در رشته‌ی پرس‌وجو می‌گیرند. متدهایی که دارایی جابه‌جا می‌کنند فقط POST هستند — پارامترها به‌صورت بدنه‌ی JSON، form-urlencoded یا پارامتر آدرس (در صورت تفاوت، مقدار بدنه ملاک است)؛ multipart/form-data رد می‌شود.
• پاسخ‌هایی که خود API تولید می‌کند این قالب JSON را دارند: موفق {"ok": true, "result": …}، خطا {"ok": false, "error": {"code": <HTTP status>, "name": "<error_name>"}}. منطق برنامه را بر اساس error.name بنویسید — رشته‌ی پایدار و ماشین‌خوان همان است.
• مقدار پرس‌وجویی با نوع نامعتبر روی متد GET (مثلاً offset=abc) ممکن است پیش از اجرای متد رد شود. وضعیت HTTP را بررسی کنید و فرض نکنید همه پاسخ‌های خطا قالب بالا را دارند. مقدارهای پرس‌وجو را با نوع درست بفرستید.

مبلغ‌ها

• مقدارهای رمزارزی رشته‌های اعشاری بر حسب واحد خود دارایی هستند ("10.5") — هرگز عدد JSON. پاسخ‌ها amount_minor را هم می‌آورند (افزوده): مقدار صحیح به واحد خرد، به‌صورت رشته، چون عددهای بزرگ بر حسب wei ممکن است از محدوده نمایش دقیق عددهای صحیح در Number جاوااسکریپت فراتر بروند.
• decimals هر دارایی از getCurrencies می‌آید — محاسبه‌ی مقدار را از همان‌جا بگیرید، نه از مقداری ثابت در کد.
• مبلغ‌های فیات حداکثر 2 رقم اعشار دارند.
• نرخ‌ها رشته‌ی ممیز ثابت‌اند، هرگز عدد.

صفحه‌بندی

متدهای فهرستی (getInvoices، getChecks، getTransfers، getSubscriptions) offset (پیش‌فرض 0) و count (پیش‌فرض 100، حداکثر 1000؛ برای getSubscriptions حداکثر 500) می‌گیرند و {"items": […]} را به ترتیب از تازه‌ترین برمی‌گردانند. فیلترهای شناسه (invoice_ids، check_ids، transfer_ids) فهرستی از عددهای جداشده با ویرگول‌اند. زمان‌ها همه‌جا رشته‌ی ISO 8601 هستند.

جلوگیری از پرداخت دوباره: spend_id

متدهایی که دارایی جابه‌جا می‌کنند کلید spend_id را می‌گیرند که خودِ فراخواننده می‌سازد (1 تا 64 نویسه): روی transfer و هر آیتم transferBatch اجباری است، روی createCheck و refundInvoice اختیاری (افزوده — باز هم از آن استفاده کنید). تلاش دوباره با همان کلید و همان پارامترها، به‌جای جابه‌جایی دوباره‌ی دارایی، همان نتیجه‌ی اول را تکرار می‌کند، پس درخواستی را که تایم‌اوت شده همیشه بی‌خطر می‌توانید دوباره بفرستید. همان کلید با پارامترهای متفاوت 409 idempotency_conflict می‌دهد؛ تلاش دوباره وقتی درخواست اول هنوز در حال اجراست 409 idempotency_in_progress می‌دهد.

سقف درخواست

برای هر برنامه، مشترک بین همه‌ی توکن‌هایش؛ عبور از آن 429 rate_limited برمی‌گرداند:

متد	سقف
createInvoice، createCheck	هر دقیقه 60 بار
refundInvoice	هر دقیقه 30 بار
transfer	هر دقیقه 30 بار
transferBatch	هر دقیقه 10 بار
updateApp	هر دقیقه 10 بار
createSubscriptionPlan	هر دقیقه 20 بار

محدودیت‌های دیگری هم ممکن است برای درخواست‌ها اعمال شوند. با دیدن 429 rate_limited، فاصله بین تلاش‌های دوباره را بیشتر کنید. هنگام تعمیرات پلتفرم، متدهای نوشتنی 503 maintenance می‌دهند و متدهای خواندنی به کار ادامه می‌دهند.

متدهای کاتالوگ و حساب

getMe

GET /pay/api/getMe — بدون پارامتر. هویت برنامه را برمی‌گرداند: app_id، name، payment_processing_bot_username، webhook_url، webhook_events (رویدادهای بیشترِ وب‌هوک که برنامه فعال کرده است)، فیلدهای معرفی توکن، یعنی همان scopes / token_name که بالاتر توضیح داده شد، و payout_mode (off / allowlist / any)، daily_payout_max_usd_cents (0 یعنی مالک سقفی تعیین نکرده) و daily_payout_spent_usd_cents (مبلغ پرداخت در 24 ساعت گذشته).

updateApp

POST /pay/api/updateApp — دامنه دسترسی webhooks. پارامترهای اختیاری: name (1 تا 64 نویسه)، webhook_url (آدرس HTTPS عمومی؛ رشته خالی آن را حذف می‌کند) و webhook_events (آرایه یا فهرست جداشده با ویرگول از نام رویدادهای اضافی پشتیبانی‌شده). فهرست خالی رویدادها فقط invoice_paid را باقی می‌گذارد. همان فیلدهای برنامه در getMe را برمی‌گرداند.

getBalance

GET /pay/api/getBalance — بدون پارامتر. برای هر دارایی پشتیبانی‌شده یک سطر برمی‌گرداند، حتی وقتی خالی است: currency_code، available (موجودی در دسترس)، onhold (دارایی چک‌های دریافت‌نشده و پرداخت‌های در انتظار به @username) و amount_minor.

getCurrencies

GET /pay/api/getCurrencies — بدون پارامتر. فهرست معتبر آنچه API پشتیبانی می‌کند: سطرهای رمزارز (is_blockchain: true) و ارزهای فیاتی که صورت‌حساب می‌تواند بر حسب آن‌ها قیمت‌گذاری شود (is_fiat: true). هر سطر code، name، decimals و پرچم is_stablecoin را دارد.

getExchangeRates

GET /pay/api/getExchangeRates — بدون پارامتر. نرخ رمزارز به فیات را با source، target، rate (رشته ممیز ثابت) و is_valid برمی‌گرداند. این نرخ‌ها را تقریبی بدانید. is_valid: true تازه بودن نرخ را تضمین نمی‌کند. اگر نرخ‌ها در دسترس نباشند، ممکن است آرایه خالی برگردد. برای تطبیق پرداخت واقعی، از مبلغ‌ها و نرخ‌های ثبت‌شده در صورت‌حساب استفاده کنید.

getStats

GET /pay/api/getStats — با start_at / end_at اختیاری (ISO 8601؛ بازه‌ی پیش‌فرض 24 ساعت گذشته است). volume (ارزش دلاری صورت‌حساب‌های پرداخت‌شده در آن بازه، با برآورد بر اساس نرخ فعلی؛ دارایی بدون نرخ، صفر حساب می‌شود)، conversion (نسبت پرداخت‌شده به ساخته‌شده، به درصد)، unique_users_count، created_invoice_count، paid_invoice_count و کران‌های مؤثر بازه را برمی‌گرداند. تاریخ ناخوانا یا نامعتبر 400 invalid_date می‌دهد.

خطاهایی که هر متدی می‌تواند بدهد

HTTP	error.name	چه وقت
401	unauthorized	توکن ارسال نشده، نامعتبر یا باطل‌شده
403	scope_required	توکن دامنه‌ی لازم آن متد را ندارد
403	payouts_disabled	حالت پرداخت برنامه off است (فقط متدهای پرداخت)
403	recipient_not_allowed	گیرنده در فهرست گیرندگان برنامه نیست (فقط متدهای پرداخت)
400	invalid_request	پارامترهای ناخوانا یا نامعتبر (POST)
403	daily_cap_exceeded	پرداخت از سقف روزانه برنامه فراتر می‌رود
403	verification_required	عملیات خروجی مالک محدود است؛ بر انتقال، چک و بازگشت وجه اثر دارد
503	merchant_payouts_paused	برداشت از موجودی برنامه موقتاً متوقف شده است
429	rate_limited	عبور از سقف درخواست
503	maintenance	تعمیرات پلتفرم (متدهای نوشتنی)
500	internal_error	خطای غیرمنتظره‌ی سرور

خطاهای خاص هر متد در صفحه‌ی خود آن متد آمده است.

خطاهای بدون ساختار JSON

صرفاً متنی یا HTML بودن پاسخ خطا مشخص نمی‌کند که کدام لایه آن را برگردانده است. وضعیت HTTP، بدنه و سرآیندهای پاسخ را بررسی کنید.

اگر Cloudflare خطای error code: 1010 را برگرداند، پیش از رسیدن درخواست به API، کلاینت را بر اساس امضای مرورگر رد کرده است. محدودهٔ دسترسی توکن علت این خطای Cloudflare نیست. نبودن User-Agent یا غیرمعمول بودن آن می‌تواند حفاظت شبکه را فعال کند. یک سرآیند User-Agent با نامی مشخص برای کلاینت خود، مانند MyShop/1.0، بفرستید و دوباره تلاش کنید؛ این کار رفع خطا را تضمین نمی‌کند. اگر خطا ادامه داشت، وضعیت HTTP، بدنه و سرآیندهای پاسخ را پس از حذف توکن‌ها و کوکی‌ها برای پشتیبانی بفرستید.