SDK و فریم‌ورک·PHP SDK

کتابخانهٔ PHP شی‌پی

کتابخانهٔ رسمی PHP شی‌پی برای سایت‌های اختصاصی و هر سامانهٔ PHP. متد confirm مبلغ را تطبیق می‌دهد، پرداخت موفق را verify می‌کند و نتیجه را در سه حالت «پرداخت‌شده»، «در انتظار» و «ناموفق» برمی‌گرداند. همین کلاینت داخل همهٔ ماژول‌های PHP شی‌پی (ووکامرس، WHMCS، اپن‌کارت و…) استفاده می‌شود.

استرداد از داخل پنل
وب‌هوک امضاشده
وضعیت «در انتظار» درست
تومان و ریال
حالت آزمایشی با sk_test_
دکمهٔ تست اتصال

نصب

۱
با Composer نصب کنید: composer require sheypay/sheypay-php. تا پیش از انتشار روی Packagist، zip را در پوشه‌ای مثل packages/sheypay-php باز کنید و آن را به‌شکل path repository در composer.json اضافه کنید.
۲
بدون Composer هم کار می‌کند: فایل src/SheyPay.php را require کنید.
۳
کلید API را از پنل شی‌پی بگیرید و در متغیر محیطی SHEYPAY_KEY بگذارید (برای آزمایش sk_test_).
۴
با createPayment پرداخت بسازید، شناسهٔ پرداخت را روی سفارش ذخیره کنید و مشتری را به payment_url بفرستید.
۵
در آدرس بازگشت confirm را با شناسهٔ ذخیره‌شده و مبلغ سفارش صدا بزنید. نمونهٔ کامل در پوشهٔ examples است.

تا پیش از انتشار روی Packagist، فایل zip را به‌شکل path repository در Composer نصب کنید.

تنظیمات

new SheyPay\Client($apiKey, $baseUrl, $timeout, $clientInfo): کلید API الزامی است. آدرس پیش‌فرض https://api.sheypay.ir و مهلت ۲۰ ثانیه است.
Idempotency-Key: آرگومان آخر createPayment و refund. برای هر تلاش یک کلید ثابت بدهید تا تکرار درخواست، پرداخت دوم نسازد.
Client::toRial($amount, 'IRT'): تبدیل تومان به ریال. API همیشه با ریال کار می‌کند.
Client::parseWebhook($body, $signature, $secret): امضای هدر SheyPay-Signature را بررسی و رویداد را برمی‌گرداند.

تست در محیط آزمایشی

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

با کلید sk_test_ پرداخت بسازید؛ در صفحهٔ بانک آزمایشی نتیجهٔ دلخواه را انتخاب کنید.
در آدرس بازگشت هر سه نتیجهٔ paid، pending و failed را امتحان کنید.
از پنل شی‌پی › وب‌هوک‌ها «ارسال رویداد آزمایشی» را بزنید و ببینید parseWebhook امضا را می‌پذیرد.

گرفتن کلید آزمایشی راهنمای محیط آزمایشی

مشکلات رایج

خطای invalid_api_key می‌گیرم.

کلید باید کامل و با sk_test_ یا sk_live_ شروع شود. فاصلهٔ اضافه در متغیر محیطی را حذف کنید.

confirm نتیجهٔ failed با پیام «مبلغ پرداخت با مبلغ سفارش یکسان نیست» می‌دهد.

مبلغ verify باید دقیقاً همان مبلغ ریالی createPayment باشد. اگر قیمت را به تومان دارید از toRial استفاده کنید.

خطای callback_domain_mismatch.

آدرس بازگشت باید روی دامنهٔ تأییدشدهٔ درگاه باشد (در حالت آزمایشی localhost هم پذیرفته می‌شود).

curl روی سرور نیست.

کلاینت خودکار از stream‌های PHP استفاده می‌کند؛ allow_url_fopen باید روشن باشد.

تغییرات

نسخهٔ ۱.۱.۰
۱۴۰۵/۰۷/۱۸
- متد confirm: تطبیق مبلغ، verify و نتیجهٔ paid/pending/failed در یک فراخوانی.
- متدهای me، listPayments، findByReference، reverse و events.
- parseWebhook، toRial و normalizeMobile؛ حذف خودکار موبایل و ایمیل نامعتبر.
- هدر SheyPay-Client، پشتیبانی بدون curl و composer.json.
نسخهٔ ۱.۰.۰
۱۴۰۵/۰۶/۲۹
- نسخهٔ اول: createPayment، getPayment، verify، refund و verifyWebhook.

ماژول‌های دیگر در «SDK و فریم‌ورک»

همهٔ ماژول‌ها

اولین رسیدتان را امروز صادر کنید

ثبت‌نام با شمارهٔ موبایل انجام می‌شود و تا تأیید مدارک، همه‌چیز را در محیط آزمایشی امتحان می‌کنید.

هزینهٔ ثبت‌نامندارد

کارمزدفقط تراکنش موفق

دریافت درگاه پرداخت گفتگو با کارشناس