پیاده‌سازی درگاه پرداخت زرین‌پال با هوش مصنوعی، بدون تحویل دوباره

دستیار هوش مصنوعی‌تان در چند دقیقه صفحهٔ پرداخت فروشگاه را به زرین‌پال وصل کرده و همه‌چیز در تست اول درست به نظر می‌رسد. ولی وقتی کد را با دقت بخوانید، می‌بینید سفارش را همین که Status=OK در نشانی بازگشت آمد «پرداخت‌شده» می‌کند، با هر رفرش صفحهٔ بازگشت سفارش را یک بار دیگر تحویل می‌دهد و مبلغ تومانی را جایی فرستاده که ریال می‌خواهد؛ یعنی ده برابر کمتر پول می‌گیرید. پیاده‌سازی درگاه پرداخت زرین‌پال با هوش مصنوعی سریع است، به شرطی که دستیار جریان درست را بداند.

مهارت «اتصال به درگاه پرداخت» همین جریان را به دستیار یاد می‌دهد: تأیید فقط سمت سرور و با مبلغ پایگاه داده، رفتار درست با کدهای ۱۰۰ و ۱۰۱، یک به‌روزرسانی شرطی که سفارش را فقط یک بار تحویل می‌دهد، مبلغ ریالی و عدد صحیح، تست در sandbox و یک کار زمان‌بندی‌شده برای پرداخت‌هایی که وسط راه ماندند. این مهارت یک فایل دستورالعمل است، نه سرور؛ به درگاه وصل نمی‌شود و فقط روش کار را به دستیار می‌دهد.

چرا کد درگاه پرداختی که هوش مصنوعی می‌نویسد خطرناک است؟

کد پرداخت جایی است که «تقریباً درست» کافی نیست. سه اشتباهی که صفحهٔ مهارت نام می‌برد، اتفاقاً همان‌هایی‌اند که در تست ساده دیده نمی‌شوند:

• اعتماد به پارامتر بازگشت: نشانی بازگشت از درگاه را هر کسی می‌تواند باز کند. اگر کد با دیدن Status=OK سفارش را پرداخت‌شده بزند، یک نشانی دست‌ساز کافی است تا کالا بی‌پول تحویل شود.
• تحویل دوباره: کاربر صفحهٔ بازگشت را رفرش می‌کند یا دو بار کلیک می‌کند و سفارش دو بار تحویل می‌شود؛ دو بار اعتبار، دو ارسال یا دو لایسنس.
• قاطی شدن ریال و تومان: هر تومان ده ریال است. مبلغ تومانی که جای ریال برود، یعنی مشتری یک‌دهم قیمت را می‌پردازد.

دستیار این‌ها را از سر بی‌دقتی نمی‌نویسد؛ نمونه‌کدهای ساده‌ای که از آن‌ها یاد گرفته معمولاً همین شکل را دارند. مهارت قاعده‌ها را صریح جلوی چشمش می‌گذارد.

پیاده‌سازی درگاه پرداخت زرین‌پال سمت سرور، قدم‌به‌قدم

جریانی که مهارت به دستیار یاد می‌دهد، همه‌اش سمت سرور است:

1. سفارش در پایگاه داده با وضعیت pending ساخته می‌شود و مبلغش را سرور به ریال و عدد صحیح حساب می‌کند.
2. سرور از درگاه درخواست پرداخت می‌کند و شناسهٔ برگشتی (authority در زرین‌پال، trackId در زیبال) را با ایندکس یکتا روی سفارش ذخیره می‌کند.
3. کاربر با ریدایرکت ۳۰۲ به صفحهٔ پرداخت درگاه می‌رود.
4. کاربر به نشانی بازگشت (callback) برمی‌گردد و سرور سفارش را با همان شناسهٔ ذخیره‌شده پیدا می‌کند. مبلغ و وضعیت هیچ‌وقت از پارامترهای نشانی خوانده نمی‌شود.
5. سرور مستقیم از درگاه تأیید (verify) می‌گیرد، با مبلغی که در پایگاه داده دارد.
6. سفارش با یک دستور UPDATE شرطی پرداخت‌شده می‌شود و تحویل فقط وقتی انجام می‌شود که این دستور واقعاً یک ردیف را تغییر داده باشد.

