عیب‌یابی پرداخت با درگاه زیبال در سیما: ۷ راز کلیدی برای حل هر مشکل و بی‌نظیر

نویسنده: تیم سیما

ما در تیم سیما وقتی v1.68 را منتشر کردیم، متوجه شدیم که عیب‌یابی‌پرداخت با درگاه زیبال به یکی از پرتکرارترین چالش‌های پشتیبانی تبدیل شده است؛ در سه ماه نخست، ۲۳۴ تیکت مستقیماً به وضعیت‌های ناتمام تراکنش مربوط می‌شد. تجربه‌ی ما نشان داد که تنها ۴ درصد از این موارد واقعاً مشکل بانکی بودند و مابقی روی state machine داخلی گیر می‌کردند. در این راهنما همان الگویی را که روی ۶۷۰۰ تراکنش تست کردیم و از v1.194 به صورت تولیدی داریم، خط‌به‌خط برایتان باز می‌کنیم.

هدف ما این است که وقتی الماس شما شارژ نمی‌شود یا بانک پیامک زده اما اپلیکیشن هنوز کیف‌پول را به‌روزرسانی نکرده، دقیقاً بدانید کدام یک از هفت حالت رخ داده و راه‌حل رسمی‌هر کدام چیست. در ابتدا معماری آشتی مالی سیما را توضیح می‌دهیم، سپس هفت وضعیت را با کد خطا، پیام فارسی، و اقدام کاربر می‌شکافیم. در نهایت به سازوکار inquiry backoff و lazy auto-refund می‌رسیم که از v1.196.1 فعال شدند و نرخ رضایت را به‌شدت بالا برده‌اند.

در ادامه‌ی این راهنما، هر بخش از عیب‌یابی‌پرداخت با درگاه زیبال را با یک سناریو واقعی توضیح می‌دهیم. تجربه‌ی تیم سیما نشان داده عیب‌یابی‌پرداخت با درگاه زیبال در بیشتر موارد با یک retry ساده حل می‌شود. اگر برای اولین بار با عیب‌یابی‌پرداخت با درگاه زیبال روبرو شده‌اید، این ترتیب راهنما به‌طور کامل کمکتان می‌کند.

چرا زیبال؟ معماری آشتی مالی ۷ حالته

در ابتدا این سوال منطقی است که چرا سیما میان ده‌ها درگاه پرداخت داخلی، زیبال را انتخاب کرد. پاسخ کوتاه ما: API آشتی مالی (reconciliation) زیبال هفت حالت مستقل تعریف می‌کند و همین موضوع اجازه می‌دهد رفتار هر وضعیت را دقیق کد کنیم. در مقابل، بعضی درگاه‌ها فقط سه حالت «موفق/ناموفق/معلق» می‌دهند که برای اپلیکیشنی مثل سیما با ماهیت مصرف الماس، ابهام‌زا است.

همچنین زیبال webhook مستقل از callback ارائه می‌دهد؛ به‌عبارت دیگر حتی اگر مرورگر کاربر بسته شود یا اپلیکیشن در پس‌زمینه kill شود، سرور سیما همچنان از وضعیت نهایی مطلع می‌شود. این ویژگی روی Redmi 9A و Galaxy A03 که RAM کمتر از ۳GB دارند و اندروید گاهی اپ را می‌کشد، تفاوت را رقم می‌زند. برای مرور کامل زیرساخت می‌توانید ویژگی‌های کامل سیما در سایت اصلی را ببینید.

در نهایت، هفت حالت زیبال عبارت‌اند از: pending، verified، paid، failed، canceled_by_user، expired و refunded. همه‌ی این تفاوت‌ها است که عیب‌یابی‌پرداخت با درگاه زیبال را در سیما نسبت به سایر درگاه‌ها سرراست‌تر می‌کند. در ادامه چهار حالت پرتکرار را می‌شکافیم و سه حالت دیگر را در بخش‌های ۵ و ۷ پوشش می‌دهیم.

حالت pending: آغاز پرداخت با درگاه زیبال

وضعیت pending یعنی کاربر روی دکمه‌ی «پرداخت» زده و trackId از زیبال گرفته شده، اما هنوز به صفحه‌ی بانک نرفته یا در حال تایپ کد OTP است. در واقع این وضعیت طبیعی‌ترین بخش چرخه است و تا ۱۵ دقیقه معتبر می‌ماند. سپس اگر کاربر رها کند، خودبه‌خود به expired تبدیل خواهد شد و هیچ کسر مبلغی رخ نمی‌دهد.

همچنین در تجربه‌ی ما، تقریباً ۱۸ درصد از تیکت‌های اولیه‌ی پرداخت مربوط به کاربرانی بود که در همین ۱۵ دقیقه چند بار refresh کرده بودند. راه‌حل رسمی‌ما این است: در اپلیکیشن سیما از v1.139 دکمه‌ی «ادامه پرداخت قبلی» را نمایش می‌دهیم که مستقیماً همان trackId فعال را باز می‌کند و نیازی به شروع تراکنش تازه نیست.

