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

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

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

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

نام	نوع	الزام	توضیحات
merchant_id	String	بله	كد ۳۶ كاراكتری اختصاصی پذیرنده
amount	Integer	بله	مبلغ تراكنش
currency	String	خیر	تعیین واحد پولی ریال (IRR) یا تومان(IRT)
description	String	بله	توضیحات مربوط به تراکنش
callback_url	String	بله	صفحه بازگشت مشتري، پس از انجام عمل پرداخت
metadata	Array		دارای مقدار های mobile و email و order_id
mobile	String	خیر	شماره تماس خریدار
email	String	خیر	ایمیل خریدار
order_id	String	خیر	شماره سفارش

نکته

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

https://payment.zarinpal.com/pg/v4/payment/request.json

درخواست

PHP
cURL


<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://payment.zarinpal.com/pg/v4/payment/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",
  "amount": "1100",
  "callback_url": "http://example.com/verify",
  "description": "Transaction description.",
  "metadata": {
    "mobile": "09121234567",
    "email": "info.test@example.com"
  }
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Accept: application/json'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

پاسخ

{
  "data": {
    "code": 100,
    "message": "Success",
    "authority": "A0000000000000000000000000000wwOGYpd",
    "fee_type": "Merchant",
    "fee": 100
  },
  "errors": []
}

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

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

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

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

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

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

نکته

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

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

# اعتبار سنجی

برای استفاده از این متد، باید ابتدا در صفحه بازگشت، با استفاده از متدverify اطلاعات ارسالی را چک کرده و در صورت موفق بودن پرداخت، آن را ثبت و شماره تراکنش را به کاربر نمایش دهید. در غیر اینصورت موظف هستید بـا توجه به كد خطایی كه توسط متد verify دریافت می‌كنید كاربر را از خطای رخ داده مطلع سازید.

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

پارامتر

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

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

نام	نوع	توضیحات
code	Integer	عددی كه نشان دهنده موفق بودن یا موفق نبودن پرداخت است.
ref_id	Integer	در صورتی كه پرداخت موفق باشد، شماره تراكنش پرداخت انجام شده را بر می‌گرداند.
card_pan	String	شماره کارت به صورت Mask
card_hash	String	هش کارت به صورت SHA256
fee_type	String	پرداخت کننده کارمزد: که در پنل کاربری میان خریدار یا خود پذیرنده قابل انتخاب است.
fee	Integer	کارمزد

مهم

درصورت موفقیت آمیز بودن تراکنش، با فراخوانی متدverify ، تنها یکبار کد100 رخ می‌دهد و در دفعات بعدی verify همان تراکنش، کد 101 اتفاق می‌افتد. در نتیجه کد 101 به معنای آن است که تراکنش موفق بوده و یک‌بار قبلا عملیات verifyبر روی آن انجام شده است. لطفا در نظر داشته باشید که در دفعات بعدی verify همان تراکنش نیز کد 101 نشان داده می‌شود.

https://payment.zarinpal.com/pg/v4/payment/verify.json

PHP
cURL


<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://payment.zarinpal.com/pg/v4/payment/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",
  "amount": "1000",
  "authority": "A0000000000000000000000000000wwOGYpd"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Accept: application/json'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

پاسخ

{
  "data": {
    "code": 100,
    "message": "Verified",
    "card_hash": "1EBE3EBEBE35C7EC0F8D6EE4F2F859107A87822CA179BC9528767EA7B5489B69",
    "card_pan": "502229******5995",
    "ref_id": 201,
    "fee_type": "Merchant",
    "fee": 0
  },
  "errors": []
}

قبلی

معرفی

بعدی

سرویس تست (sandbox)