قلب ماجرا همان قدم آخر است. شکلش در مهارت چنین است:

UPDATE orders SET status = 'paid', ref_id = $1, paid_at = now()
WHERE id = $2 AND status = 'pending';

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

اگر کاربر صفحهٔ بازگشت را رفرش کند چه می‌شود؟

زرین‌پال به اولین تأیید کد ۱۰۰ می‌دهد و به تأییدهای بعدی کد ۱۰۱، یعنی «قبلاً تأیید شده». هر دو موفق‌اند و نباید یکی را خطا حساب کرد. مشکل وقتی است که کد با دیدن هر کدام سفارش را تحویل بدهد. UPDATE شرطی بالا جلوی همین را می‌گیرد: دو درخواست هم‌زمان هر دو تأیید می‌گیرند، ولی فقط یکی ردیف را از pending بیرون می‌آورد.

کدهایی که دستیار با این مهارت باید درست تفسیر کند:

بقیهٔ کدها (مثل -9 برای خطای اعتبارسنجی ورودی، از جمله توضیح بلندتر از ۵۰۰ نویسه) در جدول خطای خود مهارت آمده است. برای معنی هر کد از روی مستندات زنده، مستندات زرین‌پال با هوش مصنوعی راه سریع‌تری است.

ریال یا تومان: مبلغ را چطور به درگاه بفرستیم؟

قاعدهٔ مهارت ساده است: مبلغ همیشه عدد صحیح و به ریال ذخیره و محاسبه می‌شود، هیچ‌وقت عدد اعشاری، و تبدیل به تومان فقط برای نمایش به کاربر است.

• زرین‌پال: فیلد اختیاری currency دو مقدار IRR (ریال) و IRT (تومان) دارد. مهارت می‌گوید IRR را صریح بفرستید و در تأیید هم همان مبلغ ریالی را بدهید.
• زیبال: فقط ریال می‌گیرد و مبلغ باید بیشتر از ۱٬۰۰۰ ریال باشد؛ کمتر از آن خطای ۱۰۵ می‌گیرد.

یکی از تست‌های مهارت دقیقاً همین است: سفارش ۱۰٬۰۰۰ تومانی باید با مبلغ ۱۰۰٬۰۰۰ ریال به درگاه برسد.

وقتی تأیید وسط کار قطع می‌شود

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

• اگر تأیید به خطای شبکه خورد، سفارش pending می‌ماند و بعداً دوباره تأیید می‌شود. تأیید دوباره بی‌خطر است، چون زرین‌پال ۱۰۱ و زیبال ۲۰۱ برمی‌گرداند.
• یک کار زمان‌بندی‌شده هر چند دقیقه سفارش‌های معلق را با inquiry.json یا فهرست پرداخت‌های تأییدنشدهٔ زرین‌پال (unVerified.json) بررسی می‌کند و برای آن‌ها تأیید می‌گیرد.
• سفارش‌هایی که پرداخت‌شده‌اند ولی هنوز fulfilled_at ندارند، دوباره تحویل داده می‌شوند. برای همین تحویل باید با شناسهٔ سفارش یکتا باشد، تا تکرارش چیزی را دو بار نسازد.
• روزی یک بار گزارش تسویهٔ پنل درگاه با سفارش‌های پرداخت‌شدهٔ شما مقایسه می‌شود.

این مهم است چون در زرین‌پال اگر تأیید خودکار خاموش باشد و در مهلت مجاز تأیید نکنید، پول به خریدار برمی‌گردد؛ زیبال هم پرداخت تأییدنشده را بعد از ۲۰ دقیقه برمی‌گرداند.

درگاه پرداخت زیبال هم پوشش داده می‌شود؟