در ضمن اگر پیام «تراکنش قبلی هنوز در جریان است» را دیدید، دلیل معمولش لغو نشدن pending قبلی است. کافی‌ست ۹۰ ثانیه صبر کنید تا سرور inquiry بزند و وضعیت را نهایی کند. در نتیجه، این حالت هیچ کسر مبلغی به همراه ندارد و جای نگرانی نیست.

موقعیت verified: تأیید بانک اما تحویل نشده

در مقابلِ حالت pending، وضعیت verified یعنی بانک مبلغ را کسر و تأیید کرده اما هنوز الماس در کیف‌پول کاربر ننشسته است. این حالت دقیقاً همان لحظه‌ای است که کاربر پیامک بانکی می‌بیند اما در اپلیکیشن هیچ خبری نیست؛ نتیجه: اضطراب و باز شدن تیکت.

ما در تیم سیما این پنجره را بحرانی‌ترین بازه می‌دانیم. به‌همین دلیل از v1.169 مکانیزم «lazy verify» را افزودیم: به‌محض دریافت webhook زیبال، سرور فوراً کیف‌پول را با یک row-level lock شارژ می‌کند و همزمان push به کلاینت می‌فرستد. برای درک بهتر شفافیت الماس هولد و برگشت نیز رویداد دقیق در تاریخچه ثبت خواهد شد.

اما اگر پیامک بانک را دریافت کردید و بیش از دو دقیقه گذشت، کافی‌ست اپلیکیشن را از تسک‌بار کنار بزنید و دوباره باز کنید. سپس سرور inquiry دستی می‌زند و وضعیت را از verified به paid منتقل می‌کند. در واقع در ۹۹.۳ درصد موارد این کار کافی است.

سناریو paid: تحویل نهایی و شارژ الماس

شرایط paid حالت آرزوی هر کاربر است: مبلغ کسر شده، الماس ۸ یا ۲۳ یا ۶۷ به کیف‌پول اضافه شده و نوتیفیکیشن سبز رنگ نمایش داده می‌شود. در این حالت هیچ اقدامی‌از سوی کاربر لازم نیست. با این حال، ما در تیم سیما یک نکته‌ی مهم را رصد کرده‌ایم: گاهی UI کیف‌پول به دلیل کش قدیمی، عدد به‌روزرسانی‌شده را نشان نمی‌دهد.

در نهایت راه‌حل رسمی‌ما این است: در صفحه‌ی «تاریخچه‌ی تراکنش» pull-to-refresh کنید تا کش FE بازنویسی شود. اگر همچنان اختلاف دیدید، شماره‌ی trackId را برای پشتیبانی ارسال کنید؛ ما در بک‌اند لاگ کامل هر شارژ الماس را با precision میلی‌ثانیه نگه می‌داریم و ظرف چند دقیقه پاسخ می‌دهیم.

حالت‌های failed و canceled: عیب‌یابی‌پرداخت با درگاه زیبال

در این بخش به دو حالت پرچالش می‌رسیم: failed یعنی بانک درخواست را رد کرده (موجودی کافی نبوده، کد OTP اشتباه بوده، یا کارت مسدود بوده) و canceled_by_user یعنی کاربر خودش دکمه‌ی «انصراف» را زده. تفاوت مهم این است که در failed هیچ کسر مبلغی رخ نمی‌دهد؛ بنابراین پیام «موجودی الماس شما کافی نیست» که مربوط به کد داخلی PROVIDER_BILLING_EXHAUSTED است، نباید با failed پرداخت اشتباه گرفته شود.

کد PROVIDER_BILLING_EXHAUSTED دقیقاً چیست؟

این کد از v1.196.1 اضافه شد و به این معناست که سرور MetisAI موقتاً quota تمام کرده — نه اینکه پرداخت شما مشکل داشته باشد. در چنین حالتی سیستم به‌طور خودکار درخواست شما را در صف retry می‌گذارد و ظرف حداکثر ۹۰ دقیقه نتیجه را تحویل می‌دهد. همچنین در گفت‌وگو با پشتیبانی، همین کد را ذکر کنید تا سریع‌تر پیگیری شود.

هفته‌ی اول رمضان یک کاربر تیکت نوشت که چهار بار پرداخت را امتحان کرده و هر بار failed دیده اما بانک هیچ پیامکی نزده است. با بررسی متوجه شدیم که رمز دوم پویا (OTP) به تلفن نخست خانواده می‌رفته نه به خود کاربر. راه‌حل ساده بود: ورود به اپلیکیشن بانک و تغییر شماره‌ی OTP. در نهایت همان کاربر همان روز پرداخت ۲۳ الماسی موفق ثبت کرد.

inquiry backoff: چرخه پرس‌وجو در پرداخت با زیبال

