کتابخانهٔ Node.js و TypeScript شی‌پی
کتابخانهٔ رسمی شی‌پی برای Node.js، Next.js، Express و هر محیطی که fetch دارد. همهٔ پاسخ‌های API تایپ‌شده‌اند و متد confirm نتیجهٔ پرداخت را در سه حالت «پرداخت‌شده»، «در انتظار» و «ناموفق» برمی‌گرداند. ابزار webhooks امضای هدر SheyPay-Signature را با مقایسهٔ زمان‌ثابت بررسی می‌کند.
- تایپ‌های کامل
- استرداد از داخل پنل
- وب‌هوک امضاشده
- وضعیت «در انتظار» درست
- تومان و ریال
- حالت آزمایشی با sk_test_
- دکمهٔ تست اتصال
نصب
- ۱
با npm نصب کنید: npm i @
sheypay/node.تا پیش از انتشار روی npm، zip را باز کنید و با npm i./sheypay-nodeنصب کنید. - ۲
کلید API را در متغیر محیطی SHEYPAY_KEY بگذارید (برای آزمایش
sk_test_). - ۳
با createPayment پرداخت بسازید، payment.id را روی سفارش ذخیره کنید و مشتری را به payment_url بفرستید.
- ۴
در مسیر بازگشت confirm را با شناسهٔ ذخیره‌شده و مبلغ سفارش صدا بزنید.
- ۵
مسیر وب‌هوک را بسازید و با webhooks.constructEvent بدنهٔ خام را بررسی کنید. نمونهٔ Express و Next.js در پوشهٔ examples است.
- تا پیش از انتشار روی npm، از فایل zip نصب کنید.
تنظیمات
- new SheyPay(apiKey, options)
- گزینه‌ها: baseUrl، timeout (میلی‌ثانیه، پیش‌فرض ۲۰٬۰۰۰)، clientInfo و fetch سفارشی.
- Idempotency-Key
- آرگومان دوم createPayment و چهارم refund؛ برای هر تلاش یک مقدار ثابت بدهید.
- toRial(amount, 'IRT')
- تبدیل تومان به ریال.
- webhooks.constructEvent(body, signature, secret)
- بررسی امضا و پارس رویداد؛ بدنه باید خام باشد.
تست در محیط آزمایشی
با کلید sk_test_ پول واقعی جابه‌جا نمی‌شود و در صفحهٔ بانک آزمایشی نتیجه را خودتان انتخاب می‌کنید.
- با کلید
sk_test_پرداخت بسازید و در بانک آزمایشی نتیجه را انتخاب کنید. - هر سه نتیجهٔ paid، pending و failed را در مسیر بازگشت امتحان کنید.
- از پنل شی‌پی رویداد آزمایشی وب‌هوک بفرستید و پاسخ ۲۰۰ مسیر را ببینید.
مشکلات رایج
constructEvent همیشه خطای امضا می‌دهد.
بدنه را پیش از JSON.parse بدهید؛ در Express از express.raw و در Next.js از req.text() استفاده کنید.
fetch is not defined
Node.js 18 یا بالاتر لازم است، یا یک پیاده‌سازی fetch را در گزینهٔ fetch بدهید.
خطای callback_domain_mismatch
آدرس بازگشت باید روی دامنهٔ تأییدشدهٔ درگاه باشد؛ در حالت آزمایشی localhost هم پذیرفته می‌شود.
تغییرات
نسخهٔ ۱.۰.۰
- نسخهٔ اول: همهٔ متدهای API پرداخت، confirm، تایپ‌های کامل و ابزار وب‌هوک.
اولین رسیدتان را امروز صادر کنید
ثبت‌نام با شمارهٔ موبایل انجام می‌شود و تا تأیید مدارک، همه‌چیز را در محیط آزمایشی امتحان می‌کنید.