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

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

transfer

POST /pay/api/transfer — دامنه‌ی payouts، سقف 30 درخواست در دقیقه. تسویه آنی و یکجا انجام می‌شود؛ حالت در انتظار ندارد.

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

نتیجه، شیء انتقال است: transfer_id، hash، user_id، asset، amount، amount_minor، spend_id، comment، status (همیشه completed)، created_at، completed_at.

خطاها: 404 user_not_found (گیرنده هیچ‌وقت از برنامه استفاده نکرده)، 409 recipient_blocked، 400 amount_too_small / 400 amount_too_big (بیرون از حد مجاز هر انتقال)، 409 insufficient_funds، 404 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، asset، amount، spend_id و در صورت نیاز comment و disable_send_notification). هر spend_id باید در دسته یکتا باشد، وگرنه کل فراخوانی پیش از اجرای هر آیتم با خطای 400 duplicate_spend_id رد می‌شود.

آیتم‌ها مستقل و به ترتیب تسویه می‌شوند — ناموفق شدن یک آیتم هرگز بقیه را باطل نمی‌کند. فراخوانی حتی وقتی بعضی آیتم‌ها ناموفق بوده باشند 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 (تطابق دقیق — یک پرداخت را با کلید خودتان پیدا کنید)، به‌علاوه‌ی offset / count. خروجی {"items": [transfer, …]} است، به ترتیب از جدیدترین.

createCheck

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

پارامتر	نوع	اجباری	معنی
asset	رشته	بله	کد دارایی
amount	رشته	بله	رشته‌ی اعشاری مثبت
pin_to_user_id	عدد صحیح	خیر	فقط این شناسه‌ی کاربری تلگرام می‌تواند دریافت کند
pin_to_username	رشته	خیر	فقط این @username می‌تواند دریافت کند (@ اختیاری است؛ وقتی pin_to_user_id هم ارسال شده باشد نادیده گرفته می‌شود). نام کاربری باید به یکی از کاربران موجود برنامه تعلق داشته باشد
spend_id	رشته	خیر	کلید جلوگیری از پرداخت دوباره (افزوده) — حتماً از آن استفاده کنید

نتیجه، شیء چک است: check_id، hash، asset، amount، amount_minor، bot_check_url (لینک دریافت t.me)، status (active / activated)، pin_to_user_id، created_at، activated_at. هر دریافت، وب‌هوک اختیاری check_activated را می‌فرستد.

خطاها: 404 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, …]} است، به ترتیب از جدیدترین؛ چک‌های حذف‌شده هرگز برگردانده نمی‌شوند.