مستندات فنی سایاپی؛
از API تا افزونهٔ فروشگاه.

اتصال واقعی فروشگاه؛ جدا از محیط آموزشی

ابتدا حساب کسب‌وکار، ایمیل، ورود دومرحله‌ای و وب‌سایت را تأیید کنید. شبای فروشنده و مدارک لازم باید به آسان‌پرداخت معرفی شوند و تأیید واقعی آن ثبت شود؛ ارسال شبا به‌تنهایی مجوز دریافت وجه نیست.

1. از بخش «فروشندگان و شباهای تأییدشده» پروندهٔ مقصد را پیگیری کنید؛ سپس در «کلید واقعی فروشگاه» کلید اختصاصی sp_live_ بسازید.
2. کلید فقط در تنظیمات خصوصی سرور فروشگاه نگهداری شود؛ هرگز در کد مرورگر، آدرس صفحه یا پیام پشتیبانی قرار نگیرد. نسخه‌های مستقل دریافت واقعی، کلید را فقط از تنظیمات خصوصی سرور می‌خوانند.
3. مبلغ و شناسهٔ سفارش از اطلاعات ذخیره‌شدهٔ فروشگاه خوانده می‌شوند. درخواست ثابت و کلید تکرارناپذیری باید پیش از تماس با API ذخیره شوند.
4. برگشت مرورگر اثبات پرداخت نیست؛ سرور فروشگاه شناسه، مبلغ، ارز و تأیید پرداخت را مستقل بررسی می‌کند. نتیجهٔ نامشخص به معنی شکست نیست؛ سفارش تازه و برداشت دوباره نسازید.

API این مسیر /api/ipg/merchant/payments است، نه API آموزشی /api/v1/payments. نسخهٔ نخست تمام مبلغ را به یک مقصد تأییدشده تخصیص می‌دهد؛ برداشت خودکار، استرداد تسویه‌شده و کارمزد تجاری خودکار ندارد. پذیرش درخواست تسویه هم اثبات واریز قطعی به حساب بانکی نیست.

افزونهٔ مستقل ووکامرس ۰.۱.۰ فقط برای تسویه‌حساب کلاسیک و ذخیره‌سازی قدیمی سفارش (CPT)، بدون HPOS و کش بیرونی است؛ در حالت‌های پشتیبانی‌نشده پرداخت را متوقف می‌کند. آزمون نصب روی WordPress و WooCommerce واقعی و یک پرداخت محدودِ مجاز هنوز لازم است. تا تکمیل این آزمون‌ها روی فروشگاه دارای فروش واقعی فعال نشود.

OpenCart ۳؛ نامزد مستقل اتصال واقعی

بستهٔ ۰.۱.۰ از افزونهٔ آموزشی قدیمی جداست و به‌صورت پیش‌فرض خاموش می‌ماند. فقط برای OpenCart ۳ در نظر گرفته شده است، نه OpenCart ۴. کلید مستقل فروشگاه، مقصد تأییدشده و شرایط پذیرندگی همچنان لازم‌اند؛ دریافت ZIP یا نصب کد، پرداخت واقعی را فعال نمی‌کند.

این نسخه نامزد بررسی فنی است: نصب و ارتقا روی میزبان بومی OpenCart، ذخیره‌سازی و قفل‌های واقعی دیتابیس، بازگشت مشتری و یک پرداخت محدودِ مجاز هنوز باید جداگانه آزمون شوند. تا تکمیل این آزمون‌ها روی فروشگاه دارای فروش واقعی فعال نشود. سفارش‌ها و کلیدهای محیط آموزشی به این روش تبدیل نمی‌شوند.

مبلغ و اقلام از سفارش ذخیره‌شده خوانده می‌شوند؛ بازگشت مشتری اثبات موفقیت نیست. نتیجهٔ نامشخص نباید با سفارش یا کلید تازه دوباره پرداخت شود. این بسته برداشت خودکار، استرداد تسویه‌شده یا واریز دلخواه بانکی ارائه نمی‌کند؛ محدودیت‌های دقیق در راهنمای همراه آمده‌اند.

۱. کلید اختصاصی بساز

در پنل توسعه‌دهندگان یک کلید بساز. آن را فقط روی سرور ذخیره کن؛ کلید کامل یک بار نمایش داده می‌شود. کلید را می‌توانی در همان پنل لغو کنی.

۲. یک پرداخت بساز

برای هر سفارش یک Idempotency-Key ثابت بفرست. تکرار همان درخواست همان پرداخت را برمی‌گرداند؛ تغییر داده با همان کلید خطای 409 دارد.

POST /api/v1/payments
Authorization: Bearer sp_test_YOUR_KEY
Content-Type: application/json
Idempotency-Key: order-1042

{
  "order_id": "1042",
  "title": "Order 1042",
  "amount": 1250000,
  "currency": "IRR",
  "return_url": "https://your-shop.example/orders/1042"
}

پاسخ شامل id، status، amount، expires_at و checkout_url است. خریدار را به checkout_url هدایت کن. پیش از پرداخت، مبلغ سفارش را روی سرور خودت محاسبه کن.

۳. نتیجه را مستقل تأیید کن

بازگشت مرورگر یا پارامتر URL اثبات پرداخت نیست. از سرور فروشگاه، وضعیت را با کلید خودت بخوان و شناسه سفارش، مبلغ و ارز را با سفارش ذخیره‌شده تطبیق بده. تکمیل سفارش باید در فروشگاه هم تکرارناپذیر باشد.

GET /api/v1/payments/PAYMENT_ID
Authorization: Bearer sp_test_YOUR_KEY

