مقدمه

وب‌سرویس (API) پِی زیتو برای اتصال به یک سایت که دارای افزونه پرداخت پِی زیتو است طراحی شده است.

به این مفهوم که شما می‌توانید در سایتی که بر روی آن افزونه پِی زیتو را دارید، با فعال‌سازی سرویس ویژه وب‌سرویس (API)، آن سایت را تبدیل به یک درگاه پرداخت واسط یا همان میزبان وب‌سرویس پرداخت کنید.

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

سایتی که قرار است میزبان وب‌سرویس باشد باید یک سایت وردپرسی یا جوملایی باشد، نسخه حرفه‌ای پِی زیتو روی آن نصب باشد و سرویس ویژه وب‌سرویس (API) را نیز خریداری و فعال‌سازی نموده باشد.

اگر فروشگاهی که قرار است به سایت میزبان وب‌سرویس وصل شود جوملا یا وردپرس است، فعالسازی بسیار ساده است. روی آن سایت هم پِی زیتو حرفه‌ای نصب و فعال‌سازی شود و سرویس ویژه وب‌سرویس (API) را نیز خریداری و فعال شده باشد؛ سپس با نصب و تنظیم درگاه وب‌سرویس در بخش درگاه‌ها، سایت خود را به سایت میزبان وب‌سرویس متصل کنید.

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

APIها بر اساس استاندارد REST هستند؛ درخواست و پاسخ JSON و فقط HTTPS.

مفاهیم

میزبان وب‌سرویس

سایتی که افزونه پِی زیتو روی آن نصب است و سرویس وب‌سرویس (API) در آن فعال شده. این سایت درگاه‌های پرداخت خود را از طریق API به دیگر فروشگاه‌ها ارائه می‌دهد.

فروشگاه

سایت، اسکریپت، ربات و… که می‌خواهد پرداخت‌هایش را از طریق میزبان وب‌سرویس انجام دهد.

BASE URL

آدرس پایه وب‌سرویس میزبان وب‌سرویس که از پنل پِی زیتو در مسیر سایت میزبان / منوی امکانات / گزینه وب‌سرویس (API) می‌توانید دریافت کنید.

مثال: https://domain.com

ساختار پاسخ API

پاسخ‌های موفق همیشه این شکل را دارند:

{ "success": true, "data": { ... } }

• success — آیا خود درخواست API با موفقیت پردازش شد (امضا، پارامترها، یافتن رکورد و…). در تأیید پرداخت، success: true به‌معنی موفقیت مالی پرداخت نیست.
• data — نتیجهٔ واقعی endpoint — فیلدهای هر بخش در مستندات همان endpoint توضیح داده شده است.

پاسخ خطا:

{ "success": false, "error": 1004, "error_message": "امضای درخواست (HMAC) با سرور میزبان مطابقت ندارد..." }

راه‌اندازی

1. در میزبان وب‌سرویس وارد مدیریت ← افزونه پِی زیتو ← امکانات ← وب‌سرویس (API) شوید.
2. یک وب‌سرویس بسازید و این سه مقدار را کپی کنید:
   • آدرس پایه وب‌سرویس — مثلاً https://domain.com
   • کلید عمومی — pz_pub_…
   • کلید خصوصی — pz_scr_…
3. اگر فروشگاه وردپرس یا جوملا است، پِی زیتو حرفه‌ای را برای فروشگاه تهیه نموده و نصب کنید، سرویس ویژه وب‌سرویس (API) را هم خریداری نموده. سپس از طریق درگاه‌ها، درگاه وب‌سرویس را نصب، فعالسازی و تنظیم کنید.
   
   اگر فروشگاه وردپرس و جوملا نیست، از طریق این API می‌توانید اتصال را انجام دهید.

احراز هویت

برای endpointهای محافظت‌شده از الگوریتم HMAC-SHA256 استفاده می‌شود. به‌جای ارسال رمز یا توکن روی شبکه، فروشگاه هر درخواست را با Secret امضا می‌کند و میزبان وب‌سرویس امضا را بررسی می‌کند.

کلیدهای API — Public Key و Secret

هر پروفایل وب‌سرویس در میزبان وب‌سرویس دو مقدار دارد:

نحوه استفاده در هر درخواست

چهار header زیر برای هر درخواست API الزامی است. X-Payzito-Key ثابت می‌ماند؛ اما X-Payzito-Timestamp، X-Payzito-Nonce و X-Payzito-Signature را برای هر درخواست از نو بسازید — کپی‌کردن مقادیر از درخواست قبلی معتبر نیست.

مقدار X-Payzito-Signature از اتصال timestamp + nonce + bodyRaw با Secret و الگوریتم HMAC-SHA256 ساخته می‌شود — bodyRaw در بخش بعد توضیح داده شده است.

bodyRaw — بدنهٔ خام درخواست

bodyRaw همان متن خام (raw) بدنهٔ HTTP است — نه آبجکت parse‌شده، بلکه دقیقاً همان رشته‌ای که در body درخواست ارسال می‌شود.

• POST با JSON: خروجی json_encode(...) (یا معادل آن) قبل از ارسال — همان رشته را هم در body بفرستید و هم در امضا به‌کار ببرید.
• GET بدون body: رشتهٔ خالی ""

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

ایجاد پرداخت

با متد POST و پارامترهای زیر یک پرداخت روی میزبان وب‌سرویس ثبت می‌کنید. در پاسخ موفق (HTTP 201) داخل data این فیلدها برمی‌گردد:

