شماره راهنما29درگاه پرداخت فروشگاه و تأیید خودکار سفارش
مرز پرداخت فروشگاهی و اشتراک، اتصال حساب عادی پذیرنده TCart، ساخت فاکتور، callback امضاشده، تطبیق مبلغ و بازیابی امن.
در مسیر جاری فروشگاه، اتصال خودکار سفارش با حساب عادی پذیرنده TCart انجام می‌شود؛ هر فروشگاه کلید API و Secret callback مستقل خود را دارد. این مسیر با درگاه‌های خرید اشتراک اوردیکس جداست. وقتی TCart برای فروشگاه فعال باشد، سفارش ابتدا ثبت و سپس فاکتور متناظر ساخته می‌شود؛ تنها callback معتبر و منطبق با فاکتور اجازه ثبت پرداخت در دفتر مالی را می‌دهد. اگر TCart غیرفعال باشد، مسیر دستی فروشگاه (نمایش مقصد و ارسال رسید برای بررسی فروشنده) باقی می‌ماند. وجود کد آداپتورهای دیگر در مخزن به‌تنهایی به معنی اتصال آن‌ها به checkout فروشگاه نیست.
مرز دو نوع پرداخت
خرید اشتراک اوردیکس از کاتالوگ درگاه‌های پلتفرم و کنترلر خرید استفاده می‌کند؛ پرداخت سفارش فروشگاه از تنظیمات همان فروشگاه و TCart استفاده می‌کند. کلید، حساب پذیرنده، فاکتور و callback این دو مسیر قابل جایگزینی نیستند.
حساب عادی پذیرنده TCart
برای هر فروشگاه، حساب عادی پذیرنده‌ای لازم است که API ساخت فاکتور را در سطح اشتراک مجاز فعال کرده باشد. مسیر جاری از مدل فروشنده زیرمجموعه پلتفرم استفاده نمی‌کند؛ شناسه vendor برای فاکتور فروشگاه باید صفر باشد. سطح دسترسی API و شرایط پلن را در پنل رسمی TCart بررسی کنید؛ اطلاعات عمومی سرویس Business به بالا را اعلام می‌کند.
کلیدهای مستقل فروشگاه
کلید API و Secret امضای callback از همان حساب پذیرنده دریافت می‌شوند و در تنظیمات همان فروشگاه ذخیره می‌شوند. کلید API برای ساخت و استعلام فاکتور است؛ Secret برای اعتبارسنجی callback. مقدار رمز در پاسخ API و DOM برگردانده نمی‌شود و فیلد خالی هنگام ذخیره، مقدار قبلی را حفظ می‌کند.
ساخت سفارش و فاکتور
checkout ابتدا سفارش را در پایگاه داده tenant ثبت می‌کند. سپس نگاشت فاکتور در Master DB با tenant_id، store_id، order_id و external_order_id ذخیره می‌شود و درخواست ساخت فاکتور به API TCart می‌رود. اگر درخواست به timeout یا پاسخ مبهم برسد، فاکتور دوم کورکورانه ساخته نمی‌شود و سفارش برای تطبیق باقی می‌ماند.
مبلغ پایه و مبلغ یکتای پرداخت
مبلغ سفارش در دیتابیس ریال است و برای TCart به تومان تبدیل می‌شود؛ مبلغ باید قابل تبدیل دقیق باشد و حداقل مبلغ پذیرنده رعایت شود. فاکتور علاوه بر مبلغ پایه، unique_amount_toman دارد. خریدار باید دقیقاً مبلغ یکتای صفحه پرداخت را بپردازد؛ مبلغ پایه یا مبلغ گرد شده ممکن است به سفارش متصل نشود.
callback و امضای HMAC
callback پرداخت به endpoint عمومی سامانه می‌رسد و هدر X-Resid-Signature را حمل می‌کند. سرور بدنه JSON را با محدودیت اندازه می‌خواند، ساختار JSON را canonical می‌کند (مرتب‌سازی بازگشتی کلیدها و JSON فشرده با UTF-8) و HMAC-SHA256 را با Secret همان فروشگاه محاسبه می‌کند؛ مقایسه با hash_equals انجام می‌شود. امضای نامعتبر هیچ تغییری در سفارش یا دفتر مالی ایجاد نمی‌کند.
تطبیق رویداد با فاکتور
رویداد باید payment.confirmed و وضعیت paid داشته باشد. invoice_id و external_order_id باید به یک نگاشت ذخیره‌شده برسند؛ vendor_id برای حساب عادی فروشگاه صفر است؛ amount_toman باید با unique_amount_toman و base_price_toman باید با مبلغ پایه فاکتور برابر باشد. مبلغ پایه نیز با total_rial سفارش تطبیق داده می‌شود.
ثبت مالی و جلوگیری از تکرار
پس از اعتبارسنجی، سرویس مالی tenant پرداخت را با مرجع یکتای tcart:payment ثبت می‌کند و وضعیت سفارش را به paid می‌برد. hash رویداد و مرجع ledger تکرار callback را بی‌اثر می‌کنند؛ ارسال دوباره callback نباید درآمد، موجودی یا تحویل را دوباره ثبت کند.
بازگشت مرورگر و استعلام GET
return_url فقط خریدار را به صفحه پیگیری بازمی‌گرداند. صفحه پیگیری وضعیت سفارش را از سرور می‌خواند. استعلام GET فاکتور می‌تواند وضعیت paid بدون callback را به manual_review ببرد، اما به‌تنهایی مجوز ثبت پرداخت نیست.
پرداخت نامشخص یا دیرهنگام
اگر callback نرسد، پاسخ شبکه مبهم باشد یا پرداخت پس از بسته‌شدن سفارش برسد، مورد باید برای تطبیق دستی نگهداری شود. تا روشن‌شدن وضعیت همان invoice، پرداخت یا فاکتور دوم نسازید. پرداخت دیرهنگام برای سفارش منقضی/لغوشده به‌صورت خودکار به سفارش تازه منتقل نمی‌شود.
مسیر دستی وقتی TCart خاموش است
اگر TCart برای فروشگاه فعال نباشد، خریدار اطلاعات مقصد پرداخت را می‌بیند و می‌تواند تصویر رسید را در مسیر خصوصی سفارش بارگذاری کند. تصویر رسید تأیید بانکی نیست؛ مسئول مجاز فروشگاه باید مبلغ و مرجع را بررسی و وضعیت را دستی تأیید کند. وقتی TCart فعال است، فرم ارسال رسید برای همان سفارش بسته می‌شود تا دو مسیر پرداخت با هم تداخل نکنند.
محدوده درگاه‌های دیگر
درگاه‌های خرید اشتراک اوردیکس مستقل از checkout فروشگاه‌اند. همچنین وجود کلاس‌های آداپتور PEXN یا Aban در سورس، به معنی در دسترس بودن آن‌ها در checkout فروشگاه نیست؛ تا وقتی کنترلر و جریان سفارش از آن‌ها استفاده نکند، نباید آن‌ها را به‌عنوان گزینه فعال فروشگاه معرفی کرد.
نقشه اجرایی: درگاه پرداخت فروشگاه و تأیید خودکار سفارش
نمای مفهومی از موضوعات این راهنما؛ عنوان‌ها و داده‌ها صرفاً آموزشی‌اند.
پس از مطالعه این راهنما چه مواردی را بررسی کنم؟
- پیش‌نیازها و محدوده دسترسی مرتبط با این بخش را پیش از شروع بررسی کنید.
- هر مرحله را با داده واقعی و در دامنه مجاز فضای کاری انجام دهید.
- پس از اجرا، وضعیت و نتیجه را در همان ماژول بازبینی کنید.
نکته مهم: این شبیه‌سازی داده واقعی را تغییر نمی‌دهد. نتیجه نهایی به مجوز کاربر، پلن، تنظیمات اتصال و سرویس‌های بیرونی وابسته است.