زیبال به‌عنوان یک شرکت پرداخت‌یار، علاوه بر وظیفه‌ی تسهیل پرداخت آنلاین برای کسب‌وکارها، موظف است تمام تراکنش‌های انجام‌شده روی درگاه‌های فعال‌شده را طبق دستورالعمل‌های شاپرک ثبت و به این نهاد ناظر گزارش دهد. یکی از الزامات مهم این گزارش‌دهی، تطابق سه آدرس مشخص در هر تراکنش است. در ادامه توضیح می‌دهیم این الزام چیست، چرا وجود دارد و اگر از طریق اپلیکیشن موبایل یا بات پیام‌رسان تراکنش ایجاد می‌کنید چه کاری باید انجام دهید.
یادآوری روال ساخت تراکنش
روال کلی ساخت یک تراکنش در درگاه به این شکل است:
- کسب‌وکار با فراخوانی سرویس request، اطلاعات پذیرندگی، مبلغ و سایر اطلاعات مربوط به پرداخت را ارسال می‌کند و در پاسخ، یک trackId دریافت می‌کند.
- برای انتقال مشتری به صفحه‌ی پرداخت، پذیرنده مرورگر مشتری را به آدرس https://zibal.ir/start/trackId هدایت می‌کند.
در زمان بررسی این درخواست، زیبال وجود هدر referer را بررسی می‌کند و در صورت خالی بودن آن، تراکنش با خطا مواجه می‌شود.
چرا هدر referer باید حتما پر باشد؟
طبق الزامات شاپرک، در لاگ هر تراکنشی که برای این نهاد ارسال می‌شود، سه آدرس زیر باید ثبت و با یکدیگر مطابقت داشته باشند:
- آدرس دامنه‌ای که درگاه پرداخت برای آن فعال شده است (دامنه‌ی ثبت‌شده و تأییدشده‌ی پذیرنده نزد زیبال و شاپرک)
- آدرس Callback تراکنش که پذیرنده هنگام ساخت تراکنش (در سرویس /request) ارسال می‌کند
- آدرس referer که هنگام فراخوانی سرویس /start در هدر درخواست ارسال می‌شود
شاپرک برای تطبیق این سه آدرس، سطح دامنه اصلی را ملاک قرار می‌دهد و زیردامنه (subdomain) یا مسیر (path) را نادیده می‌گیرد. برای مثال:
- api.test.ir با test.ir یکسان در نظر گرفته می‌شود.
- test.ir/callback/php نیز با test.ir یکسان در نظر گرفته می‌شود.
هدف از این الزام، اطمینان از این است که فرآیند پرداخت واقعا از همان کسب‌وکاری آغاز شده که درگاه برایش فعال شده، و در مسیر بین شروع تراکنش تا بازگشت نتیجه، آدرس‌ها دستکاری یا جعل نشده‌اند.
به همین دلیل، هدر referer یکی از سه رکن اصلی این راستی‌آزمایی است و نبود آن، امکان احراز تطابق موردنظر شاپرک را از بین می‌برد. به همین علت سرویس /start بدون این هدر با خطا مواجه می‌شود.
چرا این موضوع در وبسایت‌ها معمولا مشکلی ایجاد نمی‌کند؟
وقتی مشتری از طریق یک وبسایت به صفحه پرداخت هدایت می‌شود (برای مثال با لینک یا ریدایرکت مرورگر)، مرورگر به‌صورت خودکار هدر referer را بر اساس آدرس صفحه مبدا (همان دامنه فروشگاه) پر می‌کند. بنابراین در حالت عادی، نیازی به اقدام اضافی از سمت توسعه‌دهنده نیست.
چرا این موضوع در اپ موبایل و بات‌ها مشکل‌ساز می‌شود؟
اگر هدایت مشتری به صفحه پرداخت از طریق موارد زیر انجام شود:
- اپلیکیشن‌های Native اندروید یا iOS (بدون استفاده از WebView مرورگر استاندارد، یا با فراخوانی مستقیم HTTP)
- بات‌های پیام‌رسان (مانند بات تلگرام، واتساپ و غیره)
معمولاً هدر referer به‌صورت خودکار توسط سیستم‌عامل یا کلاینت پر نمی‌شود، چون این هدر مفهومی مرورگر-محور (Browser-based) است و در فراخوانی‌های مستقیم HTTP یا در برخی کامپوننت‌های نمایش وب داخل اپ، به‌طور پیش‌فرض ارسال نمی‌شود. در نتیجه، درخواست /start بدون هدر referer ارسال شده و از سمت سرویس ما با خطا مواجه می‌شود.
راه‌حل: تنظیم دستی هدر Referer
اگر ساخت و هدایت تراکنش شما از طریق اپلیکیشن موبایل یا بات انجام می‌شود، لازم است هنگام فراخوانی یا هدایت به سرویس /start، هدر referer را به‌صورت دستی با مقدار دامنه ثبت‌شده و فعال‌شده درگاه خودتان تنظیم کنید. چند نکته کاربردی:
- اگر از WebView درون اپ استفاده می‌کنید، بسته به پلتفرم (اندروید یا iOS)، امکان تنظیم هدرهای سفارشی هنگام بارگذاری URL در WebView معمولاً وجود دارد و باید هدر referer را همان‌جا تزریق کنید.
- اگر درخواست را به‌صورت مستقیم از سمت سرور یا با یک کلاینت HTTP انجام می‌دهید، باید هدر referer را در تنظیمات درخواست اضافه کنید.
- مقدار این هدر باید با همان دامنه‌ای که درگاه پرداخت برایش فعال شده و همچنین با دامنه‌ی Callback ارسالی در /request هم‌خوانی داشته باشد (در سطح دامنه اصلی، صرف‌نظر از زیردامنه یا مسیر).
رعایت این نکته، هم از بروز خطا در تکمیل تراکنش جلوگیری می‌کند و هم از انطباق کسب‌وکار شما با الزامات نظارتی شاپرک اطمینان می‌دهد.