• payment_id — شناسهٔ داخلی پرداخت روی میزبان (برای Start، Verify و Inquiry)
• trans_id — همان شمارهٔ سفارش ارسالی از فروشگاه
• invoice_code — شمارهٔ صورتحساب روی میزبان (طبق قوانین خود میزبان)
• start_url — آدرس هدایت کاربر به صفحهٔ پرداخت میزبان

پارامترها

پاسخ موفق (HTTP 201)

در صورت ثبت موفق پرداخت روی میزبان وب‌سرویس، پاسخ JSON با success: true برمی‌گردد:

{
  "success": true,
  "data": {
    "payment_id": 12345,
    "trans_id": "TP-000491",
    "invoice_code": "TP-493",
    "start_url": "{BASE_URL}/index.php/pa-api/v1/payments/12345/start"
  }
}

trans_id تکراری (HTTP 200)

اگر trans_id قبلاً برای این پروفایل وب‌سرویس ثبت شده باشد، همان پاسخ قبلی با HTTP 200 برمی‌گردد — پرداخت جدیدی ساخته نمی‌شود. فیلد duplicate: true به data اضافه می‌شود؛ بقیهٔ فیلدها مثل پاسخ 201 است:

{
  "success": true,
  "data": {
    "payment_id": 12345,
    "trans_id": "TP-000491",
    "invoice_code": "TP-493",
    "start_url": "{BASE_URL}/index.php/pa-api/v1/payments/12345/start",
    "duplicate": true
  }
}

شروع پرداخت

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

این endpoint به header احراز هویت نیاز ندارد.

Callback

پس از انجام تراکنش، کاربر به callback_url ارسال‌شده در ایجاد پرداخت برمی‌گردد. Callback فقط اطلاع‌رسانی است؛ برای نهایی شدن تراکنش حتماً endpoint تایید پرداخت را فراخوانی کنید.

تایید پرداخت

آخرین مرحله چرخه پرداخت، تایید تراکنش از میزبان وب‌سرویس است. این endpoint idempotent است.

پارامترها

پاسخ موفق (HTTP 200)

{
  "success": true,
  "data": {
    "verified": 1,
    "already_verified": 0,
    "payment_id": 12345,
    "trans_id": "TP-000491",
    "status": 10,
    "amount": 150000,
    "ref_number": "REF-98765",
    "gateway_id": 12,
    "gateway_name": "zarinpal"
  }
}

اگر پرداخت در وضعیت معلق (on hold) باشد، پاسخ کوتاه‌تر است: verified: 0 · status · message: "on_hold"

استعلام پرداخت

وضعیت فعلی یک پرداخت را فقط می‌خواند — recheck درگاه انجام نمی‌شود. برای تأیید نهایی و به‌روزرسانی از درگاه، از تایید پرداخت (Verify) استفاده کنید.

درخواست

متد GET — شناسهٔ پرداخت در مسیر URL است؛ بدنهٔ HTTP خالی است.

headerهای احراز هویت HMAC الزامی است. چون بدنه خالی است، برای امضا bodyRaw = رشتهٔ خالی "" است.

پاسخ موفق (HTTP 200)

{
  "success": true,
  "data": {
    "payment_id": 12345,
    "trans_id": "TP-000491",
    "status": 1,
    "amount": 150000,
    "ref_number": "",
    "start_url": "{BASE_URL}/index.php/pa-api/v1/payments/12345/start"
  }
}

تفاوت با Verify: استعلام فقط وضعیت ذخیره‌شده را برمی‌گرداند؛ Verify در صورت نیاز recheck درگاه انجام می‌دهد و فیلدهای verified · gateway_id · gateway_name را هم می‌دهد.

Webhook

اگر webhook_url در ایجاد پرداخت ارسال شود، میزبان وب‌سرویس پس از تغییر وضعیت یک POST امضاشده به فروشگاه می‌فرستد.

فیلدهای بدنه: event · payment_id · trans_id · status · amount · ref_number · gateway_name

رویدادها: payment.paid و payment.failed

خطاها

در پاسخ خطا ساختار یکسان است — کد عددی در error و متن خطا در error_message برمی‌گردد. فروشگاه باید برای نمایش به کاربر از error_message میزبان استفاده کند تا با به‌روزرسانی کدها، پیام اشتباه نشان داده نشود.

{
  "success": false,
  "error": 1004,
  "error_message": "امضای درخواست (HMAC) با سرور میزبان مطابقت ندارد. Secret، بدنهٔ خام (bodyRaw) و نحوهٔ encode JSON را بررسی کنید."
}

نمونهٔ خطای عدم تطابق جمع فاکتور (کد 4004) — وقتی جمع items و fees با amount یکی نباشد:

{
  "success": false,
  "error": 4004,
  "error_message": "جمع فاکتور (items و fees) برابر 135000 است اما مبلغ پرداخت (amount) برابر 150000 است. این دو مقدار باید یکسان باشند."
}

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

سری ۱ — احراز هویت (HTTP 401)

سری ۲ — دسترسی (HTTP 403)

سری ۳ — ایجاد پرداخت (HTTP 422)

سری ۴ — فاکتور (factor) (HTTP 422)

سری ۵ — تأیید / استعلام (HTTP 422)

سری ۶ — پرداخت (HTTP 404 · 409)

سری ۹ — سرور (HTTP 400 · 500 · 503)