بله، به‌عنوان جایگزین. مهارت نشانی‌های زیبال، مرچنت آزمایشی zibal و کدهای تأیید آن را دارد: ۱۰۰ موفق، ۲۰۱ قبلاً تأیید شده، ۲۰۲ پرداخت‌نشده و ۲۰۳ شناسهٔ نامعتبر. دو فرق مهم را هم گوشزد می‌کند. تأیید زیبال مبلغ نمی‌گیرد، پس کد باید مبلغ برگشتی را خودش با مبلغ سفارش مقایسه کند. صفحهٔ پرداخت زیبال هم سرآیند Referer هم‌خوان با سایت ثبت‌شده می‌خواهد؛ اپلیکیشن‌ها و ربات‌ها باید آن را خودشان بفرستند.

برای پی‌پینگ، IDPay یا درگاه مستقیم بانک‌ها دستور مشخصی ندارد. جریان کلی و فهرست امنیتی آنجا هم به کار می‌آید، ولی جزئیات API را از مستندات همان درگاه بگیرید.

از دستیار چه بخواهید و چه تحویل بگیرید

بعد از نصب، معمولاً لازم نیست اسم مهارت را بیاورید؛ دستیار وقتی کار به پرداخت ایرانی برسد سراغش می‌رود، و اگر نرفت، صریح بگویید از مهارت اتصال به درگاه پرداخت کمک بگیرد. چند نمونه درخواست:

• «پرداخت زرین‌پال را به فروشگاه Express من اضافه کن؛ سفارش‌ها در Postgres است.»
• «این کد بازگشت از درگاه را از نظر امنیت و تحویل دوباره بازبینی کن.»
• «برای اشتراک ماهانهٔ سایت جنگو، درخواست و تأیید زیبال را در Python بنویس.»

جوابی که باید انتظار داشته باشید، شکلی شبیه این دارد: ستون‌های جدول سفارش (وضعیت، مبلغ ریالی، شناسهٔ درگاه با ایندکس یکتا، ref_id، fulfilled_at)، یک تابع شروع پرداخت، یک تابع بازگشت که فقط با تأیید سمت سرور جلو می‌رود، تابع تحویل یکتا و یادداشتی برای کار زمان‌بندی‌شده. نمونه‌کدهای خود مهارت به Node.js (با fetch و مهلت ۱۵ ثانیه) و Python (با requests) است و شناسهٔ پذیرنده را از متغیر محیطی ZARINPAL_MERCHANT_ID می‌خواند. توابع پایگاه داده در این نمونه‌ها جای‌نگه‌دارند و پیاده‌سازی‌شان با شماست.

تست درگاه در sandbox پیش از انتشار

زرین‌پال محیط آزمایشی دارد: همان مسیرها روی sandbox.zarinpal.com، هر UUID به‌جای شناسهٔ پذیرنده قبول می‌شود و شناسهٔ پرداخت‌های آزمایشی با S شروع می‌شود. در نمونه‌کدهای مهارت، متغیر ZARINPAL_SANDBOX=1 همین محیط را روشن می‌کند. فهرست تست مهارت هشت حالت دارد که پیش از انتشار ارزش یک بار اجرا را دارند:

1. مسیر کامل در sandbox: پرداخت، بازگشت، تأیید ۱۰۰ و تحویل یک‌باره
2. رفرش صفحهٔ بازگشت: تأیید ۱۰۱ و بدون تحویل دوم
3. انصراف در صفحهٔ درگاه: سفارش پرداخت‌نشده می‌ماند
4. بازگشت جعلی (Status=OK) با authority تصادفی یا authority پرداخت کس دیگر: رد می‌شود
5. تأیید با مبلغ دیگر: خطای -50 و سفارش پرداخت‌نشده
6. قطع شدن درگاه هنگام تأیید: سفارش معلق می‌ماند و کار زمان‌بندی‌شده بعداً درستش می‌کند
7. از کار افتادن سرور بعد از پرداخت‌شده زدن: کار زمان‌بندی‌شده سفارش را یک بار تحویل می‌دهد
8. سفارش ۱۰٬۰۰۰ تومانی با مبلغ ۱۰۰٬۰۰۰ ریال به درگاه می‌رسد