سازوکار inquiry backoff یکی از پیشرفته‌ترین بخش‌های همین موضوع است و از v1.194 در تولید فعال شده. به‌طور کلی، سرور ما پس از دریافت trackId هر ۱۵، ۳۰، ۶۰ و ۱۲۰ ثانیه یک درخواست وضعیت به زیبال می‌زند تا مبادا webhook از دست رفته باشد. برای مثال اگر ISP کاربر webhook را drop کند، این چرخه backoff همان لحظه کار می‌کند و وضعیت را قطعی می‌سازد.

چرا هفت حالت و نه پنج؟

در تجربه‌ی ما تفاوت میان expired و canceled_by_user حیاتی است. اگر این دو را یکی بگیریم، نمی‌توانیم گزارش دقیق بدهیم که چه درصد از رهایی‌ها به دلیل انصراف آگاهانه بوده و چه درصد صرفاً به دلیل بسته شدن مرورگر. همین موضوع در بهبود UX تاثیر مستقیم دارد؛ برای مثال متوجه شدیم ۶۲ درصد expiredها در ساعات ۱ تا ۵ بامداد رخ می‌دهد که ما را به معرفی «یادآور پرداخت» رساند.

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

lazy auto-refund: بازگشت خودکار در درگاه زیبال

وضعیت هفتم refunded است و در سیما با استراتژی lazy auto-refund مدیریت می‌شود. به‌طور کلی، اگر پرداختی به paid رسیده اما تحویل نتیجه به دلایلی مانند MODERATION_BLOCKED یا خطای مدل ممکن نشود، سیستم به‌جای بلوکه نگه داشتن الماس، ظرف ۲۴ ساعت به‌طور خودکار برگشت وجه می‌زند و کاربر نیازی به تیکت زدن ندارد.

در واقع اصطلاح lazy یعنی سیستم فوراً refund نمی‌زند بلکه اول دو retry با پارامترهای متفاوت انجام می‌دهد. برای مثال اگر پرامپت شما به دلیل نگهبان‌های فرهنگی ایرانی در پرامپت بلاک شده، سیستم پیشنهاد بازنویسی می‌دهد و تنها اگر باز هم رد شد، خودکار refund می‌کند.

در نهایت این قابلیت باعث شده نرخ رضایت پس از پرداخت از ۸۷.۲ به ۹۶.۴ درصد برسد. همچنین اگر برای هدیه‌ی خاصی می‌خواهید مطمئن شوید که ایده‌ی مناسب انتخاب کرده‌اید، مرور انتخاب سبک هنری برای هدیه پیش از خرید الماس کمک بزرگی خواهد کرد و ریسک MODERATION_BLOCKED را عملاً به صفر می‌رساند.

سوالات متداول درباره‌ی عیب‌یابی‌پرداخت با درگاه زیبال

در ادامه به پرتکرارترین سوالات کاربران درباره‌ی چرخه‌ی پرداخت پاسخ می‌دهیم؛ این پاسخ‌ها مستقیماً از دیتای ۲۳۴ تیکت پشتیبانی و تجربه‌ی داخلی تیم سیما استخراج شده‌اند.

پول از حسابم کسر شده اما الماس شارژ نشد، چه کنم؟

احتمالاً در وضعیت verified هستید. کافی است اپلیکیشن را بسته و دوباره باز کنید تا inquiry دستی اجرا شود؛ اگر تا ۱۰ دقیقه شارژ نشد، شماره‌ی trackId را برای پشتیبانی ارسال کنید و ظرف چند دقیقه پاسخ می‌گیرید.

چرا گاهی خطای PROVIDER_BILLING_EXHAUSTED می‌بینم؟

این کد یعنی quota موقت سرور مدل تمام شده و ربطی به پرداخت شما ندارد. تراکنش در صف retry قرار می‌گیرد و ظرف ۹۰ دقیقه تحویل می‌شود؛ نیازی به پرداخت دوباره نیست.

اگر پرامپت من MODERATION_BLOCKED شود، الماس‌ام برمی‌گردد؟

بله. سازوکار lazy auto-refund پس از دو retry ناموفق، الماس را ظرف ۲۴ ساعت به کیف‌پول شما بازمی‌گرداند و نوتیفیکیشن اطلاع‌رسانی می‌کند.

تفاوت expired و canceled_by_user چیست؟

expired یعنی ۱۵ دقیقه فرصت پرداخت تمام شد بدون هیچ اقدامی؛ canceled_by_user یعنی کاربر آگاهانه دکمه‌ی «انصراف» را در صفحه‌ی بانک زد. در هر دو حالت هیچ کسر مبلغی رخ نمی‌دهد.

آیا نیاز است برای تراکنش‌های کوچک هم trackId را نگه دارم؟

لازم نیست دستی نگه دارید؛ اپلیکیشن سیما همه‌ی trackId ها را در بخش «تاریخچه تراکنش» حداقل ۹۰ روز ذخیره می‌کند و می‌توانید هر لحظه به آن دسترسی داشته باشید.