مرجع API: انتقال و چک

متدهای پرداخت خروجی. انتقال دارایی را از موجودی برنامه‌ی شما به کیف پول یک کاربر تلگرام می‌فرستد، یا تا زمانی که گیرنده‌ی جدید ربات را باز کند نگه می‌دارد؛ چک لینکی برای دریافت دارایی است که مبلغ آن را از پیش تأمین می‌کنید. قراردادهای مشترک (احراز اصالت، قالب پاسخ، مبلغ‌ها، spend_id) در صفحه‌ی مرجع API پذیرنده آمده است.

هر سه متد پرداخت خروجی از حالت پرداخت برنامه پیروی می‌کنند: برنامه‌ی جدید از همان ابتدا به هر کسی پرداخت می‌کند؛ اگر مالک آن را محدود کرده باشد، فقط به کاربران فهرست می‌توان پرداخت کرد (403 recipient_not_allowed) یا به هیچ‌کس (403 payouts_disabled). حالت را مالک در مینی‌برنامه تعیین می‌کند؛ از طریق API نمی‌توان آن را تغییر داد. شرایط API پذیرنده تعیین می‌کند پرداخت‌ها بابت چه چیزی مجاز است.

transfer

POST /pay/api/transfer — دامنه‌ی payouts، سقف 30 در دقیقه. گیرنده‌ی شناخته‌شده پرداخت را فوری دریافت می‌کند. برای username ناشناخته، انتقالی با وضعیت pending ساخته می‌شود: دارایی به‌صورت امانی نگه داشته می‌شود تا گیرنده با همان نام کاربری ربات را باز کند؛ دارایی دریافت‌نشده پس از پایان مهلت 30 روزه (expires_at) به موجودی برنامه برمی‌گردد. پیش از استفاده از آن در حسابداری، بازگشت را با وضعیت status: "returned" تأیید کنید. خودتان invite_url را برای گیرنده بفرستید؛ ربات نمی‌تواند به کسی که آن را شروع نکرده پیام بدهد. وضعیت نهایی completed یا returned است؛ برای پیگیری آن، وب‌هوک‌های transfer_completed و transfer_returned را فعال کنید یا getTransfers را فراخوانی کنید.

پارامتر	نوع	اجباری	معنی
user_id	عدد صحیح	دقیقاً یکی از user_id / username	شناسه‌ی کاربری تلگرام گیرنده؛ گیرنده باید از پیش کاربر برنامه باشد
username	رشته	دقیقاً یکی از user_id / username	نام کاربری گیرنده، با یا بدون @؛ برای نام کاربری ناشناخته، پرداخت در انتظار ساخته می‌شود
asset	رشته	بله	کد دارایی
amount	رشته	بله	رشته‌ی اعشاری مثبت؛ همچنین به حداقل و حداکثر هر انتقال در پلتفرم محدود است (برآورد معادل دلاری با نرخ فعلی)
spend_id	رشته	بله	کلید جلوگیری از پرداخت دوباره، 1 تا 64 نویسه، برای هر پرداخت یکتا
comment	رشته	خیر	تا 1024 نویسه، که به گیرنده نشان داده می‌شود
disable_send_notification	بولی	خیر	true اعلان گیرنده را برای پرداخت فوری غیرفعال می‌کند؛ دریافت انتقال در انتظار، مستقل از این گزینه، همچنان اعلان دارد

اگر هر دو پارامتر گیرنده را ارسال کنید یا هیچ‌کدام را مشخص نکنید، درخواست با خطای عمومی پارامترهای نامعتبر رد می‌شود.

نتیجه، شیء انتقال است: transfer_id، hash، user_id، recipient_username، asset، amount، amount_minor، spend_id، comment، status (pending / completed / returned)، created_at، completed_at، expires_at، invite_url. تا زمانی که گیرنده‌ی جدید وارد نشده باشد، user_id ممکن است null باشد؛ completed_at فقط پس از انجام انتقال با وضعیت completed مقدار می‌گیرد و پیش از آن null است.

خطاها: 403 payouts_disabled / 403 recipient_not_allowed (حالت پرداخت)، 404 user_not_found (شناسه ناشناخته است یا گیرنده در دسترس نیست)، 400 invalid_recipient (ساختار نام کاربری گیرنده معتبر نیست)، 400 amount_too_small / 400 amount_too_big (بیرون از حد مجاز هر انتقال)، 409 insufficient_funds، 400 unknown_asset، 400 invalid_amount، و دو خطای مربوط به spend_id، یعنی 409 idempotency_conflict / 409 idempotency_in_progress.

transferBatch

POST /pay/api/transferBatch — دامنه‌ی payouts، سقف 10 در دقیقه. افزوده‌ای برای پرداخت انبوه: تا 100 انتقال در یک فراخوانی.

یک پارامتر: items — آرایه‌ای که هر عضو آن یک مجموعه‌ی کامل از پارامترهای transfer است (user_id یا username، asset، amount، spend_id و در صورت نیاز comment و disable_send_notification). هر spend_id باید در دسته یکتا باشد، وگرنه کل فراخوانی پیش از اجرای هر آیتم با خطای 400 duplicate_spend_id رد می‌شود. ساختار نامعتبر آیتم، حالت پرداخت برنامه یا سقف روزانه آن هم می‌تواند کل درخواست را پیش از هر پرداخت رد کند. پس از پذیرش، نتیجه‌ها در result.items برمی‌گردند.

