پرداخت

چه زمانی استفاده کنیم؟

خطاهای رایج

• مبلغ ثابت اشتباه

  اگر مبلغ از متغیر می‌آید، مطمئن شوید قبلش set شده. مبلغ صفر یا منفی پذیرفته نمی‌شود.
• نگذاشتن درگاه

  بات باید یک Payment Provider فعال داشته باشد؛ تنظیم در منوی «پرداخت‌ها» انجام می‌شود.
• متغیر موبایل اشتباه

  فیلد استاندارد شمارهٔ کاربر `vars.user.phone` است، نه `vars.user.mobile`. اگر اشتباه بنویسید، در درگاه ارسال نمی‌شود (هرچند سامانه به‌صورت خودکار به phone برمی‌گردد). پس از «اشتراک‌گذاری شماره»، فرمت‌های 09… / +98… / 98… خودکار نرمال می‌شود.
• خالی بودن `{{user.<slug>.<field>}}` برای کاربر نماینده

  وقتی پرداخت‌کننده مالکِ مستقیمِ رکورد نیست (مثلاً پدر برای خانواده‌ای که به نام مادر ثبت شده)، در نسخه‌های قدیمی موتور، `{{user.families.family_label}}` یا فیلدهای rollup خانواده در پیامِ پس از پرداخت خالی نمایش داده می‌شد. حالا دو مسیرِ مطمئن موجود است: (۱) موتور خودش `linked_record_ids` را به snapshot کاربر آینه می‌کند، پس همان `{{user.families.family_label}}` کار می‌کند، (۲) ترجیحاً از `{{payment.record.<field>}}` استفاده کنید — این متغیر مستقیماً از روی `related_record_id` همان تراکنش ساخته می‌شود و formula/rollup را هم اعمال می‌کند.

نکات حرفه‌ای

• شاخهٔ ناموفق را معمولاً به یک نود پیام «دوباره تلاش کنید» و سپس بازگشت به همین نود وصل کنید.
• برای پر شدن خودکار شماره در درگاه، قبل از نود پرداخت یک نود «پرسش» با نوع «اشتراک‌گذاری شماره» قرار دهید تا `user.phone` ست شود.
• متغیرهای خروجی در شاخهٔ موفق: `{{payment.id}}`, `{{payment.amount}}`, `{{payment.ref_id}}`, `{{payment.card_pan}}`, `{{payment.paid_at}}` و `{{payment.record.*}}` (در صورت لینک به یک رکورد از طریق `related_record_id`). برای پیام‌های پس از پرداخت و `send_to_chat` مدیریتی همیشه از `payment.record.*` استفاده کنید — این مستقل از این است که پرداخت‌کننده مالکِ رکورد باشد یا نمایندهٔ آن.
• حداقل و حداکثر مبلغ درگاه به‌صورت ثابت پروژه‌ای در موتور نود پرداخت تعریف شده‌اند و به همهٔ فلوها به‌صورت متغیرهای سراسری `gateway.min_amount` (پیش‌فرض ۱۰٬۰۰۰ ریال) و `gateway.max_amount` (پیش‌فرض ۱٬۰۰۰٬۰۰۰٬۰۰۰ ریال = سقف زرین‌پال در هر تراکنش) تزریق می‌شوند. در شرط‌ها/پیام‌ها از همین دو متغیر استفاده کنید (مثل `{{ gateway.max_amount }}`) و عدد را در فلو هارد‌کد نکنید — اگر زرین‌پال سقف را تغییر دهد، فقط یک نقطه در کد موتور باید بروز شود.
• اگر مبلغ تراکنش بیش از `gateway.max_amount` باشد، نود پرداخت به‌جای ساخت لینک شاخهٔ `failed` را با `payment.error_kind = "amount_over_max"` فعال می‌کند. در فلوهای ثبت‌نام پرحجم، قبل از نود پرداخت یک نود `condition` با شرط `total_payable_final > {{ gateway.max_amount }}` بگذارید و در شاخهٔ true یک فلوی مستقلِ «پرداخت چندمرحله‌ای» را با `call_flow` فراخوانی کنید — این الگو رفتار پرداخت یکجا را برای مبالغ زیر سقف دست‌نخورده نگه می‌دارد و خطایابی را ساده می‌کند.
• الگوی فلوی چندمرحله‌ای: متغیر `installment_paid_total` را با ۰ مقداردهی کنید، `pay_chunk = min(amount - installment_paid_total, gateway.max_amount)` بسازید، نود پرداخت را با `pay_chunk` فراخوانی کنید، در شاخهٔ `success` مقدار را به `installment_paid_total` اضافه کنید و حلقه را تا صفر شدن باقی‌مانده ادامه دهید. برای ایمنی، یک شرط `installment_index <= 10` به‌عنوان سقف مراحل بگذارید تا حلقهٔ بی‌پایان جلوگیری شود.