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

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

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

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

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

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

POST

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

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

پرداخت با کارت خاص

برای این که کاربر با کارتی که قبلا توسط شما احراز شده است پرداخت کند و در غیر این صورت پرداخت ناموفق باشد در قسمت metadata باید card_pan را اضافه کنید

برای اطلاعات بیشتر اینجا کیلیک کنید

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

• درخواست
• پاسخ

curl -X POST \
  https://api.zarinpal.com/pg/v4/payment/request.json \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
  "merchant_id": "1344b5d4-0048-11e8-94db-005056a205be",
  "amount": 10000,
  "callback_url": "http://yoursite.com/verify",
  "description": "افزایش اعتبار کاربر شماره ۱۱۳۴۶۲۹",
  "metadata": {"mobile": "09121234567","email": "info.test@gmail.com"}
}'

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

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

در صورتی که در مرحله ارسال دیتا ، اطلاعات ارسالی صحیح باشه و دو مقدار 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/pg/v4/payment/verify.json

پارامتر

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

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

• درخواست
• پاسخ

curl -X POST \
  https://api.zarinpal.com/pg/v4/payment/verify.json \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -d '{
  "merchant_id": "1344b5d4-0048-11e8-94db-005056a205be",
  "amount": 10000,
  "authority": "A00000000000000000000000000217885159"
}'

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

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

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

مهم

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

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

---