# کتابخانه اتصال سایاپی

تمام بسته‌ها فقط `sp_test_` و حالت sandbox را می‌پذیرند. گرفتن PSP به‌تنهایی
این بسته‌ها را تولیدی نمی‌کند؛ نسخهٔ live باید جداگانه پیاده‌سازی و آزمون شود.
کلید همیشه در سرور فروشگاه نگهداری می‌شود. هیچ اطلاعات کارتی دریافت نمی‌شود.

## بسته‌ها

| اتصال | هدف سازگاری | روش نصب | وضعیت |
| --- | --- | --- | --- |
| WooCommerce | WordPress 6.5+، WooCommerce 8.5+، PHP 8.1+ | ZIP وردپرس؛ فقط checkout کلاسیک | افزونه موجود؛ آزمون نصب واقعی لازم |
| EDD | EDD 3.x، WordPress 6.5+، PHP 8.1+ | ZIP وردپرس؛ Downloads → Settings → Payments | نامزد آزمون؛ Test Mode اجباری |
| OpenCart | OpenCart 3.0.x، PHP 8.1+ | فایل ocmod.zip در Extension Installer؛ نصب و تنظیم Payments | نامزد آزمون؛ نه OpenCart 4 |
| WHMCS | WHMCS 8.x، PHP 8.1+ | کپی modules؛ اجرای install.sql روی دیتابیس آزمایش؛ فعال‌سازی gateway | نامزد آزمون؛ لایسنس لازم |
| RCP | API سازگار RCP 3.x، WordPress 6.5+، PHP 8.1+ | ZIP وردپرس؛ Settings → Sayapay RCP؛ انتخاب در RCP | نامزد آزمون؛ فقط عضویت یک‌باره |
| Virtual Freer | پس از تعیین نسخهٔ دقیق | پل اتصال Gateway.php برای توسعه‌دهنده | هنوز افزونهٔ نصب‌پذیر نیست |

هدف سازگاری، ادعای تست روی همه نسخه‌ها نیست. پیش از نصب، از دیتابیس **فروشگاه
آزمایشی** بکاپ بگیرید. این فایل‌ها را روی فروشگاه با فروش/تحویل واقعی فعال نکنید.
OpenCart باید ریال یا تومان را با `currency_value=1` ثبت کند؛ تبدیل ضمنی ارز نداریم.
جداول order، order_history، order_product، product و product_option_value در OpenCart
باید InnoDB باشند. افزونه با MyISAM پرداخت را شروع/تکمیل نمی‌کند؛ تبدیل نوع جدول
خودکار انجام نمی‌شود و باید با بکاپ و بررسی مدیر در فروشگاه آزمایش انجام شود.
وضعیت انتظار و پرداخت OpenCart باید متفاوت باشند. حذف افزونه‌ها سوابق مالی را حذف نمی‌کند.
در WHMCS تغییر ماندهٔ صورتحساب بعد از ساخت پرداخت نیازمند رسیدگی دستی است؛
شناسه جدید برای دورزدن idempotency ساخته نمی‌شود.

## کنترل‌های مشترک

مبلغ صحیح ریالی، سقف مبلغ، شناسه سفارش و پرداخت، mode، ارز، استرداد جزئی و
نشانی checkout بررسی می‌شوند. URL مرورگر، وضعیت ارسالی کاربر و موفقیت redirect
مدرک پرداخت نیست. کلید با redirect شبکه منتقل نمی‌شود. پاسخ ناقص/timeout/وضعیت
نامعلوم، سفارش را پرداخت‌شده نمی‌کند. callback تکراری نباید تحویل مجدد بسازد.
قفل callback وردپرس fail-closed است؛ قفل باقی‌مانده بعد از crash فقط پس از
بررسی وضعیت پرداخت توسط مدیر پاک شود، نه با انقضای کور.

نسخهٔ نخست EDD، RCP، WHMCS و OpenCart وابسته به بازگشت و رسیدگی دستی است؛
فقدان وب‌هوک/پیگیری زمان‌بندی‌شده روی این افزونه‌ها هنوز گیت تولید است.
تمدید خودکار، استرداد خودکار در میزبان و WooCommerce Blocks جزو این نسخه نیستند.

## معیار آزمون نصب واقعی

نصب و فعال‌سازی، خاموش/روشن، ذخیره امن تنظیمات، واحد ریال/تومان، سفارش با تخفیف،
پرداخت موفق/لغوشده/ناموفق، جعل callback، replay هم‌زمان، تغییر مبلغ سفارش،
نتیجه نامعلوم، قطع API و بازگشت بعد از refund را ثبت کنید. فقط بعد از اثبات
تکمیل یکتای سفارش/عضویت، وضعیت «آزمون نصب» تغییر می‌کند.

## منابع API میزبان

- [WHMCS third-party gateway](https://developers.whmcs.com/payment-gateways/third-party-gateway/)
- [WHMCS callback helpers](https://developers.whmcs.com/payment-gateways/callbacks/)
- [EDD gateway source](https://github.com/awesomemotive/easy-digital-downloads/blob/main/includes/gateways/manual.php)
- [RCP gateway source](https://github.com/stellarwp/restrict-content/blob/master/core/includes/gateways/class-rcp-payment-gateway-manual.php)
- [OpenCart extension system](https://github.com/opencart/opencart/wiki/Extension-System)

برای Virtual Freer فایل/نسخهٔ میزبان لازم است. پل عمومی را به‌جای افزونهٔ
آزموده‌شده معرفی نکنید و قرارداد رویداد/تحویل محصول را حدس نزنید.