13 KiB
13 KiB
مشخصات درس‌نامه: اتصال درگاه پرداخت آنلاین ایرانی با زرین‌پال در حالت سندباکس (ZarinPal Sandbox)
- شناسه در سیلابس:
L10.7 - فصل: فصل ۱۰: اتصال سرویس‌های بیرونی (Ch 10)
- نوع محتوا: 📘 درس‌نامه متنی
- زمان تقریبی مطالعه: ۲۰ دقیقه
- پیش‌نیازهای مستقیم:
L10.6(ارائه‌دهندگان احراز هویت خارجی)
۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
- درک کند (Understand): چرخه استاندارد ۲ مرحله‌ای پرداخت آنلاین شاپرک (درخواست پرداخت
\rightarrowهدایت به درگاه\rightarrowتایید نهایی تراکنش Verification) را به زبان ساده شرح دهد. - تحلیل/ارزیابی کند (Evaluate): ارزش فوق‌العاده محیط شبیه‌ساز (Sandbox) زرین‌پال را در تست تراکنش‌های مالی بدون نیاز به اینماد، کارت بانکی واقعی یا ریسک کسر وجه درک کند.
- به‌کار ببندد (Apply): قابلیت «رزرو جلسه مشاوره تخصصی ۱ ساعته» را در پورتفولیو با وب‌سرویس زرین‌پال پیاده‌سازی کرده و وضعیت پرداخت را در دیتابیس Supabase ذخیره نماید.
- ایجاد کند (Create): یک روت اعتبارسنجی (Verify Route Handler) امن بسازد که در برابر حمله پرداخت جعلی (Fake Query Attack) و پرداخت تکراری مقاوم باشد.
۲. محدوده و مرزهای محتوا (Scope & Boundaries)
آنچه باید پوشش داده شود (In-Scope):
- لحظه بلوغ تجاری محصول: تبدیل بازدیدکننده به خریدار:
- چرا توانایی دریافت وجه آنلاین، مهم‌ترین وجه تمایز یک پروژه جدی تجاری از یک تمرین دانشجویی است.
- کالبدشکافی چرخه ۲ مرحله‌ای پرداخت آنلاین در ایران (شاپرک):
- مرحله ۱ (Payment Request): ارسال مبلغ، توضیحات، ایمیل، موبایل و آدرس بازگشت به زرین‌پال
\rightarrowدریافت کد رهگیری اختصاصی (Authority). - مرحله ۲ (Redirect): هدایت مرورگر کاربر به صفحه امن درگاه پرداخت زرین‌پال با شناسه Authority.
- مرحله ۳ (Callback): بازگشت کاربر از بانک به آدرس سایت شما با پارامترهای
AuthorityوStatus=OK/NOK. - مرحله ۴ (Payment Verification): ارسال مجدد Authority و مبلغ از سمت سرور به زرین‌پال برای استعلام قطعی و دریافت شماره پیگیری (
RefID).
- مرحله ۱ (Payment Request): ارسال مبلغ، توضیحات، ایمیل، موبایل و آدرس بازگشت به زرین‌پال
- محیط سندباکس (ZarinPal Sandbox)؛ آزمایشگاه امن توسعه‌دهندگان:
- استفاده از مرچنت کد تستی بدون نیاز به احراز هویت بانکی، سفته، یا نماد اعتماد الکترونیکی (اینماد).
- امکان شبیه‌سازی هر دو حالت «تراکنش موفق» و «تراکنش ناموفق/انصراف کاربر».
- پیاده‌سازی ماژول پرداخت در پورتفولیوی شخصی:
- فیچر: «رزرو وقت مشاوره آنلاین» در صفحه پورتفولیو.
- کاربر مشخصات و زمان را انتخاب می‌کند
\rightarrowدکمه «پرداخت و ثبت نهایی» را می‌زند\rightarrowبه درگاه منتقل می‌شود\rightarrowپس از پرداخت موفق، رکورد رزرو در Supabase وضعیتpaidمی‌گیرد\rightarrowپیامک و ایمیل تایید ارسال می‌شود.
- دستورات چندسکویی برای متغیرهای محیطی زرین‌پال:
- تنظیم
ZARINPAL_MERCHANT_IDوNEXT_PUBLIC_APP_URLدر سه سیستم‌عامل.
- تنظیم
- کال‌اوت‌های آموزشی و هشدار کوئرا:
- کال‌اوت بنفش (
<details class="violet">): مفهوم تکرارناپذیری (Idempotency) و خطر کلاهبرداری بازگشت جعلی؛ هرگز بدون متد Verify به کاربر خدمات ندهید! - کال‌اوت سبز (
<details class="green">): شبیه‌سازی کارت بانکی تستی در سندباکس بدون کسر حتی یک ریال از حساب شما. - کال‌اوت قرمز (
<details class="red">): تله اشتباه گرفتن ریال و تومان؛ درگاه‌های شاپرک مبالغ را بر حسب ریال یا تومان با دقت بالا می‌خواهند.
- کال‌اوت بنفش (
آنچه نباید وارد آن شویم (Out-of-Scope):
- مراحل قانونی دریافت اینماد و کد مالیاتی (در فصل ۱۲ و چک‌لیست حقوقی بررسی می‌شود).
- پرداخت‌های بین‌المللی با ارز دیجیتال یا کارت‌های اعتباری ویزا/مستر.
۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)
| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
|---|---|---|
| Payment Gateway (IPG) | درگاه پرداخت اینترنتی | واسط نرم‌افزاری امن بانکی که امکان کسر وجه از حساب خریدار و واریز به حساب فروشنده را فراهم می‌کند |
| Merchant ID | شناسه پذیرنده | کد شناسایی ۳۶ کاراکتری یکتای شما نزد شرکت پرداخت برای تفکیک تراکنش‌های کسب‌وکار |
| Authority | شناسه تراکنش شاپرک | رشته کد ۳۶ کاراکتری که برای هر درخواست پرداخت تولید شده و مبنای پیگیری تراکنش است |
| Payment Verification | تایید نهایی پرداخت | استعلام قطعی و رمزنگاری‌شده از درگاه برای اثبات واریز واقعی پول قبل از تحویل کالا یا خدمات |
| RefID | شماره پیگیری بانکی | شماره ارجاع یکتای رسمی شبکه بانکی که روی رسید تراکنش چاپ می‌شود |
| Double Spending | پرداخت تکراری یا جعلی | تلاش خرابکارانه برای تحویل چندباره خدمات با استفاده از یک شناسه تایید شده قدیمی |
۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
راهنمای ایجنت نویسنده: تمام تصاویر باید در پوشهٔ
images/ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:
- تصویر کاور درس:
images/cover.png- موضوع: کارت بانکی نئونی با آیکون تایید سبز در حال لمس درگاه پرداخت دیجیتال زرین‌پال روی لپ‌تاپ پورتفولیو.
- چرخه ۴ مرحله‌ای پرداخت شاپرک با زرین‌پال:
images/zarinpal-payment-flow.png- موضوع: دیاگرام معماری: ۱) درخواست پرداخت سروری
\rightarrow۲) انتقال به درگاه سندباکس\rightarrow۳) بازگشت کاربر\rightarrow۴) تایید سروری (Verify)\rightarrowصدور فاکتور نهایی.
- موضوع: دیاگرام معماری: ۱) درخواست پرداخت سروری
- صفحه شبیه‌ساز پرداخت سندباکس زرین‌پال:
images/zarinpal-sandbox-mock-screen.png- موضوع: اسکرین‌شات از محیط سندباکس زرین‌پال با دکمه‌های «پرداخت موفق» و «انصراف از پرداخت» برای تست.
- رسید تراکنش موفق در پورتفولیو:
images/payment-success-receipt-card.png- موضوع: کارت رسید مدرن در سایت با کد پیگیری RefID، مبلغ، تاریخ، و دکمه دانلود جزئیات جلسه مشاوره.
۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (README.md)
- تیتر اصلی:
# اتصال درگاه پرداخت آنلاین ایرانی با زرین‌پال در حالت سندباکس (ZarinPal Sandbox) - مقدمه: هیجان‌انگیزترین لحظه برای یک خالق محصول: وقتی اولین پیامک «حساب شما شارژ شد» از راه می‌رسد!
- جدول کاور درس
- استعاره صندوقدار فروشگاه و دستگاه پوز:
- شما فاکتور صادر می‌کنید، مشتری کارت می‌کشد، دستگاه بوق تایید می‌زند، و سپس شما کالا را تحویل می‌دهید.
- معماری پرداخت در وب مدرن ایران (پروتکل دوگانه Request و Verify):
- چرا نمی‌توان تنها به بازگشت کاربر به آدرس سایت اعتماد کرد؟
- فعال‌سازی آزمایشگاه سندباکس زرین‌پال (بدون نیاز به اینماد):
- استفاده از مرچنت تستی ۳۶ کاراکتری و آدرس اندپوینت سندباکس:
https://sandbox.zarinpal.com/pg/v4/payment/request.json
- استفاده از مرچنت تستی ۳۶ کاراکتری و آدرس اندپوینت سندباکس:
- کدنویسی ماژول پرداخت
services/payment.tsدر Next.js:- تابع ایجاد درخواست پرداخت (
createPaymentRequest). - تابع اعتبارسنجی نهایی پرداخت (
verifyPayment).
- تابع ایجاد درخواست پرداخت (
- جعبه پرامپت طلایی: ساخت صفحه پرداخت و رزرو مشاوره با ایجنت:
- پرامپت دقیق:
«من ماژول پرداخت
services/payment.tsرا برای زرین‌پال دارم. لطفاً یک بخش جدید در صفحه پورتفولیو با عنوان "رزرو جلسه مشاوره تخصصی" اضافه کن. کاربر با انتخاب تاریخ و زدن دکمه پرداخت، به سرور اکشن متصل شود، به درگاه زرین‌پال سندباکس هدایت گردد، و پس از بازگشت به صفحه/payment/callback، در صورت تایید موفقیت، رسید پرداخت با شماره پیگیری RefID نمایش داده شده و وضعیت رزرو در دیتابیس به paid تغییر کند.»
- پرامپت دقیق:
- دستورات چندسکویی برای تنظیم متغیرهای محیطی پرداخت:
- منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
- Windows (PowerShell):
Add-Content .env.local "`nZARINPAL_MERCHANT_ID=00000000-0000-0000-0000-000000000000`nNEXT_PUBLIC_APP_URL=http://localhost:3000" - macOS (Terminal):
echo -e "\nZARINPAL_MERCHANT_ID=00000000-0000-0000-0000-000000000000\nNEXT_PUBLIC_APP_URL=http://localhost:3000" >> .env.local - Linux (Bash):
echo -e "\nZARINPAL_MERCHANT_ID=00000000-0000-0000-0000-000000000000\nNEXT_PUBLIC_APP_URL=http://localhost:3000" >> .env.local
- Windows (PowerShell):
- منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
- باکس نکته امنیتی Quera (
<details class="violet">): تله جعل پارامتر URL؛ اگر کسی آدرس را دستی بهStatus=OKتغییر دهد، تابعverifyPaymentمتوجه شده و تراکنش فاقد اعتبار تلقی می‌شود. - باکس هشدار Quera (
<details class="red">): واحد پول! مبالغ زرین‌پال به تومان است، اما همیشه مستندات رسمی را چک کنید تا مشتری ده برابر مبلغ واقعی پرداخت نکند! - باکس رضایت‌بخش Quera (
<details class="green">): کلیک روی دکمه پرداخت سندباکس و مشاهده صفحه تراکنش موفق بدون نیاز به کارت واقعی. - جمع‌بندی درس‌نامه: تسلط بر دریافت پول آنلاین؛ ورود به بخش هیجان‌انگیز و پایانی فصل: تزریق هوش مصنوعی به پورتفولیو با API در درس بعدی.
۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
- چرخه ۴ مرحله‌ای پرداخت اینترنتی شاپرک با نمودار و زبان شفاف تبیین گردد.
- نحوه اتصال به سندباکس زرین‌پال با مرچنت تستی به صورت کاربردی آموزش داده شود.
- روت تایید پرداخت (Payment Verification) با تدابیر امنیتی جلوگیری از تقلب پیاده شود.
- سناریوی رزرو مشاوره پورتفولیو به صورت یکپارچه با پیامک و دیتابیس ارائه گردد.