می‌توانید از دستیار بخواهید همین هشت حالت را به تست خودکار پروژه‌تان تبدیل کند.

نصب مهارت در Claude Code و claude.ai

راه نصب در صفحهٔ مهارت اتصال به درگاه پرداخت آمده است. دو راه دارد:

دستیار Claude Code (نصب دستی در پوشهٔ مهارت‌ها): این دستور را در ترمینال اجرا کنید و Claude Code را یک بار ببندید و دوباره باز کنید.

curl -fsSL --create-dirs -o ~/.claude/skills/iran-payment-gateway/SKILL.md https://mcpfarsi.ir/skills/iran-payment-gateway/SKILL.md

برای اینکه مهارت فقط در یک پروژه باشد، به‌جای ~/.claude پوشهٔ .claude ریشهٔ همان پروژه را بدهید. در PowerShell ویندوز هم curl.exe را به‌جای curl و $HOME را به‌جای ~ بنویسید.

سایت claude.ai و برنامهٔ دسکتاپ Claude: فایل zip را از صفحهٔ مهارت بگیرید، بازش نکنید و در تنظیمات Claude، بخش Capabilities، همان فایل را بارگذاری کنید. مهارت سفارشی در claude.ai برای پلن‌های Pro، Max، Team و Enterprise است، اجرای کد باید روشن باشد و مهارت برای هر کاربر جدا نصب می‌شود. مهارت‌ها بین claude.ai و Claude Code همگام نمی‌شوند؛ اگر هر دو را دارید، در هر کدام جدا نصبش کنید.

طبق فهرست agentskills.io (مهر ۱۴۰۵) برنامه‌هایی مثل Cursor هم قالب Agent Skills را پشتیبانی می‌کنند، ولی جای پوشهٔ مهارت در هر کدام فرق دارد؛ راهنمای همان برنامه را ببینید. اگر مطمئن نیستید مهارت با سرور MCP چه فرقی دارد، تفاوت Skill و MCP را بخوانید.

این مهارت چه کاری از دستش برنمی‌آید؟

• فقط متن است: به زرین‌پال یا زیبال وصل نمی‌شود، تراکنش نمی‌سازد، کلید API نمی‌خواهد و پنل پذیرنده را نمی‌بیند.
• دو درگاه مشخص: دستور دقیق فقط برای زرین‌پال نسخهٔ ۴ و زیبال دارد.
• دو زبان: نمونه‌کدها Node.js و Python است؛ برای PHP یا لاراول کد آماده ندارد و دستیار باید جریان را خودش به آن زبان برگرداند.
• تاریخ دارد: واقعیت‌های مهارت مال مهر ۱۴۰۵ است و API درگاه‌ها ممکن است عوض شود. خود مهارت پیوند مستندات رسمی را به‌عنوان مرجع نهایی آورده است.
• پیش از نصب بخوانید: کل مهارت یک فایل SKILL.md خواناست و هیچ اسکریپتی اجرا نمی‌کند. یک بار نگاهش کنید.

مستندات زنده را هم کنار مهارت بگذارید

مهارت روش کار را می‌دهد، ولی داده‌ای از بیرون نمی‌آورد. اگر می‌خواهید دستیار هنگام نوشتن کد، فیلدها و کدهای خطا را از مستندات همین امروز زرین‌پال بخواند، سرور رسمی مستندات زرین‌پال را هم وصل کنید؛ چهار قابلیت فقط‌خواندنی دارد و کلید نمی‌خواهد. اگر به‌جای درگاه روی سایت، با فاکتور و لینک پرداخت کار می‌کنید، ساخت فاکتور در پی‌پینگ را ببینید.

پیش از اینکه دکمهٔ «پرداخت» بعدی را به درگاه وصل کنید، مهارت را از صفحهٔ اتصال به درگاه پرداخت نصب کنید و هشت تست بالا را یک بار در sandbox اجرا کنید.