# راهنمای اتصال به درگاه اینترنتی زرین پال

جهت استفاده از وب سرويس زرین پال بايد از آدرس های وب سرویس , متد ها و پارامتر های ذکر شده استفاده نمایید .

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

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

به نوع داده ها و نام فیلد توجه کنید.

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

POST
https://api.zarinpal.com/v4/payment/request.json
نام نوع اجباری شرح
merchant_id String بله كد 36 كاراكتري اختصاصي پذيرنده
amount Integer بله مبلغ تراكنش به (ریال)
description String بله توضیحات مربوط به تراکنش
mobile String خیر شماره تماس خریدار
email String خیر ایمیل خریدار
callback_url String بله صفحه بازگشت مشتري، پس از انجام عمل پرداخت
  • نمونه درخواست
  • درخواست
  • پاسخ
<?php

$data = array("merchant_id" => "4ced0a1e-4ad8-4309-9668-3ea3ae8e8897=",
    "amount" => 10001,
    "callback_url" => 'http://www.yoursite.com/verify.php/',
    'description' => 'خرید تست',
    'metadata' => [
    'mobile' => '09120000000',
    'email' => 'youremail@gmail.com',
],
    );
$jsonData = json_encode($data);
$ch = curl_init('https://api.zarinpal.com/v4/payment/request.json');
curl_setopt($ch, CURLOPT_USERAGENT, 'ZarinPal Rest Api v1');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($jsonData)
));

$result = curl_exec($ch);
$err = curl_error($ch);
$result = json_decode($result, true, JSON_PRETTY_PRINT);
curl_close($ch);


if ($err) {
    echo "cURL Error #:" . $err;
} else {
    if (empty($result['errors'])) {
        if ($result['data']['code'] == 100) {
            header('Location: https://www.zarinpal.com/pg/StartPay/' . $result['data']["authority"]);
        }
    } else {
        echo '<p>' .
            $result['errors']['code'] . '<br>' .
            $result['errors']['message'] . '<br>';
        echo '</p>';
    }
}

?>

# انتقال کاربر به صفحه پرداخت

در صورتی که در مرحله ارسال دیتا ، اطلاعات ارسالی صحیح باشه و دو مقدار code و authority رو دریافت کرده باشید باید کاربر رو به درگاه پرداخت انتقال میدهید.

برای اینکار باید مقدار اتوریتی که در مرحله اول دریافت کردید رو در اخر ادرس قرار بدید و کاربر رو به URL ایجاد شده ریدایرکت کنید تا بلافاصله کاربر به درگاه پرداخت هدایت بشه و سپس مرحله سوم رو انجام بدید.

GET
Location: https://www.zarinpal.com/pg/StartPay/ . $result['data']["authority"]

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

بعد از پايان عمليات درسمت زرينپال، زرينپال وظيفه دارد كاربر را به سايت پذيرنده كه از طريق callback_url مشخص شده است بازگرداند.

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

نکته

نكته: توجه داشته باشيد كه يك Status به صورت QueryString به سايت پذيرنده ارسال ميگردد كه دو مقدار ثابت دارد ”OK“ و”NOK“ ؛ در صورتي كه اين مقدار برابر ”NOK“ بود به اين معنا بوده كه تراكنش نا موفق بوده و يا توسط كاربر لغو شده است؛ پس در صورتي verify استفاده شود كه با QueryString مقدار Status برابر با ”OK“ باشد.

GET
http://www.yoursite.ir/?Authority=A00000000000000000000000000202690354&Status=OK

در صفحه بازگشت می بایست با متد verify اطلاعات ارسالی را چک نمایید و در صورت موفق بودن پرداخت را ثبت و شماره تراکنش را به کاربر نمایش دهید

در غير اينصورت پذيرنده موظف اسـت كـه بـا توجه به كد خطايي كه توسط متد verify دريافت ميكند كاربر را از خطاي رخ داده مطلع سازد.

در این مرحله اگر مقدار پارامتر code برابر 100 بود به معنای موفق بودن تراکنش است و با پارامتر ref_id شماره تراکنش را به کاربر نمایش میدهید

POST
https://api.zarinpal.com/v4/payment/verify.json

پارامتر

نام نوع شرح
merchant_id String كد 36 كاراكتري اختصاصي پذيرنده
amount Integer مبلغ تراكنش به (ریال)
authority String كد يكتاي شناسه مرجع درخواست.

نمونه کد وریفای

  • درخواست
  • پاسخ
<?php

$Authority = $_GET['Authority'];
$data = array('merchant_id' => '1344b5d4-0048-11e8-94db-005056a205be', 'authority' => $Authority, 'amount' => 10001);
$jsonData = json_encode($data);
$ch = curl_init('https://api.zarinpal.com/v4/payment/verify.json');
curl_setopt($ch, CURLOPT_USERAGENT, 'ZarinPal Rest Api v1');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'Content-Length: ' . strlen($jsonData)
));

$result = curl_exec($ch);
curl_close($ch);
$result = json_decode($result, true);

if ($err) {
    echo "cURL Error #:" . $err;
} else {
    if ($result['data']['code'] == 100) {
        echo 'Transation success. RefID:' . $result ['data']['ref_id'];
    } else {
        echo 'Transation failed. code:' . $result ['data']['code'];
    }
}
?>

مقاديري كه توسط متد verify برگشت داده ميشود به شرح زير ميباشد.

نام نوع شرح
code Integer عددي كه نشان دهنده موفق بودن يا عدم موفق بودن پرداخت ميباشد.
ref_id Integer در صورتي كه پرداخت موفق باشد؛ شماره تراكنش پرداخت انجام شده را بر ميگرداند.

مهم

مهم : درصورت موفقیت آمیز بودن تراکنش، با فراخوانی متد verify، یکبار کد code 100 رخ میدهد و در دفعات بعدی وریفای همان تراکنش کد 101 رخ میدهد.

کد code 101 به معنای آن است که تراکنش موفق بوده و یکبار قبلا وریفای شده است و این بار دوم هست