مستندات فیک‌پال
راهنمای استفاده از API فیک‌پال برای شبیه‌سازی و تست فرآیند های پرداخت
هدف این راهنما
این صفحه شما را در فرآیند مهاجرت از شبیه‌ساز درگاه پرداخت فیک‌پال به درگاه واقعی زرین‌پال راهنمایی می‌کند. فرض بر این است که شما در محیط توسعه، بر اساس مستندات فیک‌پال و صفحات ایجاد صفحه پرداخت، انتقال به صفحه پرداخت، بازگشت به وب‌سایت و اعتبارسنجی تراکنش پیاده‌سازی اولیه را انجام داده‌اید و اکنون قصد اتصال سرویس خود به درگاه رسمی زرین‌پال را دارید.
معماری و نام‌گذاری پارامترها در فیک‌پال به‌صورت هدفمند شبیه به درگاه زرین‌پال طراحی شده‌اند تا فرآیند مهاجرت را تسهیل کنند و تغییرات لازم را تنها به اصلاحاتی جزئی در آدرس‌ها و جزئیات درخواست‌ها محدود سازند.
پیش‌نیازها
- حساب کاربری زرین‌پال: ایجاد حساب کاربری، تکمیل احراز هویت و دریافت
merchant_idاز پنل زرین‌پال. - دسترسی به کد سامانه: دسترسی به بخشی از کد که در آن، منطق اتصال به فیک‌پال (ایجاد تراکنش، انتقال کاربر، بازگشت و اعتبارسنجی) پیاده‌سازی شده است.
- تفکیک محیط توسعه و عملیاتی: تعریف متغیرهای محیطی (Environment Variables) مجزا برای آدرس‌های فیک‌پال و زرین‌پال تا بتوانید در محیط توسعه همچنان از فیک‌پال استفاده کنید و فقط در محیط عملیاتی به زرین‌پال متصل شوید.
مقایسه کلی فیک‌پال و زرین‌پال
| موارد مقایسه | فیک‌پال | زرین‌پال |
|---|---|---|
| ایجاد تراکنش (Request) | undefined/payment/request | https://payment.zarinpal.com/pg/v4/payment/request.json |
| انتقال کاربر به درگاه | undefined/payment/{Authority} | https://payment.zarinpal.com/pg/StartPay/{Authority} |
| بازگشت کاربر به سایت | …?Authority=…&Status=OK|NOK | …?Authority=…&Status=OK|NOK |
| اعتبارسنجی تراکنش (Verify) | undefined/payment/verify | https://payment.zarinpal.com/pg/v4/payment/verify.json |
همان‌طور که مشاهده می‌کنید، ساختار کلی فرآیند (ایجاد تراکنش → هدایت کاربر به درگاه → بازگشت به سایت → اعتبارسنجی) در فیک‌پال و زرین‌پال یکسان است و عمده تغییرات شما در سطح آدرس‌ها، برخی پارامترها و مدیریت پاسخ‌های بازگشتی خواهد بود.
گام اول – جایگزینی درخواست ایجاد تراکنش
در فیک‌پال، شما درخواست ایجاد صفحه پرداخت را به آدرس undefined/payment/request ارسال می‌کنید. در زرین‌پال، معادل این متد، آدرس زیر است:
https://payment.zarinpal.com/pg/v4/payment/request.jsonپارامترهای اصلی درخواست در زرین‌پال
| نام | نوع | الزام | توضیحات |
|---|---|---|---|
| merchant_id | String | بله | کد ۳۶ کاراکتری اختصاصی پذیرنده در زرین‌پال. |
| amount | Integer | بله | مبلغ تراکنش (با توجه به پارامتر انتخابی واحد پول). |
| currency | String | خیر | واحد پولی IRR (ریال) یا IRT (تومان). |
| description | String | بله | توضیحات مربوط به تراکنش. |
| callback_url | String | بله | آدرس بازگشت مشتری پس از پرداخت؛ معادل همان callback_url در فیک‌پال. |
نمونه بدنه درخواست به زرین‌پال
{
"merchant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"amount": 1020000,
"callback_url": "https://your-domain.com/payment/verify",
"description": "Transaction description.",
"metadata": {
"mobile": "09121234567",
"email": "info@example.com"
}
}در بسیاری از پیاده‌سازی‌ها، تنها تغییری که در این گام لازم است انجام دهید، جایگزین کردن آدرس فیک‌پال با آدرس زرین‌پال و تطبیق ساختار JSON مطابق با مستندات رسمی زرین‌پال است.
گام دوم – تغییر منطق انتقال کاربر به درگاه
در فیک‌پال، پس از دریافت مقدار authority، کاربر را به مسیری مانند undefined/payment/{Authority} هدایت می‌کنید. در زرین‌پال، معادل این مرحله به صورت زیر است:
https://payment.zarinpal.com/pg/StartPay/{Authority}مثال: اگر مقدار authority برابر با A0000000000000000000000000000wwOGYpd باشد، آدرس نهایی به صورت زیر خواهد بود:
https://payment.zarinpal.com/pg/StartPay/A0000000000000000000000000000wwOGYpdدر سطح کد، کافی است منطق ساخت URL فیک‌پال را با URL زرین‌پال جایگزین کنید و بقیه فرآیند هدایت کاربر مشابه گذشته باقی می‌ماند.
گام سوم – مدیریت بازگشت کاربر از درگاه
پس از اتمام فرآیند پرداخت، زرین‌پال کاربر را به آدرس callback_url شما بازمی‌گرداند؛ دقیقاً مشابه رفتار فیک‌پال.
ساختار Query String نیز همان الگوی آشنا را دارد:
https://your-domain.com/payment/verify?Authority=A0000000000000000000000000000wwOGYpd&Status=OK- در صورت موفق بودن عملیات در سمت درگاه، مقدار
Statusبرابر باOKخواهد بود. - در صورت لغو پرداخت یا بروز خطا، مقدار
Statusبرابر باNOKخواهد بود.
همانند فیک‌پال، صرف دریافت Status=OK به هیچ عنوان به معنای نهایی شدن تراکنش نیست و شما ملزم هستید در گام بعد، حتماً
متد verify زرین‌پال را فراخوانی کنید.
گام چهارم – جایگزینی متد اعتبارسنجی (Verify)
در فیک‌پال، برای اعتبارسنجی تراکنش از آدرس undefined/payment/verify استفاده می‌کنید. معادل این متد در زرین‌پال به صورت زیر است:
https://payment.zarinpal.com/pg/v4/payment/verify.jsonنمونه بدنه درخواست اعتبارسنجی در زرین‌پال
{
"merchant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"amount": 1020000,
"authority": "A0000000000000000000000000000wwOGYpd"
}نمونه پاسخ موفق زرین‌پال
{
"data": {
"code": 100,
"message": "Verified",
"card_hash": "1EBE3EBEBE35C7EC0F8D6EE4F2F859107A87822CA179BC9528767EA7B5489B69",
"card_pan": "502229******5995",
"ref_id": 201,
"fee_type": "Merchant",
"fee": 0
},
"errors": []
}- مقدار
code = 100به معنای موفق بودن تراکنش است. - در صورت فراخوانی مجدد متد
verifyبرای همان تراکنش، ممکن است مقدارcode = 101برگردد که نشان‌دهنده تأیید قبلی تراکنش است (تراکنش همچنان موفق محسوب می‌شود). - می‌توانید مقدار
ref_idرا به عنوان شماره پیگیری پرداخت به کاربر نمایش دهید و سایر اطلاعات مانندcard_panوcard_hashرا برای گزارش‌گیری یا ثبت لاگ استفاده کنید.
نکات پیشنهادی برای راه‌اندازی هم‌زمان فیک‌پال و زرین‌پال
- استفاده از متغیرهای محیطی: آدرس‌ها و کلیدها را در متغیرهای محیطی (مانند
FAKEPAL_API_BASE_URL،ZARINPAL_MERCHANT_IDو …) نگه دارید تا بتوانید بدون تغییر کد اصلی، بین محیط تست (فیک‌پال) و محیط عملیاتی (زرین‌پال) جابه‌جا شوید. - حفظ فیک‌پال برای تست: توصیه می‌شود حتی پس از اتصال به زرین‌پال، از فیک‌پال برای تست‌های خودکار (Integration Test / E2E) و محیط توسعه استفاده کنید تا بدون ایجاد تراکنش واقعی، سناریوهای مختلف را بررسی نمایید.
- مدیریت خطاها و وضعیت‌ها: کدهای خطا و پیام‌های بازگشتی زرین‌پال را مطابق مستندات رسمی آن پیاده‌سازی کنید و در صورت امکان، آن‌ها را در لاگ سامانه خود ذخیره نمایید تا در عیب‌یابی‌های بعدی مورد استفاده قرار گیرند.
برای جزئیات کامل‌تر درباره پارامترها، ساختار پاسخ‌ها و لیست کدهای خطا، حتماً به مستندات رسمی اتصال به درگاه زرین‌پال مراجعه کنید.