خانه درگاه پرداخت پرداخت مستقیم مستندات API راهنمای استفاده افزونه‌ها
خانه پرداخت مستقیم افزونه‌ها

    # پرداخت مستقیم

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

    ابتدا جهت فعالسازی این سرویس برای درگاه خود تیکت (opens new window) ارسال نمایید.

    # ارسال اطلاعات

    در مرحله اول پذیرندگان باید پارامترهای موجود در جدول زیر را ، با توجه به نوع داده‌ها و نام فیلد، با متد POST به آدرس مشخص شده ارسال نمایند.

    نام نوع الزام توضیحات
    merchant_id String بله كد 36 كاراكتری اختصاصی درگاه پذیرنده
    mobile String بله شماره تماس خریدار
    ssn String خیر کد ملی خریدار
    expire_at String بله تاریخ انقضای قرارداد پرداخت مستقیم ( مدت قرارداد حداقل باید ۳۰ روز باشد )
    max_daily_count String بله حداکثر تعداد تراکنش روزانه
    max_monthly_count String بله حداکثر تعداد تراکنش ماهانه
    max_amount String بله حداکثر مبلغ تراکنش به ریال
    callback_url String بله صفحه بازگشت پس از بستن قرارداد

    پاسخ برگشتی توسط این درخواست به شرح زیر است :

    نام نوع توضیحات
    payman_authority String مقدار آتوریتی پیمان که میبایست ذخیره کنید
    code Integer عددی كه نشان دهنده موفق بودن یا موفق نبودن پرداخت است.
    message String پیام موفقیت آمیز بودن درخواست
    errors Array در صورت وجود خطا کد خطا و پیام آن را برمیگرداند
    https://api.zarinpal.com/pg/v4/payman/request.json

    مثال :

    نمونه درخواست

    • PHP
    • cURL 
    
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.zarinpal.com/pg/v4/payman/request.json',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "merchant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "mobile": "09123456789",
  "ssn": "0480123456",
  "expire_at": "2025-04-08 00:00:00",
  "max_daily_count": "100",
  "max_monthly_count": "1000",
  "max_amount": "50000",
  "callback_url": "https://your-site.com/direct"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Accept: application/json'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
    نمونه پاسخ 
    {
  "data": {
    "payman_authority": "payman_6moa",
    "code": 100,
    "message": "Success"
  },
  "errors": []
}
    نکته

    تمامی داده‌های برگشتی از زرین‌پال به صورت json می باشد.

    # دریافت لیست بانک ها

    برای بستن قرار داد با بانک میبایست bank_code بانکی که میخواهید خریدار با آن قرار داد ببندد را داشته باشید

    برای دریافت bank_code یک درخواست GET به آدرس مشخص شده ارسال کنید

    پاسخ برگشتی توسط این درخواست به شرح زیر است :

    نام نوع توضیحات
    banks Array لیست بانک های موجود
    name String نام بانک
    slug String نام اسلاگ بانک
    bank_code String مقدار bank_code که جهت بستن قرارداد با بانک مورد نظر نیاز دارید
    max_daily_amount Integer حداکثر مبلغ روزانه که بانک قبول به پرداخت میکند
    max_daily_count
    Integer
    یا
    null
    		حداکثر تعداد تراکنش روزانه ای که بانک قبول به پرداخت میکند.
    در صورت null بودن : محدودیتی ندارد
    code Integer عددی كه نشان دهنده موفق بودن یا موفق نبودن پرداخت است.
    message String پیام موفقیت آمیز بودن درخواست
    errors Array در صورت وجود خطا کد خطا و پیام آن را برمیگرداند
    https://api.zarinpal.com/pg/v4/payman/banksList.json

    نمونه پاسخ لیست بانک ها

    {
  "data": {
    "banks": [
      ,
      {
        "name": "بانک سامان",
        "slug": "Saman",
        "bank_code": "SABCIR",
        "max_daily_amount": 100000000,
        "max_daily_count": 25
      },
      {
        "name": "بانک سينا",
        "slug": "Sina",
        "bank_code": "SINAIR",
        "max_daily_amount": 100000000,
        "max_daily_count": null
      }
    ],
    "code": 100,
    "message": "Success"
  },
  "errors": []
}

    # صفحه بستن قرارداد

    پس از دریافت authority و bank_code مقادیر را در لینک مشخص شده قرار دهید و کاربر را به صفحه بانک هدایت کنید

    https://www.zarinpal.com/pg/StartPayman/{payman_authority}/{bank_code}

    # بازگشت به وب‌سایت پذیرنده

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

    در این مرحله با توجه به نتیجه قرارداد و وضعیت آن، بانک خریدار را به آدرس درخواستی پذیرنده که در ارسال اطلاعات با پارامتر callback_url مشخص شده است، هدایت می‌کند.

    نکته

    توجه داشته باشید كه یك Status به صورت QueryString به سایت پذیرنده ارسال می‌شود كه دارای دو مقدار ثابت ”OK“ و ”NOK“ است؛ در صورتی كه این مقدار برابر ”NOK“ باشد، به این معنا است كه بست قرارداد ناموفق بوده یا توسط خریدار لغو شده است؛ درنتیجه متد دریافت signature که در زیر آمده است باید در صورتی استفاده شود كه در QueryString مقدار Status برابر با ”OK“ باشد.

    نمونه موفق :

    https://your-site.ir/?payman_authority=payman_6moa&status=OK

    نمونه ناموفق :

    https://your-site.ir/?payman_authority=payman_6moa&status=NOK

    # دریافت Signature

    پس از بستن قرارداد موفق میبایست با استفاده از این متد signature را دریافت نمایید

    برای دریافت signature میبایست یک درخواست با متد POST به آدرس مشخص شده حاوی مقادیر زیر ارسال کنید :

    نام نوع الزام توضیحات
    merchant_id String بله كد 36 كاراكتری اختصاصی درگاه پذیرنده
    payman_authority String بله مقدار آتوریتی پیمان که در متد ارسال اطلاعات دریافت کردید

    پاسخ برگشتی توسط این درخواست به شرح زیر است :

    نام نوع توضیحات
    signature String مقدار signature حاوی ۲۰۰ کاراکتر که میبایست ذخیره کنید
    code Integer عددی كه نشان دهنده موفق بودن یا موفق نبودن پرداخت است.
    message String پیام موفقیت آمیز بودن درخواست
    errors Array در صورت وجود خطا کد خطا و پیام آن را برمیگرداند
    مهم

    اطلاعات قرارداد اعم از : payman_authority و signature باید به صورت امن توسط پذیرنده نگهداری شود با استفاده از این اطلاعات، پرداخت به صورت مسقیم انجام می شود.

    https://api.zarinpal.com/pg/v4/payman/verify.json

    مثال

    نمونه درخواست

    • PHP
    • cURL 
    
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.zarinpal.com/pg/v4/payman/verify.json',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "merchant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "payman_authority": "payman_6moa"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Accept: application/json'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
    نمونه پاسخ 
    {
  "data": {
    "signature": "eyJpdiI6InpoUHZoT0hPZjdNNj...",
    "code": 100,
    "message": "Success"
  },
  "errors": []
}

    # انجام تراکنش مستقیم

    حال جهت انجام یک تراکنش مستقیم میبایست از طریق قسمت درخواست پرداخت یک پرداخت ایجاد کرده و Authority دریافت کنید.

    سپس از طریق متد Checkout که در زیر آمده است برای پرداخت تراکنش استفاده میکنید.

    برای پرداخت تراکنش ایجاد شده میبایست یک درخواست با متد POST به آدرس مشخص شده ارسال نمایید که حاوی مقادیر زیر است :

    نام نوع الزام توضیحات
    merchant_id String بله كد 36 كاراكتری اختصاصی درگاه پذیرنده
    authority String بله مقدار آتوریتی تراکنشی که از درخواست پرداخت دریافت کردید.
    signature String بله مقدار signature که از متد دریافت Signature دریافت کردید.

    پاسخ برگشتی توسط این درخواست به شرح زیر است :

    نام نوع توضیحات
    refrence_id Integer در صورتی كه پرداخت موفق باشد، شماره تراكنش پرداخت انجام شده را بر می‌گرداند.
    amount Integer مبلغ تراکنش ( به ریال )
    code Integer عددی كه نشان دهنده موفق بودن یا موفق نبودن پرداخت است.
    message String پیام موفقیت آمیز بودن درخواست
    errors Array در صورت وجود خطا کد خطا و پیام آن را برمیگرداند
    https://api.zarinpal.com/pg/v4/payman/checkout.json

    مثال

    نمونه درخواست

    • PHP
    • cURL 
    
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.zarinpal.com/pg/v4/payman/verify.json',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "merchant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "authority": "A0000000000000000000000000002vm5y3lo",
  "signature": "eyJpdiI6InpoUHZoT0hPZjdNNj...",
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Accept: application/json'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
    نمونه پاسخ 
    {
  "data": {
    "refrence_id": 53114978001,
    "amount": 2000,
    "code": 100,
    "message": "Success"
  },
  "errors": []
}

    # لغو قرارداد پرداخت مستقیم

    برای لغو یک قرارداد پرداخت مستقیم میبایست یک درخواست با متد POST به آدرس مشخص شده حاوی مقادیر زیر ارسال کنید :

    نام نوع الزام توضیحات
    merchant_id String بله كد 36 كاراكتری اختصاصی درگاه پذیرنده
    signature String بله مقدار signature که از متد دریافت Signature دریافت کردید.

    پاسخ برگشتی توسط این درخواست به شرح زیر است :

    نام نوع توضیحات
    code Integer عددی كه نشان دهنده موفق بودن یا موفق نبودن لغو پرداخت مستقیم است.
    message String پیام موفقیت آمیز بودن درخواست
    errors Array در صورت وجود خطا کد خطا و پیام آن را برمیگرداند
    مهم

    پذیرنده حتما میبایست با این API یک بخشی برای خریداران خود ایجاد کند تا کاربرانی که پرداخت مستقیم ثبت کرده اند در هر زمان دلخواهی که تمایل به لغو پرداخت مستقیم خود داشتند سرویس پرداخت مستقیم را برای قرارداد خود غیرفعال کند در صورت عدم پیاده سازی این بخش، زرین پال میتواند کل سرویس را غیرفعال کند

    https://api.zarinpal.com/pg/v4/payman/cancelContract.json

    مثال

    نمونه درخواست

    • PHP
    • cURL 
    
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.zarinpal.com/pg/v4/payman/cancelContract.json',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
  "merchant_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "signature": "eyJpdiI6InpoUHZoT0hPZjdNNj...",
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Accept: application/json'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
    نمونه پاسخ 
    {
  "data": {
    "code": 100,
    "message": "Success"
  },
  "errors": []
}

    # اعتبارسنجی تراکنش

    برای وریفای کردن تراکنش مورد نظر میتوانید از متد اعتبارسنجی در مستندات بخش راهنمای اتصالات استفاده کنید

    قبلی

    لیست خطاها

    بعدی

    واحد پولی