برای شروع کار با این سرویس و دریافت ACCESS_TOKEN، لطفاً دو اسکریپت successful.php و failed.php را در مسیر دلخواه سرور خود (مثلاً /pay/) قرار دهید و URLهای callback نهایی را به همراه ACCESS_TOKEN زرین پال خود را به تیم پشتیبانی ما ارسال کنید:

• successful.php: مسیر بازگشت پرداخت‌های موفق

  • مثال: https://your-domain.com/pay/successful.php

• failed.php: مسیر بازگشت پرداخت‌های ناموفق

  • مثال: https://your-domain.com/pay/failed.php

پس از دریافت ACCESS_TOKEN، برای همه درخواست‌های API، هدر زیر را ارسال نمایید:

Authorization: Bearer <ACCESS_TOKEN>

با این API می‌توانید:

1. ایجاد لینک پرداخت با توکن اختصاصی زرین‌لینک
2. بررسی وضعیت تراکنش و دریافت جزئیات پرداخت

⚠️ برای فعال‌سازی سرویس و دریافت توکن، پس از ارسال URLهای callback، با پشتیبانی تماس بگیرید.

• Base URL: https://zarinpay.me/api

• مسیرها:

  • /create-payment
  • /verify-payment

هر دو نقطه‌ٔ ورود از روش HTTP POST استفاده می‌کنند و داده‌ها را به صورت JSON ارسال و دریافت می‌کنند.

• همهٔ درخواست‌ها باید هدر زیر را داشته باشند:

  Authorization: Bearer <access_token>
  Content-Type: application/json

• توکن دسترسی (access_token) توسط متد authenticate() تأمین می‌شود.

تمام پاسخ‌ها شامل فیلد زیر هستند:

{
  "success": <boolean>,
  "error": "<error_message>"           // در صورت شکست
}

• success: true نشان‌دهندهٔ موفقیت عملیات است.
• success: false در صورت بروز خطا یا مشکل داخلی.

• 100: پرداخت تازه تأیید شده (success: true)
• 101: پرداخت قبلاً تأیید شده (success: true)
• -1: پرداخت ناموفق (success: false)
• -53: دسترسی غیرمجاز به تراکنش (success: false)
• -54: تراکنش یافت نشد (success: false)

• مسیر: POST /create-payment

• بدنه درخواست (JSON):

  {
    "amount": 10000,        // مبلغ به تومان
    "order_id": "654321", // شناسه سفارش در سیستم شما
    "customer_user_id": "2326546856", // شناسه کاربر
    "description": "buy acconut 654321"   // توضیحات
  }

مدت زمان فعال بودن تراکنش هم 20 دقیقه از زمان ساخت می باشد در صورتی که وضعیت سفارشتون PENDING باشد اگر با یک order_id دوبار برای ساخت درگاه درخواست بدین همون نتیجه و لینک قبل را میگیرید و بعد از کنسل شدن یا پرداخت امکان ساخت درگاه با اون order_id نمیباشد

• پاسخ موفقیت‌آمیز:

  {
    "success": true,
    "payment_link": "https://www.zarinpal.com/pg/StartPay/ABCDEF123456",
    "authority": "ABCDEF123456"
  }

• پاسخ خطا:

  {
    "success": false,
    "error": "Invalid amount"
  }

• مسیر: POST /verify-payment

• بدنه درخواست (JSON):

  {
    "authority": "ABCDEF123456"
  }

• پاسخ موفقیت‌آمیز:

  {
    "success": true,
    "data": {
      "code": 100,
      "transaction": {
         "payment_id": payment_id,
         "amount": amount,
         "order_id": order_id,
         "authority": authority
      }
    }
  }

• پاسخ خطا:

  {
    "success": false,
    "error": "Transaction not found"
  }