آیتم‌ها مستقل و به ترتیب تسویه می‌شوند — ناموفق شدن یک آیتم هرگز بقیه را باطل نمی‌کند. فراخوانی حتی وقتی بعضی آیتم‌ها ناموفق بوده باشند HTTP 200 با ok: true برمی‌گرداند، پس همیشه تک‌تک آیتم‌ها را بررسی کنید:

• موفق: {"ok": true, "spend_id": "…", "result": <transfer object>}
• ناموفق: {"ok": false, "spend_id": "…", "error": {"code": …, "name": "…"}} با همان نام خطاهای یک transfer تکی.

آیتم‌های دسته و انتقال‌های تکی فضای نام یکسانی برای spend_id دارند: تکرار کل دسته — یا فرستادن دوباره‌ی یک آیتم به‌صورت یک transfer تکی با همان spend_id — به‌جای پرداخت دوباره، همان نتیجه را تکرار می‌کند.

getTransfers

GET /pay/api/getTransfers — دامنه‌ی read. فیلترها: asset، transfer_ids (جداشده با ویرگول)، spend_id (تطابق دقیق — یک پرداخت را با کلید خودتان پیدا کنید)، status (pending / completed / returned)، به‌علاوه‌ی offset / count. خروجی {"items": [transfer, …]} است، به ترتیب از جدیدترین.

createCheck

POST /pay/api/createCheck — دامنه checks، سقف 60 در دقیقه. به‌طور پیش‌فرض چک یک‌بارمصرفی از موجودی برنامه می‌سازد که دارنده لینک یا کاربر تعیین‌شده می‌تواند دریافت کند. افزونه recipients فهرستی از گیرندگان با سهم جداگانه می‌سازد. مجموع هنگام ساخت قفل می‌شود (در getBalance از available به onhold می‌رود). ساخت چک همان سقف مبلغ و سقف پرداخت روزانه انتقال را دارد.

پارامتر	نوع	اجباری	معنی
asset	رشته	بله	کد دارایی
amount	رشته	مگر recipients تعیین شده باشد	رشته اعشاری مثبت؛ با recipients مجموع از فهرست محاسبه می‌شود
pin_to_user_id	عدد صحیح	خیر	فقط این شناسه‌ی کاربری تلگرام می‌تواند دریافت کند
pin_to_username	رشته	خیر	فقط این @username می‌تواند دریافت کند (@ اختیاری است؛ وقتی pin_to_user_id هم ارسال شده باشد نادیده گرفته می‌شود). نام کاربری باید به یکی از کاربران موجود برنامه تعلق داشته باشد
spend_id	رشته	خیر	کلید جلوگیری از پرداخت دوباره (افزوده) — حتماً از آن استفاده کنید
recipients	آرایه	خیر	افزونه: 1 تا 100 عضو، هرکدام با user_id یا username و amount به شکل رشته اعشاری مثبت. با کاربر اختصاص‌یافته قابل ترکیب نیست
password	رشته	خیر	افزونه: رمز لازم برای دریافت، تا 64 نویسه
expires_in	عدد صحیح	خیر	افزونه: عمر به ثانیه؛ ارسال نشدن یا 0 یعنی بدون انقضا

نتیجه، شیء چک است: check_id، hash، asset، amount، amount_minor، bot_check_url (لینک دریافت t.me)، status (active / activated)، pin_to_user_id، created_at، activated_at، expires_at و recipients (برای چک معمولی null؛ در غیر این صورت هر عضو شامل user_id، username، amount، amount_minor و claimed_at). هر دریافت وب‌هوک اختیاری check_activated ایجاد می‌کند؛ دریافت سهم فهرست‌شده activated_slot هم دارد. انقضا باقی‌مانده را برمی‌گرداند؛ انقضای چک با فهرست گیرندگان می‌تواند check_expired بفرستد.

پاسخ فعلی هر چکی را که کامل دریافت نشده، حتی چک منقضی‌شده را، status: "active" نشان می‌دهد. expires_at را هم بررسی کنید؛ active به‌تنهایی دریافت‌پذیری لینک را ثابت نمی‌کند.

خطاها: 403 payouts_disabled / 403 recipient_not_allowed (حالت پرداخت — در حالت allowlist هر گیرنده اختصاص‌یافته یا عضو فهرست گیرندگان باید مجاز باشد)، 400 unknown_asset، 400 invalid_amount، 404 user_not_found (نام کاربری تعیین‌شده با هیچ کاربری مطابقت ندارد)، 409 insufficient_funds، و دو خطای مربوط به spend_id.

deleteCheck

POST /pay/api/deleteCheck — دامنه‌ی checks. یک پارامتر: check_id. چک فعال را لغو می‌کند و باقی‌مانده دریافت‌نشده را به موجودی برنامه برمی‌گرداند؛ خروجی true است. خطاها: 404 check_not_found، 409 check_not_active (کامل دریافت‌شده، منقضی یا حذف‌شده).

getChecks

GET /pay/api/getChecks — دامنه‌ی read. فیلترها: asset، check_ids (جداشده با ویرگول)، status (active / activated)، به‌علاوه‌ی offset / count. خروجی {"items": [check, …]} است، به ترتیب از جدیدترین؛ چک‌های حذف‌شده هرگز برگردانده نمی‌شوند.