POST /api/v1/payments/PAYMENT_ID/verify
Authorization: Bearer sp_test_YOUR_KEY
Content-Type: application/json

{}

verify پاسخ ذخیره‌شده ارائه‌دهنده آموزشی را بررسی می‌کند. تا قبل از نتیجه قطعی، verification_pending برمی‌گردد. سفارش پرداخت‌شده دوباره اعتبار نمی‌گیرد.

استرداد، ادامه پرداخت و گزارش

POST /api/v1/payments/PAYMENT_ID/refund
Authorization: Bearer sp_test_YOUR_KEY
Idempotency-Key: refund-order-1042-1
Content-Type: application/json

{ "amount": 100000 }

POST /api/v1/payments/PAYMENT_ID/recover
Authorization: Bearer sp_test_YOUR_KEY
Content-Type: application/json

{}

GET /api/v1/payments?page=1
Authorization: Bearer sp_test_YOUR_KEY

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

رویداد و وب‌هوک

رویداد نتیجه پرداخت همراه با تراکنش مالی در outbox ثبت می‌شود. worker آن را امضا می‌کند؛ در حالت پیش‌فرض گیرنده محلی آموزشی با event_id از ثبت دوباره جلوگیری می‌کند. ارسال به نشانی HTTPS پذیرنده فقط پس از تنظیم وب‌هوک و فعال‌سازی تحویل خارجی روی سرور انجام می‌شود. تا پیش از تأیید عملیاتی آن، وضعیت پرداخت را از API نیز استعلام کن.

{
  "id": "evt_…",
  "type": "payment.paid",
  "payment_id": "pay_…",
  "mode": "sandbox",
  "created_at": "…"
}

خطاهای قابل مدیریت

مثال کد اتصال PHP

مثالِ مستقل PHP با cURL، ساخت پرداخت و استعلام/تأیید سمت سرور. کلید آموزشی را در متغیر محیطی نگه دار؛ آن را در فایل یا مرورگر قرار نده. فایل را با پسوند php ذخیره کن و با PHP 8.1 یا جدیدتر در خط فرمان اجرا کن. دستورهای مثال داخل فایل هستند.

راهنمای اتصال Laravel

از HTTP Client در سرویس سمت سرور استفاده کن. کلید را در متغیر محیطی قرار بده و پس از بازگشت مشتری، شناسه سفارش، مبلغ و ارز را با پاسخ API تطبیق بده. این کد یک مثالِ اتصال است، نه پکیج رسمی Laravel.

use Illuminate\Support\Facades\Http;

// config/services.php: 'sayapay' => ['key' => env('SAYAPAY_TEST_KEY')]
$payment = Http::withToken(config('services.sayapay.key'))
    ->withHeaders(['Idempotency-Key' => 'order-1042'])
    ->post('https://saya-pay.com/api/v1/payments', [
        'order_id' => '1042',
        'title' => 'Order 1042',
        'amount' => 1250000, // IRR
        'currency' => 'IRR',
        'return_url' => 'https://your-shop.example/orders/1042',
    ])->throw()->json();

// Redirect the buyer to $payment['checkout_url'].
// On return, query/verify on the server; never trust the browser URL.

افزونهٔ ووکامرس

بستهٔ نصب نسخهٔ ۰.۳.۰ برای فروشگاه آموزشی آماده است. پس از بارگذاری ZIP در وردپرس، از تنظیمات پرداخت ووکامرس نشانی API و کلید sp_test را وارد کن. سفارش‌های با نتیجهٔ نامشخص در وضعیت انتظار می‌مانند و حداکثر ۱۲ بار به‌صورت پس‌زمینه استعلام می‌شوند؛ برای فروش واقعی مناسب نیست. آزمون اجرایی این نسخه در WordPress و WooCommerce هنوز تکمیل نشده است.

بسته‌های اتصال آموزشی

فقط کلید sp_test_، مبلغ صحیح ریالی و HTTPS پذیرفته می‌شود. در همه اتصال‌ها، نتیجه از API سرور خوانده و با سفارش تطبیق داده می‌شود. این بسته‌ها نامزد آزمون نصب روی میزبان واقعی‌اند، نه درگاه بانکی فعال. نصب روی فروشگاه آموزشی انجام شود؛ تمدید خودکار و برداشت از حساب ندارند.

• دانلود EDD ۰.۱.۰ — Test Mode اجباری؛ تنظیمات Payments.
• دانلود OpenCart ۰.۱.۰ — Extension Installer؛ نسخه ۳ و نرخ ارز ۱.
• دانلود WHMCS ۰.۱.۰ — نصب modules و جدول install.sql روی محیط آزمایش.
• دانلود RCP ۰.۱.۰ — تنظیمات Sayapay RCP؛ فقط عضویت یک‌باره.
• دانلود پل توسعه Virtual Freer — برای برنامه‌نویس؛ افزونهٔ نصب‌پذیر نیست.

نسخه‌های نخست EDD، RCP، WHMCS و OpenCart هنوز وب‌هوک و پیگیری خودکار سفارش معلق ندارند. تا آزمون کامل و تکمیل این مسیرها، برای تولید استفاده نشوند.

راهنمای نصب، مرزها و معیار آزمون همه اتصال‌ها · نسخه، اندازه و SHA-256 بسته‌ها · راهنمای پذیرنده و سازمان

لوگو و نشان سایاپی

برای معرفی روش پرداخت در فروشگاه آموزشی، لوگوی رسمی PNG سایاپی را دریافت کن. استفاده از نشان به معنی فعال‌بودن پرداخت واقعی نیست.